@pattern-stack/codegen 0.6.4 → 0.6.5

package/runtime/subsystems/auth/protocols/integration-store.ts

@@ -64,3 +64,40 @@ export interface IntegrationTokenUpdate {
 export interface IIntegrationTokenWriter {
   persistRefresh(update: IntegrationTokenUpdate): Promise<void>;
 }
+
+/**
+ * Grant-sink port — persists a freshly-minted OAuth2 grant from the
+ * authorize-code callback (i.e. the user just connected a new provider, or
+ * re-connected an existing one).
+ *
+ * `AuthController.callback` invokes this after `ProviderStrategy.exchangeCodeForTokens`.
+ * The subsystem itself never imports a concrete `IntegrationsService` — the
+ * consumer's `auth-integrations` starter (or any equivalent) adapts this
+ * port. Keeps the auth subsystem standalone: a non-codegen consumer can
+ * satisfy the port against its own integrations storage.
+ *
+ * Semantics:
+ *   - Upserts on `(userId, provider)`. Repeated grants for the same pair
+ *     replace the prior tokens (re-connect flow).
+ *   - Implementations are responsible for encrypting tokens at rest.
+ *   - `expiresAt` / `refreshToken` / `scope` / `externalAccountId` /
+ *     `providerMetadata` are optional because not every provider supplies
+ *     them (e.g. some providers omit `expires_in`; not every flow returns
+ *     a refresh token on first grant).
+ */
+export interface IntegrationGrantInput {
+  userId: string;
+  /** Provider slug — must match the strategy's `provider`. */
+  provider: string;
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: Date;
+  scope?: string[];
+  externalAccountId?: string;
+  /** Provider-specific bag (SFDC `instance_url`, Google `sub`, …). */
+  providerMetadata?: Record<string, unknown>;
+}
+
+export interface IIntegrationGrantSink {
+  createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void>;
+}

package/runtime/subsystems/auth/protocols/oauth-state-store.ts

@@ -2,15 +2,47 @@
  * Auth subsystem — `IOAuthStateStore` port.
  *
  * CSRF protection for the OAuth2 authorize-code callback. Generic across
- * providers. Concrete backends live under `../backends/oauth-state-store/`.
+ * providers. The store mints opaque state tokens at /connect time and
+ * single-use consumes them at /callback time, returning the original
+ * record (userId + optional post-callback redirect path).
+ *
+ * Concrete backends live under `../backends/`:
+ *   - `state-store.memory-backend.ts` — in-process Map (tests/dev).
+ *   - `state-store.drizzle-backend.ts` — Postgres (prod).
+ *
+ * Semantics:
+ *   - `generate(record)` → returns an opaque state token; record is stored
+ *     under that token until consumed or until TTL expires.
+ *   - `consume(state)`   → atomically deletes the entry and returns the
+ *     record. Throws on missing, expired, or replayed state. Never returns
+ *     null — a missing/expired state is a CSRF signal.
  */
-export interface OAuthStateEntry {
+export interface OAuthStateRecord {
   userId: string;
-  createdAt: Date;
+  /** Optional post-callback redirect path (relative URL). */
+  redirect?: string;
 }
 
 export interface IOAuthStateStore {
-  put(state: string, entry: OAuthStateEntry): Promise<void>;
-  /** Single-use consume: returns entry if present + valid, deletes it. */
-  consume(state: string): Promise<OAuthStateEntry | null>;
+  /** Mint an opaque state token bound to `record`. Single-use. */
+  generate(record: OAuthStateRecord): Promise<string>;
+  /**
+   * Atomically consume `state`, returning the bound record. Throws on
+   * missing / expired / replayed state.
+   */
+  consume(state: string): Promise<OAuthStateRecord>;
+}
+
+/**
+ * Thrown by `IOAuthStateStore.consume` when the state token is unknown,
+ * expired, or has already been consumed (replay attempt).
+ */
+export class OAuthStateError extends Error {
+  constructor(
+    message: string,
+    public readonly reason: 'missing' | 'expired',
+  ) {
+    super(message);
+    this.name = 'OAuthStateError';
+  }
 }

package/runtime/subsystems/auth/protocols/provider-strategy.ts

@@ -0,0 +1,41 @@
+/**
+ * Auth subsystem — `ProviderStrategy` contract.
+ *
+ * Extension of `OAuth2RefreshStrategy` (which already covers the refresh
+ * path) that adds the two methods needed by the connect/callback dance:
+ *
+ *   - `buildAuthorizeUrl({ state, redirectUri })` → consent-page URL.
+ *   - `exchangeCodeForTokens({ code, redirectUri })` → tokens after consent.
+ *
+ * Concrete per-provider strategies (HubSpot, SFDC, Google, Gong, Fathom, …)
+ * stay consumer-side per ADR-031 ("every app has different combinations").
+ * They typically subclass `OAuth2RefreshStrategy` for the refresh path and
+ * implement these two methods structurally — that satisfies
+ * `ProviderStrategy` because TS lets interfaces extend classes by type.
+ *
+ * AuthController never imports a concrete strategy — it injects the
+ * `STRATEGY_REGISTRY` (a `ReadonlyMap<provider-slug, ProviderStrategy>`)
+ * and dispatches by slug.
+ */
+import type { OAuth2RefreshStrategy } from '../runtime/oauth2-refresh.strategy';
+
+export interface ExchangedTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: Date;
+  scope?: string[];
+  externalAccountId?: string;
+  /** Provider-specific bag (SFDC `instance_url`, Google `sub`, …). */
+  providerMetadata?: Record<string, unknown>;
+}
+
+export interface ProviderStrategy extends OAuth2RefreshStrategy {
+  buildAuthorizeUrl(args: { state: string; redirectUri: string }): string;
+  exchangeCodeForTokens(args: {
+    code: string;
+    redirectUri: string;
+  }): Promise<ExchangedTokens>;
+}
+
+/** The DI value type behind the `STRATEGY_REGISTRY` token. */
+export type ProviderStrategyRegistry = ReadonlyMap<string, ProviderStrategy>;

package/runtime/subsystems/auth/protocols/user-context.ts

@@ -0,0 +1,22 @@
+/**
+ * Auth subsystem — `IUserContext` port.
+ *
+ * Resolves "who is the current user" from a request. The shape is
+ * universal; the implementation is always app-specific:
+ *
+ *   - WorkOS session:   `req.session.user.id`
+ *   - JWT bearer:       `decode(req.headers.authorization).sub`
+ *   - Test fixture:     hardcoded UUID
+ *
+ * The auth subsystem cannot ship a default — every app does auth differently —
+ * but the port is universal, so the contract ships here. Consumers bind a
+ * concrete implementation under the `AUTH_USER_CONTEXT` token in their app
+ * module.
+ *
+ * `req` is typed as `unknown` deliberately: this protocol must not pull a
+ * dependency on `express` / `fastify` / NestJS request types. The concrete
+ * adapter narrows it (e.g. via a `Request` import).
+ */
+export interface IUserContext {
+  getCurrentUserId(req: unknown): Promise<string>;
+}

package/runtime/subsystems/index.ts

@@ -56,14 +56,22 @@ export {
   OAUTH_STATE_STORE,
   AUTH_INTEGRATION_READER,
   AUTH_INTEGRATION_TOKEN_WRITER,
+  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_USER_CONTEXT,
+  STRATEGY_REGISTRY,
+  AUTH_OPTIONS,
   AuthModule,
+  AuthController,
   OAuth2RefreshStrategy,
   withAuthRetry,
   IntegrationBrokenError,
   SessionExpiredError,
   isSessionExpiredError,
+  OAuthStateError,
   EnvEncryptionKey,
-  InMemoryOAuthStateStore,
+  MemoryOAuthStateStore,
+  DrizzleOAuthStateStore,
+  authOAuthState,
 } from './auth';
 export type {
   IAuthStrategy,
@@ -71,10 +79,17 @@ export type {
   IOAuthStateStore,
   IIntegrationReader,
   IIntegrationTokenWriter,
+  IIntegrationGrantSink,
+  IntegrationGrantInput,
+  IUserContext,
+  ProviderStrategy,
+  ProviderStrategyRegistry,
+  ExchangedTokens,
   AuthCredentials,
   AuthResolveOptions,
   DecryptedIntegration,
-  OAuthStateEntry,
+  OAuthStateRecord,
   IntegrationTokenUpdate,
   ParsedRefreshResponse,
+  AuthOAuthState,
 } from './auth';

package/templates/subsystem/auth/app-module-hook.ejs.t

@@ -0,0 +1,21 @@
+---
+to: "<%= appModulePath %>"
+inject: true
+append: true
+skip_if: "AuthModule"
+---
+
+// TODO: Register AuthModule (auth subsystem)
+// Add to AppModule.imports:
+//
+//   import { AuthModule } from '@shared/subsystems/auth';
+//   // ...
+//   AuthModule.forRoot({
+//     encryptionKey: 'env',
+//     oauthStateStore: 'drizzle',
+//     enableController: true,
+//     redirectUriBase: process.env.AUTH_REDIRECT_URI_BASE ?? '<%= redirectUriBase %>',
+//   }),
+//
+// Requires TOKEN_ENCRYPTION_KEY in your environment (see .env.config).
+// Provide an IUserContext adapter (your app's session/JWT scheme).

package/templates/subsystem/auth/auth-oauth-state.schema.ejs.t

@@ -0,0 +1,35 @@
+---
+to: "<%= schemaPath %>"
+force: true
+---
+// Schema barrel append tracked in #284 — same gap as events/jobs/sync today.
+/**
+ * Drizzle schema for the `auth_oauth_state` table — backs the
+ * `DrizzleOAuthStateStore` (`state-store.drizzle-backend.ts`).
+ *
+ * One row per outstanding /connect → /callback dance. Single-use; rows are
+ * deleted on consume. A periodic sweep (or a `WHERE expires_at < now()`
+ * filter on read) clears abandoned rows.
+ *
+ * Columns:
+ *   - `state`       — opaque random token, primary key.
+ *   - `user_id`     — text (matches the consumer-defined user-id shape;
+ *                     the auth subsystem doesn't constrain this to UUID
+ *                     because some apps key users by external id).
+ *   - `redirect`    — optional post-callback redirect path.
+ *   - `expires_at`  — TTL boundary; entries past this are treated as absent.
+ *
+ * Convention: schema files live at the root of the subsystem dir
+ * (mirrors `cache.schema.ts`, `sync-audit.schema.ts`, `domain-events.schema.ts`).
+ */
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+import type { InferSelectModel } from 'drizzle-orm';
+
+export const authOAuthState = pgTable('auth_oauth_state', {
+  state: text('state').primaryKey(),
+  userId: text('user_id').notNull(),
+  redirect: text('redirect'),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+});
+
+export type AuthOAuthState = InferSelectModel<typeof authOAuthState>;

package/templates/subsystem/auth/env-config.ejs.t

@@ -0,0 +1,20 @@
+---
+to: "<%= envConfigPath %>"
+inject: true
+append: true
+skip_if: "TOKEN_ENCRYPTION_KEY"
+---
+
+# OAuth integration token encryption key — 32 bytes base64 (AES-256-GCM).
+# DO NOT REUSE this dev value in prod. To regenerate locally:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+# Re-running `codegen subsystem install auth` does NOT rotate this key —
+# `skip_if: "TOKEN_ENCRYPTION_KEY"` blocks the inject intentionally, because
+# silently rotating would invalidate every encrypted token already in the
+# consumer's `integrations` table. Rotation is a separate, auditable op.
+# In production: store the key in `secrets/secrets.yaml` (or your secret
+# manager) and have your deploy pipeline materialise it into the env at
+# boot — this `.env.config` line should be a placeholder, not the source.
+TOKEN_ENCRYPTION_KEY=<%= tokenEncryptionKey %>
+# Public base URL where OAuth providers redirect back. Override in staging/prod.
+AUTH_REDIRECT_URI_BASE=<%= redirectUriBase %>

package/templates/subsystem/auth/prompt.js

@@ -0,0 +1,46 @@
+/**
+ * Hygen prompt.js — #287 auth subsystem scaffold.
+ *
+ * Locals are resolved by the CLI (src/cli/shared/auth-scaffold-locals.ts)
+ * and forwarded as CLI args. This prompt.js just coerces and forwards;
+ * no interactive prompts.
+ *
+ * Invoked via:
+ *   bunx hygen subsystem auth \
+ *     --appName <string> \
+ *     --configPath <abs> \
+ *     --schemaPath <abs> \
+ *     --appModulePath <abs> \
+ *     --envConfigPath <abs> \
+ *     --redirectUriBase <url> \
+ *     --tokenEncryptionKey <b64-32-bytes>
+ *
+ * The three templates this folder steers:
+ *   - `auth-oauth-state.schema.ejs.t` — emits the `auth_oauth_state`
+ *     drizzle schema (sole emitter; copyRuntime skips the runtime source).
+ *   - `app-module-hook.ejs.t` — appends a TODO comment block to
+ *     app.module.ts directing the human to register
+ *     `AuthModule.forRoot({ ... })`. Same convention as observability.
+ *   - `env-config.ejs.t` — appends `TOKEN_ENCRYPTION_KEY=<b64>` and
+ *     `AUTH_REDIRECT_URI_BASE=<url>` to `.env.config`. Idempotent via
+ *     `skip_if: "TOKEN_ENCRYPTION_KEY"` — re-running install does NOT
+ *     regenerate the key (rotation is a separate operation).
+ *
+ * Auth has NO `multi_tenant` knob (see auth-scaffold-locals.ts docstring).
+ */
+
+export default {
+  prompt: async ({ args }) => {
+    return {
+      appName: args.appName ?? "",
+      configPath: args.configPath ?? "codegen.config.yaml",
+      schemaPath:
+        args.schemaPath ??
+        "src/shared/subsystems/auth/auth-oauth-state.schema.ts",
+      appModulePath: args.appModulePath ?? "src/app.module.ts",
+      envConfigPath: args.envConfigPath ?? ".env.config",
+      redirectUriBase: args.redirectUriBase ?? "http://localhost:3000",
+      tokenEncryptionKey: args.tokenEncryptionKey ?? "",
+    };
+  },
+};

package/templates/subsystem/auth-config/codegen-config-auth-block.ejs.t

@@ -0,0 +1,20 @@
+---
+to: "<%= configPath %>"
+inject: true
+append: true
+skip_if: "auth:"
+---
+
+auth:
+  # ── Encryption key (TOKEN_ENCRYPTION_KEY from .env.config) ──
+  encryption_key: env
+
+  # ── OAuth state store (drizzle for prod, memory for tests) ──
+  oauth_state_store: drizzle
+
+  # ── Public base URL — providers redirect back here ──
+  # Override in staging/prod via AUTH_REDIRECT_URI_BASE env var.
+  redirect_uri_base: http://localhost:3000
+
+  # ── Mount AuthController under /auth/:provider ──
+  enable_controller: true

package/templates/subsystem/auth-config/prompt.js

@@ -0,0 +1,20 @@
+/**
+ * Hygen prompt.js — #287 auth config-block scaffold.
+ *
+ * Split from `templates/subsystem/auth/` so the CLI can invoke the
+ * config-block inject step independently — `subsystem install auth --force`
+ * preserves an existing `auth:` block by skipping this action; pass
+ * `--force-config` to opt into regeneration. Mirrors `events-config` /
+ * `sync-config` / `observability-config` exactly.
+ *
+ * Invoked via:
+ *   bunx hygen subsystem auth-config --configPath <abs>
+ */
+
+export default {
+  prompt: async ({ args }) => {
+    return {
+      configPath: args.configPath ?? "codegen.config.yaml",
+    };
+  },
+};

package/templates/subsystem/auth-integrations/app-module-hook.ejs.t

@@ -0,0 +1,16 @@
+---
+to: "<%= appModulePath %>"
+inject: true
+append: true
+skip_if: "IntegrationsAuthModule"
+---
+
+// TODO: Register IntegrationsAuthModule (vendored from auth-integrations starter)
+// Add to AppModule.imports AFTER AuthModule:
+//
+//   import { IntegrationsAuthModule } from '@shared/integrations/integrations-auth.module';
+//   // ...
+//   IntegrationsAuthModule,
+//
+// Requires AuthModule.forRoot(...) registered first (provides ENCRYPTION_KEY).
+// Run `cdp entity new integration` to scaffold the codegen layer the adapters import.

package/templates/subsystem/auth-integrations/prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Hygen prompt.js — #287 auth-integrations starter scaffold.
+ *
+ * Locals are resolved by the CLI
+ * (src/cli/shared/auth-integrations-scaffold-locals.ts) and forwarded as
+ * CLI args. The vendor copies (runtime/integrations/** + integration.yaml)
+ * happen in subsystem.ts (`runAuthIntegrationsScaffold`); this template
+ * folder only injects the TODO comment block into app.module.ts.
+ *
+ * Invoked via:
+ *   bunx hygen subsystem auth-integrations \
+ *     --appName <string> \
+ *     --appModulePath <abs>
+ */
+
+export default {
+  prompt: async ({ args }) => {
+    return {
+      appName: args.appName ?? "",
+      appModulePath: args.appModulePath ?? "src/app.module.ts",
+    };
+  },
+};

package/dist/runtime/subsystems/auth/backends/oauth-state-store/in-memory.d.ts

@@ -1,24 +0,0 @@
-import { IOAuthStateStore, OAuthStateEntry } from '../../protocols/oauth-state-store.js';
-
-/**
- * In-memory OAuth state store.
- *
- * Single-process dev store. Production deployments need a Redis-backed impl
- * (follow-up) so state survives restarts + is shared across workers.
- */
-
-interface InMemoryOAuthStateStoreOptions {
-    /** TTL in ms. Entries older than this are treated as absent. Default 10min. */
-    ttlMs?: number;
-    now?: () => number;
-}
-declare class InMemoryOAuthStateStore implements IOAuthStateStore {
-    private readonly store;
-    private readonly ttlMs;
-    private readonly now;
-    constructor(opts?: InMemoryOAuthStateStoreOptions);
-    put(state: string, entry: OAuthStateEntry): Promise<void>;
-    consume(state: string): Promise<OAuthStateEntry | null>;
-}
-
-export { InMemoryOAuthStateStore, type InMemoryOAuthStateStoreOptions };

package/dist/runtime/subsystems/auth/backends/oauth-state-store/in-memory.js

@@ -1,24 +0,0 @@
-// runtime/subsystems/auth/backends/oauth-state-store/in-memory.ts
-var InMemoryOAuthStateStore = class {
-  store = /* @__PURE__ */ new Map();
-  ttlMs;
-  now;
-  constructor(opts = {}) {
-    this.ttlMs = opts.ttlMs ?? 10 * 60 * 1e3;
-    this.now = opts.now ?? (() => Date.now());
-  }
-  async put(state, entry) {
-    this.store.set(state, { entry, expiresAt: this.now() + this.ttlMs });
-  }
-  async consume(state) {
-    const slot = this.store.get(state);
-    if (!slot) return null;
-    this.store.delete(state);
-    if (slot.expiresAt <= this.now()) return null;
-    return slot.entry;
-  }
-};
-export {
-  InMemoryOAuthStateStore
-};
-//# sourceMappingURL=in-memory.js.map

package/dist/runtime/subsystems/auth/backends/oauth-state-store/in-memory.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../runtime/subsystems/auth/backends/oauth-state-store/in-memory.ts"],"sourcesContent":["/**\n * In-memory OAuth state store.\n *\n * Single-process dev store. Production deployments need a Redis-backed impl\n * (follow-up) so state survives restarts + is shared across workers.\n */\nimport type {\n  IOAuthStateStore,\n  OAuthStateEntry,\n} from '../../protocols/oauth-state-store';\n\nexport interface InMemoryOAuthStateStoreOptions {\n  /** TTL in ms. Entries older than this are treated as absent. Default 10min. */\n  ttlMs?: number;\n  now?: () => number;\n}\n\nexport class InMemoryOAuthStateStore implements IOAuthStateStore {\n  private readonly store = new Map<\n    string,\n    { entry: OAuthStateEntry; expiresAt: number }\n  >();\n  private readonly ttlMs: number;\n  private readonly now: () => number;\n\n  constructor(opts: InMemoryOAuthStateStoreOptions = {}) {\n    this.ttlMs = opts.ttlMs ?? 10 * 60 * 1000;\n    this.now = opts.now ?? (() => Date.now());\n  }\n\n  async put(state: string, entry: OAuthStateEntry): Promise<void> {\n    this.store.set(state, { entry, expiresAt: this.now() + this.ttlMs });\n  }\n\n  async consume(state: string): Promise<OAuthStateEntry | null> {\n    const slot = this.store.get(state);\n    if (!slot) return null;\n    this.store.delete(state);\n    if (slot.expiresAt <= this.now()) return null;\n    return slot.entry;\n  }\n}\n"],"mappings":";AAiBO,IAAM,0BAAN,MAA0D;AAAA,EAC9C,QAAQ,oBAAI,IAG3B;AAAA,EACe;AAAA,EACA;AAAA,EAEjB,YAAY,OAAuC,CAAC,GAAG;AACrD,SAAK,QAAQ,KAAK,SAAS,KAAK,KAAK;AACrC,SAAK,MAAM,KAAK,QAAQ,MAAM,KAAK,IAAI;AAAA,EACzC;AAAA,EAEA,MAAM,IAAI,OAAe,OAAuC;AAC9D,SAAK,MAAM,IAAI,OAAO,EAAE,OAAO,WAAW,KAAK,IAAI,IAAI,KAAK,MAAM,CAAC;AAAA,EACrE;AAAA,EAEA,MAAM,QAAQ,OAAgD;AAC5D,UAAM,OAAO,KAAK,MAAM,IAAI,KAAK;AACjC,QAAI,CAAC,KAAM,QAAO;AAClB,SAAK,MAAM,OAAO,KAAK;AACvB,QAAI,KAAK,aAAa,KAAK,IAAI,EAAG,QAAO;AACzC,WAAO,KAAK;AAAA,EACd;AACF;","names":[]}

package/runtime/subsystems/auth/backends/oauth-state-store/in-memory.ts

@@ -1,42 +0,0 @@
-/**
- * In-memory OAuth state store.
- *
- * Single-process dev store. Production deployments need a Redis-backed impl
- * (follow-up) so state survives restarts + is shared across workers.
- */
-import type {
-  IOAuthStateStore,
-  OAuthStateEntry,
-} from '../../protocols/oauth-state-store';
-
-export interface InMemoryOAuthStateStoreOptions {
-  /** TTL in ms. Entries older than this are treated as absent. Default 10min. */
-  ttlMs?: number;
-  now?: () => number;
-}
-
-export class InMemoryOAuthStateStore implements IOAuthStateStore {
-  private readonly store = new Map<
-    string,
-    { entry: OAuthStateEntry; expiresAt: number }
-  >();
-  private readonly ttlMs: number;
-  private readonly now: () => number;
-
-  constructor(opts: InMemoryOAuthStateStoreOptions = {}) {
-    this.ttlMs = opts.ttlMs ?? 10 * 60 * 1000;
-    this.now = opts.now ?? (() => Date.now());
-  }
-
-  async put(state: string, entry: OAuthStateEntry): Promise<void> {
-    this.store.set(state, { entry, expiresAt: this.now() + this.ttlMs });
-  }
-
-  async consume(state: string): Promise<OAuthStateEntry | null> {
-    const slot = this.store.get(state);
-    if (!slot) return null;
-    this.store.delete(state);
-    if (slot.expiresAt <= this.now()) return null;
-    return slot.entry;
-  }
-}