@pattern-stack/codegen 0.6.4 → 0.6.6

package/runtime/subsystems/auth/index.ts

@@ -6,19 +6,32 @@
  * ```typescript
  * import {
  *   AuthModule,
+ *   AuthController,
  *   ENCRYPTION_KEY,
  *   OAUTH_STATE_STORE,
  *   AUTH_INTEGRATION_READER,
  *   AUTH_INTEGRATION_TOKEN_WRITER,
+ *   AUTH_INTEGRATION_GRANT_SINK,
+ *   AUTH_USER_CONTEXT,
+ *   STRATEGY_REGISTRY,
+ *   AUTH_OPTIONS,
  *   OAuth2RefreshStrategy,
  *   withAuthRetry,
  *   IntegrationBrokenError,
  *   SessionExpiredError,
+ *   OAuthStateError,
  *   type IAuthStrategy,
  *   type IEncryptionKey,
  *   type IOAuthStateStore,
+ *   type OAuthStateRecord,
  *   type IIntegrationReader,
  *   type IIntegrationTokenWriter,
+ *   type IIntegrationGrantSink,
+ *   type IntegrationGrantInput,
+ *   type IUserContext,
+ *   type IProviderStrategy,
+ *   type ProviderStrategyRegistry,
+ *   type ExchangedTokens,
  * } from '@pattern-stack/codegen/runtime/subsystems/auth';
  * ```
  */
@@ -32,14 +45,23 @@ export type {
 export type { IEncryptionKey } from './protocols/encryption-key';
 export type {
   IOAuthStateStore,
-  OAuthStateEntry,
+  OAuthStateRecord,
 } from './protocols/oauth-state-store';
+export { OAuthStateError } from './protocols/oauth-state-store';
 export type {
   DecryptedIntegration,
   IIntegrationReader,
   IIntegrationTokenWriter,
   IntegrationTokenUpdate,
+  IIntegrationGrantSink,
+  IntegrationGrantInput,
 } from './protocols/integration-store';
+export type { IUserContext } from './protocols/user-context';
+export type {
+  IProviderStrategy,
+  ProviderStrategyRegistry,
+  ExchangedTokens,
+} from './protocols/provider-strategy';
 
 // Tokens
 export {
@@ -47,6 +69,10 @@ export {
   OAUTH_STATE_STORE,
   AUTH_INTEGRATION_READER,
   AUTH_INTEGRATION_TOKEN_WRITER,
+  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_USER_CONTEXT,
+  STRATEGY_REGISTRY,
+  AUTH_OPTIONS,
 } from './auth.tokens';
 
 // Runtime
@@ -63,15 +89,28 @@ export {
   isSessionExpiredError,
 } from './runtime/session-expired.error';
 
+// Schema (drizzle backend)
+export {
+  authOAuthState,
+  type AuthOAuthState,
+} from './auth-oauth-state.schema';
+
 // Backends
 export {
   EnvEncryptionKey,
   type EnvEncryptionKeyOptions,
 } from './backends/encryption-key/env';
 export {
-  InMemoryOAuthStateStore,
-  type InMemoryOAuthStateStoreOptions,
-} from './backends/oauth-state-store/in-memory';
+  MemoryOAuthStateStore,
+  type MemoryOAuthStateStoreOptions,
+} from './backends/state-store.memory-backend';
+export {
+  DrizzleOAuthStateStore,
+  type DrizzleOAuthStateStoreOptions,
+} from './backends/state-store.drizzle-backend';
+
+// Controller
+export { AuthController } from './controllers/auth.controller';
 
 // Module
 export { AuthModule, type AuthModuleOptions } from './auth.module';

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

@@ -7,7 +7,7 @@
  * `OAuth2RefreshStrategy` template-method base in `../runtime/`.
  *
  * See `docs/adrs/ADR-031-auth-subsystem.md` and
- * `docs/gate-1-auth-extraction-findings.md` (inbound from dealbrain-v2) for
+ * `docs/gate-1-auth-extraction-findings.md` (extraction-source findings) for
  * the rationale.
  */
 

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

@@ -6,7 +6,7 @@
  * those rows — consumers implement these narrow ports against whatever
  * `integrations` table their app uses.
  *
- * In dealbrain-v2 (the extraction source) both ports are satisfied by a
+ * In the extraction-source app both ports are satisfied by a
  * pair of thin adapters over `IntegrationService` + `RefreshIntegrationUseCase`.
  * The codegen-patterns `examples/auth-integrations/` starter (separate PR)
  * ships a canonical `integration.yaml` whose generated service + use case
@@ -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 `IProviderStrategy.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,48 @@
+/**
+ * Auth subsystem — `IProviderStrategy` 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
+ * `IProviderStrategy` because TS lets interfaces extend classes by type.
+ *
+ * AuthController never imports a concrete strategy — it injects the
+ * `STRATEGY_REGISTRY` (a `ReadonlyMap<provider-slug, IProviderStrategy>`)
+ * and dispatches by slug.
+ *
+ * **Naming convention:** interfaces that describe behavioral ports use the
+ * `I` prefix (`IProviderStrategy`, `IIntegrationReader`, `IUserContext`,
+ * `IOAuthStateStore`, `IEncryptionKey`). Plain data types / DTOs (e.g.
+ * `ExchangedTokens`, `DecryptedIntegration`, `IntegrationGrantInput`) do
+ * not. Abstract template-method classes (e.g. `OAuth2RefreshStrategy`) also
+ * do not — the `I` is for interfaces only.
+ */
+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 IProviderStrategy 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, IProviderStrategy>;

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/auth/runtime/oauth2-refresh.strategy.ts

@@ -2,8 +2,8 @@
  * Abstract base class for OAuth2 refresh-token strategies.
  *
  * Template-method pattern: `resolve()` is concrete; four small hooks inject
- * provider specifics. Validated across two providers in dealbrain-v2
- * (SalesforceAuthStrategy, HubSpotAuthStrategy) before extraction here — see
+ * provider specifics. Validated across two providers (Salesforce, HubSpot)
+ * in the extraction-source app before being extracted here — see
  * `docs/gate-1-auth-extraction-findings.md` for the "build first, extract
  * later" evidence.
  *

package/runtime/subsystems/auth/runtime/session-expired.error.ts

@@ -8,8 +8,8 @@
  * the `isSessionExpiredError` predicate to decide whether to force-refresh
  * and retry once.
  *
- * This discriminator replaces the SFDC-only `instanceof` check from
- * dealbrain-v2's original `withAuthRetry`. See
+ * This discriminator replaces the SFDC-only `instanceof` check from the
+ * extraction-source app's original `withAuthRetry`. See
  * `docs/gate-1-auth-extraction-findings.md` (recommendation 4).
  */
 export class SessionExpiredError extends Error {

package/runtime/subsystems/auth/runtime/with-auth-retry.ts

@@ -6,7 +6,7 @@
  * on the refreshed token propagates rather than looping, so transient
  * adapter bugs can't hang the caller.
  *
- * Generalisation over dealbrain's original SFDC-specific version: the
+ * Generalisation over the extraction source's SFDC-specific original: the
  * session-expired classifier is injected. Providers mark their session-
  * expired errors (via `instanceof` of a marker class, or by setting a known
  * property) and pass a classifier matching that shape.

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,
+  IProviderStrategy,
+  ProviderStrategyRegistry,
+  ExchangedTokens,
   AuthCredentials,
   AuthResolveOptions,
   DecryptedIntegration,
-  OAuthStateEntry,
+  OAuthStateRecord,
   IntegrationTokenUpdate,
   ParsedRefreshResponse,
+  AuthOAuthState,
 } from './auth';

package/runtime/subsystems/sync/deep-equal.differ.ts

@@ -5,7 +5,7 @@
  * per-field diff (`{ from, to }`) for every field whose value changed.
  * Returns `'noop'` when the record is unchanged.
  *
- * Design decisions (extracted from dealbrain-v2 + HS-9 findings):
+ * Design decisions (extracted from the upstream consumer + HS-9 findings):
  *
  * 1. **Ignore list** — row metadata that sinks/services stamp unconditionally
  *    so upstream cannot reasonably disagree:

package/runtime/subsystems/sync/execute-sync.use-case.ts

@@ -41,7 +41,7 @@
  * is strictly provider-agnostic:
  *   - `entityType` is `string` throughout; no `'opportunity' | 'account' | ...`
  *     narrowing leaks into the use case
- *   - dealbrain's `SyncRunRecorderService` class injection replaced with the
+ *   - the upstream consumer's `SyncRunRecorderService` class injection replaced with the
  *     `ISyncRunRecorder` protocol (backend lands in SYNC-4)
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';

package/runtime/subsystems/sync/sync-change-source.protocol.ts

@@ -6,7 +6,7 @@
  * depend on a specific backend implementation.
  *
  * Three detection modes (poll / cdc / webhook) converge on this single port
- * per ADR-0002 (dealbrain-v2). Per-mode differences live in the
+ * per ADR-0002 (the upstream consumer). Per-mode differences live in the
  * `Change.source` / `dedupKey` / `providerChangedFields` metadata fields,
  * not in separate ports.
  *

package/runtime/subsystems/sync/sync-cursor-store.memory-backend.ts

@@ -21,7 +21,7 @@
  * could occur. Tests that want to assert per-tenant isolation should
  * target the Drizzle backend.
  *
- * Not shipped in dealbrain-v2; this is a subsystem-first addition for the
+ * Not shipped in the upstream consumer; this is a subsystem-first addition for the
  * test surface. Consumed by:
  *   - SYNC-5 unit tests (`ExecuteSyncUseCase` against synthetic sources)
  *   - SYNC-6 module tests (`SyncModule.forRoot({ backend: 'memory' })`)

package/runtime/subsystems/sync/sync-loopback.protocol.ts

@@ -14,10 +14,9 @@
  * a backend in Phase 1; consumers that need loopback suppression provide
  * their own (redis-hashed, memory TTL, etc.).
  *
- * `entityType` is `string` (not a union) — per dealbrain-v2's HS-9 findings
- * the CRM-specific narrowing `'opportunity' | 'account' | 'contact'` bled
- * into the port and had to be removed. Consumers narrow internally if they
- * want.
+ * `entityType` is `string` (not a union) — per HS-9 findings the
+ * CRM-specific narrowing `'opportunity' | 'account' | 'contact'` bled into
+ * the port and had to be removed. Consumers narrow internally if they want.
  */
 
 export interface ILoopbackFingerprintStore<T = unknown> {

package/runtime/subsystems/sync/sync-run-recorder.drizzle-backend.ts

@@ -1,7 +1,7 @@
 /**
  * DrizzleSyncRunRecorder — Drizzle-backed `ISyncRunRecorder` (SYNC-4).
  *
- * Generic write path only — extracted from dealbrain-v2's
+ * Generic write path only — extracted from the source app's
  * `SyncRunRecorderService`, minus CRM-specific convenience methods. Those
  * stay consumer-owned; the subsystem ships the substrate.
  *

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 INTEGRATION_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: "INTEGRATION_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: "INTEGRATION_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.
+INTEGRATION_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 `INTEGRATION_TOKEN_ENCRYPTION_KEY=<b64>`
+ *     and `AUTH_REDIRECT_URI_BASE=<url>` to `.env.config`. Idempotent via
+ *     `skip_if: "INTEGRATION_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 (INTEGRATION_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",
+    };
+  },
+};