nestjs-ddd-cli 3.2.2 → 3.3.1

package/dist/templates/recipes/oidc-bff-session/valkey.ts.hbs

@@ -0,0 +1,148 @@
+import { createClient } from '@redis/client';
+import type { SessionCommands } from './opaque-session-store';
+
+export class SessionStorageUnavailableError extends Error {
+  constructor() {
+    super('BFF session storage is unavailable');
+    this.name = 'SessionStorageUnavailableError';
+  }
+}
+export type ValkeySessionOptions = Readonly<{
+  url: string;
+  commandTimeoutMs?: number;
+  trustedInternalPlaintext?: boolean;
+}>;
+export interface SessionConnection {
+  readonly isOpen: boolean;
+  readonly isReady: boolean;
+  on(event: 'error', listener: () => void): unknown;
+  connect(): Promise<unknown>;
+  destroy(): void;
+  withAbortSignal(signal: AbortSignal): SessionCommands;
+}
+export type ValkeySessionDependencies = Readonly<{
+  createConnection?: (options: Readonly<{ url: string; timeoutMs: number }>) => SessionConnection;
+}>;
+
+/** One reusable command owner, no environment lookup, implicit retries or local fallback. */
+export function createValkeySessionCommands(
+  input: ValkeySessionOptions,
+  dependencies: ValkeySessionDependencies = {},
+): SessionCommands & { close(): void } {
+  const options = Object.freeze({ ...input });
+  const timeoutMs = options.commandTimeoutMs ?? 2000;
+  let url: URL;
+  try {
+    url = new URL(options.url);
+  } catch {
+    throw new TypeError('Invalid BFF session storage configuration');
+  }
+  if (
+    (url.protocol !== 'rediss:' &&
+      !(url.protocol === 'redis:' && options.trustedInternalPlaintext === true)) ||
+    !url.hostname ||
+    url.search ||
+    url.hash ||
+    !/^(?:\/(?:\d{1,5})?)?$/.test(url.pathname) ||
+    options.url.length > 8192 ||
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 10 ||
+    timeoutMs > 5000
+  ) {
+    throw new TypeError('Invalid BFF session storage configuration');
+  }
+  const createConnection =
+    dependencies.createConnection ??
+    ((config) =>
+      createClient({
+        url: config.url,
+        disableOfflineQueue: true,
+        commandsQueueMaxLength: 128,
+        socket: { connectTimeout: config.timeoutMs, reconnectStrategy: false },
+      }));
+  let connecting: Promise<SessionConnection> | undefined;
+  let current: SessionConnection | undefined;
+  let closed = false;
+
+  async function client(): Promise<SessionConnection> {
+    if (closed) throw new SessionStorageUnavailableError();
+    if (!connecting) {
+      const connection = createConnection({ url: options.url, timeoutMs });
+      current = connection;
+      connection.on('error', () => {});
+      connecting = connection
+        .connect()
+        .then(() => connection)
+        .catch(() => {
+          if (connection.isOpen) connection.destroy();
+          if (current === connection) {
+            current = undefined;
+            connecting = undefined;
+          }
+          throw new SessionStorageUnavailableError();
+        });
+    }
+    const connection = await connecting;
+    if (closed || !connection.isReady) {
+      if (connection.isOpen) connection.destroy();
+      if (current === connection) {
+        current = undefined;
+        connecting = undefined;
+      }
+      throw new SessionStorageUnavailableError();
+    }
+    return connection;
+  }
+  return Object.freeze({
+    close() {
+      closed = true;
+      if (current?.isOpen) current.destroy();
+      current = undefined;
+      connecting = undefined;
+    },
+    async eval(script: string, command: { keys: string[]; arguments: string[] }): Promise<unknown> {
+      if (
+        typeof script !== 'string' ||
+        script.length > 16384 ||
+        !Array.isArray(command.keys) ||
+        !Array.isArray(command.arguments) ||
+        command.keys.length > 16 ||
+        command.arguments.length > 32 ||
+        command.keys.some((key: unknown) => typeof key !== 'string' || key.length > 1024) ||
+        command.arguments.some(
+          (argument: unknown) => typeof argument !== 'string' || argument.length > 40000,
+        )
+      ) {
+        throw new SessionStorageUnavailableError();
+      }
+      const keys = [...command.keys],
+        arguments_ = [...command.arguments];
+      const controller = new AbortController();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new SessionStorageUnavailableError());
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([
+          (async () => {
+            const connection = await client();
+            if (controller.signal.aborted) throw new SessionStorageUnavailableError();
+            return await connection.withAbortSignal(controller.signal).eval(script, {
+              keys,
+              arguments: arguments_,
+            });
+          })(),
+          deadline,
+        ]);
+      } catch {
+        throw new SessionStorageUnavailableError();
+      } finally {
+        clearTimeout(timer);
+        controller.abort();
+      }
+    },
+  });
+}

package/dist/templates/recipes/oidc-resource-server/README.md.hbs

@@ -0,0 +1,74 @@
+# OIDC resource-server JWT verification
+
+Generate with:
+
+```bash
+ddd recipe oidc-resource-server --path <service> --dry-run
+ddd recipe oidc-resource-server --path <service>
+```
+
+Dry-run writes nothing. Conflicting files abort before writes; identical reruns
+leave files alone. No module is auto-wired and no dependency is added: the
+verifier uses NestJS plus the Node/Bun `node:crypto` and Fetch APIs already
+available to the service.
+
+## Runtime registration
+
+Prefer `registerAsync` so deployment configuration passes through the owning
+service's validated configuration boundary:
+
+```ts
+OidcResourceServerModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService): OidcResourceServerOptions => ({
+    issuer: config.getOrThrow<string>('OIDC_ISSUER'),
+    jwksUri: config.getOrThrow<string>('OIDC_JWKS_URI'),
+    audiences: [config.getOrThrow<string>('OIDC_RESOURCE_AUDIENCE')],
+    authorizedClients: [config.getOrThrow<string>('OIDC_AUTHORIZED_CLIENT_ID')],
+    clockToleranceSeconds: 5,
+  }),
+})
+```
+
+Static `register(options)` remains available for already-validated in-memory
+configuration and focused tests. The barrel exports:
+
+- `OidcResourceServerModule`
+- `OidcResourceServerModuleAsyncOptions`
+- `OIDC_RESOURCE_SERVER_OPTIONS`
+- `OidcResourceServerOptions`
+- `OidcAccessTokenVerifier`
+- `VerifiedOidcAccessToken`
+
+Inject `OidcAccessTokenVerifier` and call `verify(originalAccessToken)`.
+
+All URLs must be explicitly trusted HTTPS URLs from deployment configuration,
+never request data. Audiences are resource/API audiences, not automatically
+browser client IDs. Client allowlisting reads the issuer's `azp` claim.
+
+The verifier deliberately supports RS256 only. It validates the signature,
+exact issuer, resource audience, authorized client, nonempty subject, finite
+required `exp`/`iat`, and optional `nbf`. Clock skew is bounded to 0..60 seconds.
+Tokens, individual segments, JWKS bodies, JWKS key counts, RSA modulus sizes,
+timeouts, cache lifetime, and unknown-key refresh frequency are bounded. Key
+selection is by `kid`; rotation refreshes the JWKS after a controlled cooldown.
+Fetch, parse, timeout, redirect, key-import, key-selection, and signature errors
+all fail closed. Authentication errors never include bearer tokens, claims, keys,
+or upstream response bodies.
+
+The generated `oidc-access-token-verifier.spec.ts` uses real RSA keys and should
+remain in the consuming repository. It proves valid verification plus rejection
+of wrong signatures, algorithms, issuers, audiences, clients, subjects, times,
+missing required claims, a typical ID-token substitute, and rotated keys.
+
+This verifies a JWT, not universal proof that it is an access token. Issuers can
+issue ID and access tokens with overlapping signed claims. The consumer MUST
+enforce its selected provider access-token profile and current actor validation
+before granting access. A valid ID token is never an API credential. Do not map
+returned roles/groups to product permissions implicitly. HUMAN versus machine,
+current organization, canonical identity binding, staff membership, revocation,
+and transactional authorization belong to the consuming service.
+
+Runtime baseline: Node 18+ or Bun with standards-compatible `fetch`, Web Streams,
+and `node:crypto` JWK import. No package-manager or lockfile migration is required.

package/dist/templates/recipes/oidc-resource-server/index.ts.hbs

@@ -0,0 +1,2 @@
+export * from './oidc-access-token-verifier';
+export * from './oidc-resource-server.module';

package/dist/templates/recipes/oidc-resource-server/module.ts.hbs

@@ -0,0 +1,51 @@
+import {
+  DynamicModule,
+  FactoryProvider,
+  Module,
+  ModuleMetadata,
+} from '@nestjs/common';
+import {
+  OIDC_RESOURCE_SERVER_OPTIONS,
+  OidcAccessTokenVerifier,
+  OidcResourceServerOptions,
+} from './oidc-access-token-verifier';
+
+export interface OidcResourceServerModuleAsyncOptions
+  extends Pick<ModuleMetadata, 'imports'> {
+  inject?: FactoryProvider<OidcResourceServerOptions>['inject'];
+  useFactory: FactoryProvider<OidcResourceServerOptions>['useFactory'];
+}
+
+const verifierProvider: FactoryProvider<OidcAccessTokenVerifier> = {
+  provide: OidcAccessTokenVerifier,
+  inject: [OIDC_RESOURCE_SERVER_OPTIONS],
+  useFactory: (options: OidcResourceServerOptions) => new OidcAccessTokenVerifier(options),
+};
+
+@Module({})
+export class OidcResourceServerModule {
+  static register(options: OidcResourceServerOptions): DynamicModule {
+    return {
+      module: OidcResourceServerModule,
+      providers: [
+        { provide: OIDC_RESOURCE_SERVER_OPTIONS, useValue: options },
+        verifierProvider,
+      ],
+      exports: [OidcAccessTokenVerifier],
+    };
+  }
+
+  static registerAsync(options: OidcResourceServerModuleAsyncOptions): DynamicModule {
+    const optionsProvider: FactoryProvider<OidcResourceServerOptions> = {
+      provide: OIDC_RESOURCE_SERVER_OPTIONS,
+      inject: options.inject ?? [],
+      useFactory: options.useFactory,
+    };
+    return {
+      module: OidcResourceServerModule,
+      imports: options.imports ?? [],
+      providers: [optionsProvider, verifierProvider],
+      exports: [OidcAccessTokenVerifier],
+    };
+  }
+}

package/dist/templates/recipes/oidc-resource-server/verifier.spec.ts.hbs

@@ -0,0 +1,186 @@
+import {
+  constants,
+  generateKeyPairSync,
+  KeyObject,
+  sign as signPayload,
+} from 'node:crypto';
+import {
+  OidcAccessTokenVerifier,
+  OidcResourceServerOptions,
+} from './oidc-access-token-verifier';
+
+function encode(value: unknown): string {
+  return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+
+function signedToken(
+  claims: Record<string, unknown>,
+  privateKey: KeyObject,
+  header: Record<string, unknown> = { alg: 'RS256', kid: 'trusted' },
+): string {
+  const encodedHeader = encode(header);
+  const encodedPayload = encode(claims);
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signature = signPayload('RSA-SHA256', Buffer.from(signingInput, 'ascii'), {
+    key: privateKey,
+    padding: constants.RSA_PKCS1_PADDING,
+  });
+  return `${signingInput}.${signature.toString('base64url')}`;
+}
+
+describe('OidcAccessTokenVerifier', () => {
+  const trusted = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const wrong = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const rotated = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const trustedJwk = {
+    ...trusted.publicKey.export({ format: 'jwk' }),
+    kid: 'trusted',
+    alg: 'RS256',
+    use: 'sig',
+  };
+  const rotatedJwk = {
+    ...rotated.publicKey.export({ format: 'jwk' }),
+    kid: 'rotated',
+    alg: 'RS256',
+    use: 'sig',
+  };
+  const options: OidcResourceServerOptions = {
+    issuer: 'https://issuer.example',
+    jwksUri: 'https://issuer.example/keys',
+    audiences: ['resource-project'],
+    authorizedClients: ['ops-client'],
+    clockToleranceSeconds: 0,
+    jwksRefreshCooldownSeconds: 1,
+  };
+  const originalFetch = globalThis.fetch;
+  let publishedKeys: unknown[];
+  let requests: number;
+
+  beforeEach(() => {
+    publishedKeys = [trustedJwk];
+    requests = 0;
+    globalThis.fetch = (input) => {
+      expect(String(input)).toBe(options.jwksUri);
+      requests += 1;
+      return Promise.resolve(
+        new Response(JSON.stringify({ keys: publishedKeys }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+  });
+
+  afterAll(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function claims(patch: Record<string, unknown> = {}): Record<string, unknown> {
+    const now = Math.floor(Date.now() / 1000);
+    return {
+      sub: 'synthetic-human',
+      iss: options.issuer,
+      aud: ['resource-project'],
+      azp: 'ops-client',
+      iat: now,
+      exp: now + 300,
+      nbf: now - 1,
+      ...patch,
+    };
+  }
+
+  it('verifies RS256 and reuses the cached kid', async () => {
+    const verifier = new OidcAccessTokenVerifier(options);
+    await expect(verifier.verify(signedToken(claims(), trusted.privateKey))).resolves.toMatchObject({
+      sub: 'synthetic-human',
+    });
+    await expect(verifier.verify(signedToken(claims(), trusted.privateKey))).resolves.toBeDefined();
+    expect(requests).toBe(1);
+  });
+
+  it.each([
+    ['algorithm', claims(), { alg: 'HS256', kid: 'trusted' }],
+    ['issuer', claims({ iss: 'https://wrong.example' }), undefined],
+    ['audience', claims({ aud: 'browser-client' }), undefined],
+    ['authorized client', claims({ azp: 'sibling-client' }), undefined],
+    ['subject', claims({ sub: '   ' }), undefined],
+    ['expired timestamp', claims({ exp: 1 }), undefined],
+    ['future issued-at timestamp', claims({ iat: Date.now() / 1000 + 90 }), undefined],
+    ['future not-before timestamp', claims({ nbf: Date.now() / 1000 + 90 }), undefined],
+    // A typical ID token is audience-bound to the browser client, not this API resource.
+    ['ID-token substitute', claims({ aud: 'ops-client', nonce: 'browser-session' }), undefined],
+  ])('rejects the wrong %s', async (_case, tokenClaims, header) => {
+    const verifier = new OidcAccessTokenVerifier(options);
+    await expect(
+      verifier.verify(signedToken(tokenClaims, trusted.privateKey, header)),
+    ).rejects.toThrow('Invalid resource access token');
+  });
+
+  it('rejects a wrong signature without leaking token material', async () => {
+    const token = signedToken(claims(), wrong.privateKey);
+    const verifier = new OidcAccessTokenVerifier(options);
+    let message = '';
+    try {
+      await verifier.verify(token);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toBe('Invalid resource access token');
+    expect(message).not.toContain(token);
+    expect(message).not.toContain('synthetic-human');
+  });
+
+  it.each(['sub', 'exp', 'iat', 'azp', 'iss', 'aud'])('rejects a missing %s claim', async (claim) => {
+    const payload = claims();
+    delete payload[claim];
+    const verifier = new OidcAccessTokenVerifier(options);
+    await expect(verifier.verify(signedToken(payload, trusted.privateKey))).rejects.toThrow(
+      'Invalid resource access token',
+    );
+  });
+
+  it('refreshes by kid when the issuer rotates keys', async () => {
+    const verifier = new OidcAccessTokenVerifier(options);
+    await verifier.verify(signedToken(claims(), trusted.privateKey));
+    publishedKeys = [rotatedJwk];
+    const currentTime = Date.now();
+    const now = jest.spyOn(Date, 'now').mockReturnValue(currentTime + 1100);
+    try {
+      await expect(
+        verifier.verify(
+          signedToken(claims(), rotated.privateKey, { alg: 'RS256', kid: 'rotated' }),
+        ),
+      ).resolves.toBeDefined();
+    } finally {
+      now.mockRestore();
+    }
+    expect(requests).toBe(2);
+  });
+
+  it('rejects unsafe configuration before any network request', () => {
+    expect(() =>
+      new OidcAccessTokenVerifier({ ...options, issuer: 'http://issuer.example' }),
+    ).toThrow();
+    expect(() => new OidcAccessTokenVerifier({ ...options, audiences: [] })).toThrow();
+    expect(() => new OidcAccessTokenVerifier({ ...options, authorizedClients: [] })).toThrow();
+    expect(() =>
+      new OidcAccessTokenVerifier({ ...options, clockToleranceSeconds: 61 }),
+    ).toThrow();
+    expect(() =>
+      new OidcAccessTokenVerifier({ ...options, jwksRefreshCooldownSeconds: 0 }),
+    ).toThrow();
+    expect(requests).toBe(0);
+  });
+
+  it('fails closed and rate-limits repeated JWKS outage retries', async () => {
+    globalThis.fetch = () => {
+      requests += 1;
+      return Promise.reject(new Error('offline with upstream details'));
+    };
+    const verifier = new OidcAccessTokenVerifier(options);
+    const token = signedToken(claims(), trusted.privateKey);
+    await expect(verifier.verify(token)).rejects.toThrow('Invalid resource access token');
+    await expect(verifier.verify(token)).rejects.toThrow('Invalid resource access token');
+    expect(requests).toBe(1);
+  });
+});