nestjs-ddd-cli 3.2.1 → 3.3.0

package/dist/templates/recipes/oauth2-client-credentials/client.spec.ts.hbs

@@ -0,0 +1,234 @@
+import {
+  OAuth2ClientCredentialsClient,
+  OAuth2ClientCredentialsOptions,
+  OAuth2ClientCredentialsUnavailableError,
+} from './oauth2-client-credentials.client';
+import { OAuth2ClientCredentialsModule } from './oauth2-client-credentials.module';
+
+describe('OAuth2 client credentials', () => {
+  const response = (changes: Record<string, unknown> = {}) =>
+    new Response(
+      JSON.stringify({
+        access_token: 'PRIVATE_TOKEN',
+        token_type: 'Bearer',
+        expires_in: 3600,
+        ...changes,
+      }),
+    );
+  const create = (options: Partial<OAuth2ClientCredentialsOptions> = {}) =>
+    new OAuth2ClientCredentialsClient({
+      tokenUrl: 'https://provider.example.test/oauth/v3/token',
+      clientId: 'PRIVATE_ID',
+      clientSecret: 'PRIVATE_SECRET',
+      transport: () => Promise.resolve(response()),
+      ...options,
+    });
+
+  it('uses form encoded Basic components and a fixed form grant with snapshotted scopes', async () => {
+    const transport = jest.fn((_url: string, _init: RequestInit) => {
+      void _url;
+      void _init;
+      return Promise.resolve(response());
+    });
+    const scopes = ['messages.send'];
+    const client = create({
+      clientId: 'client:with space',
+      clientSecret: 'secret+value',
+      scopes,
+      transport,
+    });
+    scopes.push('admin');
+    expect(await client.getAccessToken()).toBe('PRIVATE_TOKEN');
+    const call = transport.mock.calls[0];
+    if (!call) throw new Error('Missing provider request');
+    expect(call[0]).toBe('https://provider.example.test/oauth/v3/token');
+    expect(call[1]).toMatchObject({
+      method: 'POST',
+      redirect: 'error',
+      cache: 'no-store',
+      body: 'grant_type=client_credentials&scope=messages.send',
+    });
+    expect(call[1].headers).toMatchObject({
+      authorization: `Basic ${Buffer.from('client%3Awith+space:secret%2Bvalue').toString('base64')}`,
+      'content-type': 'application/x-www-form-urlencoded',
+    });
+    expect(JSON.stringify(client)).toBe('{}');
+  });
+
+  it('shares concurrent acquisition then caches the same current token', async () => {
+    let release: ((value: Response) => void) | undefined;
+    const transport = jest.fn(
+      () =>
+        new Promise<Response>((resolve) => {
+          release = resolve;
+        }),
+    );
+    const client = create({ transport });
+    const results = Array.from({ length: 20 }, () => client.getAccessToken());
+    expect(transport).toHaveBeenCalledTimes(1);
+    if (!release) throw new Error('Missing grant');
+    release(response());
+    expect(await Promise.all(results)).toEqual(
+      Array.from({ length: 20 }, () => 'PRIVATE_TOKEN'),
+    );
+    expect(await client.getAccessToken()).toBe('PRIVATE_TOKEN');
+    expect(transport).toHaveBeenCalledTimes(1);
+  });
+
+  it('renews at request-start expiry with a conservative lifetime margin', async () => {
+    let now = 1000;
+    let count = 0;
+    const transport = jest.fn(() =>
+      Promise.resolve(
+        response({ access_token: `token${++count}`, expires_in: 10 }),
+      ),
+    );
+    const client = create({ clock: () => now, transport });
+    expect(await client.getAccessToken()).toBe('token1');
+    now = 9999;
+    expect(await client.getAccessToken()).toBe('token1');
+    now = 10000;
+    expect(await client.getAccessToken()).toBe('token2');
+    expect(transport).toHaveBeenCalledTimes(2);
+  });
+
+  it('compare-token invalidation preserves a newer cache and never resends anything', async () => {
+    let count = 0;
+    const transport = jest.fn(() =>
+      Promise.resolve(response({ access_token: `token${++count}` })),
+    );
+    const client = create({ transport });
+    const old = await client.getAccessToken();
+    client.invalidate(old);
+    const current = await client.getAccessToken();
+    client.invalidate(old);
+    expect(await client.getAccessToken()).toBe(current);
+    expect(transport).toHaveBeenCalledTimes(2);
+  });
+
+  it('clears failed single-flight state, rejects stale cache and does not implicitly retry', async () => {
+    let now = 1000;
+    const transport = jest
+      .fn()
+      .mockImplementationOnce(() =>
+        Promise.resolve(response({ expires_in: 1 })),
+      )
+      .mockImplementationOnce(() =>
+        Promise.resolve(new Response('PRIVATE_RESPONSE', { status: 503 })),
+      )
+      .mockImplementationOnce(() => Promise.resolve(response()));
+    const client = create({ transport, clock: () => now });
+    await client.getAccessToken();
+    now = 2000;
+    const error = await client
+      .getAccessToken()
+      .catch((value: unknown) => value);
+    expect(error).toBeInstanceOf(OAuth2ClientCredentialsUnavailableError);
+    expect(error).toMatchObject({
+      message: 'Provider credentials unavailable',
+      reason: 'http',
+      status: 503,
+    });
+    expect(String(error)).not.toContain('PRIVATE');
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(await client.getAccessToken()).toBe('PRIVATE_TOKEN');
+    expect(transport).toHaveBeenCalledTimes(3);
+  });
+
+  it('requires explicit decimal-string expiry compatibility', async () => {
+    const transport = () => Promise.resolve(response({ expires_in: '3600' }));
+    await expect(create({ transport }).getAccessToken()).rejects.toMatchObject({
+      reason: 'invalid_response',
+    });
+    expect(
+      await create({ transport, allowStringExpiresIn: true }).getAccessToken(),
+    ).toBe('PRIVATE_TOKEN');
+  });
+
+  it.each([
+    { access_token: '' },
+    { access_token: 'PRIVATE\nTOKEN' },
+    { access_token: 'x'.repeat(17000) },
+    { token_type: 'MAC' },
+    { expires_in: undefined },
+    { expires_in: 0 },
+    { expires_in: -1 },
+    { expires_in: 90000 },
+    { expires_in: 1.5 },
+    { expires_in: '3600.0' },
+  ])('rejects invalid provider token contracts safely', async (changes) => {
+    await expect(
+      create({
+        transport: () => Promise.resolve(response(changes)),
+      }).getAccessToken(),
+    ).rejects.toMatchObject({
+      message: 'Provider credentials unavailable',
+      reason: 'invalid_response',
+    });
+  });
+
+  it('rejects tokens which expired during acquisition and invalid clock evidence', async () => {
+    let now = 1000;
+    await expect(
+      create({
+        clock: () => now,
+        transport: () => {
+          now = 5000;
+          return Promise.resolve(response({ expires_in: 1 }));
+        },
+      }).getAccessToken(),
+    ).rejects.toMatchObject({ reason: 'invalid_response' });
+    await expect(
+      create({ clock: () => NaN }).getAccessToken(),
+    ).rejects.toMatchObject({ reason: 'invalid_response' });
+  });
+
+  it.each([
+    { tokenUrl: 'http://provider.example.test/token' },
+    { tokenUrl: 'https://PRIVATE@provider.example.test/token' },
+    { tokenUrl: 'https://provider.example.test/token?PRIVATE' },
+    { tokenUrl: 'https://provider.example.test/' },
+    { tokenUrl: 'https://provider.example.test/%2E%2E/token' },
+    { clientId: '' },
+    { clientSecret: '' },
+    { scopes: ['scope with space'] },
+    { scopes: ['x', 'x'] },
+    { renewalMarginMs: 60001 },
+  ])('rejects unsafe configuration without exposing values', (options) => {
+    expect(() => create(options)).toThrow(
+      'Invalid provider credential configuration',
+    );
+  });
+
+  it('bounds grant network/stream timeouts and sanitizes unexpected transport failures', async () => {
+    await expect(
+      create({
+        timeoutMs: 10,
+        transport: () => new Promise<Response>(() => undefined),
+      }).getAccessToken(),
+    ).rejects.toMatchObject({ reason: 'timeout' });
+    await expect(
+      create({
+        transport: () => Promise.reject(new Error('PRIVATE_CREDENTIALS')),
+      }).getAccessToken(),
+    ).rejects.toMatchObject({
+      message: 'Provider credentials unavailable',
+      reason: 'network',
+    });
+  });
+
+  it('exports one owning sync/async Nest provider without app wiring', () => {
+    const options = {
+      tokenUrl: 'https://provider.example.test/token',
+      clientId: 'id',
+      clientSecret: 'secret',
+    };
+    expect(OAuth2ClientCredentialsModule.register(options).exports).toEqual([
+      OAuth2ClientCredentialsClient,
+    ]);
+    expect(
+      OAuth2ClientCredentialsModule.registerAsync({ useFactory: () => options })
+        .exports,
+    ).toEqual([OAuth2ClientCredentialsClient]);
+  });
+});

package/dist/templates/recipes/oauth2-client-credentials/client.ts.hbs

@@ -0,0 +1,210 @@
+import {
+  BoundedJsonHttpClient,
+  BoundedJsonHttpUnavailableError,
+} from '../oauth2-token-introspection/bounded-json-http.client';
+
+export const OAUTH2_CLIENT_CREDENTIALS_OPTIONS = Symbol(
+  'OAUTH2_CLIENT_CREDENTIALS_OPTIONS',
+);
+
+export interface OAuth2ClientCredentialsOptions {
+  tokenUrl: string;
+  clientId: string;
+  clientSecret: string;
+  scopes?: readonly string[];
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  maxTokenBytes?: number;
+  renewalMarginMs?: number;
+  /** Explicit compatibility for providers documenting decimal-string lifetimes. */
+  allowStringExpiresIn?: boolean;
+  transport?: (url: string, init: RequestInit) => Promise<Response>;
+  clock?: () => number;
+}
+
+export class OAuth2ClientCredentialsUnavailableError extends Error {
+  constructor(
+    readonly reason: 'timeout' | 'network' | 'http' | 'invalid_response',
+    readonly status?: number,
+  ) {
+    super('Provider credentials unavailable');
+    this.name = 'OAuth2ClientCredentialsUnavailableError';
+  }
+}
+
+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 formComponent(value: string): string {
+  return new URLSearchParams({ v: value }).toString().slice(2);
+}
+
+function isScopeList(value: unknown): value is readonly string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= 32 &&
+    value.every(
+      (scope: unknown) =>
+        typeof scope === 'string' &&
+        scope.length > 0 &&
+        scope.length <= 200 &&
+        ![...scope].some(
+          (c) =>
+            c.charCodeAt(0) < 33 ||
+            c.charCodeAt(0) > 126 ||
+            c === '"' ||
+            c === '\\',
+        ),
+    )
+  );
+}
+
+/** Grant acquisition only. Consumers own authorization and provider side effects. */
+export class OAuth2ClientCredentialsClient {
+  readonly #http: BoundedJsonHttpClient;
+  readonly #segments: readonly string[];
+  readonly #form: Readonly<Record<string, string>>;
+  readonly #clock: () => number;
+  readonly #margin: number;
+  readonly #maxTokenBytes: number;
+  readonly #allowStringExpiry: boolean;
+  #cached?: { token: string; refreshAt: number };
+  #inFlight?: Promise<string>;
+
+  constructor(options: OAuth2ClientCredentialsOptions) {
+    try {
+      const url = new URL(options.tokenUrl);
+      if (
+        url.href !== options.tokenUrl ||
+        url.href.length > 8192 ||
+        url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        url.search ||
+        url.pathname === '/'
+      )
+        throw new Error();
+      for (const value of [options.clientId, options.clientSecret]) {
+        if (typeof value !== 'string' || !value.length || value.length > 4096)
+          throw new Error();
+      }
+      const scopes = options.scopes ?? [];
+      if (!isScopeList(scopes) || new Set(scopes).size !== scopes.length)
+        throw new Error();
+      if (
+        options.allowStringExpiresIn !== undefined &&
+        typeof options.allowStringExpiresIn !== 'boolean'
+      )
+        throw new Error();
+      this.#segments = Object.freeze(
+        url.pathname
+          .slice(1)
+          .split('/')
+          .map((segment) => decodeURIComponent(segment)),
+      );
+      if (
+        this.#segments.some(
+          (segment) => !segment || ['.', '..'].includes(segment),
+        )
+      )
+        throw new Error();
+      this.#http = new BoundedJsonHttpClient({
+        origin: url.origin,
+        requestHeaders: {
+          authorization: `Basic ${Buffer.from(`${formComponent(options.clientId)}:${formComponent(options.clientSecret)}`).toString('base64')}`,
+        },
+        timeoutMs: options.timeoutMs,
+        maxResponseBytes: options.maxResponseBytes,
+        transport: options.transport,
+      });
+      this.#form = Object.freeze({
+        grant_type: 'client_credentials',
+        ...(scopes.length ? { scope: scopes.join(' ') } : {}),
+      });
+      this.#clock = options.clock ?? (() => Math.floor(performance.now()));
+      if (typeof this.#clock !== 'function') throw new Error();
+      this.#margin = bounded(options.renewalMarginMs, 30000, 0, 60000);
+      this.#maxTokenBytes = bounded(options.maxTokenBytes, 16384, 1, 65536);
+      this.#allowStringExpiry = options.allowStringExpiresIn === true;
+    } catch {
+      throw new Error('Invalid provider credential configuration');
+    }
+  }
+
+  getAccessToken(): Promise<string> {
+    const now = this.#clock();
+    if (!Number.isSafeInteger(now) || now < 0)
+      return Promise.reject(
+        new OAuth2ClientCredentialsUnavailableError('invalid_response'),
+      );
+    if (this.#cached && now < this.#cached.refreshAt)
+      return Promise.resolve(this.#cached.token);
+    this.#cached = undefined;
+    this.#inFlight ??= this.acquire(now).finally(() => {
+      this.#inFlight = undefined;
+    });
+    return this.#inFlight;
+  }
+
+  /** A late rejection of token A must not evict a newer token B. No retry occurs. */
+  invalidate(rejectedToken: string): void {
+    if (this.#cached?.token === rejectedToken) this.#cached = undefined;
+  }
+
+  private async acquire(startedAt: number): Promise<string> {
+    try {
+      const result = await this.#http.postForm(this.#segments, this.#form);
+      if (!result || typeof result !== 'object' || Array.isArray(result))
+        throw new OAuth2ClientCredentialsUnavailableError('invalid_response');
+      const body = result as Record<string, unknown>;
+      const token = body['access_token'];
+      const tokenType = body['token_type'];
+      const lifetime = body['expires_in'];
+      const seconds =
+        this.#allowStringExpiry &&
+        typeof lifetime === 'string' &&
+        /^[1-9][0-9]{0,4}$/.test(lifetime)
+          ? Number(lifetime)
+          : lifetime;
+      if (
+        typeof token !== 'string' ||
+        !token.length ||
+        new TextEncoder().encode(token).byteLength > this.#maxTokenBytes ||
+        [...token].some((c) => c.charCodeAt(0) < 33 || c.charCodeAt(0) > 126) ||
+        typeof tokenType !== 'string' ||
+        tokenType.toLowerCase() !== 'bearer' ||
+        typeof seconds !== 'number' ||
+        !Number.isSafeInteger(seconds) ||
+        seconds < 1 ||
+        seconds > 86400
+      )
+        throw new OAuth2ClientCredentialsUnavailableError('invalid_response');
+      const ttl = seconds * 1000;
+      const refreshAt =
+        startedAt + ttl - Math.min(this.#margin, Math.floor(ttl / 10));
+      const now = this.#clock();
+      if (!Number.isSafeInteger(now) || now < startedAt || now >= refreshAt)
+        throw new OAuth2ClientCredentialsUnavailableError('invalid_response');
+      this.#cached = { token, refreshAt };
+      return token;
+    } catch (error) {
+      if (error instanceof OAuth2ClientCredentialsUnavailableError) throw error;
+      if (error instanceof BoundedJsonHttpUnavailableError)
+        throw new OAuth2ClientCredentialsUnavailableError(
+          error.reason,
+          error.status,
+        );
+      throw new OAuth2ClientCredentialsUnavailableError('network');
+    }
+  }
+}

package/dist/templates/recipes/oauth2-client-credentials/index.ts.hbs

@@ -0,0 +1,2 @@
+export * from './oauth2-client-credentials.client';
+export * from './oauth2-client-credentials.module';

package/dist/templates/recipes/oauth2-client-credentials/module.ts.hbs

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

package/dist/templates/recipes/oauth2-token-introspection/README.md.hbs

@@ -0,0 +1,158 @@
+# OAuth2 token introspection
+
+```sh
+ddd recipe oauth2-token-introspection --path <service> --dry-run
+ddd recipe oauth2-token-introspection --path <service>
+```
+
+The recipe adds a dependency-free RFC7662 client, sync/async Nest module, barrel,
+consumer tests and this document. It does not wire AppModule, install packages,
+change lockfiles or grant access. Dry-run writes nothing. All targets are checked
+before writes; differing files and symlinks fail closed, identical reruns are
+untouched, and failed writes roll back unchanged files created by this invocation.
+Rollback checks inode, timestamps and content; concurrent owner changes are
+preserved and reported as an explicit rollback conflict.
+
+## Configuration and composition
+
+Import the owning module; do not redeclare its exported client in a consumer.
+
+```ts
+OAuth2TokenIntrospectionModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService): OAuth2TokenIntrospectionOptions => ({
+    introspectionUrl: config.getOrThrow<string>('OAUTH2_INTROSPECTION_URL'),
+    requestHeaders: { authorization: config.getOrThrow<string>('OAUTH2_INTROSPECTION_AUTHORIZATION') },
+    timeoutMs: 3000,
+  }),
+})
+```
+
+Set the exact trusted URL and required provider authentication headers from
+validated deployment configuration. Never derive the URL or headers from a
+request. HTTPS is the default. Credentials, queries and fragments in the URL
+are rejected; redirects are disabled. For a verified private HTTP endpoint,
+explicitly set `trustedInternalHttp: true`. For example, self-hosted Hydra v26.2.0
+can use `http://hydra-admin.ory-staging.svc.cluster.local:4445/admin/oauth2/introspect`.
+This opt-in does not add TLS or secure a cluster: the operator must establish
+private routing and network policy and keep admin ports off public ingress.
+Hydra's admin listener uses private network protection; do not assume a Basic
+header authenticates it. Omit `requestHeaders` when the selected server does not
+require them. No introspection endpoint is discovered from token contents.
+
+Options snapshot URL/headers and bound timeout (10..30000 ms, default 3000),
+response bytes (128..1048576, default 65536) and token bytes (1..65536, default
+16384). Tokens must be nonempty visible ASCII without a Bearer prefix. A timeout
+includes transport and response streaming; even a noncompliant transport cannot
+hold the caller indefinitely. `transport(url, RequestInit)` is an injectable
+Fetch-compatible seam for tests or an owned transport; it must honor the URL,
+AbortSignal and redirect policy. No retries or positive-validation cache exist.
+Every call rechecks the provider. Runtime baseline is Node 18+ or Bun with Fetch
+and Web Streams; no consumer dependency installation is needed.
+
+## Bounded provider JSON GET
+
+The barrel also exports `BoundedJsonHttpClient`, its options and
+`BoundedJsonHttpUnavailableError`. Introspection delegates to this same mechanism;
+provider adapters do not need to copy timeout, stream limits or HTTP error logic.
+Each instance has an exact trusted origin from validated deployment config, with
+no path, query, fragment or credentials. Its GET API accepts path segments and a
+bounded query record; it percent-encodes segments and rejects dot traversal.
+No call can select another origin. No bearer token or body is sent on GET.
+
+```ts
+const kratos = new BoundedJsonHttpClient({
+  origin: config.getOrThrow<string>('KRATOS_ADMIN_ORIGIN'),
+  trustedInternalHttp: true, // only for the verified private cluster endpoint
+  timeoutMs: 3000,
+});
+// The owning adapter validates sessionId/identityId as UUIDs before these calls.
+const sessionJson = await kratos.get(['admin', 'sessions', sessionId], { expand: 'identity' });
+const identityJson = await kratos.get(['admin', 'identities', identityId]);
+```
+
+Use only configured origin and fixed resource route segments, followed by encoded
+identifiers validated by the consumer. Never pass an origin from request data.
+The return type is unknown JSON; the consumer validates provider schema, active
+session/identity, expiry, assurance, binding and authorization. The mechanism
+does not infer account status from JSON. Transport errors retain safe reason and
+optional numeric HTTP status, so the adapter can distinguish a missing session
+from upstream unavailability without inspecting or logging response bodies.
+The helper also exposes bounded `postForm` for the introspection client and
+`postJson`/`patchJson`/`putJson` for explicit consumer-owned JSON endpoints. JSON is
+snapshotted before dispatch, validated against the same byte/depth/value bounds,
+and sent once to the configured origin with no redirects or retries. It
+applies the same origin, redirect, timeout, byte, nesting and no-cache rules.
+
+`putJson(pathSegments, payload, query = {})` also accepts the same bounded query
+record as GET. For example, Hydra login/consent accept and reject APIs use a
+JSON PUT body with the challenge in a query parameter:
+
+```ts
+const result = await hydra.putJson(
+  ['admin', 'oauth2', 'auth', 'requests', 'login', 'accept'],
+  { subject: validatedKratosIdentityId, remember: false },
+  { login_challenge: validatedLoginChallenge },
+);
+```
+
+The adapter must first verify the challenge, exact client/scopes/audience,
+current Kratos session and canonical admission policy. A successful transport
+request establishes none of those facts. Challenge query values are snapshotted
+and encoded before dispatch; failed or uncertain decisions are not retried.
+
+## Evidence and consumer policy
+
+`introspect(originalAccessToken)` POSTs form-encoded `token` and
+`token_type_hint=access_token`. The hint does not prove token kind. Active false
+throws `InvalidOAuth2TokenError`; active true returns immutable evidence with
+optional issuer, subject, client ID, numeric dates, token type/use, audience and
+scope arrays, raw claims, and provider extensions. RFC7662 permits missing
+claims; the client does not invent them or map them into people or permissions.
+
+Prefer `validate(token, policy)` to return only a consumer-approved principal:
+
+```ts
+const principal = await client.validate(token, {
+  validate: async (evidence) => {
+    // The owner must enforce the selected provider's required issuer, resource
+    // audience, authorized client, time, access-token profile and actor contract.
+    // Then check canonical identity, current session/revocation and domain scope.
+    if (evidence.issuer !== trustedIssuer || evidence.tokenUse !== 'access_token') {
+      throw new InvalidOAuth2TokenError('policy_rejected');
+    }
+    return owningAdmissionPolicy.resolve(evidence);
+  },
+});
+```
+
+The example delegates the remaining checks; matching issuer and token_use alone
+is insufficient. No generic grant-type or human/machine inference is made.
+ZITADEL JWT validation remains a separate supported recipe; this transport must
+not become an automatic fallback after a rejected token. For Hydra v26.2.0,
+introspection returns `client_id`, `token_use`, `aud` and `ext`; arbitrary
+consent `session.access_token` data is returned in `ext` and carried through
+refresh grants. A Kratos binding in that data is a consumer-defined convention,
+not a built-in introspection session field. Hydra and Kratos session revocation
+are separate; the owner must validate any bound Kratos session independently.
+
+## Failures and proof
+
+`InvalidOAuth2TokenError` means malformed, inactive or explicitly policy-rejected
+credentials; map to the consumer's denial response. `OAuth2IntrospectionUnavailableError`
+means timeout, transport, HTTP, malformed upstream response or unexpected policy
+failure; deny access while distinguishing an unavailable validator operationally.
+Errors contain fixed messages and safe reason enums, never tokens, headers,
+claims, URLs or upstream bodies. The client performs no logging. Explicit policy
+errors preserve these safe classes; unexpected exceptions are sanitized.
+Policy implementations own their own I/O limits and must not log credentials.
+
+The generated spec verifies wire format, immutable evidence, no validation
+cache, denial, HTTP opt-in, malformed/bounded responses, hangs, error redaction,
+consumer policy and module ownership. It proves a transport contract, not
+deployment, provider authentication, clinical permissions or real actor access.
+
+Sources: [RFC7662](https://www.rfc-editor.org/rfc/rfc7662),
+[pinned Hydra API](https://raw.githubusercontent.com/ory/hydra/v26.2.0/spec/api.json),
+[pinned Hydra admin server](https://raw.githubusercontent.com/ory/hydra/v26.2.0/cmd/server/handler.go).