@loopstack/oauth-module

npm install @loopstack/oauth-module

import { Module } from '@nestjs/common';
import { OAuthModule } from '@loopstack/oauth-module';
 
@Module({
  imports: [OAuthModule],
})
export class AppModule {}

import { BaseWorkflow, CallbackSchema, Guard, Transition, Workflow } from '@loopstack/common';
import type { RunContext } from '@loopstack/common';
import { OAuthWorkflow } from '@loopstack/oauth-module';
 
@Workflow({
  schema: z.object({ calendarId: z.string().default('primary') }).strict(),
})
export class CalendarWorkflow extends BaseWorkflow<{ calendarId: string }, CalendarState> {
  constructor(
    private readonly calendarFetchEvents: CalendarFetchEventsTool,
    private readonly oAuth: OAuthWorkflow,
  ) {
    super();
  }
 
  @Transition({ to: 'calendar_fetched' })
  async fetchEvents(state: CalendarState, ctx: RunContext): Promise<CalendarState> {
    const args = ctx.args as { calendarId: string };
    const result = await this.calendarFetchEvents.call({ calendarId: args.calendarId });
    return {
      ...state,
      requiresAuthentication: result.data!.error === 'unauthorized',
      events: result.data!.events,
    };
  }
 
  @Transition({ from: 'calendar_fetched', to: 'awaiting_auth', priority: 10 })
  @Guard('needsAuth')
  async authRequired(state: CalendarState): Promise<CalendarState> {
    await this.oAuth.run(
      { provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar.readonly'] },
      { callback: { transition: 'authCompleted' }, show: 'inline', label: 'Google authentication required' },
    );
    return state;
  }
 
  needsAuth(state: CalendarState): boolean {
    return !!state.requiresAuthentication;
  }
 
  @Transition({ from: 'awaiting_auth', to: 'start', wait: true, schema: CallbackSchema })
  async authCompleted(state: CalendarState, _payload: { workflowId: string }): Promise<CalendarState> {
    return state;
  }
 
  @Transition({ from: 'calendar_fetched', to: 'end' })
  async displayResults(state: CalendarState): Promise<unknown> {
    await this.documentStore.save(MarkdownDocument, {
      markdown: this.render(__dirname + '/templates/summary.md', { events: state.events }),
    });
    return {};
  }
}

oauth-module (generic)              provider module (e.g. google)
┌──────────────────────────────┐    ┌──────────────────────────────┐
│  OAuthProviderRegistry       │◄───│  GoogleWorkspaceOAuthProvider│
│  OAuthTokenStore             │    │  (implements interface,      │
│  BuildOAuthUrlTool           │    │   registers on init)         │
│  ExchangeOAuthTokenTool      │    └──────────────────────────────┘
│  OAuthWorkflow               │
│  OAuthPromptDocument         │    consumer workflow
└──────────────────────────────┘    ┌──────────────────────────────┐
                                    │  uses OAuthTokenStore        │
                                    │  launches OAuthWorkflow      │
                                    │  via constructor injection   │
                                    └──────────────────────────────┘

start ──► initiateOAuth ──► awaiting_auth ──► exchangeToken ──► end
              │                                     │
              │  Builds auth URL via                 │  Validates CSRF state,
              │  BuildOAuthUrlTool,                  │  exchanges code via
              │  saves OAuthPromptDocument           │  ExchangeOAuthTokenTool,
              │  with sign-in prompt                 │  stores tokens, updates
              │                                      │  document to 'success'
              ▼                                      ▼
         (waits for user to                    (callback resumes
          complete OAuth in browser)            parent workflow)

import { z } from 'zod';
import { BaseTool, Tool, ToolResult } from '@loopstack/common';
import type { RunContext } from '@loopstack/common';
import { OAuthTokenStore } from '@loopstack/oauth-module';
 
@Tool({
  name: 'my_api_fetch',
  description: 'Fetches data from an OAuth-protected API.',
  schema: z.object({ query: z.string() }).strict(),
})
export class MyApiFetchTool extends BaseTool {
  constructor(private readonly tokenStore: OAuthTokenStore) {
    super();
  }
 
  protected async handle(args: { query: string }, ctx: RunContext): Promise<ToolResult> {
    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'my-provider');
 
    if (!accessToken) {
      return { data: { error: 'unauthorized' } };
    }
 
    const response = await fetch('https://api.example.com/data', {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
 
    return { data: await response.json() };
  }
}

interface OAuthProviderInterface {
  readonly providerId: string; // Unique identifier, e.g. 'google', 'github'
  readonly defaultScopes: string[]; // Fallback scopes when none are specified
 
  buildAuthUrl(scopes: string[], state: string): string;
  exchangeCode(code: string): Promise<OAuthTokenSet>;
  refreshToken(refreshToken: string): Promise<OAuthTokenSet>;
}
 
interface OAuthTokenSet {
  accessToken: string;
  refreshToken?: string;
  expiresIn: number; // Seconds until expiry
  scope: string;
}

@Injectable()
export class MyOAuthProvider implements OAuthProviderInterface, OnModuleInit {
  readonly providerId = 'my-provider';
  readonly defaultScopes = ['read', 'write'];
 
  constructor(private readonly registry: OAuthProviderRegistry) {}
 
  onModuleInit(): void {
    this.registry.register(this);
  }
 
  buildAuthUrl(scopes: string[], state: string): string {
    /* ... */
  }
  async exchangeCode(code: string): Promise<OAuthTokenSet> {
    /* ... */
  }
  async refreshToken(refreshToken: string): Promise<OAuthTokenSet> {
    /* ... */
  }
}

@Module({
  imports: [OAuthModule],
  providers: [MyOAuthProvider],
  exports: [MyOAuthProvider],
})
export class MyOAuthModule {}