@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/security/jwt/services/wildo-worker-bootstrap-client.backend.service.js

@@ -101,6 +101,19 @@ let WildoWorkerBootstrapClientService = class WildoWorkerBootstrapClientService
         this.cachedAt = 0;
         this.logDebug('WildoWorkerBootstrapClientService cache cleared');
     }
+    /**
+     * Hard deadline for the apps-manager bootstrap read.
+     *
+     * apps-manager is ours rather than a vendor's, which makes an unbounded wait here less likely and
+     * no less terminal: this runs at worker startup, and the `catch` below is the only thing that ever
+     * reports a failure — so a peer that accepts the connection and never answers does not produce a
+     * slow start, it produces a worker that never becomes ready and never says why.
+     *
+     * 10s because the response is a small JSON bootstrap document from a service on the same network:
+     * nothing legitimate here spends time moving bytes, and a longer bound would only lengthen the
+     * silence.
+     */
+    static BOOTSTRAP_REQUEST_TIMEOUT_MS = 10_000;
     async fetchBootstrap() {
         const url = this.buildBootstrapUrl();
         this.logDebug('Fetching worker bootstrap from apps-manager', { url });
@@ -122,6 +135,7 @@ let WildoWorkerBootstrapClientService = class WildoWorkerBootstrapClientService
                     [WildoHeaderKeys.PLATFORM_SECRET]: this.platformApplicationPrimarySecret,
                     [WildoHeaderKeys.APPLICATION_ID]: this.applicationId,
                 },
+                signal: AbortSignal.timeout(WildoWorkerBootstrapClientService_1.BOOTSTRAP_REQUEST_TIMEOUT_MS),
             });
         }
         catch (error) {

package/dist/esm/security/jwt/services/wildo-worker-bootstrap-client.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"wildo-worker-bootstrap-client.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/jwt/services/wildo-worker-bootstrap-client.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, injectable } from 'inversify';\nimport { AppWorkerBootstrapResponseSchema, type AppWorkerBootstrapResponse } from '@wildo-ai/platform-config-lib';\nimport { ErrorCustomMessageReference, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';\nimport { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { API_ROUTES_BACKEND_DEFINITIONS } from '~wildo-backend-lib/requests/models/api-routes.backend.defintions';\n\n/**\n * Worker-side dynamic resolver for the trusted `APPLICATION_WORKER_REQUEST`\n * public key. Per Q3 LOCKED of\n * `.claude/plans/minions-and-workers-implementation.md`, the Wildo worker\n * runtime fetches this key at boot from apps-manager and refreshes it on a\n * JWKS-style cadence — never burns a static key into the image.\n *\n * Lives in `saas-backend-lib` so the Node worker host\n * (`@wildo-ai/saas-workers-node-lib`) can DI-bind it without inventing a\n * parallel HTTP client; non-Node workers (Rust / Java) implement the same\n * fetch contract natively against the same `/apps-to-manager/workers/:workerName/bootstrap`\n * endpoint and the shipped `AppWorkerBootstrapResponseSchema` shape.\n *\n * Dependency-light by design (only `LoggerService` + `ErrorBuilderBackendService`)\n * so the worker DI container can pull it without dragging Mongo / Redis /\n * RabbitMQ bindings into the worker boundary (KD-3).\n */\n@injectable()\nexport class WildoWorkerBootstrapClientService {\n  /** Default JWKS-style refresh cadence: 1h between trusted-key polls. */\n  private static readonly DEFAULT_REFRESH_INTERVAL_MS = 60 * 60 * 1000;\n\n  private appsManagerBaseUrl?: string;\n  private workerName?: string;\n  private applicationId?: string;\n  /**\n   * Application primary secret used by `getAppDataWithVerification` on the\n   * apps-manager `apps-to-manager/workers/:workerName/bootstrap` endpoint\n   * (`x-platform-secret` header — APP_TO_PLATFORM origin per `PlatformRequestsBackendUtils`).\n   * Comes from the four-env bootstrap-env-contract Secret mounted via K8s\n   * `envFrom: secretRef: {appSlug}-secret`.\n   */\n  private platformApplicationPrimarySecret?: string;\n  private refreshIntervalMs = WildoWorkerBootstrapClientService.DEFAULT_REFRESH_INTERVAL_MS;\n  private cachedResponse?: AppWorkerBootstrapResponse;\n  private cachedAt = 0;\n  private isInitialized = false;\n\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)\n    private readonly errorBuilder: ErrorBuilderBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('WildoWorkerBootstrapClientService');\n    this.logger.setDebugTypeLogging('WildoWorkerBootstrapClientService', false);\n  }\n\n  initialize(input: {\n    appsManagerBaseUrl: string;\n    applicationId: string;\n    workerName: string;\n    /**\n     * `PLATFORM_APPLICATION_PRIMARY_SECRET` from the four-env bootstrap\n     * contract — required so the GET request is authenticated as\n     * `APP_TO_PLATFORM` per `PlatformRequestsBackendUtils.buildPlatformRequestContext`.\n     * Without it the apps-manager handler rejects the bootstrap fetch\n     * with `Missing X-Platform-Secret`.\n     */\n    platformApplicationPrimarySecret: string;\n    refreshIntervalMs?: number;\n  }): void {\n    this.appsManagerBaseUrl = stripTrailingSlash(input.appsManagerBaseUrl);\n    this.applicationId = input.applicationId;\n    this.workerName = input.workerName;\n    this.platformApplicationPrimarySecret = input.platformApplicationPrimarySecret;\n    if (input.refreshIntervalMs !== undefined) {\n      this.refreshIntervalMs = input.refreshIntervalMs;\n    }\n    this.isInitialized = true;\n    this.logDebug('WildoWorkerBootstrapClientService initialized', {\n      appsManagerBaseUrl: this.appsManagerBaseUrl,\n      applicationId: this.applicationId,\n      workerName: this.workerName,\n      refreshIntervalMs: this.refreshIntervalMs,\n    });\n  }\n\n  /**\n   * Returns the trusted public key + rotation metadata for verifying inbound\n   * `APPLICATION_WORKER_REQUEST` JWTs. Cached for `refreshIntervalMs`; the\n   * caller can force a fetch via `getBootstrap({ force: true })`.\n   */\n  public async getBootstrap(\n    options?: { force?: boolean },\n  ): Promise<AppWorkerBootstrapResponse> {\n    this.assertInitialized();\n    const force = options?.force === true;\n    if (!force && this.cachedResponse && Date.now() - this.cachedAt < this.refreshIntervalMs) {\n      return this.cachedResponse;\n    }\n    const fetched = await this.fetchBootstrap();\n    this.cachedResponse = fetched;\n    this.cachedAt = Date.now();\n    return fetched;\n  }\n\n  public clearCache(): void {\n    this.cachedResponse = undefined;\n    this.cachedAt = 0;\n    this.logDebug('WildoWorkerBootstrapClientService cache cleared');\n  }\n\n  private async fetchBootstrap(): Promise<AppWorkerBootstrapResponse> {\n    const url = this.buildBootstrapUrl();\n    this.logDebug('Fetching worker bootstrap from apps-manager', { url });\n\n    if (!this.platformApplicationPrimarySecret || !this.applicationId) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message:\n            'WildoWorkerBootstrapClientService is missing platformApplicationPrimarySecret or applicationId; ' +\n            'these come from the four-env bootstrap-env-contract Secret and are required so the apps-manager ' +\n            'handler accepts the request as APP_TO_PLATFORM.',\n        },\n      });\n    }\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          [WildoHeaderKeys.PLATFORM_SECRET]: this.platformApplicationPrimarySecret,\n          [WildoHeaderKeys.APPLICATION_ID]: this.applicationId,\n        },\n      });\n    } catch (error) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Failed to reach apps-manager worker-bootstrap endpoint',\n          url,\n          workerName: this.workerName,\n          applicationId: this.applicationId,\n          error: describeCaughtError(error),\n        },\n      });\n    }\n\n    if (!response.ok) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Apps-manager worker-bootstrap endpoint returned non-2xx',\n          status: response.status,\n          url,\n          workerName: this.workerName,\n          applicationId: this.applicationId,\n        },\n      });\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = await response.json();\n    } catch (error) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Apps-manager worker-bootstrap response was not valid JSON',\n          url,\n          error: describeCaughtError(error),\n        },\n      });\n    }\n\n    const result = AppWorkerBootstrapResponseSchema.safeParse(parsed);\n    if (!result.success) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message: 'Apps-manager worker-bootstrap response failed schema validation',\n          url,\n          workerName: this.workerName,\n          issues: result.error.issues,\n        },\n      });\n    }\n    return result.data;\n  }\n\n  private buildBootstrapUrl(): string {\n    if (!this.appsManagerBaseUrl || !this.workerName) {\n      throw new Error('WildoWorkerBootstrapClientService is not initialized');\n    }\n    const path = API_ROUTES_BACKEND_DEFINITIONS.APPS_MANAGER.GET_APPLICATION_WORKER_BOOTSTRAP(\n      this.workerName,\n    );\n    return `${this.appsManagerBaseUrl}${path}`;\n  }\n\n  private assertInitialized(): void {\n    if (!this.isInitialized) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message:\n            'WildoWorkerBootstrapClientService.getBootstrap() called before initialize(); ' +\n            'wire it from the worker host bootstrap (saas-workers-node-lib).',\n        },\n      });\n    }\n  }\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.endsWith('/') ? url.slice(0, -1) : url;\n}\n"]}
+{"version":3,"file":"wildo-worker-bootstrap-client.backend.service.js","sourceRoot":"","sources":["../../../../../src/security/jwt/services/wildo-worker-bootstrap-client.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, injectable } from 'inversify';\nimport { AppWorkerBootstrapResponseSchema, type AppWorkerBootstrapResponse } from '@wildo-ai/platform-config-lib';\nimport { ErrorCustomMessageReference, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';\nimport { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { API_ROUTES_BACKEND_DEFINITIONS } from '~wildo-backend-lib/requests/models/api-routes.backend.defintions';\n\n/**\n * Worker-side dynamic resolver for the trusted `APPLICATION_WORKER_REQUEST`\n * public key. Per Q3 LOCKED of\n * `.claude/plans/minions-and-workers-implementation.md`, the Wildo worker\n * runtime fetches this key at boot from apps-manager and refreshes it on a\n * JWKS-style cadence — never burns a static key into the image.\n *\n * Lives in `saas-backend-lib` so the Node worker host\n * (`@wildo-ai/saas-workers-node-lib`) can DI-bind it without inventing a\n * parallel HTTP client; non-Node workers (Rust / Java) implement the same\n * fetch contract natively against the same `/apps-to-manager/workers/:workerName/bootstrap`\n * endpoint and the shipped `AppWorkerBootstrapResponseSchema` shape.\n *\n * Dependency-light by design (only `LoggerService` + `ErrorBuilderBackendService`)\n * so the worker DI container can pull it without dragging Mongo / Redis /\n * RabbitMQ bindings into the worker boundary (KD-3).\n */\n@injectable()\nexport class WildoWorkerBootstrapClientService {\n  /** Default JWKS-style refresh cadence: 1h between trusted-key polls. */\n  private static readonly DEFAULT_REFRESH_INTERVAL_MS = 60 * 60 * 1000;\n\n  private appsManagerBaseUrl?: string;\n  private workerName?: string;\n  private applicationId?: string;\n  /**\n   * Application primary secret used by `getAppDataWithVerification` on the\n   * apps-manager `apps-to-manager/workers/:workerName/bootstrap` endpoint\n   * (`x-platform-secret` header — APP_TO_PLATFORM origin per `PlatformRequestsBackendUtils`).\n   * Comes from the four-env bootstrap-env-contract Secret mounted via K8s\n   * `envFrom: secretRef: {appSlug}-secret`.\n   */\n  private platformApplicationPrimarySecret?: string;\n  private refreshIntervalMs = WildoWorkerBootstrapClientService.DEFAULT_REFRESH_INTERVAL_MS;\n  private cachedResponse?: AppWorkerBootstrapResponse;\n  private cachedAt = 0;\n  private isInitialized = false;\n\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)\n    private readonly errorBuilder: ErrorBuilderBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('WildoWorkerBootstrapClientService');\n    this.logger.setDebugTypeLogging('WildoWorkerBootstrapClientService', false);\n  }\n\n  initialize(input: {\n    appsManagerBaseUrl: string;\n    applicationId: string;\n    workerName: string;\n    /**\n     * `PLATFORM_APPLICATION_PRIMARY_SECRET` from the four-env bootstrap\n     * contract — required so the GET request is authenticated as\n     * `APP_TO_PLATFORM` per `PlatformRequestsBackendUtils.buildPlatformRequestContext`.\n     * Without it the apps-manager handler rejects the bootstrap fetch\n     * with `Missing X-Platform-Secret`.\n     */\n    platformApplicationPrimarySecret: string;\n    refreshIntervalMs?: number;\n  }): void {\n    this.appsManagerBaseUrl = stripTrailingSlash(input.appsManagerBaseUrl);\n    this.applicationId = input.applicationId;\n    this.workerName = input.workerName;\n    this.platformApplicationPrimarySecret = input.platformApplicationPrimarySecret;\n    if (input.refreshIntervalMs !== undefined) {\n      this.refreshIntervalMs = input.refreshIntervalMs;\n    }\n    this.isInitialized = true;\n    this.logDebug('WildoWorkerBootstrapClientService initialized', {\n      appsManagerBaseUrl: this.appsManagerBaseUrl,\n      applicationId: this.applicationId,\n      workerName: this.workerName,\n      refreshIntervalMs: this.refreshIntervalMs,\n    });\n  }\n\n  /**\n   * Returns the trusted public key + rotation metadata for verifying inbound\n   * `APPLICATION_WORKER_REQUEST` JWTs. Cached for `refreshIntervalMs`; the\n   * caller can force a fetch via `getBootstrap({ force: true })`.\n   */\n  public async getBootstrap(\n    options?: { force?: boolean },\n  ): Promise<AppWorkerBootstrapResponse> {\n    this.assertInitialized();\n    const force = options?.force === true;\n    if (!force && this.cachedResponse && Date.now() - this.cachedAt < this.refreshIntervalMs) {\n      return this.cachedResponse;\n    }\n    const fetched = await this.fetchBootstrap();\n    this.cachedResponse = fetched;\n    this.cachedAt = Date.now();\n    return fetched;\n  }\n\n  public clearCache(): void {\n    this.cachedResponse = undefined;\n    this.cachedAt = 0;\n    this.logDebug('WildoWorkerBootstrapClientService cache cleared');\n  }\n\n  /**\n   * Hard deadline for the apps-manager bootstrap read.\n   *\n   * apps-manager is ours rather than a vendor's, which makes an unbounded wait here less likely and\n   * no less terminal: this runs at worker startup, and the `catch` below is the only thing that ever\n   * reports a failure — so a peer that accepts the connection and never answers does not produce a\n   * slow start, it produces a worker that never becomes ready and never says why.\n   *\n   * 10s because the response is a small JSON bootstrap document from a service on the same network:\n   * nothing legitimate here spends time moving bytes, and a longer bound would only lengthen the\n   * silence.\n   */\n  private static readonly BOOTSTRAP_REQUEST_TIMEOUT_MS = 10_000;\n\n  private async fetchBootstrap(): Promise<AppWorkerBootstrapResponse> {\n    const url = this.buildBootstrapUrl();\n    this.logDebug('Fetching worker bootstrap from apps-manager', { url });\n\n    if (!this.platformApplicationPrimarySecret || !this.applicationId) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message:\n            'WildoWorkerBootstrapClientService is missing platformApplicationPrimarySecret or applicationId; ' +\n            'these come from the four-env bootstrap-env-contract Secret and are required so the apps-manager ' +\n            'handler accepts the request as APP_TO_PLATFORM.',\n        },\n      });\n    }\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          [WildoHeaderKeys.PLATFORM_SECRET]: this.platformApplicationPrimarySecret,\n          [WildoHeaderKeys.APPLICATION_ID]: this.applicationId,\n        },\n        signal: AbortSignal.timeout(WildoWorkerBootstrapClientService.BOOTSTRAP_REQUEST_TIMEOUT_MS),\n      });\n    } catch (error) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Failed to reach apps-manager worker-bootstrap endpoint',\n          url,\n          workerName: this.workerName,\n          applicationId: this.applicationId,\n          error: describeCaughtError(error),\n        },\n      });\n    }\n\n    if (!response.ok) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Apps-manager worker-bootstrap endpoint returned non-2xx',\n          status: response.status,\n          url,\n          workerName: this.workerName,\n          applicationId: this.applicationId,\n        },\n      });\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = await response.json();\n    } catch (error) {\n      throw this.errorBuilder.buildError(ErrorType.EXTERNAL_SERVICE, undefined, {\n        customMessageReference: ErrorCustomMessageReference.EXTERNAL_SERVICE,\n        context: {\n          message: 'Apps-manager worker-bootstrap response was not valid JSON',\n          url,\n          error: describeCaughtError(error),\n        },\n      });\n    }\n\n    const result = AppWorkerBootstrapResponseSchema.safeParse(parsed);\n    if (!result.success) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message: 'Apps-manager worker-bootstrap response failed schema validation',\n          url,\n          workerName: this.workerName,\n          issues: result.error.issues,\n        },\n      });\n    }\n    return result.data;\n  }\n\n  private buildBootstrapUrl(): string {\n    if (!this.appsManagerBaseUrl || !this.workerName) {\n      throw new Error('WildoWorkerBootstrapClientService is not initialized');\n    }\n    const path = API_ROUTES_BACKEND_DEFINITIONS.APPS_MANAGER.GET_APPLICATION_WORKER_BOOTSTRAP(\n      this.workerName,\n    );\n    return `${this.appsManagerBaseUrl}${path}`;\n  }\n\n  private assertInitialized(): void {\n    if (!this.isInitialized) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: {\n          message:\n            'WildoWorkerBootstrapClientService.getBootstrap() called before initialize(); ' +\n            'wire it from the worker host bootstrap (saas-workers-node-lib).',\n        },\n      });\n    }\n  }\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.endsWith('/') ? url.slice(0, -1) : url;\n}\n"]}

package/dist/esm/security/jwt/utils/jwt-verification-error-classification.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-verification-error-classification.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../../src/security/jwt/utils/jwt-verification-error-classification.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,uBAAuB,CAAC;AAE/B,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAKpF;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAW3F"}
+{"version":3,"file":"jwt-verification-error-classification.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/jwt/utils/jwt-verification-error-classification.backend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,uBAAuB,CAAC;AAE/B,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAKpF;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAW3F"}

package/dist/esm/security/oauth-clients/oauth-client-generation.backend.utils.d.ts

@@ -55,4 +55,30 @@ export interface GeneratedOAuthClientSecretMaterial {
  * `plainSecret` exactly once.
  */
 export declare function generateOAuthClientSecretMaterial(scope: ApiKeyScope): GeneratedOAuthClientSecretMaterial;
+/**
+ * Hash a presented registration access token into its persisted lookup representation.
+ *
+ * Deterministic SHA-256, for the same reason as the client secret: the configuration endpoint
+ * resolves a presented Bearer token by re-hashing and matching an indexed column, and the plaintext
+ * is 32 random bytes rather than a password. Any change here must be mirrored wherever a presented
+ * token is looked up, or every issued token stops authenticating.
+ */
+export declare function hashRegistrationAccessToken(plainToken: string): string;
+export interface GeneratedRegistrationAccessTokenMaterial {
+    /** Full token — returned to the client once, at registration, and never persisted. */
+    plainToken: string;
+    /** First 8 chars — persisted so an operator can identify the token without seeing it. */
+    registrationAccessTokenPrefix: string;
+    /** `sha256(plainToken)` — the only persisted representation. */
+    registrationAccessTokenHash: string;
+}
+/**
+ * Mint a registration access token for a dynamically registered client.
+ *
+ * The caller persists the two derived fields and returns `plainToken` exactly once, in the RFC 7591
+ * registration response. There is no way to recover it afterwards — which is why RFC 7592 §5 says it
+ * "SHOULD NOT expire while a client is still actively registered": a client that loses it has lost
+ * the ability to manage its own registration, permanently.
+ */
+export declare function generateRegistrationAccessTokenMaterial(): GeneratedRegistrationAccessTokenMaterial;
 //# sourceMappingURL=oauth-client-generation.backend.utils.d.ts.map

package/dist/esm/security/oauth-clients/oauth-client-generation.backend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-client-generation.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/oauth-clients/oauth-client-generation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAkBpD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,MAAM,WAAW,kCAAkC;IACjD,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,WAAW,GAAG,kCAAkC,CAQxG"}
+{"version":3,"file":"oauth-client-generation.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/oauth-clients/oauth-client-generation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAkBpD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,MAAM,WAAW,kCAAkC;IACjD,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,WAAW,GAAG,kCAAkC,CAQxG;AAsBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,MAAM,WAAW,wCAAwC;IACvD,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,6BAA6B,EAAE,MAAM,CAAC;IACtC,gEAAgE;IAChE,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,uCAAuC,IAAI,wCAAwC,CAOlG"}

package/dist/esm/security/oauth-clients/oauth-client-generation.backend.utils.js

@@ -71,4 +71,47 @@ export function generateOAuthClientSecretMaterial(scope) {
         hashedSecret: hashOAuthClientSecret(plainSecret),
     };
 }
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Registration access token (RFC 7592)
+ * ────────────────────────────────────────────────────────────────────────── */
+/** Exact length of the persisted `registrationAccessTokenPrefix` display field (schema: `.length(8)`). */
+const REGISTRATION_ACCESS_TOKEN_PREFIX_LENGTH = 8;
+/** Plaintext entropy: 32 random bytes → 64 hex chars, matching the client secret. */
+const REGISTRATION_ACCESS_TOKEN_RANDOM_BYTES = 32;
+/**
+ * Its own prefix, distinct from `oc_app_` / `oc_org_`.
+ *
+ * The request-auth choke point routes a presented credential by prefix, and this token must NEVER
+ * resolve to a machine principal: it authenticates a caller's standing to administer ONE client's
+ * registration, not the client itself. A shared prefix would make that distinction depend on which
+ * lookup happened to run first.
+ */
+const REGISTRATION_ACCESS_TOKEN_PREFIX = 'rat_';
+/**
+ * Hash a presented registration access token into its persisted lookup representation.
+ *
+ * Deterministic SHA-256, for the same reason as the client secret: the configuration endpoint
+ * resolves a presented Bearer token by re-hashing and matching an indexed column, and the plaintext
+ * is 32 random bytes rather than a password. Any change here must be mirrored wherever a presented
+ * token is looked up, or every issued token stops authenticating.
+ */
+export function hashRegistrationAccessToken(plainToken) {
+    return crypto.createHash('sha256').update(plainToken).digest('hex');
+}
+/**
+ * Mint a registration access token for a dynamically registered client.
+ *
+ * The caller persists the two derived fields and returns `plainToken` exactly once, in the RFC 7591
+ * registration response. There is no way to recover it afterwards — which is why RFC 7592 §5 says it
+ * "SHOULD NOT expire while a client is still actively registered": a client that loses it has lost
+ * the ability to manage its own registration, permanently.
+ */
+export function generateRegistrationAccessTokenMaterial() {
+    const plainToken = `${REGISTRATION_ACCESS_TOKEN_PREFIX}${crypto.randomBytes(REGISTRATION_ACCESS_TOKEN_RANDOM_BYTES).toString('hex')}`;
+    return {
+        plainToken,
+        registrationAccessTokenPrefix: plainToken.slice(0, REGISTRATION_ACCESS_TOKEN_PREFIX_LENGTH),
+        registrationAccessTokenHash: hashRegistrationAccessToken(plainToken),
+    };
+}
 //# sourceMappingURL=oauth-client-generation.backend.utils.js.map

package/dist/esm/security/oauth-clients/oauth-client-generation.backend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-client-generation.backend.utils.js","sourceRoot":"","sources":["../../../../../src/security/oauth-clients/oauth-client-generation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,yFAAyF;AACzF,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAE5C,sFAAsF;AACtF,MAAM,gCAAgC,GAAG,EAAE,CAAC;AAE5C;;;;GAIG;AACH,MAAM,2BAA2B,GAAgC;IAC/D,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,SAAS;IACrC,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,SAAS;CACrC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,KAAkB;IAClE,MAAM,MAAM,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,GAAG,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,gCAAgC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IACvG,OAAO;QACL,WAAW;QACX,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,iCAAiC,CAAC;QACrE,YAAY,EAAE,qBAAqB,CAAC,WAAW,CAAC;KACjD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * OAuth Client Secret Generation & Hashing Utilities\n *\n * Server-side generation of the secret material for the `organizationOAuthClients`\n * and `applicationOAuthClients` resources. FAITHFUL MIRROR of\n * `api-key-generation.backend.utils.ts` — an OAuth client secret has three parts,\n * two persisted and one ephemeral:\n *\n * - `plainSecret`  — the full secret, shown to the caller EXACTLY ONCE at creation\n *                    (surfaced through the CREATE operation's `plainSecret` ephemeral\n *                    response field) and NEVER persisted. Format\n *                    `oc_org_<hex>` / `oc_app_<hex>`. The `oc_` prefix (distinct from\n *                    the api-key `sk_` prefix) is DELIBERATE: the request-auth choke\n *                    point routes a presented secret to a DISTINCT principal\n *                    (an OAuth client vs an api-key credential — both resolve to the same machine principal) by\n *                    this prefix.\n * - `hashedSecret` — `sha256(plainSecret)` (hex). The ONLY representation persisted,\n *                    and the indexed unique column (`.isUnique().isDBIndexed()`) the\n *                    client-credentials token exchange resolves a presented secret\n *                    against (re-hash, then equality-match) in O(1). A deterministic\n *                    hash — not bcrypt — is REQUIRED for an indexed equality lookup;\n *                    it is safe here because the secret is high-entropy (32 random\n *                    bytes), so the offline fast-hash brute-force risk that motivates\n *                    bcrypt for low-entropy passwords does not apply.\n * - `secretPrefix` — the first 8 characters of `plainSecret`, persisted and shown in\n *                    lists (`.isSummaryField()`) so an admin can identify a client\n *                    without revealing the secret.\n *\n * SHA-256 here matches the framework's established token-hashing scheme (api-keys,\n * SCIM token generation).\n */\n\nimport crypto from 'node:crypto';\nimport { ApiKeyScope } from '@wildo-ai/saas-models';\n\n/** Exact length of the persisted `secretPrefix` display field (schema: `.length(8)`). */\nconst OAUTH_CLIENT_SECRET_PREFIX_LENGTH = 8;\n\n/** Plaintext entropy: 32 random bytes → 64 hex chars (matches api-key generation). */\nconst OAUTH_CLIENT_SECRET_RANDOM_BYTES = 32;\n\n/**\n * Human-routable scope prefix the request-auth choke point keys off (`startsWith`).\n * Distinct from the api-key `sk_org_`/`sk_app_` prefixes so a presented secret routes\n * to the correct principal kind.\n */\nconst OAUTH_CLIENT_SCOPE_PREFIXES: Record<ApiKeyScope, string> = {\n  [ApiKeyScope.ORGANIZATION]: 'oc_org_',\n  [ApiKeyScope.APPLICATION]: 'oc_app_',\n};\n\n/**\n * Hash a plaintext OAuth client secret into its persisted, indexed lookup\n * representation.\n *\n * Deterministic (SHA-256 hex) so the client-credentials token exchange can resolve a\n * presented secret by re-hashing it and matching the unique `hashedSecret` column.\n * Any future change here MUST be mirrored in whatever the auth path uses to look up a\n * presented secret, or previously-issued secrets stop authenticating.\n */\nexport function hashOAuthClientSecret(plainSecret: string): string {\n  return crypto.createHash('sha256').update(plainSecret).digest('hex');\n}\n\nexport interface GeneratedOAuthClientSecretMaterial {\n  /** Full secret — surfaced to the caller once, never persisted. */\n  plainSecret: string;\n  /** First 8 chars of `plainSecret` — persisted + shown for identification. */\n  secretPrefix: string;\n  /** `sha256(plainSecret)` — the only persisted / indexed representation. */\n  hashedSecret: string;\n}\n\n/**\n * Generate fresh OAuth client secret material for the given scope. Returns the\n * one-time plaintext alongside the two persisted fields (`secretPrefix`,\n * `hashedSecret`). The caller persists `secretPrefix` + `hashedSecret` and surfaces\n * `plainSecret` exactly once.\n */\nexport function generateOAuthClientSecretMaterial(scope: ApiKeyScope): GeneratedOAuthClientSecretMaterial {\n  const prefix = OAUTH_CLIENT_SCOPE_PREFIXES[scope];\n  const plainSecret = `${prefix}${crypto.randomBytes(OAUTH_CLIENT_SECRET_RANDOM_BYTES).toString('hex')}`;\n  return {\n    plainSecret,\n    secretPrefix: plainSecret.slice(0, OAUTH_CLIENT_SECRET_PREFIX_LENGTH),\n    hashedSecret: hashOAuthClientSecret(plainSecret),\n  };\n}\n"]}
+{"version":3,"file":"oauth-client-generation.backend.utils.js","sourceRoot":"","sources":["../../../../src/security/oauth-clients/oauth-client-generation.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,yFAAyF;AACzF,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAE5C,sFAAsF;AACtF,MAAM,gCAAgC,GAAG,EAAE,CAAC;AAE5C;;;;GAIG;AACH,MAAM,2BAA2B,GAAgC;IAC/D,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,SAAS;IACrC,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,SAAS;CACrC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,KAAkB;IAClE,MAAM,MAAM,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,GAAG,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,gCAAgC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IACvG,OAAO;QACL,WAAW;QACX,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,iCAAiC,CAAC;QACrE,YAAY,EAAE,qBAAqB,CAAC,WAAW,CAAC;KACjD,CAAC;AACJ,CAAC;AAED;;gFAEgF;AAEhF,0GAA0G;AAC1G,MAAM,uCAAuC,GAAG,CAAC,CAAC;AAElD,qFAAqF;AACrF,MAAM,sCAAsC,GAAG,EAAE,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,gCAAgC,GAAG,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,UAAkB;IAC5D,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,uCAAuC;IACrD,MAAM,UAAU,GAAG,GAAG,gCAAgC,GAAG,MAAM,CAAC,WAAW,CAAC,sCAAsC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IACtI,OAAO;QACL,UAAU;QACV,6BAA6B,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,uCAAuC,CAAC;QAC3F,2BAA2B,EAAE,2BAA2B,CAAC,UAAU,CAAC;KACrE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * OAuth Client Secret Generation & Hashing Utilities\n *\n * Server-side generation of the secret material for the `organizationOAuthClients`\n * and `applicationOAuthClients` resources. FAITHFUL MIRROR of\n * `api-key-generation.backend.utils.ts` — an OAuth client secret has three parts,\n * two persisted and one ephemeral:\n *\n * - `plainSecret`  — the full secret, shown to the caller EXACTLY ONCE at creation\n *                    (surfaced through the CREATE operation's `plainSecret` ephemeral\n *                    response field) and NEVER persisted. Format\n *                    `oc_org_<hex>` / `oc_app_<hex>`. The `oc_` prefix (distinct from\n *                    the api-key `sk_` prefix) is DELIBERATE: the request-auth choke\n *                    point routes a presented secret to a DISTINCT principal\n *                    (an OAuth client vs an api-key credential — both resolve to the same machine principal) by\n *                    this prefix.\n * - `hashedSecret` — `sha256(plainSecret)` (hex). The ONLY representation persisted,\n *                    and the indexed unique column (`.isUnique().isDBIndexed()`) the\n *                    client-credentials token exchange resolves a presented secret\n *                    against (re-hash, then equality-match) in O(1). A deterministic\n *                    hash — not bcrypt — is REQUIRED for an indexed equality lookup;\n *                    it is safe here because the secret is high-entropy (32 random\n *                    bytes), so the offline fast-hash brute-force risk that motivates\n *                    bcrypt for low-entropy passwords does not apply.\n * - `secretPrefix` — the first 8 characters of `plainSecret`, persisted and shown in\n *                    lists (`.isSummaryField()`) so an admin can identify a client\n *                    without revealing the secret.\n *\n * SHA-256 here matches the framework's established token-hashing scheme (api-keys,\n * SCIM token generation).\n */\n\nimport crypto from 'node:crypto';\nimport { ApiKeyScope } from '@wildo-ai/saas-models';\n\n/** Exact length of the persisted `secretPrefix` display field (schema: `.length(8)`). */\nconst OAUTH_CLIENT_SECRET_PREFIX_LENGTH = 8;\n\n/** Plaintext entropy: 32 random bytes → 64 hex chars (matches api-key generation). */\nconst OAUTH_CLIENT_SECRET_RANDOM_BYTES = 32;\n\n/**\n * Human-routable scope prefix the request-auth choke point keys off (`startsWith`).\n * Distinct from the api-key `sk_org_`/`sk_app_` prefixes so a presented secret routes\n * to the correct principal kind.\n */\nconst OAUTH_CLIENT_SCOPE_PREFIXES: Record<ApiKeyScope, string> = {\n  [ApiKeyScope.ORGANIZATION]: 'oc_org_',\n  [ApiKeyScope.APPLICATION]: 'oc_app_',\n};\n\n/**\n * Hash a plaintext OAuth client secret into its persisted, indexed lookup\n * representation.\n *\n * Deterministic (SHA-256 hex) so the client-credentials token exchange can resolve a\n * presented secret by re-hashing it and matching the unique `hashedSecret` column.\n * Any future change here MUST be mirrored in whatever the auth path uses to look up a\n * presented secret, or previously-issued secrets stop authenticating.\n */\nexport function hashOAuthClientSecret(plainSecret: string): string {\n  return crypto.createHash('sha256').update(plainSecret).digest('hex');\n}\n\nexport interface GeneratedOAuthClientSecretMaterial {\n  /** Full secret — surfaced to the caller once, never persisted. */\n  plainSecret: string;\n  /** First 8 chars of `plainSecret` — persisted + shown for identification. */\n  secretPrefix: string;\n  /** `sha256(plainSecret)` — the only persisted / indexed representation. */\n  hashedSecret: string;\n}\n\n/**\n * Generate fresh OAuth client secret material for the given scope. Returns the\n * one-time plaintext alongside the two persisted fields (`secretPrefix`,\n * `hashedSecret`). The caller persists `secretPrefix` + `hashedSecret` and surfaces\n * `plainSecret` exactly once.\n */\nexport function generateOAuthClientSecretMaterial(scope: ApiKeyScope): GeneratedOAuthClientSecretMaterial {\n  const prefix = OAUTH_CLIENT_SCOPE_PREFIXES[scope];\n  const plainSecret = `${prefix}${crypto.randomBytes(OAUTH_CLIENT_SECRET_RANDOM_BYTES).toString('hex')}`;\n  return {\n    plainSecret,\n    secretPrefix: plainSecret.slice(0, OAUTH_CLIENT_SECRET_PREFIX_LENGTH),\n    hashedSecret: hashOAuthClientSecret(plainSecret),\n  };\n}\n\n/* ─────────────────────────────────────────────────────────────────────────────\n * Registration access token (RFC 7592)\n * ────────────────────────────────────────────────────────────────────────── */\n\n/** Exact length of the persisted `registrationAccessTokenPrefix` display field (schema: `.length(8)`). */\nconst REGISTRATION_ACCESS_TOKEN_PREFIX_LENGTH = 8;\n\n/** Plaintext entropy: 32 random bytes → 64 hex chars, matching the client secret. */\nconst REGISTRATION_ACCESS_TOKEN_RANDOM_BYTES = 32;\n\n/**\n * Its own prefix, distinct from `oc_app_` / `oc_org_`.\n *\n * The request-auth choke point routes a presented credential by prefix, and this token must NEVER\n * resolve to a machine principal: it authenticates a caller's standing to administer ONE client's\n * registration, not the client itself. A shared prefix would make that distinction depend on which\n * lookup happened to run first.\n */\nconst REGISTRATION_ACCESS_TOKEN_PREFIX = 'rat_';\n\n/**\n * Hash a presented registration access token into its persisted lookup representation.\n *\n * Deterministic SHA-256, for the same reason as the client secret: the configuration endpoint\n * resolves a presented Bearer token by re-hashing and matching an indexed column, and the plaintext\n * is 32 random bytes rather than a password. Any change here must be mirrored wherever a presented\n * token is looked up, or every issued token stops authenticating.\n */\nexport function hashRegistrationAccessToken(plainToken: string): string {\n  return crypto.createHash('sha256').update(plainToken).digest('hex');\n}\n\nexport interface GeneratedRegistrationAccessTokenMaterial {\n  /** Full token — returned to the client once, at registration, and never persisted. */\n  plainToken: string;\n  /** First 8 chars — persisted so an operator can identify the token without seeing it. */\n  registrationAccessTokenPrefix: string;\n  /** `sha256(plainToken)` — the only persisted representation. */\n  registrationAccessTokenHash: string;\n}\n\n/**\n * Mint a registration access token for a dynamically registered client.\n *\n * The caller persists the two derived fields and returns `plainToken` exactly once, in the RFC 7591\n * registration response. There is no way to recover it afterwards — which is why RFC 7592 §5 says it\n * \"SHOULD NOT expire while a client is still actively registered\": a client that loses it has lost\n * the ability to manage its own registration, permanently.\n */\nexport function generateRegistrationAccessTokenMaterial(): GeneratedRegistrationAccessTokenMaterial {\n  const plainToken = `${REGISTRATION_ACCESS_TOKEN_PREFIX}${crypto.randomBytes(REGISTRATION_ACCESS_TOKEN_RANDOM_BYTES).toString('hex')}`;\n  return {\n    plainToken,\n    registrationAccessTokenPrefix: plainToken.slice(0, REGISTRATION_ACCESS_TOKEN_PREFIX_LENGTH),\n    registrationAccessTokenHash: hashRegistrationAccessToken(plainToken),\n  };\n}\n"]}

package/dist/esm/security/oauth-clients/oauth-clients.custom-impl.backend.service.d.ts

@@ -54,7 +54,14 @@ import type { RoleHierarchyResolver } from '../../security/authorizations/role-c
 export type OAuthClientImplHandlers = Parameters<typeof createResourceCustomServiceImplementation>[0]['handlers'];
 /** CREATE — enforce the role-ceiling, then mint material; surface `plainSecret` once. Exported for focused create-pipeline unit tests. */
 export declare function buildOAuthClientMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): OAuthClientImplHandlers;
-/** CREATE impls — org default + org `admin` + app default. */
+/**
+ * EXPIRE impls — registered separately from the other ops rather than through
+ * `oauthClientFactoriesForOperation`, because that helper hardcodes `variantType: API_CALL` and
+ * fans out over each resource's HTTP variants. EXPIRE is INTERNAL_CALL with a single default
+ * variant, so it needs its own registration or the lookup key would never match and the guard above
+ * would be silently unreachable.
+ */
+export declare function createOAuthClientExpireFactories(): ResourceCustomServiceImplementationFactory[];
 export declare function createOAuthClientCreateFactories(): ResourceCustomServiceImplementationFactory[];
 /** ROTATE impls — bounded grace window. */
 export declare function createOAuthClientRotateFactories(): ResourceCustomServiceImplementationFactory[];

package/dist/esm/security/oauth-clients/oauth-clients.custom-impl.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-clients.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/security/oauth-clients/oauth-clients.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EACL,WAAW,EASZ,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,yCAAyC,EACzC,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAMpH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uEAAuE,CAAC;AAqDnH,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG,UAAU,CAAC,OAAO,yCAAyC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AA4DlH,0IAA0I;AAC1I,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,qBAAqB,GAAG,uBAAuB,CAyBtI;AA4DD,8DAA8D;AAC9D,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAK/F;AAED,2CAA2C;AAC3C,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAK/F;AAED,6CAA6C;AAC7C,wBAAgB,oCAAoC,IAAI,0CAA0C,EAAE,CAKnG"}
+{"version":3,"file":"oauth-clients.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/security/oauth-clients/oauth-clients.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EACL,WAAW,EASZ,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,yCAAyC,EACzC,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAMpH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uEAAuE,CAAC;AAqDnH,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG,UAAU,CAAC,OAAO,yCAAyC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AA4DlH,0IAA0I;AAC1I,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,qBAAqB,GAAG,uBAAuB,CAyBtI;AA4FD;;;;;;GAMG;AACH,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAc/F;AAED,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAK/F;AAED,2CAA2C;AAC3C,wBAAgB,gCAAgC,IAAI,0CAA0C,EAAE,CAK/F;AAED,6CAA6C;AAC7C,wBAAgB,oCAAoC,IAAI,0CAA0C,EAAE,CAKnG"}

package/dist/esm/security/oauth-clients/oauth-clients.custom-impl.backend.service.js

@@ -214,6 +214,55 @@ function buildOAuthClientReissueHandlers(scope, kind) {
     };
 }
 /** CREATE impls — org default + org `admin` + app default. */
+/**
+ * ACTIVE → EXPIRED, forced — the transition the credential-expiry sweep dispatches (#413).
+ *
+ * The FIRST status-transition handler on this resource: OAuth clients ship ROTATE and REGENERATE
+ * and no deactivate/reactivate pair, so unlike api-keys there was no generic transition helper to
+ * reuse. The 409 is the whole reason the sweep goes through a verb — an INACTIVE client was retired
+ * by an administrator, and relabelling it EXPIRED would erase who ended it.
+ *
+ * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — credential state transitions are
+ * explicit and validated, never inferred from a caller-supplied field.
+ */
+function buildOAuthClientExpireHandlers() {
+    return {
+        prefixCoreOperations: async (_id, _input, executionContext, _operationPath, utils) => {
+            const current = utils.currentObject;
+            if (current && current.status !== OAuthClientStatus.ACTIVE) {
+                throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFLICT,
+                    context: {
+                        message: `OAuth client cannot move to '${OAuthClientStatus.EXPIRED}' from status '${current.status}'`,
+                        oauthClientStatus: current.status,
+                    },
+                });
+            }
+            return { status: OAuthClientStatus.EXPIRED };
+        },
+    };
+}
+/**
+ * EXPIRE impls — registered separately from the other ops rather than through
+ * `oauthClientFactoriesForOperation`, because that helper hardcodes `variantType: API_CALL` and
+ * fans out over each resource's HTTP variants. EXPIRE is INTERNAL_CALL with a single default
+ * variant, so it needs its own registration or the lookup key would never match and the guard above
+ * would be silently unreachable.
+ */
+export function createOAuthClientExpireFactories() {
+    return OAUTH_CLIENT_TARGETS.map((target) => {
+        const factory = (_resourcesRegistryService, _container) => createResourceCustomServiceImplementation({
+            operationPath: {
+                resourceIdentifier: target.resourceType,
+                operationIdentifier: target.ops.EXPIRE,
+                variantType: ResourceOperationVariantType.INTERNAL_CALL,
+                isOperationDefault: true,
+            },
+            handlers: buildOAuthClientExpireHandlers(),
+        });
+        return factory;
+    });
+}
 export function createOAuthClientCreateFactories() {
     return oauthClientFactoriesForOperation(() => CoreResourceOperation.CREATE, (target, container) => buildOAuthClientMintHandlers(target.scope, createRoleHierarchyResolver(container)));
 }

package/dist/esm/security/oauth-clients/oauth-clients.custom-impl.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-clients.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../src/security/oauth-clients/oauth-clients.custom-impl.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OAuth Clients Custom Implementations\n *\n * Implements the server-side behaviour for the organization + application OAuth-client\n * resources (`organizationOAuthClients`, `applicationOAuthClients`) that the schema\n * alone cannot express. FAITHFUL MIRROR of the api-keys mint pipeline\n * (`api-keys.custom-impl.backend.service.ts`), FOCUSED to the trunk operation set:\n *\n *   CREATE      → mint fresh secret material (the client must never supply it).\n *   ROTATE      → reissue the secret; retain the prior secret in a grace window that\n *                 stops authenticating at the caller-chosen `oldSecretInvalidationDate`.\n *   REGENERATE  → reissue the secret; keep the prior secret valid open-endedly (until\n *                 the next rotation) for a zero-downtime overlap.\n *\n * (api-keys' DEACTIVATE/REACTIVATE/EXTEND_EXPIRY/USAGE_STATS impls are deferred to the\n * OIDC branch alongside their resource-config ops.)\n *\n * WHY MINTING NEEDS AN IMPL: the schema requires `secretPrefix` + `hashedSecret`, but\n * both are `.excludeFromCreate().excludeFromUpdate()` (the client must never supply\n * them) and `plainSecret` is an ephemeral response-only field. Nothing generated them,\n * so a bare create/update persisted a row missing the required fields. These impls are\n * the single server-side choke point that mints secret material.\n *\n * PATTERN (CREATE / ROTATE / REGENERATE — all \"mint a secret\" ops):\n *   prefixCoreOperations  → mint material; inject the persisted `secretPrefix` +\n *                           `hashedSecret` (and, for rotate/regenerate, the previous-\n *                           secret grace-window fields) into the payload. Those fields\n *                           are `.excludeFrom{Create,Update}()`, so returning them from\n *                           the prefix is what carries them into the core write — the\n *                           orchestration diffs the prefix-added keys and forwards them\n *                           to the repository's `preserveServerInjectedFields` allowlist\n *                           so the final strict parse re-attaches (rather than strips)\n *                           them. Stash the one-time `plainSecret` for the postfix.\n *   postfixCoreOperations → attach the one-time `plainSecret` (+ rotate's `oldClientId` /\n *                           `oldSecretInvalidationDate`) to the response so the\n *                           operation's ephemeral `plainSecret` field surfaces it.\n * The core write still runs, so notifications / websocket events fire normally — which\n * is why this is prefix+postfix rather than `replaceCoreOperations`.\n *\n * VARIANT COVERAGE: a custom impl is matched to a running op by its FULL operation-path\n * identity — `isOperationDefault` (the `isDefault` sentinel) vs `variantKey` produce\n * DISTINCT keys (`createOperationPathKey`). So a single default registration only\n * intercepts the default variant; the cross-tenant app-super-admin `admin` variant\n * (org clients only) needs its own registration or it runs the bare core op and fails.\n * `OAUTH_CLIENT_TARGETS` enumerates every (resource × variant) each op exposes. Minting\n * is org-agnostic — the target `organizationId` rides in the payload / pre-fetched\n * record, never from these handlers — so the admin variant reuses the identical handlers\n * and (per the user security decision) also receives the tenant's one-time `plainSecret`.\n */\n\nimport {\n  ApiKeyScope,\n  AppOAuthClients_Operations,\n  CoreResourceOperation,\n  CoreResourceType,\n  ErrorCustomMessageReference,\n  ErrorType,\n  OAuthClientStatus,\n  OrgOAuthClients_Operations,\n  ResourceOperationVariantType,\n} from '@wildo-ai/saas-models';\nimport type { OAuthClientBase } from '@wildo-ai/saas-models';\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { generateOAuthClientSecretMaterial } from './oauth-client-generation.backend.utils';\nimport type { Container } from 'inversify';\nimport { assertRequestedRolesWithinCallerCeiling, createRoleHierarchyResolver } from '~wildo-backend-lib/security/authorizations/role-ceiling.backend.utils';\nimport type { RoleHierarchyResolver } from '~wildo-backend-lib/security/authorizations/role-ceiling.backend.utils';\n\n/**\n * Bridge for the one-time plaintext secret between the CREATE prefix (which mints it)\n * and the postfix (which returns it), keyed by the per-operation `ExecutionContext`\n * INSTANCE. The orchestration threads the SAME `executionContext` through both handlers\n * (`services-registry-handler.backend.service.ts` prefix + postfix calls), so it is a\n * stable, per-invocation correlation key.\n *\n * A `WeakMap` keyed by the EC is deliberately chosen over a `Map` keyed by `hashedSecret`\n * / `_id`: (1) NO LEAK — the entry is reclaimed by GC when the request's EC becomes\n * unreachable, so a core-write failure between prefix and postfix cannot strand the\n * plaintext in memory; (2) NO RACE — concurrent operations run on DISTINCT EC instances,\n * so two simultaneous mints/reissues never collide on a shared key. `plainSecret` is\n * never persisted; the postfix also deletes the entry for promptness.\n */\nconst PLAINTEXT_SECRET_BY_EC = new WeakMap<ExecutionContext<any>, string>();\n\n/**\n * Bridge for ROTATE / REGENERATE, keyed by the same per-operation `ExecutionContext`\n * instance (see {@link PLAINTEXT_SECRET_BY_EC}). Carries the one-time `plainSecret` AND\n * the applied `previousSecretInvalidationDate`, so the postfix builds ROTATE's\n * `oldSecretInvalidationDate` from the value the prefix actually applied — independent of\n * whether the update result round-trips that field.\n */\nconst REISSUE_BRIDGE_BY_EC = new WeakMap<ExecutionContext<any>, { plainSecret: string; previousSecretInvalidationDate: Date | null }>();\n\n/** ROTATE keeps a bounded grace window; REGENERATE keeps an open-ended overlap. */\nenum OAuthClientReissueKind {\n  ROTATE = 'rotate',\n  REGENERATE = 'regenerate',\n}\n\n/**\n * The pre-fetched client fields the reissue prefix reads. `hashedSecret`/`secretPrefix`\n * are present on every persisted client of either scope.\n */\ntype ReissuableOAuthClient = Pick<OAuthClientBase, 'status'> & { hashedSecret: string; secretPrefix: string };\n\n/**\n * Structural view of a per-resource custom-operation enum — the members that have a\n * backend impl in this file. Both `OrgOAuthClients_Operations` and\n * `AppOAuthClients_Operations` satisfy it (identical string values).\n */\ntype OAuthClientCustomOps = { ROTATE: string; REGENERATE: string };\n\ntype OAuthClientTarget = {\n  resourceType: CoreResourceType;\n  scope: ApiKeyScope;\n  ops: OAuthClientCustomOps;\n  variants: ReadonlyArray<{ isOperationDefault: boolean; variantKey?: string }>;\n};\n\n/** The handler-object shape accepted by `createResourceCustomServiceImplementation`. */\nexport type OAuthClientImplHandlers = Parameters<typeof createResourceCustomServiceImplementation>[0]['handlers'];\n\n/**\n * The OAuth-client resources, their scope (drives the `oc_org_` / `oc_app_` prefix), the\n * per-resource custom-op enum, and every op VARIANT each resource exposes.\n *\n * - ORG clients expose an org-admin DEFAULT + a cross-tenant app-super-admin `admin`\n *   variant → both registered.\n * - APP clients are single-variant (APP_ADMIN-scoped) → default only.\n */\nconst OAUTH_CLIENT_TARGETS: ReadonlyArray<OAuthClientTarget> = [\n  {\n    resourceType: CoreResourceType.OAUTH_CLIENTS_ORGANIZATION,\n    scope: ApiKeyScope.ORGANIZATION,\n    ops: OrgOAuthClients_Operations,\n    variants: [\n      { isOperationDefault: true },\n      { isOperationDefault: false, variantKey: 'admin' },\n    ],\n  },\n  {\n    resourceType: CoreResourceType.OAUTH_CLIENTS_APPLICATION,\n    scope: ApiKeyScope.APPLICATION,\n    ops: AppOAuthClients_Operations,\n    variants: [\n      { isOperationDefault: true },\n    ],\n  },\n];\n\n/**\n * Register one custom-impl factory per (target × variant) for a single operation.\n * Every OAuth-client op is API_CALL and needs a distinct registration per variant\n * identity (see the module header) — this centralizes that fan-out.\n */\nfunction oauthClientFactoriesForOperation(\n  operationIdentifierFor: (target: OAuthClientTarget) => string | CoreResourceOperation,\n  handlersFor: (target: OAuthClientTarget, container: Container) => OAuthClientImplHandlers,\n): ResourceCustomServiceImplementationFactory[] {\n  return OAUTH_CLIENT_TARGETS.flatMap((target) =>\n    target.variants.map(({ isOperationDefault, variantKey }) => {\n      const factory = (_resourcesRegistryService: ResourcesRegistryBackendService, container: Container) =>\n        createResourceCustomServiceImplementation({\n          operationPath: {\n            resourceIdentifier: target.resourceType,\n            // API_CALL: the lookup key is built from the RUNNING operation's variantType\n            // (`extractOperationPath` passes it through unchanged), and OAuth-client ops\n            // are dispatched as direct HTTP API_CALLs. Must match exactly.\n            operationIdentifier: operationIdentifierFor(target),\n            variantType: ResourceOperationVariantType.API_CALL,\n            isOperationDefault,\n            variantKey,\n          },\n          handlers: handlersFor(target, container),\n        });\n      return factory as unknown as ResourceCustomServiceImplementationFactory;\n    }),\n  );\n}\n\n/** CREATE — enforce the role-ceiling, then mint material; surface `plainSecret` once. Exported for focused create-pipeline unit tests. */\nexport function buildOAuthClientMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): OAuthClientImplHandlers {\n  return {\n    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n      // Role-ceiling gate — a principal cannot mint a client carrying roles it does not itself hold\n      // (self-service privilege-escalation prevention; APPLICATION-scoped super-admin + system writes\n      // bypass). The ceiling is hierarchy-aware, so an ORG_ADMIN may mint a client carrying the roles\n      // its own role confers (ORG_MANAGER/ORG_MEMBER/…) but never ORG_OWNER above it.\n      // assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege on machine-credential minting.\n      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);\n      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);\n      // Bridge the one-time secret to the postfix, keyed by the per-op EC instance; never persisted.\n      PLAINTEXT_SECRET_BY_EC.set(executionContext, plainSecret);\n      // secretPrefix + hashedSecret are `.excludeFromCreate()`; returning them injects\n      // them into the create payload (preserveServerInjectedFields re-attaches them past\n      // the strict parse) so the row persists with the required fields.\n      return { ...(input as Record<string, unknown>), secretPrefix, hashedSecret };\n    },\n    postfixCoreOperations: async (_id, createdClient, executionContext, _operationPath, _utils) => {\n      if (!createdClient || typeof createdClient !== 'object') return createdClient;\n      const plainSecret = PLAINTEXT_SECRET_BY_EC.get(executionContext);\n      PLAINTEXT_SECRET_BY_EC.delete(executionContext);\n      if (!plainSecret) return createdClient;\n      return { ...(createdClient as Record<string, unknown>), plainSecret };\n    },\n  };\n}\n\n/**\n * ROTATE / REGENERATE — reissue the secret on the SAME record, moving the prior secret\n * into the grace-window slot. The client-credentials exchange keeps honoring the prior\n * secret until `previousSecretInvalidationDate` (ROTATE: the caller-chosen instant,\n * defaulting to now = immediate cutover; REGENERATE: `null` = open-ended overlap).\n */\nfunction buildOAuthClientReissueHandlers(scope: ApiKeyScope, kind: OAuthClientReissueKind): OAuthClientImplHandlers {\n  return {\n    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n      // `currentObject` is the pre-fetched DB record for this UPDATE-borrow op — it\n      // includes the backend-only `hashedSecret`/`secretPrefix` we move into the\n      // previous slot.\n      const current = utils.currentObject as ReissuableOAuthClient | undefined;\n\n      // Only an ACTIVE client can be reissued (409 for a revoked/expired client —\n      // otherwise rotation would silently re-arm a deactivated credential).\n      if (current && current.status !== OAuthClientStatus.ACTIVE) {\n        throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {\n          customMessageReference: ErrorCustomMessageReference.CONFLICT,\n          context: { message: `OAuth client secret cannot be reissued in status '${current.status}'`, oauthClientStatus: current.status },\n        });\n      }\n\n      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);\n      const previousSecretInvalidationDate = kind === OAuthClientReissueKind.ROTATE\n        ? ((input as { oldSecretInvalidationDate?: Date }).oldSecretInvalidationDate ?? new Date())\n        : null;\n      REISSUE_BRIDGE_BY_EC.set(executionContext, { plainSecret, previousSecretInvalidationDate });\n\n      return {\n        ...(input as Record<string, unknown>),\n        hashedSecret,\n        secretPrefix,\n        // Move the outgoing secret into the grace-window slot (server-managed,\n        // excludeFrom{Create,Update} → carried by preserveServerInjectedFields).\n        previousHashedSecret: current?.hashedSecret,\n        previousSecretPrefix: current?.secretPrefix,\n        previousSecretInvalidationDate,\n      };\n    },\n    postfixCoreOperations: async (_id, updated, executionContext, _operationPath, _utils) => {\n      if (!updated || typeof updated !== 'object') return updated;\n      const record = updated as Record<string, unknown>;\n      const bridged = REISSUE_BRIDGE_BY_EC.get(executionContext);\n      REISSUE_BRIDGE_BY_EC.delete(executionContext);\n\n      const withPlainSecret = bridged?.plainSecret ? { ...record, plainSecret: bridged.plainSecret } : { ...record };\n      if (kind === OAuthClientReissueKind.ROTATE) {\n        // ROTATE's response DTO additionally carries the rotated record's id + when the\n        // prior secret is invalidated. Same record, so `oldClientId` is its own `_id`.\n        return { ...withPlainSecret, oldClientId: _id, oldSecretInvalidationDate: bridged?.previousSecretInvalidationDate };\n      }\n      // REGENERATE's response DTO is resource + plainSecret only.\n      return withPlainSecret;\n    },\n  };\n}\n\n/** CREATE impls — org default + org `admin` + app default. */\nexport function createOAuthClientCreateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    () => CoreResourceOperation.CREATE,\n    (target, container) => buildOAuthClientMintHandlers(target.scope, createRoleHierarchyResolver(container)),\n  );\n}\n\n/** ROTATE impls — bounded grace window. */\nexport function createOAuthClientRotateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    (target) => target.ops.ROTATE,\n    (target) => buildOAuthClientReissueHandlers(target.scope, OAuthClientReissueKind.ROTATE),\n  );\n}\n\n/** REGENERATE impls — open-ended overlap. */\nexport function createOAuthClientRegenerateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    (target) => target.ops.REGENERATE,\n    (target) => buildOAuthClientReissueHandlers(target.scope, OAuthClientReissueKind.REGENERATE),\n  );\n}\n"]}
+{"version":3,"file":"oauth-clients.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../src/security/oauth-clients/oauth-clients.custom-impl.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OAuth Clients Custom Implementations\n *\n * Implements the server-side behaviour for the organization + application OAuth-client\n * resources (`organizationOAuthClients`, `applicationOAuthClients`) that the schema\n * alone cannot express. FAITHFUL MIRROR of the api-keys mint pipeline\n * (`api-keys.custom-impl.backend.service.ts`), FOCUSED to the trunk operation set:\n *\n *   CREATE      → mint fresh secret material (the client must never supply it).\n *   ROTATE      → reissue the secret; retain the prior secret in a grace window that\n *                 stops authenticating at the caller-chosen `oldSecretInvalidationDate`.\n *   REGENERATE  → reissue the secret; keep the prior secret valid open-endedly (until\n *                 the next rotation) for a zero-downtime overlap.\n *\n * (api-keys' DEACTIVATE/REACTIVATE/EXTEND_EXPIRY/USAGE_STATS impls are deferred to the\n * OIDC branch alongside their resource-config ops.)\n *\n * WHY MINTING NEEDS AN IMPL: the schema requires `secretPrefix` + `hashedSecret`, but\n * both are `.excludeFromCreate().excludeFromUpdate()` (the client must never supply\n * them) and `plainSecret` is an ephemeral response-only field. Nothing generated them,\n * so a bare create/update persisted a row missing the required fields. These impls are\n * the single server-side choke point that mints secret material.\n *\n * PATTERN (CREATE / ROTATE / REGENERATE — all \"mint a secret\" ops):\n *   prefixCoreOperations  → mint material; inject the persisted `secretPrefix` +\n *                           `hashedSecret` (and, for rotate/regenerate, the previous-\n *                           secret grace-window fields) into the payload. Those fields\n *                           are `.excludeFrom{Create,Update}()`, so returning them from\n *                           the prefix is what carries them into the core write — the\n *                           orchestration diffs the prefix-added keys and forwards them\n *                           to the repository's `preserveServerInjectedFields` allowlist\n *                           so the final strict parse re-attaches (rather than strips)\n *                           them. Stash the one-time `plainSecret` for the postfix.\n *   postfixCoreOperations → attach the one-time `plainSecret` (+ rotate's `oldClientId` /\n *                           `oldSecretInvalidationDate`) to the response so the\n *                           operation's ephemeral `plainSecret` field surfaces it.\n * The core write still runs, so notifications / websocket events fire normally — which\n * is why this is prefix+postfix rather than `replaceCoreOperations`.\n *\n * VARIANT COVERAGE: a custom impl is matched to a running op by its FULL operation-path\n * identity — `isOperationDefault` (the `isDefault` sentinel) vs `variantKey` produce\n * DISTINCT keys (`createOperationPathKey`). So a single default registration only\n * intercepts the default variant; the cross-tenant app-super-admin `admin` variant\n * (org clients only) needs its own registration or it runs the bare core op and fails.\n * `OAUTH_CLIENT_TARGETS` enumerates every (resource × variant) each op exposes. Minting\n * is org-agnostic — the target `organizationId` rides in the payload / pre-fetched\n * record, never from these handlers — so the admin variant reuses the identical handlers\n * and (per the user security decision) also receives the tenant's one-time `plainSecret`.\n */\n\nimport {\n  ApiKeyScope,\n  AppOAuthClients_Operations,\n  CoreResourceOperation,\n  CoreResourceType,\n  ErrorCustomMessageReference,\n  ErrorType,\n  OAuthClientStatus,\n  OrgOAuthClients_Operations,\n  ResourceOperationVariantType,\n} from '@wildo-ai/saas-models';\nimport type { OAuthClientBase } from '@wildo-ai/saas-models';\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { generateOAuthClientSecretMaterial } from './oauth-client-generation.backend.utils';\nimport type { Container } from 'inversify';\nimport { assertRequestedRolesWithinCallerCeiling, createRoleHierarchyResolver } from '~wildo-backend-lib/security/authorizations/role-ceiling.backend.utils';\nimport type { RoleHierarchyResolver } from '~wildo-backend-lib/security/authorizations/role-ceiling.backend.utils';\n\n/**\n * Bridge for the one-time plaintext secret between the CREATE prefix (which mints it)\n * and the postfix (which returns it), keyed by the per-operation `ExecutionContext`\n * INSTANCE. The orchestration threads the SAME `executionContext` through both handlers\n * (`services-registry-handler.backend.service.ts` prefix + postfix calls), so it is a\n * stable, per-invocation correlation key.\n *\n * A `WeakMap` keyed by the EC is deliberately chosen over a `Map` keyed by `hashedSecret`\n * / `_id`: (1) NO LEAK — the entry is reclaimed by GC when the request's EC becomes\n * unreachable, so a core-write failure between prefix and postfix cannot strand the\n * plaintext in memory; (2) NO RACE — concurrent operations run on DISTINCT EC instances,\n * so two simultaneous mints/reissues never collide on a shared key. `plainSecret` is\n * never persisted; the postfix also deletes the entry for promptness.\n */\nconst PLAINTEXT_SECRET_BY_EC = new WeakMap<ExecutionContext<any>, string>();\n\n/**\n * Bridge for ROTATE / REGENERATE, keyed by the same per-operation `ExecutionContext`\n * instance (see {@link PLAINTEXT_SECRET_BY_EC}). Carries the one-time `plainSecret` AND\n * the applied `previousSecretInvalidationDate`, so the postfix builds ROTATE's\n * `oldSecretInvalidationDate` from the value the prefix actually applied — independent of\n * whether the update result round-trips that field.\n */\nconst REISSUE_BRIDGE_BY_EC = new WeakMap<ExecutionContext<any>, { plainSecret: string; previousSecretInvalidationDate: Date | null }>();\n\n/** ROTATE keeps a bounded grace window; REGENERATE keeps an open-ended overlap. */\nenum OAuthClientReissueKind {\n  ROTATE = 'rotate',\n  REGENERATE = 'regenerate',\n}\n\n/**\n * The pre-fetched client fields the reissue prefix reads. `hashedSecret`/`secretPrefix`\n * are present on every persisted client of either scope.\n */\ntype ReissuableOAuthClient = Pick<OAuthClientBase, 'status'> & { hashedSecret: string; secretPrefix: string };\n\n/**\n * Structural view of a per-resource custom-operation enum — the members that have a\n * backend impl in this file. Both `OrgOAuthClients_Operations` and\n * `AppOAuthClients_Operations` satisfy it (identical string values).\n */\ntype OAuthClientCustomOps = { ROTATE: string; REGENERATE: string; EXPIRE: string };\n\ntype OAuthClientTarget = {\n  resourceType: CoreResourceType;\n  scope: ApiKeyScope;\n  ops: OAuthClientCustomOps;\n  variants: ReadonlyArray<{ isOperationDefault: boolean; variantKey?: string }>;\n};\n\n/** The handler-object shape accepted by `createResourceCustomServiceImplementation`. */\nexport type OAuthClientImplHandlers = Parameters<typeof createResourceCustomServiceImplementation>[0]['handlers'];\n\n/**\n * The OAuth-client resources, their scope (drives the `oc_org_` / `oc_app_` prefix), the\n * per-resource custom-op enum, and every op VARIANT each resource exposes.\n *\n * - ORG clients expose an org-admin DEFAULT + a cross-tenant app-super-admin `admin`\n *   variant → both registered.\n * - APP clients are single-variant (APP_ADMIN-scoped) → default only.\n */\nconst OAUTH_CLIENT_TARGETS: ReadonlyArray<OAuthClientTarget> = [\n  {\n    resourceType: CoreResourceType.OAUTH_CLIENTS_ORGANIZATION,\n    scope: ApiKeyScope.ORGANIZATION,\n    ops: OrgOAuthClients_Operations,\n    variants: [\n      { isOperationDefault: true },\n      { isOperationDefault: false, variantKey: 'admin' },\n    ],\n  },\n  {\n    resourceType: CoreResourceType.OAUTH_CLIENTS_APPLICATION,\n    scope: ApiKeyScope.APPLICATION,\n    ops: AppOAuthClients_Operations,\n    variants: [\n      { isOperationDefault: true },\n    ],\n  },\n];\n\n/**\n * Register one custom-impl factory per (target × variant) for a single operation.\n * Every OAuth-client op is API_CALL and needs a distinct registration per variant\n * identity (see the module header) — this centralizes that fan-out.\n */\nfunction oauthClientFactoriesForOperation(\n  operationIdentifierFor: (target: OAuthClientTarget) => string | CoreResourceOperation,\n  handlersFor: (target: OAuthClientTarget, container: Container) => OAuthClientImplHandlers,\n): ResourceCustomServiceImplementationFactory[] {\n  return OAUTH_CLIENT_TARGETS.flatMap((target) =>\n    target.variants.map(({ isOperationDefault, variantKey }) => {\n      const factory = (_resourcesRegistryService: ResourcesRegistryBackendService, container: Container) =>\n        createResourceCustomServiceImplementation({\n          operationPath: {\n            resourceIdentifier: target.resourceType,\n            // API_CALL: the lookup key is built from the RUNNING operation's variantType\n            // (`extractOperationPath` passes it through unchanged), and OAuth-client ops\n            // are dispatched as direct HTTP API_CALLs. Must match exactly.\n            operationIdentifier: operationIdentifierFor(target),\n            variantType: ResourceOperationVariantType.API_CALL,\n            isOperationDefault,\n            variantKey,\n          },\n          handlers: handlersFor(target, container),\n        });\n      return factory as unknown as ResourceCustomServiceImplementationFactory;\n    }),\n  );\n}\n\n/** CREATE — enforce the role-ceiling, then mint material; surface `plainSecret` once. Exported for focused create-pipeline unit tests. */\nexport function buildOAuthClientMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): OAuthClientImplHandlers {\n  return {\n    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n      // Role-ceiling gate — a principal cannot mint a client carrying roles it does not itself hold\n      // (self-service privilege-escalation prevention; APPLICATION-scoped super-admin + system writes\n      // bypass). The ceiling is hierarchy-aware, so an ORG_ADMIN may mint a client carrying the roles\n      // its own role confers (ORG_MANAGER/ORG_MEMBER/…) but never ORG_OWNER above it.\n      // assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege on machine-credential minting.\n      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);\n      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);\n      // Bridge the one-time secret to the postfix, keyed by the per-op EC instance; never persisted.\n      PLAINTEXT_SECRET_BY_EC.set(executionContext, plainSecret);\n      // secretPrefix + hashedSecret are `.excludeFromCreate()`; returning them injects\n      // them into the create payload (preserveServerInjectedFields re-attaches them past\n      // the strict parse) so the row persists with the required fields.\n      return { ...(input as Record<string, unknown>), secretPrefix, hashedSecret };\n    },\n    postfixCoreOperations: async (_id, createdClient, executionContext, _operationPath, _utils) => {\n      if (!createdClient || typeof createdClient !== 'object') return createdClient;\n      const plainSecret = PLAINTEXT_SECRET_BY_EC.get(executionContext);\n      PLAINTEXT_SECRET_BY_EC.delete(executionContext);\n      if (!plainSecret) return createdClient;\n      return { ...(createdClient as Record<string, unknown>), plainSecret };\n    },\n  };\n}\n\n/**\n * ROTATE / REGENERATE — reissue the secret on the SAME record, moving the prior secret\n * into the grace-window slot. The client-credentials exchange keeps honoring the prior\n * secret until `previousSecretInvalidationDate` (ROTATE: the caller-chosen instant,\n * defaulting to now = immediate cutover; REGENERATE: `null` = open-ended overlap).\n */\nfunction buildOAuthClientReissueHandlers(scope: ApiKeyScope, kind: OAuthClientReissueKind): OAuthClientImplHandlers {\n  return {\n    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n      // `currentObject` is the pre-fetched DB record for this UPDATE-borrow op — it\n      // includes the backend-only `hashedSecret`/`secretPrefix` we move into the\n      // previous slot.\n      const current = utils.currentObject as ReissuableOAuthClient | undefined;\n\n      // Only an ACTIVE client can be reissued (409 for a revoked/expired client —\n      // otherwise rotation would silently re-arm a deactivated credential).\n      if (current && current.status !== OAuthClientStatus.ACTIVE) {\n        throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {\n          customMessageReference: ErrorCustomMessageReference.CONFLICT,\n          context: { message: `OAuth client secret cannot be reissued in status '${current.status}'`, oauthClientStatus: current.status },\n        });\n      }\n\n      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);\n      const previousSecretInvalidationDate = kind === OAuthClientReissueKind.ROTATE\n        ? ((input as { oldSecretInvalidationDate?: Date }).oldSecretInvalidationDate ?? new Date())\n        : null;\n      REISSUE_BRIDGE_BY_EC.set(executionContext, { plainSecret, previousSecretInvalidationDate });\n\n      return {\n        ...(input as Record<string, unknown>),\n        hashedSecret,\n        secretPrefix,\n        // Move the outgoing secret into the grace-window slot (server-managed,\n        // excludeFrom{Create,Update} → carried by preserveServerInjectedFields).\n        previousHashedSecret: current?.hashedSecret,\n        previousSecretPrefix: current?.secretPrefix,\n        previousSecretInvalidationDate,\n      };\n    },\n    postfixCoreOperations: async (_id, updated, executionContext, _operationPath, _utils) => {\n      if (!updated || typeof updated !== 'object') return updated;\n      const record = updated as Record<string, unknown>;\n      const bridged = REISSUE_BRIDGE_BY_EC.get(executionContext);\n      REISSUE_BRIDGE_BY_EC.delete(executionContext);\n\n      const withPlainSecret = bridged?.plainSecret ? { ...record, plainSecret: bridged.plainSecret } : { ...record };\n      if (kind === OAuthClientReissueKind.ROTATE) {\n        // ROTATE's response DTO additionally carries the rotated record's id + when the\n        // prior secret is invalidated. Same record, so `oldClientId` is its own `_id`.\n        return { ...withPlainSecret, oldClientId: _id, oldSecretInvalidationDate: bridged?.previousSecretInvalidationDate };\n      }\n      // REGENERATE's response DTO is resource + plainSecret only.\n      return withPlainSecret;\n    },\n  };\n}\n\n/** CREATE impls — org default + org `admin` + app default. */\n/**\n * ACTIVE → EXPIRED, forced — the transition the credential-expiry sweep dispatches (#413).\n *\n * The FIRST status-transition handler on this resource: OAuth clients ship ROTATE and REGENERATE\n * and no deactivate/reactivate pair, so unlike api-keys there was no generic transition helper to\n * reuse. The 409 is the whole reason the sweep goes through a verb — an INACTIVE client was retired\n * by an administrator, and relabelling it EXPIRED would erase who ended it.\n *\n * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — credential state transitions are\n * explicit and validated, never inferred from a caller-supplied field.\n */\nfunction buildOAuthClientExpireHandlers(): OAuthClientImplHandlers {\n  return {\n    prefixCoreOperations: async (_id, _input, executionContext, _operationPath, utils) => {\n      const current = utils.currentObject as { status?: OAuthClientStatus } | undefined;\n\n      if (current && current.status !== OAuthClientStatus.ACTIVE) {\n        throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {\n          customMessageReference: ErrorCustomMessageReference.CONFLICT,\n          context: {\n            message: `OAuth client cannot move to '${OAuthClientStatus.EXPIRED}' from status '${current.status}'`,\n            oauthClientStatus: current.status,\n          },\n        });\n      }\n\n      return { status: OAuthClientStatus.EXPIRED };\n    },\n  };\n}\n\n/**\n * EXPIRE impls — registered separately from the other ops rather than through\n * `oauthClientFactoriesForOperation`, because that helper hardcodes `variantType: API_CALL` and\n * fans out over each resource's HTTP variants. EXPIRE is INTERNAL_CALL with a single default\n * variant, so it needs its own registration or the lookup key would never match and the guard above\n * would be silently unreachable.\n */\nexport function createOAuthClientExpireFactories(): ResourceCustomServiceImplementationFactory[] {\n  return OAUTH_CLIENT_TARGETS.map((target) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService, _container: Container) =>\n      createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: target.resourceType,\n          operationIdentifier: target.ops.EXPIRE,\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isOperationDefault: true,\n        },\n        handlers: buildOAuthClientExpireHandlers(),\n      });\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\nexport function createOAuthClientCreateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    () => CoreResourceOperation.CREATE,\n    (target, container) => buildOAuthClientMintHandlers(target.scope, createRoleHierarchyResolver(container)),\n  );\n}\n\n/** ROTATE impls — bounded grace window. */\nexport function createOAuthClientRotateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    (target) => target.ops.ROTATE,\n    (target) => buildOAuthClientReissueHandlers(target.scope, OAuthClientReissueKind.ROTATE),\n  );\n}\n\n/** REGENERATE impls — open-ended overlap. */\nexport function createOAuthClientRegenerateFactories(): ResourceCustomServiceImplementationFactory[] {\n  return oauthClientFactoriesForOperation(\n    (target) => target.ops.REGENERATE,\n    (target) => buildOAuthClientReissueHandlers(target.scope, OAuthClientReissueKind.REGENERATE),\n  );\n}\n"]}

package/dist/esm/security/outbound/outbound-request-deadline.backend.utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The half of an outbound deadline that is easy to lose: response-BODY consumption.
+ *
+ * ## Why a bound on the request alone is not a bound
+ *
+ * A deadline usually gets written as "abort the fetch after N ms", and that reads complete. It is
+ * not: a provider that returns response headers promptly and then stalls its body retains the
+ * request exactly as effectively as one that never answers at all. The socket stays open, the
+ * caller stays parked, and the timer that was supposed to cap it has already been cleared because
+ * `fetch` resolved.
+ *
+ * ## Why the abort has to be raced rather than assumed
+ *
+ * A conforming `fetch` tears down the response stream when the request's signal aborts, so where
+ * the platform `fetch` is reached DIRECTLY the signal alone covers the body. That reasoning stops
+ * being available the moment the transport is a SEAM something else can substitute — an injected
+ * `fetchImpl`, a stubbed global, a polyfill — because honouring the signal on an in-flight body
+ * read is a property of the implementation and not of the contract. Racing the read against the
+ * signal makes the deadline a property of THIS code rather than of whichever transport happens to
+ * be bound.
+ *
+ * Use this wherever the transport is substitutable. Where the platform `fetch` is called directly
+ * and cannot be replaced, passing the signal to `fetch` is sufficient and this is unnecessary.
+ */
+/**
+ * Read a response body as text, failing at the moment `signal` aborts rather than whenever the
+ * body decides to finish.
+ *
+ * Rejects with the signal's own `reason` when that reason is an `Error`, so the caller's error
+ * message names the deadline that was exceeded rather than a generic abort.
+ */
+export declare function readResponseTextWithinDeadline(response: Pick<Response, 'text'>, signal: AbortSignal): Promise<string>;
+/**
+ * An abort `reason` is `unknown` by contract: `AbortController.abort()` may be handed anything, and
+ * `AbortSignal.timeout` supplies a `TimeoutError` `DOMException`. Normalise it so a caller can
+ * always read a `message`.
+ */
+export declare function abortReasonToError(reason: unknown, fallbackMessage?: string): Error;
+//# sourceMappingURL=outbound-request-deadline.backend.utils.d.ts.map

package/dist/esm/security/outbound/outbound-request-deadline.backend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-request-deadline.backend.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/outbound/outbound-request-deadline.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;GAMG;AACH,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,eAAe,SAAiC,GAAG,KAAK,CAG3G"}

package/dist/esm/security/outbound/outbound-request-deadline.backend.utils.js

@@ -0,0 +1,60 @@
+/**
+ * The half of an outbound deadline that is easy to lose: response-BODY consumption.
+ *
+ * ## Why a bound on the request alone is not a bound
+ *
+ * A deadline usually gets written as "abort the fetch after N ms", and that reads complete. It is
+ * not: a provider that returns response headers promptly and then stalls its body retains the
+ * request exactly as effectively as one that never answers at all. The socket stays open, the
+ * caller stays parked, and the timer that was supposed to cap it has already been cleared because
+ * `fetch` resolved.
+ *
+ * ## Why the abort has to be raced rather than assumed
+ *
+ * A conforming `fetch` tears down the response stream when the request's signal aborts, so where
+ * the platform `fetch` is reached DIRECTLY the signal alone covers the body. That reasoning stops
+ * being available the moment the transport is a SEAM something else can substitute — an injected
+ * `fetchImpl`, a stubbed global, a polyfill — because honouring the signal on an in-flight body
+ * read is a property of the implementation and not of the contract. Racing the read against the
+ * signal makes the deadline a property of THIS code rather than of whichever transport happens to
+ * be bound.
+ *
+ * Use this wherever the transport is substitutable. Where the platform `fetch` is called directly
+ * and cannot be replaced, passing the signal to `fetch` is sufficient and this is unnecessary.
+ */
+/**
+ * Read a response body as text, failing at the moment `signal` aborts rather than whenever the
+ * body decides to finish.
+ *
+ * Rejects with the signal's own `reason` when that reason is an `Error`, so the caller's error
+ * message names the deadline that was exceeded rather than a generic abort.
+ */
+export async function readResponseTextWithinDeadline(response, signal) {
+    if (signal.aborted) {
+        throw abortReasonToError(signal.reason);
+    }
+    let abortListener;
+    const aborted = new Promise((_resolve, reject) => {
+        abortListener = () => reject(abortReasonToError(signal.reason));
+        signal.addEventListener('abort', abortListener, { once: true });
+    });
+    try {
+        return await Promise.race([response.text(), aborted]);
+    }
+    finally {
+        if (abortListener) {
+            signal.removeEventListener('abort', abortListener);
+        }
+    }
+}
+/**
+ * An abort `reason` is `unknown` by contract: `AbortController.abort()` may be handed anything, and
+ * `AbortSignal.timeout` supplies a `TimeoutError` `DOMException`. Normalise it so a caller can
+ * always read a `message`.
+ */
+export function abortReasonToError(reason, fallbackMessage = 'Outbound request was aborted') {
+    if (reason instanceof Error)
+        return reason;
+    return new Error(typeof reason === 'string' ? reason : fallbackMessage);
+}
+//# sourceMappingURL=outbound-request-deadline.backend.utils.js.map

package/dist/esm/security/outbound/outbound-request-deadline.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-request-deadline.backend.utils.js","sourceRoot":"","sources":["../../../../src/security/outbound/outbound-request-deadline.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,QAAgC,EAChC,MAAmB;IAEnB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,aAAuC,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QACtD,aAAa,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAChE,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;YAAS,CAAC;QACT,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe,EAAE,eAAe,GAAG,8BAA8B;IAClG,IAAI,MAAM,YAAY,KAAK;QAAE,OAAO,MAAM,CAAC;IAC3C,OAAO,IAAI,KAAK,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;AAC1E,CAAC","sourcesContent":["/**\n * The half of an outbound deadline that is easy to lose: response-BODY consumption.\n *\n * ## Why a bound on the request alone is not a bound\n *\n * A deadline usually gets written as \"abort the fetch after N ms\", and that reads complete. It is\n * not: a provider that returns response headers promptly and then stalls its body retains the\n * request exactly as effectively as one that never answers at all. The socket stays open, the\n * caller stays parked, and the timer that was supposed to cap it has already been cleared because\n * `fetch` resolved.\n *\n * ## Why the abort has to be raced rather than assumed\n *\n * A conforming `fetch` tears down the response stream when the request's signal aborts, so where\n * the platform `fetch` is reached DIRECTLY the signal alone covers the body. That reasoning stops\n * being available the moment the transport is a SEAM something else can substitute — an injected\n * `fetchImpl`, a stubbed global, a polyfill — because honouring the signal on an in-flight body\n * read is a property of the implementation and not of the contract. Racing the read against the\n * signal makes the deadline a property of THIS code rather than of whichever transport happens to\n * be bound.\n *\n * Use this wherever the transport is substitutable. Where the platform `fetch` is called directly\n * and cannot be replaced, passing the signal to `fetch` is sufficient and this is unnecessary.\n */\n\n/**\n * Read a response body as text, failing at the moment `signal` aborts rather than whenever the\n * body decides to finish.\n *\n * Rejects with the signal's own `reason` when that reason is an `Error`, so the caller's error\n * message names the deadline that was exceeded rather than a generic abort.\n */\nexport async function readResponseTextWithinDeadline(\n  response: Pick<Response, 'text'>,\n  signal: AbortSignal,\n): Promise<string> {\n  if (signal.aborted) {\n    throw abortReasonToError(signal.reason);\n  }\n\n  let abortListener: (() => void) | undefined;\n  const aborted = new Promise<never>((_resolve, reject) => {\n    abortListener = () => reject(abortReasonToError(signal.reason));\n    signal.addEventListener('abort', abortListener, { once: true });\n  });\n\n  try {\n    return await Promise.race([response.text(), aborted]);\n  } finally {\n    if (abortListener) {\n      signal.removeEventListener('abort', abortListener);\n    }\n  }\n}\n\n/**\n * An abort `reason` is `unknown` by contract: `AbortController.abort()` may be handed anything, and\n * `AbortSignal.timeout` supplies a `TimeoutError` `DOMException`. Normalise it so a caller can\n * always read a `message`.\n */\nexport function abortReasonToError(reason: unknown, fallbackMessage = 'Outbound request was aborted'): Error {\n  if (reason instanceof Error) return reason;\n  return new Error(typeof reason === 'string' ? reason : fallbackMessage);\n}\n"]}

package/dist/esm/security/outbound/outbound-request-headers.backend.utils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Merging engine-owned headers over a header set the engine does not control.
+ *
+ * ## The defect this exists to remove
+ *
+ * Every outbound arm in the engine composes its request headers the same way: take a set the
+ * PROVIDER supplied (transport headers off a runtime contract, a harvested REST catalogue's
+ * `defaultHeaders`) and apply the engine's own credential over the top. Written as an object
+ * literal that reads as safe, and four arms carried a JSDoc saying so — a variant of *"it is
+ * applied AFTER the provider's headers, so a provider cannot take authentication over by naming
+ * that header"*.
+ *
+ * **That reasoning holds only for an IDENTICAL spelling.** HTTP header names are case-insensitive;
+ * a JavaScript object's keys are not. A provider naming `Authorization` while the engine writes
+ * `authorization` produces TWO DISTINCT KEYS, and neither `fetch` nor `Headers` treats the later
+ * one as a replacement — they are COMBINED into a single comma-joined field value:
+ *
+ * ```
+ * authorization: Bearer provider-chosen, Basic QUMtYWNjb3VudDpzM2NyM3Q=
+ * ```
+ *
+ * That is strictly worse than the takeover the ordering was defending against. A takeover
+ * authenticates as the provider; a combination authenticates as NOBODY, so the arm fails closed
+ * against its vendor with a credential error that names neither cause. It is a provider-caused
+ * outage the arm's own promise says cannot happen.
+ *
+ * ## Why the collision is likely rather than theoretical
+ *
+ * The two spellings are not equally probable. `WildoHeaderKeys.AUTHORIZATION` is `authorization`,
+ * lower-case, while `Authorization` is the conventional spelling throughout vendor documentation —
+ * so the colliding case is the one a provider author writes BY DEFAULT, and the safe one is the
+ * one they would have to be told to write.
+ *
+ * ## Why a shared function rather than a filter per arm
+ *
+ * Five sites merge these two sources, and the defect had already been fixed at one of them by hand
+ * before anyone counted the rest. A predicate applied N times is a predicate that will be applied
+ * N-1 times; the invariant belongs somewhere a new arm reaches by calling rather than by
+ * remembering. See `.claude/rules/invariant-call-site-enumeration.md` — "prefer making the
+ * invariant unbypassable over applying it N times".
+ *
+ * ## Why DROP rather than REFUSE
+ *
+ * A provider that names the engine's credential header has made a mistake, not an attack. Refusing
+ * the request would turn a harmless declaration into a dead capability — on the SMS arm, one that
+ * carries phone verification and the second factor. The engine's value is authoritative either
+ * way, so dropping the provider's key restores exactly the promise the JSDoc always made.
+ */
+/**
+ * The provider's headers, with every case-insensitive spelling of an engine-owned header removed,
+ * and the engine's own values applied over the result.
+ *
+ * The returned record is safe to hand to `fetch`: no two of its keys name the same HTTP header, so
+ * the `Headers` layer has nothing to combine.
+ *
+ * `engineOwned` wins unconditionally — that is what makes it engine-owned. Keys of `engineOwned`
+ * whose value is `undefined` are omitted rather than sent empty, so a caller may build its set
+ * conditionally without an intermediate spread.
+ *
+ * @param providerSupplied Headers the engine did not author: a provider contract's transport
+ *   headers, a harvested catalogue's `defaultHeaders`, or any set crossing a trust boundary.
+ * @param engineOwned Headers the engine owns and that must reach the wire exactly once — the
+ *   credential, and anything else whose value a provider must not influence.
+ */
+export declare function withEngineOwnedHeaders(providerSupplied: Readonly<Record<string, string>> | undefined, engineOwned: Readonly<Record<string, string | undefined>>): Record<string, string>;
+//# sourceMappingURL=outbound-request-headers.backend.utils.d.ts.map