@pattern-stack/codegen 0.6.6 → 0.6.8

package/examples/auth-integrations/README.md

@@ -0,0 +1,125 @@
+# auth-integrations starter
+
+Canonical OAuth2 integration storage for apps using the
+`@pattern-stack/codegen` auth subsystem (ADR-031 / `runtime/subsystems/auth/`).
+
+The auth subsystem ships the abstract OAuth2 plumbing — `OAuth2RefreshStrategy`,
+`AuthController`, `withAuthRetry`, encryption, error types, and a set of narrow
+hexagonal ports for integration storage. It deliberately doesn't ship the
+concrete `integrations` table or the adapters that satisfy those ports, because
+every consumer would need to fork them. **This starter is what plugs that gap.**
+
+## What ships here
+
+```
+examples/auth-integrations/
+  definitions/
+    entities/
+      integration.yaml                      # canonical entity (run cdp entity new)
+
+  runtime/integrations/                     # vendored next to the codegen-emitted
+                                            #   integration entity module — i.e.
+                                            #   <backend_src>/modules/integrations/
+                                            #   (override via paths.modules_dir).
+    adapters/
+      integration-reader.adapter.ts         # IIntegrationReader impl
+      integration-token-writer.adapter.ts   # IIntegrationTokenWriter impl
+      integration-grant-sink.adapter.ts     # IIntegrationGrantSink impl
+    facade/
+      integrations.service.ts               # consumer-facing facade
+    oauth/
+      use-cases/
+        create-or-update-from-oauth-grant.use-case.ts
+        mark-integration-requires-reauth.use-case.ts
+        disconnect-integration.use-case.ts
+        list-user-integrations.use-case.ts
+    integrations-auth.module.ts             # @Global() — binds the three
+                                            #   AUTH_INTEGRATION_* tokens.
+```
+
+## How to install
+
+```bash
+cdp subsystem install auth          # one-time: vendor the auth subsystem
+cdp subsystem install auth-integrations
+cdp entity new integration          # emits the entity module next to the vendor
+```
+
+The `auth-integrations` install:
+- copies `definitions/entities/integration.yaml` into your configured
+  `paths.entities` (or legacy `paths.entities_dir`) directory.
+- vendors `runtime/integrations/**` under
+  `<backend_src>/modules/integrations/` (override via `paths.modules_dir`),
+  rewriting bare `@pattern-stack/codegen/runtime/subsystems/auth` imports to
+  relative paths that resolve against the vendored auth subsystem at
+  `<paths.subsystems>/auth`.
+- appends a TODO to `<backend_src>/app.module.ts` reminding you to register
+  `IntegrationsAuthModule` AFTER `AuthModule.forRoot(...)`.
+
+`IntegrationsAuthModule` is `@Global()` because `AuthController` (inside
+`AuthModule`'s injector) resolves the `AUTH_INTEGRATION_*` providers exposed
+by it.
+
+## Two interfaces, two purposes
+
+The auth subsystem requires three narrow ports:
+
+| Token                            | Port                       | Used by                        |
+| -------------------------------- | -------------------------- | ------------------------------ |
+| `AUTH_INTEGRATION_READER`        | `IIntegrationReader`       | `OAuth2RefreshStrategy.resolve` |
+| `AUTH_INTEGRATION_TOKEN_WRITER`  | `IIntegrationTokenWriter`  | `OAuth2RefreshStrategy.resolve` |
+| `AUTH_INTEGRATION_GRANT_SINK`    | `IIntegrationGrantSink`    | `AuthController.callback`       |
+
+These stay narrow on purpose — a non-codegen consumer with a hand-rolled
+integrations table can satisfy them without pulling in the rest of this
+starter.
+
+The starter's `IntegrationsService` is **a separate, richer interface** that
+your app code (controllers, handlers, frontend-facing routes) talks to
+directly. It composes the use cases, applies encryption, and exposes
+consumer-shaped methods like `findByUserAndProvider`, `listByUser`,
+`createOrUpdateFromOAuthGrant`, `markRequiresReauth`, and `disconnect`.
+
+Same precedent as EAV: `FieldValueService.upsertFieldsTransactional` is
+wider than `IFieldValueRepository.upsertCurrentValues`.
+
+## `scopes` is `json`, not `string_array`
+
+This is deliberate. The codegen `string_array` field type currently emits
+`z.unknown()` in generated DTOs (open bug #281). Storing as `json` keeps the
+column shape correct (`jsonb` holding `string[]`) without DTO regressions.
+Once #281 lands, the field can be re-typed to `string_array` without behavior
+change.
+
+**Do not "clean up" to `string_array` until #281 ships.**
+
+## `provider` is `string`, not `enum`
+
+Adding a new provider (`google`, `gusto`, …) should be a code change (a new
+`IProviderStrategy` registered in `STRATEGY_REGISTRY`), not a YAML/migration
+change. The string column matches the strategy registry's key type and
+supports any provider slug your app cares about.
+
+## Smoke checklist
+
+After install:
+
+- [ ] `IntegrationsService.findByUserAndProvider(userId, 'hubspot-crm')`
+      returns `null` for missing rows, decrypted-creds for present rows.
+- [ ] `createOrUpdateFromOAuthGrant({ userId, provider, accessToken, ... })`
+      upserts on `(user_id, provider)`. Re-running with a different access
+      token replaces the prior token; omitting `refreshToken` keeps the
+      existing ciphertext.
+- [ ] `markRequiresReauth(integrationId)` flips status to `requires_reauth`.
+- [ ] `disconnect(integrationId)` flips status to `revoked` and clears the
+      stored ciphertexts.
+- [ ] `OAuth2RefreshStrategy.resolve()` end-to-end refresh works against a
+      provider-strategy you've registered (out of scope — provider strategies
+      are consumer-side per ADR-031).
+
+## Related
+
+- ADR-031 — auth subsystem (Accepted)
+- #285 — this starter (tracking issue)
+- #286 — `AuthController` + integration-store ports (merged in PR #289)
+- #287 — `cdp subsystem install auth-integrations` template (follow-up)

package/examples/auth-integrations/definitions/entities/integration.yaml

@@ -0,0 +1,98 @@
+# auth-integrations: Integration
+# Canonical OAuth2 integration row — one per (user_id, provider) pair.
+# Vendored alongside the auth subsystem to satisfy IIntegrationReader /
+# IIntegrationTokenWriter / IIntegrationGrantSink ports out of the box.
+#
+# `provider` stays a string (not enum) intentionally so consumers can add
+# provider keys ('hubspot-crm', 'salesforce-crm', 'google', …) without
+# forking the entity YAML. Strategy lookup happens in code via
+# STRATEGY_REGISTRY.
+
+entity:
+  name: integration
+  plural: integrations
+  table: integrations
+  pattern: Base
+  folder_structure: nested
+
+fields:
+  user_id:
+    type: uuid
+    required: true
+    index: true
+
+  # Provider slug — matches the strategy.provider in STRATEGY_REGISTRY.
+  # Stays string (not enum) so adding a new provider is a code change,
+  # not a YAML/migration change. See README.
+  provider:
+    type: string
+    required: true
+    index: true
+    max_length: 64
+
+  external_account_id:
+    type: string
+    nullable: true
+    max_length: 255
+
+  # Ciphertexts — encryption is applied inside the IntegrationsService
+  # facade + adapter layer (via IEncryptionKey). The DB row only ever
+  # holds the encrypted form; decryption happens on read in the reader
+  # adapter.
+  access_token_encrypted:
+    type: string
+    nullable: true
+
+  refresh_token_encrypted:
+    type: string
+    nullable: true
+
+  expires_at:
+    type: datetime
+    nullable: true
+
+  # NOTE: typed `json` rather than `string_array` deliberately. The
+  # `string_array` codegen field type currently emits `z.unknown()` in
+  # generated DTOs (open bug #281). Storing as `json` keeps the column
+  # shape correct (jsonb holding string[]) without DTO regressions.
+  # Once #281 lands, this can be re-typed to `string_array` without
+  # behavior change. Do NOT "clean up" until then.
+  scopes:
+    type: json
+    nullable: true
+
+  # SFDC-specific instance URL; null for providers that don't need it.
+  instance_url:
+    type: string
+    nullable: true
+    max_length: 512
+
+  provider_metadata:
+    type: json
+    nullable: true
+
+  status:
+    type: enum
+    choices: [active, requires_reauth, revoked]
+    required: true
+    default: active
+    index: true
+
+behaviors:
+  - timestamps
+
+queries:
+  # Primary lookup: "does this user already have a connection to this
+  # provider?" — used by createOrUpdateFromOAuthGrant + every consumer
+  # that loads tokens for an outbound API call.
+  - by: [user_id, provider]
+    unique: true
+
+  # Settings page: list a user's connected integrations, newest first.
+  - by: [user_id]
+    order: created_at desc
+
+  # Operational query: find broken integrations needing reauth across
+  # all users (admin / monitoring).
+  - by: [provider, status]
+    order: updated_at desc

package/examples/auth-integrations/runtime/integrations/adapters/integration-grant-sink.adapter.ts

@@ -0,0 +1,29 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  IIntegrationGrantSink,
+  IntegrationGrantInput,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { CreateOrUpdateFromOAuthGrantUseCase } from '../oauth/use-cases/create-or-update-from-oauth-grant.use-case';
+
+/**
+ * `IIntegrationGrantSink` adapter — pass-through to
+ * `CreateOrUpdateFromOAuthGrantUseCase`. The auth subsystem's
+ * `AuthController.callback` invokes this after
+ * `IProviderStrategy.exchangeCodeForTokens`.
+ *
+ * This adapter injects the use case directly (not the
+ * `IntegrationsService` facade) for symmetry with the reader and
+ * token-writer adapters, which also bypass the facade and talk to
+ * the codegen-emitted layer directly. The port and the use case share
+ * the exact same `IntegrationGrantInput` shape, so no field mapping is
+ * needed — encryption, upsert resolution, and status handling all live
+ * inside the use case.
+ */
+@Injectable()
+export class IntegrationGrantSinkAdapter implements IIntegrationGrantSink {
+  constructor(private readonly useCase: CreateOrUpdateFromOAuthGrantUseCase) {}
+
+  async createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void> {
+    await this.useCase.execute(input);
+  }
+}

package/examples/auth-integrations/runtime/integrations/adapters/integration-reader.adapter.ts

@@ -0,0 +1,52 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  ENCRYPTION_KEY,
+  type DecryptedIntegration,
+  type IEncryptionKey,
+  type IIntegrationReader,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { IntegrationService } from '../integration.service';
+
+/**
+ * `IIntegrationReader` adapter — fetches the integration row by id and
+ * decrypts its ciphertexts to satisfy the auth subsystem's read port.
+ *
+ * Stays narrow on purpose: this adapter exists purely to feed
+ * `OAuth2RefreshStrategy.resolve()`. Anything wider belongs in
+ * `IntegrationsService` (the consumer-facing facade).
+ *
+ * Note: this duplicates the decryption logic in `IntegrationsService`
+ * by design — the adapter must not depend on the facade because the
+ * facade depends on the use cases which depend on the adapter (well,
+ * not directly, but via the same module). Keeping the read path
+ * standalone avoids a circular DI graph and matches the auth
+ * subsystem's "narrow port" contract.
+ */
+@Injectable()
+export class IntegrationReaderAdapter implements IIntegrationReader {
+  constructor(
+    private readonly integrations: IntegrationService,
+    @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
+  ) {}
+
+  async findByIdDecrypted(integrationId: string): Promise<DecryptedIntegration | null> {
+    const row = await this.integrations.findById(integrationId);
+    if (!row) return null;
+
+    const accessToken = row.accessTokenEncrypted
+      ? await this.encryption.decrypt(row.accessTokenEncrypted)
+      : '';
+    const refreshToken = row.refreshTokenEncrypted
+      ? await this.encryption.decrypt(row.refreshTokenEncrypted)
+      : null;
+
+    return {
+      id: row.id,
+      provider: row.provider,
+      accessToken,
+      refreshToken,
+      expiresAt: row.expiresAt,
+      providerMetadata: (row.providerMetadata as Record<string, unknown> | null) ?? null,
+    };
+  }
+}

package/examples/auth-integrations/runtime/integrations/adapters/integration-token-writer.adapter.ts

@@ -0,0 +1,43 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  ENCRYPTION_KEY,
+  type IEncryptionKey,
+  type IIntegrationTokenWriter,
+  type IntegrationTokenUpdate,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { IntegrationService } from '../integration.service';
+
+/**
+ * `IIntegrationTokenWriter` adapter — encrypts the new access token
+ * (and rotated refresh token, if present) and persists them onto the
+ * integration row.
+ *
+ * `IntegrationTokenUpdate.refreshToken` semantics:
+ *   - `undefined` → provider didn't rotate, leave existing ciphertext
+ *   - `string`    → provider rotated, re-encrypt + persist
+ *
+ * On a successful refresh we also flip status back to 'active' — if
+ * the row was previously `requires_reauth` and the user re-connected,
+ * a successful refresh is the signal that the integration is healthy
+ * again.
+ */
+@Injectable()
+export class IntegrationTokenWriterAdapter implements IIntegrationTokenWriter {
+  constructor(
+    private readonly integrations: IntegrationService,
+    @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
+  ) {}
+
+  async persistRefresh(update: IntegrationTokenUpdate): Promise<void> {
+    const accessTokenEncrypted = await this.encryption.encrypt(update.accessToken);
+    const patch: Record<string, unknown> = {
+      accessTokenEncrypted,
+      expiresAt: update.expiresAt,
+      status: 'active',
+    };
+    if (update.refreshToken !== undefined) {
+      patch.refreshTokenEncrypted = await this.encryption.encrypt(update.refreshToken);
+    }
+    await this.integrations.update(update.integrationId, patch);
+  }
+}

package/examples/auth-integrations/runtime/integrations/facade/integrations.service.ts

@@ -0,0 +1,150 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  ENCRYPTION_KEY,
+  type IEncryptionKey,
+  type IntegrationGrantInput,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { IntegrationService } from '../integration.service';
+import type { Integration } from '../integration.entity';
+import { CreateOrUpdateFromOAuthGrantUseCase } from '../oauth/use-cases/create-or-update-from-oauth-grant.use-case';
+import { DisconnectIntegrationUseCase } from '../oauth/use-cases/disconnect-integration.use-case';
+import { ListUserIntegrationsUseCase } from '../oauth/use-cases/list-user-integrations.use-case';
+import { MarkIntegrationRequiresReauthUseCase } from '../oauth/use-cases/mark-integration-requires-reauth.use-case';
+
+/**
+ * Decrypted integration shape — used by consumer code that needs to
+ * make outbound API calls (frontend never sees this; it's server-side
+ * only). Mirrors the auth subsystem's `DecryptedIntegration` but is
+ * the consumer-facing return type for `findByUserAndProvider`.
+ */
+export interface DecryptedIntegrationRow {
+  id: string;
+  userId: string;
+  provider: string;
+  externalAccountId: string | null;
+  accessToken: string;
+  refreshToken: string | null;
+  expiresAt: Date | null;
+  scopes: string[] | null;
+  instanceUrl: string | null;
+  providerMetadata: Record<string, unknown> | null;
+  status: 'active' | 'requires_reauth' | 'revoked';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * IntegrationsService — consumer-facing facade over the codegen-emitted
+ * `IntegrationService` plus the auth subsystem's `IEncryptionKey`.
+ *
+ * Wider than the auth subsystem ports (`IIntegrationReader`,
+ * `IIntegrationTokenWriter`, `IIntegrationGrantSink`) on purpose: the
+ * narrow ports are the subsystem's hexagonal seam (so non-codegen
+ * consumers can implement them); the facade is what app code talks to
+ * directly (controllers, handlers, frontend-facing use cases).
+ *
+ * Same pattern as EAV's `FieldValueService.upsertFieldsTransactional`
+ * being wider than `IFieldValueRepository.upsertCurrentValues`.
+ *
+ * Ciphertexts never leave the facade in plaintext form except via
+ * `findByUserAndProvider` (server-side only — the caller is expected
+ * to use the tokens to make an outbound API call). `listByUser`
+ * intentionally strips them to a safe metadata shape.
+ */
+@Injectable()
+export class IntegrationsService {
+  constructor(
+    private readonly integrations: IntegrationService,
+    @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
+    private readonly createOrUpdateUseCase: CreateOrUpdateFromOAuthGrantUseCase,
+    private readonly markReauthUseCase: MarkIntegrationRequiresReauthUseCase,
+    private readonly disconnectUseCase: DisconnectIntegrationUseCase,
+    private readonly listUseCase: ListUserIntegrationsUseCase,
+  ) {}
+
+  /**
+   * Loads the integration for `(userId, provider)` and returns it with
+   * decrypted tokens, or `null` if no row exists. Returns the row even
+   * if `status !== 'active'` so callers can distinguish "never
+   * connected" from "connected but broken" — gate on `status` yourself.
+   */
+  async findByUserAndProvider(
+    userId: string,
+    provider: string,
+  ): Promise<DecryptedIntegrationRow | null> {
+    const row = await this.integrations.findByUserIdAndProvider(userId, provider);
+    if (!row) return null;
+    return this.decrypt(row);
+  }
+
+  /**
+   * Lists a user's integrations newest-first, with ciphertexts stripped.
+   * Safe to return to a frontend.
+   */
+  async listByUser(userId: string): Promise<Array<Omit<Integration, 'accessTokenEncrypted' | 'refreshTokenEncrypted'>>> {
+    const rows = await this.listUseCase.execute(userId);
+    return rows.map((row) => {
+      const { accessTokenEncrypted: _accessTokenEncrypted, refreshTokenEncrypted: _refreshTokenEncrypted, ...safe } = row;
+      return safe;
+    });
+  }
+
+  /**
+   * Upserts a freshly-minted OAuth2 grant from the authorize-code
+   * callback. Pass-through to `CreateOrUpdateFromOAuthGrantUseCase` —
+   * the input shape matches the auth subsystem's `IntegrationGrantInput`
+   * exactly so `IntegrationGrantSinkAdapter` can forward without
+   * mapping.
+   */
+  async createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void> {
+    await this.createOrUpdateUseCase.execute(input);
+  }
+
+  /**
+   * Flips status to `requires_reauth`. Called from `withAuthRetry`'s
+   * broken-integration handler.
+   */
+  async markRequiresReauth(integrationId: string): Promise<void> {
+    await this.markReauthUseCase.execute(integrationId);
+  }
+
+  /**
+   * User-initiated disconnect. Status → 'revoked', tokens cleared.
+   */
+  async disconnect(integrationId: string): Promise<void> {
+    await this.disconnectUseCase.execute(integrationId);
+  }
+
+  /**
+   * Decrypts ciphertexts on a raw `Integration` row. Used internally
+   * by `findByUserAndProvider` and by `IntegrationReaderAdapter`.
+   *
+   * Empty access tokens (e.g. revoked rows where the ciphertext was
+   * cleared) decrypt to the empty string — matches
+   * `DecryptedIntegration.accessToken`'s "empty if never granted"
+   * contract.
+   */
+  private async decrypt(row: Integration): Promise<DecryptedIntegrationRow> {
+    const accessToken = row.accessTokenEncrypted
+      ? await this.encryption.decrypt(row.accessTokenEncrypted)
+      : '';
+    const refreshToken = row.refreshTokenEncrypted
+      ? await this.encryption.decrypt(row.refreshTokenEncrypted)
+      : null;
+    return {
+      id: row.id,
+      userId: row.userId,
+      provider: row.provider,
+      externalAccountId: row.externalAccountId,
+      accessToken,
+      refreshToken,
+      expiresAt: row.expiresAt,
+      scopes: (row.scopes as string[] | null) ?? null,
+      instanceUrl: row.instanceUrl,
+      providerMetadata: (row.providerMetadata as Record<string, unknown> | null) ?? null,
+      status: row.status,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/examples/auth-integrations/runtime/integrations/integrations-auth.module.ts

@@ -0,0 +1,81 @@
+import { Global, Module } from '@nestjs/common';
+import {
+  AUTH_INTEGRATION_GRANT_SINK,
+  AUTH_INTEGRATION_READER,
+  AUTH_INTEGRATION_TOKEN_WRITER,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { IntegrationsModule } from './integrations.module';
+import { IntegrationGrantSinkAdapter } from './adapters/integration-grant-sink.adapter';
+import { IntegrationReaderAdapter } from './adapters/integration-reader.adapter';
+import { IntegrationTokenWriterAdapter } from './adapters/integration-token-writer.adapter';
+import { IntegrationsService } from './facade/integrations.service';
+import { CreateOrUpdateFromOAuthGrantUseCase } from './oauth/use-cases/create-or-update-from-oauth-grant.use-case';
+import { DisconnectIntegrationUseCase } from './oauth/use-cases/disconnect-integration.use-case';
+import { ListUserIntegrationsUseCase } from './oauth/use-cases/list-user-integrations.use-case';
+import { MarkIntegrationRequiresReauthUseCase } from './oauth/use-cases/mark-integration-requires-reauth.use-case';
+
+/**
+ * `IntegrationsAuthModule` — wires the consumer-side adapters that
+ * satisfy the auth subsystem's three integration-store ports plus the
+ * `IntegrationsService` facade and its use cases.
+ *
+ * Imports `IntegrationsModule` (the codegen-emitted entity module) to
+ * pull in `IntegrationService` + its repository.
+ *
+ * Depends on a registered `ENCRYPTION_KEY` provider — that comes from
+ * `AuthModule.forRoot({ encryptionKey: ... })`. Make sure
+ * `AuthModule.forRoot(...)` is imported in your app's root module BEFORE
+ * `IntegrationsAuthModule` (or globally — `AuthModule` is `global: true`
+ * by convention).
+ *
+ * Token bindings (per #285 / #286):
+ *   - AUTH_INTEGRATION_READER       → IntegrationReaderAdapter
+ *   - AUTH_INTEGRATION_TOKEN_WRITER → IntegrationTokenWriterAdapter
+ *   - AUTH_INTEGRATION_GRANT_SINK   → IntegrationGrantSinkAdapter
+ *
+ * `@Global()` is required: `AuthController` lives inside `AuthModule`'s
+ * own injector and resolves the `AUTH_INTEGRATION_*` providers exposed
+ * here. Without `@Global()`, the controller's injector cannot see these
+ * tokens and Nest fails to boot. Same pattern as the `auth-bindings`
+ * module shipped in #93.
+ */
+@Global()
+@Module({
+  imports: [IntegrationsModule],
+  providers: [
+    // Use cases (consumed by the facade)
+    CreateOrUpdateFromOAuthGrantUseCase,
+    MarkIntegrationRequiresReauthUseCase,
+    DisconnectIntegrationUseCase,
+    ListUserIntegrationsUseCase,
+
+    // Facade (consumer-facing API; controllers/handlers inject this)
+    IntegrationsService,
+
+    // Subsystem port adapters (concrete classes — also exposed under
+    // their token aliases for `@Inject(...)` consumers in the auth
+    // subsystem).
+    IntegrationReaderAdapter,
+    IntegrationTokenWriterAdapter,
+    IntegrationGrantSinkAdapter,
+    {
+      provide: AUTH_INTEGRATION_READER,
+      useExisting: IntegrationReaderAdapter,
+    },
+    {
+      provide: AUTH_INTEGRATION_TOKEN_WRITER,
+      useExisting: IntegrationTokenWriterAdapter,
+    },
+    {
+      provide: AUTH_INTEGRATION_GRANT_SINK,
+      useExisting: IntegrationGrantSinkAdapter,
+    },
+  ],
+  exports: [
+    IntegrationsService,
+    AUTH_INTEGRATION_READER,
+    AUTH_INTEGRATION_TOKEN_WRITER,
+    AUTH_INTEGRATION_GRANT_SINK,
+  ],
+})
+export class IntegrationsAuthModule {}

package/examples/auth-integrations/runtime/integrations/oauth/use-cases/create-or-update-from-oauth-grant.use-case.ts

@@ -0,0 +1,75 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  ENCRYPTION_KEY,
+  type IEncryptionKey,
+  type IntegrationGrantInput,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { IntegrationService } from '../../integration.service';
+import type { Integration } from '../../integration.entity';
+
+/**
+ * Persists an OAuth2 grant from the authorize-code callback (initial
+ * connect or re-connect). Upserts on `(user_id, provider)`:
+ *
+ *   - existing row → re-encrypt + persist tokens, status → 'active'
+ *   - missing row  → insert a new row in 'active' status
+ *
+ * The input shape is exactly `IntegrationGrantInput` from the auth
+ * subsystem so `IntegrationGrantSinkAdapter` can be a pass-through —
+ * the port and use case share the same boundary type. Encryption is
+ * applied here (inside the use case) before ciphertexts hit the row.
+ *
+ * Re-connect semantics: if the new grant omits `refreshToken`
+ * (provider didn't return one), the existing ciphertext is preserved
+ * — providers commonly omit the refresh token on a re-grant when
+ * they haven't rotated it.
+ */
+@Injectable()
+export class CreateOrUpdateFromOAuthGrantUseCase {
+  constructor(
+    private readonly integrations: IntegrationService,
+    @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
+  ) {}
+
+  async execute(input: IntegrationGrantInput): Promise<Integration> {
+    const accessTokenEncrypted = await this.encryption.encrypt(input.accessToken);
+    const refreshTokenEncrypted =
+      input.refreshToken !== undefined
+        ? await this.encryption.encrypt(input.refreshToken)
+        : undefined;
+
+    const existing = await this.integrations.findByUserIdAndProvider(
+      input.userId,
+      input.provider,
+    );
+
+    const baseRow = {
+      userId: input.userId,
+      provider: input.provider,
+      accessTokenEncrypted,
+      expiresAt: input.expiresAt ?? null,
+      externalAccountId: input.externalAccountId ?? null,
+      scopes: input.scope ?? null,
+      providerMetadata: input.providerMetadata ?? null,
+      status: 'active' as const,
+    };
+
+    if (existing) {
+      // Preserve the existing refresh-token ciphertext when the grant
+      // didn't include a new refresh token (common on re-grants).
+      const patch: Partial<Integration> = {
+        ...baseRow,
+        refreshTokenEncrypted:
+          refreshTokenEncrypted !== undefined
+            ? refreshTokenEncrypted
+            : existing.refreshTokenEncrypted,
+      };
+      return this.integrations.update(existing.id, patch);
+    }
+
+    return this.integrations.create({
+      ...baseRow,
+      refreshTokenEncrypted: refreshTokenEncrypted ?? null,
+    });
+  }
+}

package/examples/auth-integrations/runtime/integrations/oauth/use-cases/disconnect-integration.use-case.ts

@@ -0,0 +1,29 @@
+import { Injectable } from '@nestjs/common';
+import { IntegrationService } from '../../integration.service';
+import type { Integration } from '../../integration.entity';
+
+/**
+ * User-initiated disconnect. Flips status to `revoked` and clears the
+ * stored ciphertexts so a leaked DB dump never re-grants access. The
+ * row is preserved (audit trail, FK integrity); a follow-up grant on
+ * the same `(user_id, provider)` will re-activate it via
+ * CreateOrUpdateFromOAuthGrantUseCase.
+ *
+ * Note: this does NOT call the provider's revoke endpoint. Providers
+ * vary widely on revoke API shapes — that step belongs in a
+ * provider-specific strategy if/when needed (out of scope for the
+ * starter).
+ */
+@Injectable()
+export class DisconnectIntegrationUseCase {
+  constructor(private readonly integrations: IntegrationService) {}
+
+  async execute(integrationId: string): Promise<Integration> {
+    return this.integrations.update(integrationId, {
+      status: 'revoked',
+      accessTokenEncrypted: null,
+      refreshTokenEncrypted: null,
+      expiresAt: null,
+    });
+  }
+}