nestjs-ddd-cli 3.2.2 → 3.3.0

package/dist/templates/recipes/oauth2-token-introspection/http-client.ts.hbs

@@ -0,0 +1,343 @@
+export interface BoundedJsonHttpOptions {
+  /** Exact origin from validated deployment configuration; no path or request data. */
+  origin: string;
+  requestHeaders?: Readonly<Record<string, string>>;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  trustedInternalHttp?: boolean;
+  transport?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+export class BoundedJsonHttpUnavailableError extends Error {
+  constructor(
+    readonly reason: 'timeout' | 'network' | 'http' | 'invalid_response',
+    readonly status?: number,
+  ) {
+    super('Provider validation unavailable');
+    this.name = 'BoundedJsonHttpUnavailableError';
+  }
+}
+
+function bounded(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result < min || result > max)
+    throw new Error();
+  return result;
+}
+
+function freeze(value: unknown, depth = 0): void {
+  if (depth > 32) throw new BoundedJsonHttpUnavailableError('invalid_response');
+  if (value !== null && typeof value === 'object') {
+    for (const child of Object.values(value)) freeze(child, depth + 1);
+    Object.freeze(value);
+  }
+}
+
+function hasControls(value: string): boolean {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+
+function pathSegments(value: unknown): value is readonly string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= 32 &&
+    value.every(
+      (segment: unknown) =>
+        typeof segment === 'string' &&
+        segment.length <= 1024 &&
+        !['.', '..'].includes(segment) &&
+        !hasControls(segment),
+    )
+  );
+}
+
+/** Minimal JSON transport. It neither authenticates a person nor grants permissions. */
+export class BoundedJsonHttpClient {
+  private readonly origin: string;
+  readonly #headers: Readonly<Record<string, string>>;
+  private readonly timeoutMs: number;
+  private readonly maxResponseBytes: number;
+  private readonly transport: (
+    url: string,
+    init: RequestInit,
+  ) => Promise<Response>;
+
+  constructor(options: BoundedJsonHttpOptions) {
+    try {
+      const url = new URL(options.origin);
+      if (
+        url.username ||
+        url.password ||
+        url.hash ||
+        url.search ||
+        url.pathname !== '/' ||
+        (url.protocol !== 'https:' &&
+          !(url.protocol === 'http:' && options.trustedInternalHttp === true))
+      )
+        throw new Error();
+      this.origin = url.origin;
+      const headers = new Headers({ accept: 'application/json' });
+      for (const [key, value] of Object.entries(options.requestHeaders ?? {})) {
+        if (['accept', 'content-type'].includes(key.toLowerCase()))
+          throw new Error();
+        headers.set(key, value);
+      }
+      this.#headers = Object.freeze(Object.fromEntries(headers.entries()));
+      this.timeoutMs = bounded(options.timeoutMs, 3000, 10, 30000);
+      this.maxResponseBytes = bounded(
+        options.maxResponseBytes,
+        65536,
+        128,
+        1048576,
+      );
+      this.transport = options.transport ?? ((url, init) => fetch(url, init));
+    } catch {
+      throw new Error('Invalid provider HTTP configuration');
+    }
+  }
+
+  get(
+    pathSegments: readonly string[],
+    query: Readonly<Record<string, string>> = {},
+  ): Promise<unknown> {
+    return this.execute('GET', pathSegments, query);
+  }
+
+  postForm(
+    pathSegments: readonly string[],
+    form: Readonly<Record<string, string>>,
+  ): Promise<unknown> {
+    if (Object.values(form).some((value) => typeof value !== 'string'))
+      throw new Error('Invalid provider request configuration');
+    const body = new URLSearchParams(form).toString();
+    if (new TextEncoder().encode(body).byteLength > 262144)
+      throw new Error('Invalid provider request configuration');
+    return this.execute(
+      'POST',
+      pathSegments,
+      {},
+      body,
+      'application/x-www-form-urlencoded',
+    );
+  }
+
+  postJson(
+    pathSegments: readonly string[],
+    payload: unknown,
+  ): Promise<unknown> {
+    return this.json('POST', pathSegments, payload);
+  }
+
+  patchJson(
+    pathSegments: readonly string[],
+    payload: unknown,
+  ): Promise<unknown> {
+    return this.json('PATCH', pathSegments, payload);
+  }
+
+  putJson(
+    pathSegments: readonly string[],
+    payload: unknown,
+    query: Readonly<Record<string, string>> = {},
+  ): Promise<unknown> {
+    return this.json('PUT', pathSegments, payload, query);
+  }
+
+  private json(
+    method: 'POST' | 'PATCH' | 'PUT',
+    pathSegments: readonly string[],
+    payload: unknown,
+    query: Readonly<Record<string, string>> = {},
+  ): Promise<unknown> {
+    let nodes = 0;
+    const seen = new Set<object>();
+    const visit = (value: unknown, depth: number): void => {
+      if (++nodes > 10000 || depth > 32) throw new Error();
+      if (
+        value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean'
+      )
+        return;
+      if (typeof value === 'number' && Number.isFinite(value)) return;
+      if (typeof value !== 'object' || !value || seen.has(value))
+        throw new Error();
+      seen.add(value);
+      if (Array.isArray(value)) {
+        if (Object.getPrototypeOf(value) !== Array.prototype) throw new Error();
+        for (let i = 0; i < value.length; i++) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+          if (!descriptor || !('value' in descriptor)) throw new Error();
+          visit(descriptor.value, depth + 1);
+        }
+        if (Object.getOwnPropertyNames(value).length !== value.length + 1)
+          throw new Error();
+      } else {
+        const prototype: unknown = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+          throw new Error();
+        for (const descriptor of Object.values(
+          Object.getOwnPropertyDescriptors(value),
+        )) {
+          if (!descriptor.enumerable || !('value' in descriptor))
+            throw new Error();
+          visit(descriptor.value, depth + 1);
+        }
+      }
+      if (Object.getOwnPropertySymbols(value).length) throw new Error();
+      seen.delete(value);
+    };
+    try {
+      visit(payload, 0);
+      const body = JSON.stringify(payload);
+      if (new TextEncoder().encode(body).byteLength > 262144) throw new Error();
+      return this.execute(method, pathSegments, query, body, 'application/json');
+    } catch {
+      throw new Error('Invalid provider request configuration');
+    }
+  }
+
+  private async execute(
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT',
+    segments: readonly string[],
+    query: Readonly<Record<string, string>>,
+    body?: string,
+    contentType?: string,
+  ): Promise<unknown> {
+    if (!pathSegments(segments)) {
+      throw new Error('Invalid provider request configuration');
+    }
+    const entries = Object.entries(query);
+    if (
+      entries.length > 32 ||
+      entries.some(
+        ([key, value]) =>
+          !key ||
+          key.length > 128 ||
+          typeof value !== 'string' ||
+          value.length > 2048 ||
+          hasControls(key + value),
+      )
+    ) {
+      throw new Error('Invalid provider request configuration');
+    }
+    let url: URL;
+    try {
+      url = new URL(
+        `${this.origin}/${segments.map((segment) => encodeURIComponent(segment)).join('/')}`,
+      );
+      for (const [key, value] of entries) url.searchParams.set(key, value);
+      if (url.origin !== this.origin || url.href.length > 8192)
+        throw new Error();
+    } catch {
+      throw new Error('Invalid provider request configuration');
+    }
+    const abort = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        abort.abort();
+        reject(new BoundedJsonHttpUnavailableError('timeout'));
+      }, this.timeoutMs);
+    });
+    try {
+      return await Promise.race([
+        this.request(url.href, method, body, abort.signal, contentType),
+        timeout,
+      ]);
+    } catch (error) {
+      if (error instanceof BoundedJsonHttpUnavailableError) throw error;
+      throw new BoundedJsonHttpUnavailableError('network');
+    } finally {
+      clearTimeout(timer);
+      abort.abort();
+    }
+  }
+
+  private async request(
+    url: string,
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT',
+    body: string | undefined,
+    signal: AbortSignal,
+    contentType?: string,
+  ): Promise<unknown> {
+    const response = await this.transport(url, {
+      method,
+      body,
+      headers:
+        method !== 'GET'
+          ? {
+              ...this.#headers,
+              'content-type':
+                contentType ?? 'application/x-www-form-urlencoded',
+            }
+          : { ...this.#headers },
+      redirect: 'error',
+      cache: 'no-store',
+      signal,
+    });
+    if (!response.ok || response.redirected) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new BoundedJsonHttpUnavailableError('http', response.status);
+    }
+    if (signal.aborted) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new BoundedJsonHttpUnavailableError('timeout');
+    }
+    const length = response.headers.get('content-length');
+    if (
+      length !== null &&
+      (!/^\d+$/.test(length) || Number(length) > this.maxResponseBytes)
+    ) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new BoundedJsonHttpUnavailableError('invalid_response');
+    }
+    if (!response.body)
+      throw new BoundedJsonHttpUnavailableError('invalid_response');
+    const reader = response.body.getReader();
+    const cancel = () => {
+      void reader.cancel().catch(() => undefined);
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > this.maxResponseBytes)
+          throw new BoundedJsonHttpUnavailableError('invalid_response');
+        chunks.push(value);
+      }
+      const bytes = new Uint8Array(size);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      try {
+        const parsed: unknown = JSON.parse(
+          new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+        );
+        freeze(parsed);
+        return parsed;
+      } catch (error) {
+        if (error instanceof BoundedJsonHttpUnavailableError) throw error;
+        throw new BoundedJsonHttpUnavailableError('invalid_response');
+      }
+    } finally {
+      signal.removeEventListener('abort', cancel);
+      void reader.cancel().catch(() => undefined);
+      reader.releaseLock();
+    }
+  }
+}

package/dist/templates/recipes/oauth2-token-introspection/index.ts.hbs

@@ -0,0 +1,3 @@
+export * from './oauth2-token-introspection.client';
+export * from './oauth2-token-introspection.module';
+export * from './bounded-json-http.client';

package/dist/templates/recipes/oauth2-token-introspection/module.ts.hbs

@@ -0,0 +1,58 @@
+import {
+  DynamicModule,
+  FactoryProvider,
+  Module,
+  ModuleMetadata,
+} from '@nestjs/common';
+import {
+  OAUTH2_TOKEN_INTROSPECTION_OPTIONS,
+  OAuth2TokenIntrospectionClient,
+  OAuth2TokenIntrospectionOptions,
+} from './oauth2-token-introspection.client';
+
+export interface OAuth2TokenIntrospectionModuleAsyncOptions extends Pick<
+  ModuleMetadata,
+  'imports'
+> {
+  inject?: FactoryProvider<OAuth2TokenIntrospectionOptions>['inject'];
+  useFactory: FactoryProvider<OAuth2TokenIntrospectionOptions>['useFactory'];
+}
+
+const clientProvider: FactoryProvider<OAuth2TokenIntrospectionClient> = {
+  provide: OAuth2TokenIntrospectionClient,
+  inject: [OAUTH2_TOKEN_INTROSPECTION_OPTIONS],
+  useFactory: (options: OAuth2TokenIntrospectionOptions) =>
+    new OAuth2TokenIntrospectionClient(options),
+};
+
+@Module({})
+export class OAuth2TokenIntrospectionModule {
+  static register(options: OAuth2TokenIntrospectionOptions): DynamicModule {
+    return {
+      module: OAuth2TokenIntrospectionModule,
+      providers: [
+        { provide: OAUTH2_TOKEN_INTROSPECTION_OPTIONS, useValue: options },
+        clientProvider,
+      ],
+      exports: [OAuth2TokenIntrospectionClient],
+    };
+  }
+
+  static registerAsync(
+    options: OAuth2TokenIntrospectionModuleAsyncOptions,
+  ): DynamicModule {
+    return {
+      module: OAuth2TokenIntrospectionModule,
+      imports: options.imports ?? [],
+      providers: [
+        {
+          provide: OAUTH2_TOKEN_INTROSPECTION_OPTIONS,
+          inject: options.inject ?? [],
+          useFactory: options.useFactory,
+        },
+        clientProvider,
+      ],
+      exports: [OAuth2TokenIntrospectionClient],
+    };
+  }
+}

package/dist/templates/recipes/oidc-bff-session/README.md.hbs

@@ -0,0 +1,96 @@
+# Confidential OIDC BFF sessions
+
+Run `ddd recipe oidc-bff-session --path <app> --dry-run` before applying the same
+command without `--dry-run`. Generated files live in `src/shared/oidc-bff`.
+Generation preflights every target, rejects symlinks/different owner content,
+preserves identical reruns and rolls back only unchanged files it created.
+No module, route, cookie, environment variable, business policy, package manifest,
+lockfile or provider configuration is changed automatically.
+
+Consumer runtime requirements: Node 20+ or Bun, `jose@6.2.12` and
+`@redis/client@6.3.0`. Add these through the app's approved dependency workflow;
+on the local Bun host use `bun add --exact jose@6.2.12 @redis/client@6.3.0`.
+Preserve an existing CI/container package-manager contract and its lockfile.
+
+`createOidcBffClient` takes immutable explicit issuer, client ID/secret, exact
+HTTPS callback, configured scopes, five same-origin HTTPS metadata endpoints
+(discovery, authorization, token, revocation, JWKS), and optional configured
+authorization parameters. Reserved OIDC/PKCE/state parameters cannot be
+overridden. The consumer owns any provider-specific audience parameter and
+exact issuer/path policy. Only `client_secret_basic`, code/S256 and RS256 signed
+ID tokens are supported. Required scopes include `openid` and `offline_access`;
+authenticated output requires a complete access/refresh token pair.
+
+Supply the existing server-owned pending record to `beginAuthorization` and
+`exchangeAuthorizationCode`; the client does not create a second pending record.
+Fresh authentication is required. It verifies signed issuer, subject, client
+audience, authorized party, nonce, expiration, issued time and authentication
+time after pending start, with bounded clock tolerance. Optional signed
+access/code hashes must match. Requested prompt alone does not prove fresh
+authentication; the provider integration must actually perform it.
+
+Discovery must match every configured endpoint exactly. No redirect, retry,
+fallback or positive-validation cache exists. A total operation deadline covers
+discovery, token exchange, token custody hook, streamed JWKS, verification and
+best-effort rejected-token cleanup. Responses are capped at 64 KiB; safe token
+fields at 16 KiB; public RSA JWKS at 16 keys and bounded moduli. Errors have fixed
+messages and never include provider bodies, credentials or raw exceptions.
+
+The async `onTokenPairIssued` hook stages every independently bounded safe
+credential before scope/type/expiry/ID-token admission policy, including
+access-only or refresh-only responses. At least one safe credential is needed.
+Malformed expiry uses `maxAccessTokenSeconds` only as a retirement hint; this
+fallback is never admitted as a verified token set. Persist the retirement
+record before proceeding. Persistence failure rejects sign-in and attempts
+immediate revocation. A wholly malformed/oversize response cannot safely
+disclose token material; it is rejected without session admission.
+
+`OpaqueSessionStore` accepts injected `SessionCommands`, a trusted stable client
+namespace, optional clock (integer seconds) and immutable duration settings.
+Browser cookies contain only random handles; pending PKCE and token material
+remain server-side. Client-hashed Redis Cluster slots isolate keys. Lua owns
+one-time pending claim/completion, browser/generation/client binding, fresh
+account switch, current-session index, logout, staged exact-pair transfer and
+durable revocation enqueue/lease/ack/retry. Only successful exact pending and
+pair commit removes the staged ticket. Once any worker claims retirement, a
+durable non-admissible marker prevents later session commit through retries or
+expired leases; only completed retirement removes that marker. Expired access retains refresh custody.
+Restart uses the same backend/client namespace; there is no local fallback.
+
+Defaults: session 3300s, pending 600s, browser generation 1 year, provider access
+maximum 3600s, provider refresh maximum 86400s, token custody 90000s, lease 30s,
+retry 60s. These are conservative documented defaults, not discovery facts.
+The owner must configure provider lifetime bounds explicitly and keep custody
+strictly longer than both provider maxima. Options are bounded and cannot
+reduce custody below those bounds. Retirement expiry hints are not session
+admission. Do not expire the whole token row with browser access expiry.
+
+`createValkeySessionCommands` takes an explicit trusted URL, timeout and optional
+test connection seam. TLS (`rediss`) is default; plaintext requires an explicit
+trusted-internal opt-in. Connect and command share a bounded deadline, disable
+offline queues/reconnects, and share one connection attempt. No command runs
+after its connection deadline. `close` permanently retires this command owner.
+No URL/token logging occurs. The Redis library owns RESP framing; this adapter
+bounds deadlines/queued commands and request arguments, and the store validates
+returned records. It does not claim streamed HTTP-style response byte control.
+
+Each app still owns configuration, cookie flags, same-origin guards, Next
+server-only marker, authorization wrappers, locale/navigation and durable worker
+scheduling. Each request must perform current provider and canonical domain
+admission. Provider traits, JWT subject or an existing browser session are not
+business permissions. Per-app token retirement leaves shared provider SSO;
+global logout requires its explicitly owned provider operation.
+
+Run generated unit cases with `bun test src/shared/oidc-bff`. Actual Lua proof
+additionally requires `OIDC_BFF_TEST_VALKEY_URL` pointing to a disposable Redis
+database with a separately authorized profile. Tests use random client
+namespaces and never flush, stop or alter the server. Unit/source evidence is
+separate from CI, deployed provider behavior, browser and authorized actor proof.
+
+Storage custody: key hashing and Redis Cluster hash tags do not encrypt the JSON
+values. Access/refresh credentials and PKCE material are plaintext within the
+server store. Production activation requires authenticated app-scoped Redis
+ACLs, verified private/TLS transport, and verified encryption/access controls
+for persistent storage and backups. An unauthenticated shared Redis instance is
+not a suitable production deployment. This recipe does not provision or prove
+those operator controls.