@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/modules/oauth/adapters/MockOAuthAdapter.ts

@@ -0,0 +1,138 @@
+import type {
+  AuthUrlOptions,
+  ExchangeCodeOptions,
+  OAuthAdapter,
+  OAuthClientCredentials,
+  TokenResponse,
+} from "./OAuthAdapter.js";
+
+/**
+ * In-memory `OAuthAdapter` for tests + local development. Returns
+ * deterministic responses, captures every call for assertions, and
+ * lets tests preset the responses to simulate provider failures.
+ *
+ * Usage in route tests:
+ *
+ * ```ts
+ * const adapter = new MockOAuthAdapter("mock-google");
+ * adapter.setExchangeResponse({ accessToken: "tok", ... });
+ * const registry = oauthAdapterRegistry(adapter);
+ * defineOAuthRoutes(app, { service, provider, adapters: registry });
+ * ```
+ */
+export class MockOAuthAdapter implements OAuthAdapter {
+  readonly providerCode: string;
+
+  /** Each call to `buildAuthorizationUrl` is captured here. */
+  authUrlCalls: Array<{
+    credentials: OAuthClientCredentials;
+    opts: AuthUrlOptions;
+  }> = [];
+  exchangeCalls: Array<{
+    code: string;
+    credentials: OAuthClientCredentials;
+    opts?: ExchangeCodeOptions;
+  }> = [];
+  refreshCalls: Array<{
+    refreshToken: string;
+    credentials: OAuthClientCredentials;
+  }> = [];
+  revokeCalls: Array<{
+    accessToken: string;
+    credentials: OAuthClientCredentials;
+  }> = [];
+
+  private exchangeResponse: TokenResponse = {
+    accessToken: "mock-access",
+    refreshToken: "mock-refresh",
+    expiresAt: new Date(Date.now() + 3_600_000),
+    scope: "openid",
+    tokenType: "Bearer",
+    metadata: { source: "mock" },
+  };
+
+  private refreshResponse: TokenResponse = {
+    accessToken: "mock-access-refreshed",
+    refreshToken: "mock-refresh",
+    expiresAt: new Date(Date.now() + 3_600_000),
+    scope: "openid",
+    tokenType: "Bearer",
+    metadata: { source: "mock-refresh" },
+  };
+
+  private providerAccountId = "mock-provider-account-1";
+
+  /** Set in tests to make the next exchange/refresh throw. */
+  private exchangeError: Error | undefined;
+  private refreshError: Error | undefined;
+
+  constructor(providerCode = "mock") {
+    this.providerCode = providerCode;
+  }
+
+  buildAuthorizationUrl(credentials: OAuthClientCredentials, opts: AuthUrlOptions): string {
+    this.authUrlCalls.push({ credentials, opts });
+    const params = new URLSearchParams({
+      client_id: credentials.clientId,
+      redirect_uri: credentials.redirectUri,
+      response_type: "code",
+      scope: opts.scopes.join(" "),
+      state: opts.state,
+    });
+    return `https://mock.example.test/authorize?${params.toString()}`;
+  }
+
+  async exchangeCodeForTokens(
+    code: string,
+    credentials: OAuthClientCredentials,
+    opts: ExchangeCodeOptions = {},
+  ): Promise<TokenResponse> {
+    this.exchangeCalls.push({ code, credentials, opts });
+    if (this.exchangeError) throw this.exchangeError;
+    return this.exchangeResponse;
+  }
+
+  async refreshTokens(
+    refreshToken: string,
+    credentials: OAuthClientCredentials,
+  ): Promise<TokenResponse> {
+    this.refreshCalls.push({ refreshToken, credentials });
+    if (this.refreshError) throw this.refreshError;
+    return this.refreshResponse;
+  }
+
+  async getProviderAccountId(): Promise<string> {
+    return this.providerAccountId;
+  }
+
+  async revokeAccess(accessToken: string, credentials: OAuthClientCredentials): Promise<void> {
+    this.revokeCalls.push({ accessToken, credentials });
+  }
+
+  // ─── Test-only setters ────────────────────────────────────────────
+
+  setExchangeResponse(response: TokenResponse): this {
+    this.exchangeResponse = response;
+    return this;
+  }
+
+  setRefreshResponse(response: TokenResponse): this {
+    this.refreshResponse = response;
+    return this;
+  }
+
+  setProviderAccountId(id: string): this {
+    this.providerAccountId = id;
+    return this;
+  }
+
+  failNextExchange(err: Error): this {
+    this.exchangeError = err;
+    return this;
+  }
+
+  failNextRefresh(err: Error): this {
+    this.refreshError = err;
+    return this;
+  }
+}

package/lib/modules/oauth/adapters/OAuthAdapter.ts

@@ -0,0 +1,211 @@
+/**
+ * v4 OAuth provider adapter contract.
+ *
+ * Provider-specific quirks (Google's `prompt=consent` to force refresh-
+ * token reissue, Microsoft's tenant-aware authority URL, Gmail's
+ * scope-narrowing helpers) live behind concrete adapter implementations;
+ * the framework only sees this interface.
+ *
+ * Adapters MUST:
+ *   - Build a provider-compatible authorization URL with the supplied
+ *     `state` opaque (the framework signs / verifies state — adapters
+ *     just round-trip the string).
+ *   - Exchange an authorization code for tokens using only the standard
+ *     `OAuthClientCredentials` shape — no globals, no env reads.
+ *   - Refresh tokens via the provider's documented refresh-token flow.
+ *   - Return a `TokenResponse` that maps cleanly to the schema columns:
+ *     `accessToken`, `refreshToken?`, `expiresAt?`, `scope?`,
+ *     `tokenType?`, `metadata?`. Provider extras land in `metadata`.
+ *   - Throw `OAuthAdapterError` (subclassed appropriately) on
+ *     translation failures so the routes layer can map to AppError /
+ *     status codes consistently.
+ *
+ * Adapters SHOULD:
+ *   - Accept an injected `fetch` in their constructor so tests can
+ *     swap it without monkey-patching globals.
+ *   - Be fetch-based when possible — no axios / SDK requirements when
+ *     the OAuth flow is plain HTTP. SDK-backed adapters (e.g.
+ *     `googleapis`) declare the SDK as an optional dep so consumers
+ *     who don't use those adapters don't pay for them.
+ *
+ * The interface deliberately differs from v3's
+ * `IOAuthProviderAdapter` in two ways:
+ *   - State is an opaque string the framework owns end-to-end (signs +
+ *     verifies + binds to user). v3 had adapters JSON-encode `userId`
+ *     into state, mixing concerns; v4 keeps state opaque.
+ *   - `userId: bigint` parameter is gone. The framework holds the user
+ *     identity; adapters never see it. That's a security property —
+ *     v3's adapters could in principle leak userId into provider
+ *     telemetry by encoding it into URLs they construct.
+ */
+
+export interface OAuthClientCredentials {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}
+
+export interface AuthUrlOptions {
+  /**
+   * The signed/opaque state the framework gives the adapter to embed
+   * in the URL. Passed back to the framework on the callback for
+   * verification — adapters never inspect it.
+   */
+  state: string;
+  /** OAuth scopes to request. Provider-specific values. */
+  scopes: readonly string[];
+  /**
+   * Provider-specific extras the cross-provider surface doesn't
+   * model (`access_type: "offline"`, `prompt: "consent"`, Microsoft
+   * `tenant`, …). Adapters may consult this freely.
+   */
+  providerOptions?: Record<string, unknown>;
+  /**
+   * PKCE code-challenge — the SHA-256 hash of the framework-generated
+   * code-verifier, base64url-encoded. When supplied, the adapter
+   * emits `code_challenge` + `code_challenge_method` on the
+   * authorization URL.
+   *
+   * The framework's routes layer generates the verifier, computes
+   * the challenge, signs the verifier into state, and passes the
+   * challenge here. Adapters never see the verifier on this call.
+   * The verifier comes back later via `exchangeCodeForTokens`'s
+   * `opts.codeVerifier`.
+   *
+   * Server-side flows are confidential clients, so PKCE is
+   * defense-in-depth — defends against the (rare) case where the
+   * authorization code is intercepted but the client_secret isn't.
+   * OAuth 2.1 makes PKCE mandatory; the framework's posture matches.
+   */
+  codeChallenge?: string;
+  /** PKCE challenge method. Default `"S256"`; only S256 is recommended. */
+  codeChallengeMethod?: "S256" | "plain";
+}
+
+/**
+ * Per-call options for `exchangeCodeForTokens` / `refreshTokens`.
+ * `codeVerifier` is the PKCE counterpart to `AuthUrlOptions.codeChallenge` —
+ * the framework's routes layer recovers it from the signed state on
+ * callback and passes it here.
+ */
+export interface ExchangeCodeOptions {
+  /** Abort the upstream HTTP call. */
+  signal?: AbortSignal;
+  /**
+   * PKCE verifier (the raw secret the framework generated alongside
+   * the challenge). Passed verbatim into the provider's token-
+   * exchange body as `code_verifier`. Adapters that don't support
+   * PKCE (or providers that ignore the field) simply forward it.
+   */
+  codeVerifier?: string;
+}
+
+export interface TokenResponse {
+  accessToken: string;
+  refreshToken?: string;
+  /** Computed expiry instant — adapters convert provider `expires_in` seconds. */
+  expiresAt?: Date;
+  scope?: string;
+  /** Typically `"Bearer"`; some providers omit. */
+  tokenType?: string;
+  /**
+   * Provider-specific extras (e.g. Google `id_token`, Microsoft
+   * `tenant_id`, full SDK response object) that don't fit the
+   * cross-provider columns. The schema's `metadata` jsonb column
+   * stores this verbatim.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+export interface OAuthAdapter {
+  /** Stable provider identifier. Matches the `providerCode` column. */
+  readonly providerCode: string;
+
+  /**
+   * Build the provider's authorization URL. Pure / synchronous —
+   * adapter callers (the routes layer) do `Response.redirect(url)`
+   * themselves.
+   */
+  buildAuthorizationUrl(credentials: OAuthClientCredentials, opts: AuthUrlOptions): string;
+
+  /** Exchange the authorization code for an initial token pair. */
+  exchangeCodeForTokens(
+    code: string,
+    credentials: OAuthClientCredentials,
+    opts?: ExchangeCodeOptions,
+  ): Promise<TokenResponse>;
+
+  /** Use the refresh token to mint a new access token. */
+  refreshTokens(
+    refreshToken: string,
+    credentials: OAuthClientCredentials,
+    opts?: { signal?: AbortSignal },
+  ): Promise<TokenResponse>;
+
+  /**
+   * Resolve the upstream provider's stable subject identifier from a
+   * `TokenResponse`. Used to populate `provider_account_id` on the
+   * connection row — lets a re-auth match an existing row instead of
+   * creating a duplicate when the provider changes the access token
+   * but keeps the same user.
+   */
+  getProviderAccountId(
+    tokens: TokenResponse,
+    credentials: OAuthClientCredentials,
+    opts?: { signal?: AbortSignal },
+  ): Promise<string>;
+
+  /**
+   * Optional revoke-access endpoint call. Best-effort; routes layer
+   * still nulls the local row even if upstream revoke fails.
+   */
+  revokeAccess?(
+    accessToken: string,
+    credentials: OAuthClientCredentials,
+    opts?: { signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────
+
+export class OAuthAdapterError extends Error {
+  constructor(
+    public readonly providerCode: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "OAuthAdapterError";
+  }
+}
+
+export class TokenExchangeError extends OAuthAdapterError {
+  constructor(providerCode: string, message: string) {
+    super(providerCode, message);
+    this.name = "TokenExchangeError";
+  }
+}
+
+export class TokenRefreshError extends OAuthAdapterError {
+  constructor(providerCode: string, message: string) {
+    super(providerCode, message);
+    this.name = "TokenRefreshError";
+  }
+}
+
+export class InvalidCredentialsError extends OAuthAdapterError {
+  constructor(providerCode: string, message: string) {
+    super(providerCode, message);
+    this.name = "InvalidCredentialsError";
+  }
+}
+
+export class OAuthRateLimitError extends OAuthAdapterError {
+  constructor(
+    providerCode: string,
+    message: string,
+    public readonly retryAfterSeconds?: number,
+  ) {
+    super(providerCode, message);
+    this.name = "OAuthRateLimitError";
+  }
+}

package/lib/modules/oauth/adapters/OAuthAdapterRegistry.ts

@@ -0,0 +1,77 @@
+import type { OAuthAdapter } from "./OAuthAdapter.js";
+
+/**
+ * Registry of `OAuthAdapter`s keyed by `providerCode`. The routes
+ * layer does `registry.get(providerCode)` to dispatch each request
+ * to the right provider implementation.
+ *
+ * Replaces v3's `AdapterRegistry` static-class pattern with an
+ * instance-based registry — lets consumers compose multiple registries
+ * (e.g., a per-tenant subset of providers) and lets tests construct a
+ * registry with a single mock adapter without touching globals.
+ *
+ * Why instance-based: v3's `AdapterRegistry` was a static class with a
+ * hard-coded `ADAPTER_MAP`, which meant adding a provider required
+ * editing the framework. v4 pushes the choice of which providers a
+ * consumer supports out to the consumer's bootstrap code:
+ *
+ * ```ts
+ * const registry = new OAuthAdapterRegistry()
+ *   .register(new GoogleOAuthAdapter())
+ *   .register(new MicrosoftOAuthAdapter());
+ *
+ * defineOAuthRoutes(app, { service, provider, adapters: registry });
+ * ```
+ */
+export class OAuthAdapterRegistry {
+  private readonly adapters = new Map<string, OAuthAdapter>();
+
+  /** Add an adapter. Chainable. Throws on duplicate `providerCode`. */
+  register(adapter: OAuthAdapter): this {
+    if (this.adapters.has(adapter.providerCode)) {
+      throw new Error(
+        `OAuthAdapterRegistry: duplicate adapter for provider "${adapter.providerCode}"`,
+      );
+    }
+    this.adapters.set(adapter.providerCode, adapter);
+    return this;
+  }
+
+  /** Look up an adapter, returns `undefined` when not registered. */
+  get(providerCode: string): OAuthAdapter | undefined {
+    return this.adapters.get(providerCode);
+  }
+
+  /**
+   * Look up an adapter, throws when not registered. Use from routes
+   * layer when the request is parameterized on a provider that
+   * `mustExist` semantically.
+   */
+  require(providerCode: string): OAuthAdapter {
+    const adapter = this.adapters.get(providerCode);
+    if (!adapter) {
+      throw new Error(
+        `No OAuth adapter registered for provider "${providerCode}". Registered: ${this.providerCodes().join(", ") || "(none)"}.`,
+      );
+    }
+    return adapter;
+  }
+
+  has(providerCode: string): boolean {
+    return this.adapters.has(providerCode);
+  }
+
+  providerCodes(): string[] {
+    return [...this.adapters.keys()];
+  }
+
+  size(): number {
+    return this.adapters.size;
+  }
+}
+
+export function oauthAdapterRegistry(...adapters: OAuthAdapter[]): OAuthAdapterRegistry {
+  const registry = new OAuthAdapterRegistry();
+  for (const a of adapters) registry.register(a);
+  return registry;
+}

package/lib/modules/oauth/adapters/OutlookOAuthAdapter.ts

@@ -0,0 +1,38 @@
+import {
+  MicrosoftOAuthAdapter,
+  type MicrosoftOAuthAdapterOptions,
+} from "./MicrosoftOAuthAdapter.js";
+
+/**
+ * Outlook-flavored Microsoft OAuth adapter — convenience subclass
+ * that pre-fills `providerCode: "outlook"`.
+ *
+ * Same OAuth 2.0 flow as `MicrosoftOAuthAdapter` (Outlook uses the
+ * same Azure AD v2.0 endpoints; Outlook/Mail-specific scopes like
+ * `https://graph.microsoft.com/Mail.Read` are caller-supplied via
+ * `AuthUrlOptions.scopes`, not adapter-specific).
+ *
+ * Why a separate class instead of a runtime tag: connection rows
+ * carry `providerCode` as the cross-table key, and consumers
+ * frequently want Outlook-scoped connections to live alongside
+ * generic Microsoft sign-in connections without colliding on the
+ * unique (account_id, provider_code) composite. Registering both
+ * `MicrosoftOAuthAdapter` (`"microsoft"`) and `OutlookOAuthAdapter`
+ * (`"outlook"`) in the same registry gives consumers two distinct
+ * provider rows per account.
+ *
+ * Usage:
+ *
+ *   const adapters = oauthAdapterRegistry(
+ *     new MicrosoftOAuthAdapter(),
+ *     new OutlookOAuthAdapter(),
+ *   );
+ *
+ * All other options forward to the underlying `MicrosoftOAuthAdapter`
+ * (tenant, fetchImpl, …).
+ */
+export class OutlookOAuthAdapter extends MicrosoftOAuthAdapter {
+  constructor(opts: Omit<MicrosoftOAuthAdapterOptions, "providerCode"> = {}) {
+    super({ ...opts, providerCode: "outlook" });
+  }
+}

package/lib/modules/oauth/index.ts

@@ -0,0 +1,79 @@
+/**
+ * OAuth module — public barrel.
+ *
+ * Multi-step OAuth flow with pluggable provider adapters
+ * (Google / Microsoft / Gmail / Outlook), state signing, and
+ * connection persistence. Wired via `defineOAuthRoutes(app, deps)`.
+ */
+
+export { GmailOAuthAdapter } from "./adapters/GmailOAuthAdapter.js";
+export {
+  GoogleOAuthAdapter,
+  type GoogleOAuthAdapterOptions,
+} from "./adapters/GoogleOAuthAdapter.js";
+export {
+  MicrosoftOAuthAdapter,
+  type MicrosoftOAuthAdapterOptions,
+} from "./adapters/MicrosoftOAuthAdapter.js";
+export { MockOAuthAdapter } from "./adapters/MockOAuthAdapter.js";
+export {
+  type AuthUrlOptions,
+  InvalidCredentialsError,
+  type OAuthAdapter,
+  OAuthAdapterError,
+  type OAuthClientCredentials,
+  OAuthRateLimitError,
+  TokenExchangeError,
+  TokenRefreshError,
+  type TokenResponse,
+} from "./adapters/OAuthAdapter.js";
+export { OAuthAdapterRegistry, oauthAdapterRegistry } from "./adapters/OAuthAdapterRegistry.js";
+export { OutlookOAuthAdapter } from "./adapters/OutlookOAuthAdapter.js";
+export {
+  OAUTH_PERMISSION_DEFINITIONS,
+  OAUTH_PERMISSIONS,
+  type OAuthPermission,
+} from "./permissions.js";
+export {
+  buildOAuthApp,
+  defineOAuthRoutes,
+  type OAuthCredentialsResolver,
+  type OAuthRoutesDeps,
+  validateReturnTo,
+} from "./routes.js";
+export {
+  authorizationHeader,
+  isActive,
+  isExpired,
+  isExpiringSoon,
+  type NewOAuthConnection,
+  needsRefresh,
+  type OAuthConnection,
+  oauthConnections,
+  oauthConnectionsRelations,
+} from "./schema.js";
+export { OAuthConnectionService } from "./services/OAuthConnectionService.js";
+export {
+  InvalidStateError,
+  type SignStateOptions,
+  type StatePayload,
+  type StateSecret,
+  signState,
+  type VerifyStateOptions,
+  verifyState,
+} from "./state.js";
+
+/**
+ * OAuth state replay defense (F16). Default in-memory cache ships
+ * with the framework; consumers running behind a load balancer
+ * implement `StateJtiCache` against shared storage (e.g. Redis) and
+ * pass it via `OAuthRoutesDeps.stateJtiCache`.
+ */
+export { InMemoryStateJtiCache, type StateJtiCache } from "./stateJtiCache.js";
+/**
+ * `@internal` OIDC id_token verifier (F13). No adapter currently
+ * consumes id_token as an identity decision; this helper exists so
+ * any future code path that does MUST route through it (signature +
+ * iss/aud/exp + nonce echo against framework-signed state).
+ */
+export { type VerifyIdTokenOptions, verifyIdToken } from "./verifyIdToken.js";

package/lib/modules/oauth/module.json

@@ -0,0 +1,23 @@
+{
+  "name": "oauth",
+  "description": "OAuth 2.0 authentication on the v4 substrate — pluggable provider adapters, Drizzle-backed token storage, Hono routes. State lives in the URL `state` param; tokens persist in DB; no express-session.",
+  "version": "2.0.0-alpha.1",
+  "dependencies": ["accounts"],
+  "npmDependencies": {},
+  "requiredEnvVars": [],
+  "optionalEnvVars": [
+    "OAUTH_GOOGLE_CLIENT_ID",
+    "OAUTH_GOOGLE_CLIENT_SECRET",
+    "OAUTH_GMAIL_REDIRECT_URI",
+    "OAUTH_GOOGLE_CONTACTS_REDIRECT_URI",
+    "OAUTH_MICROSOFT_CLIENT_ID",
+    "OAUTH_MICROSOFT_CLIENT_SECRET",
+    "OAUTH_OUTLOOK_REDIRECT_URI"
+  ],
+  "postInstall": [
+    "Add the schema to your composed schema: `createApp({ schema: { ...accountsSchema, oauthConnections, oauthConnectionsRelations } })`",
+    "Wire the routes: `defineOAuthRoutes(app, { service, provider, adapters })`",
+    "Configure OAuth credentials in .env for the providers you support",
+    "Generate the migration: `npm run db:generate`"
+  ]
+}

package/lib/modules/oauth/permissions.ts

@@ -0,0 +1,39 @@
+/**
+ * Permission slugs for the oauth module.
+ *
+ * v3 enforced authorization via @HasPermission decorators on controller
+ * methods; v4 enforces it via `requirePermission(slug)` middleware at
+ * the route. The permission rows themselves are seeded by the consuming
+ * app.
+ */
+
+import type { PermissionDefinition } from "@sixthsummit/ship-api";
+
+export const OAUTH_PERMISSIONS = {
+  /** View one's own connections (typical scope for end-user-facing endpoints). */
+  readSelf: "oauth:connections:read-self",
+  /** View any connection (admin-style; for support/audit UIs). */
+  readAny: "oauth:connections:read-any",
+  /** Initiate a new OAuth connection on one's own account. */
+  connect: "oauth:connections:connect",
+  /** Revoke / disconnect a connection. */
+  disconnect: "oauth:connections:disconnect",
+  /** Force-refresh an access token. */
+  refresh: "oauth:connections:refresh",
+} as const;
+
+export type OAuthPermission = (typeof OAUTH_PERMISSIONS)[keyof typeof OAUTH_PERMISSIONS];
+
+export const OAUTH_PERMISSION_DEFINITIONS = [
+  {
+    slug: OAUTH_PERMISSIONS.readSelf,
+    label: "View Own OAuth Connections",
+  },
+  {
+    slug: OAUTH_PERMISSIONS.readAny,
+    label: "View Any OAuth Connection (Admin)",
+  },
+  { slug: OAUTH_PERMISSIONS.connect, label: "Initiate OAuth Connection" },
+  { slug: OAUTH_PERMISSIONS.disconnect, label: "Disconnect OAuth Provider" },
+  { slug: OAUTH_PERMISSIONS.refresh, label: "Force-Refresh OAuth Token" },
+] as const satisfies readonly PermissionDefinition[];