@webpieces/core-util 0.4.963 → 0.4.965

package/src/http/RouteMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadata.ts"],"names":[],"mappings":"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","sourcesContent":["import { MaskSpec } from './LogFieldMask';\nimport { AuthMeta } from './auth-mode';\nimport { EndpointResponseType, HttpParameterBinding } from './HttpContract';\nimport { StreamingEndpointMetadata } from './StreamingContract';\nimport { EndpointOperation } from './HttpEndpointOptions';\nimport { CallMode } from '../errors/CallMode';\nimport { AnyContextKey } from '../ContextKey';\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n *\n * Lives in its own file (one class per file) purely for file size, exactly as `api-kind.ts` and\n * `external-caller.ts` were split off `decorators.ts` before it. Nothing about its role changed.\n */\nexport class RouteMetadata {\n    apiClass?: Function;\n    // webpieces-disable no-any-unknown -- erased application policy is validated by AuthorizationHook at server startup\n    authorization?: import('./authorization').AuthorizationRequirement<unknown>;\n    localOnly = false;\n    /**\n     * True when the contract is `EXTERNAL_OUTBOUND`: an outside system's API. Its client sends ONLY\n     * {@link externalContextKeys} and believes no response header (`DestinationTrust.forRoute`).\n     */\n    externalOutbound = false;\n    /** `@ExternalContextKeys(...)` resolved for this method — class-level keys plus the method's own. */\n    externalContextKeys: readonly AnyContextKey[] = [];\n\n    /** Clients clone metadata per call so a concrete winning mode governs both trust directions. */\n    withSelectedAuth(method: import('./auth-mode').AuthMode): RouteMetadata {\n        if (!this.authMeta?.methods.includes(method)) throw new Error('Selected credential is not declared by this endpoint.');\n        const route = Object.assign(new RouteMetadata(this.httpMethod, this.path, this.methodName, this.operation), this);\n        route.authMeta = new AuthMeta([method], method.kind === 'public' ? this.authMeta.publicReason : undefined);\n        return route;\n    }\n    /**\n     * Whether the user is waiting on THIS call (#1293). Not an endpoint declaration: a client stamps\n     * it per call with {@link withCallMode}, from the `ClientConfig` it was built with. FOREGROUND on\n     * every route a contract's decorators build.\n     */\n    callMode: CallMode = CallMode.FOREGROUND;\n\n    /**\n     * A per-call copy carrying `mode`. A BACKGROUND call also gets {@link hideProgress} — nobody is\n     * waiting on it — so an app's `RequestLifecycleListener` keeps it out of the progress bar with\n     * no endpoint declaration. FOREGROUND returns this route unchanged.\n     */\n    withCallMode(mode: CallMode): RouteMetadata {\n        if (mode === CallMode.FOREGROUND) return this;\n        const route = new RouteMetadata(\n            this.httpMethod,\n            this.path,\n            this.methodName,\n            this.operation,\n            this.controllerClassName,\n            this.authMeta,\n            this.apiName,\n            this.formPost,\n            this.mask,\n            this.rawBody,\n            this.parameterBindings,\n            this.bodyParameterIndex,\n            this.responseType,\n            this.streaming,\n            true,\n            this.noLogging,\n            this.allowUpgradeInFlight,\n            this.noResponseBody,\n        );\n        route.apiClass = this.apiClass;\n        route.authorization = this.authorization;\n        route.localOnly = this.localOnly;\n        route.externalOutbound = this.externalOutbound;\n        route.externalContextKeys = this.externalContextKeys;\n        route.callMode = mode;\n        return route;\n    }\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n    /**\n     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded\n     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch\n     * without knowing the apiClass/methodName. Default false = JSON.\n     */\n    readonly formPost: boolean;\n    /**\n     * The @MaskLog field-mask spec for this route, or undefined when the method declared none. Read\n     * ONCE here at route-build time and handed to {@link LogApiCallImpl} via ApiMethodInfo, so the per-call\n     * log path pays for masking only on routes that opted in (the rest stay on plain JSON.stringify).\n     */\n    readonly mask?: MaskSpec;\n    /**\n     * True when @Endpoint(..., { rawBody: true }): the transport must retain the verbatim bytes +\n     * absolute url for `VendorAuthHook.verify` to check a vendor credential over. Rides the route\n     * metadata for the same reason {@link formPost} does — the transport adapter decides how to read\n     * the body from the ROUTE, without knowing the apiClass/methodName.\n     */\n    readonly rawBody: boolean;\n    /**\n     * True when @Endpoint(..., { hideProgress: true }): the app should show no progress UI for this\n     * call. webpieces does not act on it; an app's `RequestLifecycleListener.onRequestStart/onRequestEnd`\n     * reads it from the ROUTE, for the same reason {@link formPost} and {@link rawBody} ride here —\n     * the consumer branches without knowing the apiClass/methodName. Default false = the call drives\n     * the progress UI.\n     */\n    readonly hideProgress: boolean;\n    /**\n     * True when @Endpoint(..., { noLogging: true }): read by {@link LogApiCallImpl} (via\n     * ApiMethodInfo, exactly as {@link mask} is) so no `[API-*-req]`/`[API-*-resp-*]` line is\n     * emitted for the call, on the client or the server. Default false = an ordinary, fully-logged\n     * route.\n     */\n    readonly noLogging: boolean;\n    /**\n     * True when @Endpoint(..., { allowUpgradeInFlight: true }): an app may upgrade while this call is\n     * in flight, and the call neither blocks nor arms an upgrade. webpieces only carries it; the\n     * app's `RequestLifecycleListener` / upgrade logic reads it. Default false = the app must not\n     * upgrade while the call is in flight, and its success counts toward arming one.\n     */\n    readonly allowUpgradeInFlight: boolean;\n    /**\n     * True when the endpoint is CLOUDTASKS or CRON (no response body BY KIND, #1348), or declares\n     * @Endpoint(..., { responseBody: NONE }): the method returns `Promise<void>` and the\n     * success response is 0 bytes. The server answers 204 with no body; every client accepts `{}`,\n     * an empty 200 or a 204 and resolves `undefined`. Default false = a JSON body.\n     */\n    readonly noResponseBody: boolean;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        /** Explicit side-effect semantics; deliberately independent of the HTTP verb. */\n        readonly operation: EndpointOperation,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n        formPost: boolean = false,\n        mask?: MaskSpec,\n        rawBody: boolean = false,\n        /** Explicit path/query mappings, in API declaration order. */\n        readonly parameterBindings: readonly HttpParameterBinding[] = [],\n        /** The sole unannotated POST parameter, or undefined for a bodyless route. */\n        readonly bodyParameterIndex?: number,\n        /** Whether clients receive only the body or the complete status/header/body response. */\n        readonly responseType: EndpointResponseType = 'body',\n        /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */\n        readonly streaming?: StreamingEndpointMetadata,\n        hideProgress: boolean = false,\n        noLogging: boolean = false,\n        allowUpgradeInFlight: boolean = false,\n        noResponseBody: boolean = false,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n        this.formPost = formPost;\n        this.mask = mask;\n        this.rawBody = rawBody;\n        this.parameterBindings = parameterBindings;\n        this.bodyParameterIndex = bodyParameterIndex;\n        this.responseType = responseType;\n        this.streaming = streaming;\n        this.hideProgress = hideProgress;\n        this.noLogging = noLogging;\n        this.allowUpgradeInFlight = allowUpgradeInFlight;\n        this.noResponseBody = noResponseBody;\n    }\n}\n"]}
+{"version":3,"file":"RouteMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadata.ts"],"names":[],"mappings":"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","sourcesContent":["import { MaskSpec } from './LogFieldMask';\nimport { AuthMeta } from './auth-mode';\nimport { EndpointResponseType, HttpParameterBinding } from './HttpContract';\nimport { StreamingEndpointMetadata } from './StreamingContract';\nimport { EndpointOperation } from './HttpEndpointOptions';\nimport { CallMode } from '../errors/CallMode';\nimport { AnyContextKey } from '../ContextKey';\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n *\n * Lives in its own file (one class per file) purely for file size, exactly as `api-kind.ts` and\n * `external-caller.ts` were split off `decorators.ts` before it. Nothing about its role changed.\n */\nexport class RouteMetadata {\n    apiClass?: Function;\n    // webpieces-disable no-any-unknown -- erased application policy is validated by AuthorizationHook at server startup\n    authorization?: import('./authorization').AuthorizationRequirement<unknown>;\n    localOnly = false;\n    /**\n     * True when the contract is `EXTERNAL_OUTBOUND`: an outside system's API. Its client sends ONLY\n     * {@link externalContextKeys} and believes no response header (`DestinationTrust.forRoute`).\n     */\n    externalOutbound = false;\n    /** `@ExternalContextKeys(...)` resolved for this method — class-level keys plus the method's own. */\n    externalContextKeys: readonly AnyContextKey[] = [];\n\n    /** Clients clone metadata per call so a concrete winning mode governs both trust directions. */\n    withSelectedAuth(method: import('./auth-mode').AuthMode): RouteMetadata {\n        if (!this.authMeta?.methods.includes(method)) throw new Error('Selected credential is not declared by this endpoint.');\n        const route = Object.assign(new RouteMetadata(this.httpMethod, this.path, this.methodName, this.operation), this);\n        route.authMeta = new AuthMeta([method], method.kind === 'public' ? this.authMeta.publicReason : undefined);\n        return route;\n    }\n    /**\n     * Whether the user is waiting on THIS call (#1293). Not an endpoint declaration: a client stamps\n     * it per call with {@link withCallMode}, from the `ClientConfig` it was built with. FOREGROUND on\n     * every route a contract's decorators build.\n     */\n    callMode: CallMode = CallMode.FOREGROUND;\n\n    /**\n     * A per-call copy carrying `mode`. A BACKGROUND call also gets {@link hideProgress} — nobody is\n     * waiting on it — so an app's `RequestLifecycleListener` keeps it out of the progress bar with\n     * no endpoint declaration. FOREGROUND returns this route unchanged.\n     */\n    withCallMode(mode: CallMode): RouteMetadata {\n        if (mode === CallMode.FOREGROUND) return this;\n        const route = new RouteMetadata(\n            this.httpMethod,\n            this.path,\n            this.methodName,\n            this.operation,\n            this.controllerClassName,\n            this.authMeta,\n            this.apiName,\n            this.formPost,\n            this.mask,\n            this.rawBody,\n            this.parameterBindings,\n            this.bodyParameterIndex,\n            this.responseType,\n            this.streaming,\n            true,\n            this.noLogging,\n            this.allowUpgradeInFlight,\n            this.noResponseBody,\n        );\n        route.apiClass = this.apiClass;\n        route.authorization = this.authorization;\n        route.localOnly = this.localOnly;\n        route.externalOutbound = this.externalOutbound;\n        route.externalContextKeys = this.externalContextKeys;\n        route.callMode = mode;\n        return route;\n    }\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n    /**\n     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded\n     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch\n     * without knowing the apiClass/methodName. Default false = JSON.\n     */\n    readonly formPost: boolean;\n    /**\n     * The @MaskLog field-mask spec for this route, or undefined when the method declared none. Read\n     * ONCE here at route-build time and handed to {@link LogApiCallImpl} via ApiMethodInfo, so the per-call\n     * log path pays for masking only on routes that opted in (the rest stay on plain JSON.stringify).\n     */\n    readonly mask?: MaskSpec;\n    /**\n     * True when @Endpoint(..., { rawBody: true }): the transport must retain the verbatim bytes +\n     * absolute url for `VendorAuthVerifier.verify` to check a vendor credential over. Rides the route\n     * metadata for the same reason {@link formPost} does — the transport adapter decides how to read\n     * the body from the ROUTE, without knowing the apiClass/methodName.\n     */\n    readonly rawBody: boolean;\n    /**\n     * True when @Endpoint(..., { hideProgress: true }): the app should show no progress UI for this\n     * call. webpieces does not act on it; an app's `RequestLifecycleListener.onRequestStart/onRequestEnd`\n     * reads it from the ROUTE, for the same reason {@link formPost} and {@link rawBody} ride here —\n     * the consumer branches without knowing the apiClass/methodName. Default false = the call drives\n     * the progress UI.\n     */\n    readonly hideProgress: boolean;\n    /**\n     * True when @Endpoint(..., { noLogging: true }): read by {@link LogApiCallImpl} (via\n     * ApiMethodInfo, exactly as {@link mask} is) so no `[API-*-req]`/`[API-*-resp-*]` line is\n     * emitted for the call, on the client or the server. Default false = an ordinary, fully-logged\n     * route.\n     */\n    readonly noLogging: boolean;\n    /**\n     * True when @Endpoint(..., { allowUpgradeInFlight: true }): an app may upgrade while this call is\n     * in flight, and the call neither blocks nor arms an upgrade. webpieces only carries it; the\n     * app's `RequestLifecycleListener` / upgrade logic reads it. Default false = the app must not\n     * upgrade while the call is in flight, and its success counts toward arming one.\n     */\n    readonly allowUpgradeInFlight: boolean;\n    /**\n     * True when the endpoint is CLOUDTASKS or CRON (no response body BY KIND, #1348), or declares\n     * @Endpoint(..., { responseBody: NONE }): the method returns `Promise<void>` and the\n     * success response is 0 bytes. The server answers 204 with no body; every client accepts `{}`,\n     * an empty 200 or a 204 and resolves `undefined`. Default false = a JSON body.\n     */\n    readonly noResponseBody: boolean;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        /** Explicit side-effect semantics; deliberately independent of the HTTP verb. */\n        readonly operation: EndpointOperation,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n        formPost: boolean = false,\n        mask?: MaskSpec,\n        rawBody: boolean = false,\n        /** Explicit path/query mappings, in API declaration order. */\n        readonly parameterBindings: readonly HttpParameterBinding[] = [],\n        /** The sole unannotated POST parameter, or undefined for a bodyless route. */\n        readonly bodyParameterIndex?: number,\n        /** Whether clients receive only the body or the complete status/header/body response. */\n        readonly responseType: EndpointResponseType = 'body',\n        /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */\n        readonly streaming?: StreamingEndpointMetadata,\n        hideProgress: boolean = false,\n        noLogging: boolean = false,\n        allowUpgradeInFlight: boolean = false,\n        noResponseBody: boolean = false,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n        this.formPost = formPost;\n        this.mask = mask;\n        this.rawBody = rawBody;\n        this.parameterBindings = parameterBindings;\n        this.bodyParameterIndex = bodyParameterIndex;\n        this.responseType = responseType;\n        this.streaming = streaming;\n        this.hideProgress = hideProgress;\n        this.noLogging = noLogging;\n        this.allowUpgradeInFlight = allowUpgradeInFlight;\n        this.noResponseBody = noResponseBody;\n    }\n}\n"]}

package/src/http/StreamErrorControl.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamErrorControl = exports.StreamDisconnectedError = exports.StreamProtocolError = void 0;
-const ClientRegistry_1 = require("./ClientRegistry");
+const ApiRegistry_1 = require("./ApiRegistry");
 const HttpResponseDto_1 = require("./HttpResponseDto");
 const WebpiecesDefaultErrorTranslator_1 = require("./WebpiecesDefaultErrorTranslator");
 const errorUtils_1 = require("../lib/errorUtils");
@@ -58,7 +58,7 @@ class StreamErrorControl {
         return new StreamProtocolError('Error translator returned for a JSONL error control record.');
     }
     translator() {
-        return ClientRegistry_1.ClientRegistry.getErrorTranslator(this.route.apiClass, this.route.methodName);
+        return ApiRegistry_1.ApiRegistry.getErrorTranslator(this.route.apiClass, this.route.methodName);
     }
     response(line) {
         let control;

package/src/http/StreamErrorControl.js.map

@@ -1 +1 @@
-{"version":3,"file":"StreamErrorControl.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/StreamErrorControl.ts"],"names":[],"mappings":";;;AACA,qDAAkD;AAClD,uDAAoF;AACpF,uFAAuF;AAEvF,kDAA4C;AAC5C,2DAA2D;AAI3D,MAAa,mBAAoB,SAAQ,wCAAoB;CAAG;AAAhE,kDAAgE;AAEhE,MAAa,uBAAwB,SAAQ,wCAAoB;CAAG;AAApE,0DAAoE;AAEpE,MAAM,aAAa;IACf,IAAI,CAAU;IACd,MAAM,CAAU;CACnB;AAED,MAAM,aAAa;IACf,IAAI,CAAU;IACd,KAAK,CAAU;CAClB;AAED,MAAM,eAAe;IACjB,MAAM,CAAiB;IACvB,OAAO,CAAmB;IAC1B,IAAI,CAAY;CACnB;AAED,MAAM,aAAa;IACf,OAAO,CAAU;IACjB,QAAQ,CAAmB;CAC9B;AAED;;;;GAIG;AACH,MAAa,kBAAkB;IACE;IAA7B,YAA6B,KAAoB;QAApB,UAAK,GAAL,KAAK,CAAe;IAAG,CAAC;IAErD,MAAM,CAAC,KAAY;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjD,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC;IAC7F,CAAC;IAED,uFAAuF;IACvF,MAAM,CAAC,IAAY,EAAE,IAAgB;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrC,+GAA+G;QAC/G,IAAI,CAAC;YACD,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC3C,oEAAkC,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,IAAI,mBAAmB,CAC1B,6DAA6D,CAChE,CAAC;IACN,CAAC;IAEO,UAAU;QACd,OAAO,+BAAc,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACzF,CAAC;IAEO,QAAQ,CAAC,IAAY;QACzB,IAAI,OAAsB,CAAC;QAC3B,8GAA8G;QAC9G,IAAI,CAAC;YACD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAkB,CAAC;QACzD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,MAAM,IAAI,mBAAmB,CACzB,uCAAuC,EACvC,SAAS,EACT,SAAS,EACT,KAAK,CACR,CAAC;QACN,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC;QACzC,MAAM,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;QAC3C,IACI,OAAO,EAAE,OAAO,KAAK,OAAO;YAC5B,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ;YAChC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;YACjC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAEvB,MAAM,IAAI,mBAAmB,CAAC,uCAAuC,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAqB,EAAc,EAAE;YAC7D,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACvE,MAAM,IAAI,mBAAmB,CAAC,uCAAuC,CAAC,CAAC;YAC3E,CAAC;YACD,OAAO,IAAI,4BAAU,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,iCAAe,CACtB,IAAI,oCAAkB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAClD,MAAM,EACN,OAAO,CAAC,QAAQ,EAAE,IAAI,CACzB,CAAC;IACN,CAAC;CACJ;AA/DD,gDA+DC","sourcesContent":["import { ClientRole } from '../errors/ClientRole';\nimport { ClientRegistry } from './ClientRegistry';\nimport { HttpHeader, HttpResponseDto, HttpResponseStatus } from './HttpResponseDto';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { DtoValue } from '../mcp/DtoSchema';\nimport { toError } from '../lib/errorUtils';\nimport { StreamTransportError } from './StreamingContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { ErrorTranslator } from './ErrorTranslator';\n\nexport class StreamProtocolError extends StreamTransportError {}\n\nexport class StreamDisconnectedError extends StreamTransportError {}\n\nclass ControlStatus {\n    code?: number;\n    reason?: string;\n}\n\nclass ControlHeader {\n    name?: string;\n    value?: string;\n}\n\nclass ControlResponse {\n    status?: ControlStatus;\n    headers?: ControlHeader[];\n    body?: DtoValue;\n}\n\nclass ControlRecord {\n    control?: string;\n    response?: ControlResponse;\n}\n\n/**\n * Reserved ASCII-RS controls share exactly the unary ErrorTranslator seam in both directions —\n * including its `CallScope` ladder: the translator is resolved for the streaming ROUTE's contract\n * class and method (method -> API -> ALL -> webpieces default), exactly as a unary call's is.\n */\nexport class StreamErrorControl {\n    constructor(private readonly route: RouteMetadata) {}\n\n    encode(error: Error): string {\n        const response = this.translator().toWire(error);\n        return `${String.fromCharCode(0x1e)}${JSON.stringify({ control: 'error', response })}\\n`;\n    }\n\n    /** @param role - who is receiving the record, declared at the reading side's setup. */\n    decode(line: string, role: ClientRole): Error {\n        const response = this.response(line);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- fromWire returns its typed result by throwing\n        try {\n            this.translator().fromWire(response, role);\n            WEBPIECES_DEFAULT_ERROR_TRANSLATOR.fromWire(response, role);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return error;\n        }\n        return new StreamProtocolError(\n            'Error translator returned for a JSONL error control record.',\n        );\n    }\n\n    private translator(): ErrorTranslator {\n        return ClientRegistry.getErrorTranslator(this.route.apiClass, this.route.methodName);\n    }\n\n    private response(line: string): HttpResponseDto {\n        let control: ControlRecord;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- JSON.parse is the untrusted control boundary\n        try {\n            control = JSON.parse(line.slice(1)) as ControlRecord;\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new StreamProtocolError(\n                'Malformed JSONL error control record.',\n                undefined,\n                undefined,\n                error,\n            );\n        }\n        const status = control?.response?.status;\n        const headers = control?.response?.headers;\n        if (\n            control?.control !== 'error' ||\n            typeof status?.code !== 'number' ||\n            typeof status.reason !== 'string' ||\n            !Array.isArray(headers)\n        )\n            throw new StreamProtocolError('Malformed JSONL error control record.');\n        const mapped = headers.map((header: ControlHeader): HttpHeader => {\n            if (typeof header?.name !== 'string' || typeof header.value !== 'string') {\n                throw new StreamProtocolError('Malformed JSONL error control header.');\n            }\n            return new HttpHeader(header.name, header.value);\n        });\n        return new HttpResponseDto(\n            new HttpResponseStatus(status.code, status.reason),\n            mapped,\n            control.response?.body,\n        );\n    }\n}\n"]}
+{"version":3,"file":"StreamErrorControl.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/StreamErrorControl.ts"],"names":[],"mappings":"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","sourcesContent":["import { ClientRole } from '../errors/ClientRole';\nimport { ApiRegistry } from './ApiRegistry';\nimport { HttpHeader, HttpResponseDto, HttpResponseStatus } from './HttpResponseDto';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { DtoValue } from '../mcp/DtoSchema';\nimport { toError } from '../lib/errorUtils';\nimport { StreamTransportError } from './StreamingContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { ErrorTranslator } from './ErrorTranslator';\n\nexport class StreamProtocolError extends StreamTransportError {}\n\nexport class StreamDisconnectedError extends StreamTransportError {}\n\nclass ControlStatus {\n    code?: number;\n    reason?: string;\n}\n\nclass ControlHeader {\n    name?: string;\n    value?: string;\n}\n\nclass ControlResponse {\n    status?: ControlStatus;\n    headers?: ControlHeader[];\n    body?: DtoValue;\n}\n\nclass ControlRecord {\n    control?: string;\n    response?: ControlResponse;\n}\n\n/**\n * Reserved ASCII-RS controls share exactly the unary ErrorTranslator seam in both directions —\n * including its `CallScope` ladder: the translator is resolved for the streaming ROUTE's contract\n * class and method (method -> API -> ALL -> webpieces default), exactly as a unary call's is.\n */\nexport class StreamErrorControl {\n    constructor(private readonly route: RouteMetadata) {}\n\n    encode(error: Error): string {\n        const response = this.translator().toWire(error);\n        return `${String.fromCharCode(0x1e)}${JSON.stringify({ control: 'error', response })}\\n`;\n    }\n\n    /** @param role - who is receiving the record, declared at the reading side's setup. */\n    decode(line: string, role: ClientRole): Error {\n        const response = this.response(line);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- fromWire returns its typed result by throwing\n        try {\n            this.translator().fromWire(response, role);\n            WEBPIECES_DEFAULT_ERROR_TRANSLATOR.fromWire(response, role);\n        } catch (err: unknown) {\n            const error = toError(err);\n            return error;\n        }\n        return new StreamProtocolError(\n            'Error translator returned for a JSONL error control record.',\n        );\n    }\n\n    private translator(): ErrorTranslator {\n        return ApiRegistry.getErrorTranslator(this.route.apiClass, this.route.methodName);\n    }\n\n    private response(line: string): HttpResponseDto {\n        let control: ControlRecord;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- JSON.parse is the untrusted control boundary\n        try {\n            control = JSON.parse(line.slice(1)) as ControlRecord;\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new StreamProtocolError(\n                'Malformed JSONL error control record.',\n                undefined,\n                undefined,\n                error,\n            );\n        }\n        const status = control?.response?.status;\n        const headers = control?.response?.headers;\n        if (\n            control?.control !== 'error' ||\n            typeof status?.code !== 'number' ||\n            typeof status.reason !== 'string' ||\n            !Array.isArray(headers)\n        )\n            throw new StreamProtocolError('Malformed JSONL error control record.');\n        const mapped = headers.map((header: ControlHeader): HttpHeader => {\n            if (typeof header?.name !== 'string' || typeof header.value !== 'string') {\n                throw new StreamProtocolError('Malformed JSONL error control header.');\n            }\n            return new HttpHeader(header.name, header.value);\n        });\n        return new HttpResponseDto(\n            new HttpResponseStatus(status.code, status.reason),\n            mapped,\n            control.response?.body,\n        );\n    }\n}\n"]}

package/src/http/TransportDefault.d.ts

@@ -1,10 +1,10 @@
 import { CallStrategy } from './CallStrategy';
 /**
  * What a TRANSPORT does for a call nobody registered a policy for — the last rung of
- * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
+ * {@link ClientRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
  * ALL, else this).
  *
- * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so
+ * It is the ONLY per-transport difference: every transport calls the same `ClientRegistry.execute`, so
  * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.
  *
  * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no

package/src/http/TransportDefault.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransportDefault = void 0;
 /**
  * What a TRANSPORT does for a call nobody registered a policy for — the last rung of
- * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
+ * {@link ClientRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
  * ALL, else this).
  *
- * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so
+ * It is the ONLY per-transport difference: every transport calls the same `ClientRegistry.execute`, so
  * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.
  *
  * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no

package/src/http/TransportDefault.js.map

@@ -1 +1 @@
-{"version":3,"file":"TransportDefault.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/TransportDefault.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IAGZ;IAGA;IALb;IACI,mFAAmF;IAC1E,SAAiB;IAC1B,2FAA2F;IAC3F,4FAA4F;IACnF,QAAgC;QAHhC,cAAS,GAAT,SAAS,CAAQ;QAGjB,aAAQ,GAAR,QAAQ,CAAwB;IAC1C,CAAC;CACP;AARD,4CAQC","sourcesContent":["import { CallStrategy } from './CallStrategy';\n\n/**\n * What a TRANSPORT does for a call nobody registered a policy for — the last rung of\n * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →\n * ALL, else this).\n *\n * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so\n * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.\n *\n * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no\n *   default retry, because only the application knows whether repeating a POST is safe.\n * - Cloud Tasks enqueue: `new TransportDefault(30_000, new RetryStrategy(5_000, 3, 500, 2, 4_000).run)`\n *   — enqueue is idempotent by construction (one task name for every attempt), so it retries.\n */\nexport class TransportDefault {\n    constructor(\n        /** The single attempt's deadline when no strategy (registered or default) runs. */\n        readonly timeoutMs: number,\n        /** The transport's own strategy; when set it owns timing exactly like a registered one. */\n        // webpieces-disable no-any-unknown -- transport strategies span heterogeneous response DTOs\n        readonly strategy?: CallStrategy<unknown>,\n    ) {}\n}\n"]}
+{"version":3,"file":"TransportDefault.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/TransportDefault.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IAGZ;IAGA;IALb;IACI,mFAAmF;IAC1E,SAAiB;IAC1B,2FAA2F;IAC3F,4FAA4F;IACnF,QAAgC;QAHhC,cAAS,GAAT,SAAS,CAAQ;QAGjB,aAAQ,GAAR,QAAQ,CAAwB;IAC1C,CAAC;CACP;AARD,4CAQC","sourcesContent":["import { CallStrategy } from './CallStrategy';\n\n/**\n * What a TRANSPORT does for a call nobody registered a policy for — the last rung of\n * {@link ClientRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →\n * ALL, else this).\n *\n * It is the ONLY per-transport difference: every transport calls the same `ClientRegistry.execute`, so\n * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.\n *\n * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no\n *   default retry, because only the application knows whether repeating a POST is safe.\n * - Cloud Tasks enqueue: `new TransportDefault(30_000, new RetryStrategy(5_000, 3, 500, 2, 4_000).run)`\n *   — enqueue is idempotent by construction (one task name for every attempt), so it retries.\n */\nexport class TransportDefault {\n    constructor(\n        /** The single attempt's deadline when no strategy (registered or default) runs. */\n        readonly timeoutMs: number,\n        /** The transport's own strategy; when set it owns timing exactly like a registered one. */\n        // webpieces-disable no-any-unknown -- transport strategies span heterogeneous response DTOs\n        readonly strategy?: CallStrategy<unknown>,\n    ) {}\n}\n"]}

package/src/http/WebpiecesDefaultErrorTranslator.d.ts

@@ -5,7 +5,7 @@ import { HttpResponseDto } from './HttpResponseDto';
  * THE webpieces default {@link ErrorTranslator} — ONE class, BOTH halves, used by the node server, by
  * every node client and by the browser bundle alike.
  *
- * It is what {@link ClientRegistry.getErrorTranslator} answers for a call no `CallScope` rung
+ * It is what {@link ApiRegistry.getErrorTranslator} answers for a call no `CallScope` rung
  * (method, API, ALL) has a translator for, and it is
  * what an app's own translator calls to DECLINE an error:
  *
@@ -14,7 +14,7 @@ import { HttpResponseDto } from './HttpResponseDto';
  * ```
  *
  * so "no translator registered" and "a translator that does not claim this error" produce
- * byte-identical output. It lives in core-util, beside {@link ClientRegistry}, because core-util is
+ * byte-identical output. It lives in core-util, beside {@link ApiRegistry}, because core-util is
  * the package every API contract already depends on and the only one both a server and a browser
  * bundle can reach. Both halves needed nothing else: the outbound half wants
  * {@link ApiErrorBoundary} + {@link ApiErrorHttpStatus}, the inbound half wants

package/src/http/WebpiecesDefaultErrorTranslator.js

@@ -14,7 +14,7 @@ const HttpResponseDto_1 = require("./HttpResponseDto");
  * THE webpieces default {@link ErrorTranslator} — ONE class, BOTH halves, used by the node server, by
  * every node client and by the browser bundle alike.
  *
- * It is what {@link ClientRegistry.getErrorTranslator} answers for a call no `CallScope` rung
+ * It is what {@link ApiRegistry.getErrorTranslator} answers for a call no `CallScope` rung
  * (method, API, ALL) has a translator for, and it is
  * what an app's own translator calls to DECLINE an error:
  *
@@ -23,7 +23,7 @@ const HttpResponseDto_1 = require("./HttpResponseDto");
  * ```
  *
  * so "no translator registered" and "a translator that does not claim this error" produce
- * byte-identical output. It lives in core-util, beside {@link ClientRegistry}, because core-util is
+ * byte-identical output. It lives in core-util, beside {@link ApiRegistry}, because core-util is
  * the package every API contract already depends on and the only one both a server and a browser
  * bundle can reach. Both halves needed nothing else: the outbound half wants
  * {@link ApiErrorBoundary} + {@link ApiErrorHttpStatus}, the inbound half wants

package/src/http/WebpiecesDefaultErrorTranslator.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesDefaultErrorTranslator.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesDefaultErrorTranslator.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiErrorBoundary } from '../errors/ApiErrorBoundary';\nimport { ApiErrorCodec } from '../errors/ApiErrorCodec';\nimport { ApiCodedError, ApiError } from '../errors/ApiError';\nimport { ClientRole } from '../errors/ClientRole';\nimport { ReceivedApiErrorRule } from '../errors/ReceivedApiErrorRule';\nimport { OAuthErrorResponse } from '../oauth/OAuthErrorResponse';\nimport { OAuthProtocolError } from '../oauth/OAuthProtocolError';\nimport { ApiCallTimeoutError } from './ApiCallTimeoutError';\nimport { ApiErrorHttpStatus, PublishedKind } from './ApiErrorHttpStatus';\nimport { ErrorTranslator } from './ErrorTranslator';\nimport { HttpHeader, HttpResponseDto, HttpResponseStatus } from './HttpResponseDto';\n\n/**\n * THE webpieces default {@link ErrorTranslator} — ONE class, BOTH halves, used by the node server, by\n * every node client and by the browser bundle alike.\n *\n * It is what {@link ClientRegistry.getErrorTranslator} answers for a call no `CallScope` rung\n * (method, API, ALL) has a translator for, and it is\n * what an app's own translator calls to DECLINE an error:\n *\n * ```ts\n * private readonly fallback = new WebpiecesDefaultErrorTranslator();\n * ```\n *\n * so \"no translator registered\" and \"a translator that does not claim this error\" produce\n * byte-identical output. It lives in core-util, beside {@link ClientRegistry}, because core-util is\n * the package every API contract already depends on and the only one both a server and a browser\n * bundle can reach. Both halves needed nothing else: the outbound half wants\n * {@link ApiErrorBoundary} + {@link ApiErrorHttpStatus}, the inbound half wants\n * {@link ApiErrorCodec} + {@link ReceivedApiErrorRule}, and all four were already here.\n *\n * It holds no ROLE: who is receiving ({@link ClientRole}) is an argument of `fromWire`, supplied by\n * the client that read the response from its own setup, so one stateless instance serves a server's\n * clients and a browser's alike.\n *\n * Stateless, so {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR} is a shared instance — but constructing\n * your own costs nothing and reads better at a delegation site.\n */\nexport class WebpiecesDefaultErrorTranslator implements ErrorTranslator {\n    /** Reason phrase for a client deadline; see {@link ApiCallTimeoutError}. Never 'Gateway Timeout'. */\n    static readonly CALL_TIMEOUT_REASON = 'Network Timeout';\n\n    private readonly boundary = new ApiErrorBoundary();\n\n    private readonly genericMessages: Map<number, string> = new Map<number, string>([\n        [266, 'End User Error'],\n        [400, 'Bad Request'],\n        [401, 'Unauthorized'],\n        [403, 'Forbidden'],\n        [404, 'Not Found'],\n        [408, 'Request Timeout'],\n        [409, 'Conflict'],\n        [412, 'Precondition Failed'],\n        [415, 'Unsupported Media Type'],\n        [422, 'Unprocessable Content'],\n        [426, 'Upgrade Required'],\n        [429, 'Too Many Requests'],\n        [500, 'Internal Server Error'],\n        [501, 'Not Implemented'],\n        [502, 'Bad Gateway'],\n        [503, 'Service Unavailable'],\n        [504, 'Gateway Timeout'],\n    ]);\n\n    /**\n     * SERVER: an exception in, the exact HTTP response out.\n     *\n     * The payload IS the answer. {@link ApiErrorBoundary.encode} has already applied both shared\n     * rules — a caller-local `ApiConnectionError` (and every non-`ApiError`) publishes as\n     * `implementation`, and only an `ApiEndUserError`'s own message is disclosed — and the payload\n     * carries everything HTTP needs after that: `kind`, `statusCode`, `edgeHttpStatus` and\n     * `retryAfterSeconds`. So there is no `instanceof` here and nothing re-derived from the raw\n     * error; unknown throws and caller-local failures come out as a 500 implementation failure\n     * because that is what the payload says.\n     *\n     * The one exception is an {@link OAuthProtocolError}: its caller is an OAuth client, so it is\n     * answered in the RFC shape by `OAuthErrorResponse`, not as a payload.\n     *\n     * An `ApiEndUserError` publishes 266 here, ALWAYS. Whether a particular REQUEST republishes that\n     * as a real 4xx is a property of the CALLER, not of the error, so it is decided once per request\n     * from `WebpiecesCoreHeaders.SURFACE` by the server boundary (`ExpressWrapper.handleError`) —\n     * see {@link SurfaceEndUserStatus}. That is why this class takes no constructor argument any\n     * more: the old `new ApiErrorHttpMapper('gui' | 'edge')` made every delegating app translator\n     * responsible for repeating its router's mode, and repeating it wrongly was silent.\n     */\n    toWire(error: Error): HttpResponseDto {\n        // An OAuth refusal is answered to an OAuth CLIENT, which parses the RFC 6749/6750 body and\n        // never the ApiError envelope (#1176). Same renderer as every other OAuth boundary.\n        if (error instanceof OAuthProtocolError) {\n            return OAuthErrorResponse.toResponse(error, undefined);\n        }\n        const payload = this.boundary.encode(error);\n        // The boundary never publishes kind 'connection' — that is the whole first rule above — so\n        // this is the published subset ApiErrorHttpStatus.codeFor accepts.\n        const kind = payload.kind as PublishedKind;\n        const status = ApiErrorHttpStatus.codeFor(kind, payload.statusCode);\n        const headers =\n            payload.retryAfterSeconds !== undefined\n                ? [new HttpHeader('retry-after', String(payload.retryAfterSeconds))]\n                : [];\n        return new HttpResponseDto(\n            new HttpResponseStatus(status, this.reasonPhrase(error, status)),\n            headers,\n            payload,\n        );\n    }\n\n    /**\n     * The reason phrase for `error`. An {@link ApiCallTimeoutError} is THIS process's own client\n     * deadline firing on an outbound call: no gateway was involved, so it is never titled\n     * 'Gateway Timeout' (issue #1170). It keeps its 504 status and `dependency-timeout` payload —\n     * retry semantics are unchanged — and only the human framing differs.\n     */\n    private reasonPhrase(error: Error, status: number): string {\n        if (error instanceof ApiCallTimeoutError) {\n            return WebpiecesDefaultErrorTranslator.CALL_TIMEOUT_REASON;\n        }\n        return this.genericMessage(status);\n    }\n\n    /**\n     * CLIENT: the response in, a THROW out — or a silent return for an ordinary success.\n     *\n     * Called for EVERY response, 2xx included (see {@link ErrorTranslator.fromWire}). A 2xx that is\n     * not 266 is exactly the case where webpieces has nothing to say, so it returns and the caller\n     * gets its DTO. Everything else throws, which is what lets `ProxyClient` call this and then simply\n     * stop — a failure response can never fall through to a typed caller.\n     *\n     * The rule applied is {@link ReceivedApiErrorRule}, shared verbatim with IPC: ordinary 4xx is MY\n     * bug, ordinary 5xx is THEIRS, retry-relevant statuses retain their specific timeout/gateway/\n     * backoff/unavailable meaning, 266 is the end user's own answer, a 426 `client-too-old` stays\n     * {@link ApiClientTooOldError}, and a 401 depends on `role` (see {@link ClientRole}).\n     *\n     * @param role - who is receiving, declared at the client's setup. No default.\n     */\n    fromWire(response: HttpResponseDto, role: ClientRole): void {\n        const code = response.status.code;\n        if (code >= 200 && code < 300 && code !== 266) {\n            return;\n        }\n        const decoded = this.decodeBody(response);\n        const message =\n            decoded?.message ?? this.fallbackMessage(response.body, response.status.reason);\n        throw ReceivedApiErrorRule.adapt(\n            role,\n            code,\n            message,\n            decoded,\n            this.retryAfterSeconds(response.headers),\n        );\n    }\n\n    /** The reason phrase webpieces writes beside a status it chose itself. */\n    genericMessage(code: number): string {\n        return this.genericMessages.get(code) ?? 'Request Failed';\n    }\n\n    /**\n     * A webpieces peer sends an {@link ApiErrorPayload}; a foreign responder sends anything at all.\n     * The status is only believed when it AGREES with the kind the body claims — a body saying\n     * `not-found` beside a 500 is a mismatched response, not a 404, and falls back to the status.\n     */\n    private decodeBody(response: HttpResponseDto): ApiError | undefined {\n        if (!ApiErrorCodec.isPayload(response.body)) {\n            return undefined;\n        }\n        const decoded = ApiErrorCodec.decode(response.body);\n        if (!ApiErrorHttpStatus.hasCode(decoded)) {\n            return undefined;\n        }\n        // `statusCode` is the 'coded' kind's own status, the one thing the shared table cannot know.\n        const statusCode = decoded instanceof ApiCodedError ? decoded.statusCode : undefined;\n        const declared = ApiErrorHttpStatus.codeFor(decoded.kind, statusCode);\n        return declared === response.status.code ? decoded : undefined;\n    }\n\n    // webpieces-disable no-any-unknown -- HTTP response bodies are app-owned until this boundary safely inspects them\n    private fallbackMessage(body: unknown, reason: string): string {\n        if (typeof body === 'object' && body !== null) {\n            const message = Object.getOwnPropertyDescriptor(body, 'message')?.value;\n            if (typeof message === 'string' && message.length > 0) return message.slice(0, 4096);\n        }\n        return reason || 'Request Failed';\n    }\n\n    /** Parse either legal Retry-After form and bound untrusted guidance to one day. */\n    private retryAfterSeconds(headers: readonly HttpHeader[]): number | undefined {\n        const raw = headers.find(\n            (header: HttpHeader) => header.name.toLowerCase() === 'retry-after',\n        )?.value;\n        if (raw === undefined) return undefined;\n        const seconds = Number(raw.trim());\n        if (Number.isFinite(seconds) && seconds >= 0) return Math.min(Math.ceil(seconds), 86_400);\n        const at = Date.parse(raw);\n        if (!Number.isFinite(at)) return undefined;\n        return Math.min(Math.max(Math.ceil((at - Date.now()) / 1_000), 0), 86_400);\n    }\n}\n\n/** Process-wide built-in instance — stateless, so one shared instance is enough. */\nexport const WEBPIECES_DEFAULT_ERROR_TRANSLATOR = new WebpiecesDefaultErrorTranslator();\n"]}
+{"version":3,"file":"WebpiecesDefaultErrorTranslator.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesDefaultErrorTranslator.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiErrorBoundary } from '../errors/ApiErrorBoundary';\nimport { ApiErrorCodec } from '../errors/ApiErrorCodec';\nimport { ApiCodedError, ApiError } from '../errors/ApiError';\nimport { ClientRole } from '../errors/ClientRole';\nimport { ReceivedApiErrorRule } from '../errors/ReceivedApiErrorRule';\nimport { OAuthErrorResponse } from '../oauth/OAuthErrorResponse';\nimport { OAuthProtocolError } from '../oauth/OAuthProtocolError';\nimport { ApiCallTimeoutError } from './ApiCallTimeoutError';\nimport { ApiErrorHttpStatus, PublishedKind } from './ApiErrorHttpStatus';\nimport { ErrorTranslator } from './ErrorTranslator';\nimport { HttpHeader, HttpResponseDto, HttpResponseStatus } from './HttpResponseDto';\n\n/**\n * THE webpieces default {@link ErrorTranslator} — ONE class, BOTH halves, used by the node server, by\n * every node client and by the browser bundle alike.\n *\n * It is what {@link ApiRegistry.getErrorTranslator} answers for a call no `CallScope` rung\n * (method, API, ALL) has a translator for, and it is\n * what an app's own translator calls to DECLINE an error:\n *\n * ```ts\n * private readonly fallback = new WebpiecesDefaultErrorTranslator();\n * ```\n *\n * so \"no translator registered\" and \"a translator that does not claim this error\" produce\n * byte-identical output. It lives in core-util, beside {@link ApiRegistry}, because core-util is\n * the package every API contract already depends on and the only one both a server and a browser\n * bundle can reach. Both halves needed nothing else: the outbound half wants\n * {@link ApiErrorBoundary} + {@link ApiErrorHttpStatus}, the inbound half wants\n * {@link ApiErrorCodec} + {@link ReceivedApiErrorRule}, and all four were already here.\n *\n * It holds no ROLE: who is receiving ({@link ClientRole}) is an argument of `fromWire`, supplied by\n * the client that read the response from its own setup, so one stateless instance serves a server's\n * clients and a browser's alike.\n *\n * Stateless, so {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR} is a shared instance — but constructing\n * your own costs nothing and reads better at a delegation site.\n */\nexport class WebpiecesDefaultErrorTranslator implements ErrorTranslator {\n    /** Reason phrase for a client deadline; see {@link ApiCallTimeoutError}. Never 'Gateway Timeout'. */\n    static readonly CALL_TIMEOUT_REASON = 'Network Timeout';\n\n    private readonly boundary = new ApiErrorBoundary();\n\n    private readonly genericMessages: Map<number, string> = new Map<number, string>([\n        [266, 'End User Error'],\n        [400, 'Bad Request'],\n        [401, 'Unauthorized'],\n        [403, 'Forbidden'],\n        [404, 'Not Found'],\n        [408, 'Request Timeout'],\n        [409, 'Conflict'],\n        [412, 'Precondition Failed'],\n        [415, 'Unsupported Media Type'],\n        [422, 'Unprocessable Content'],\n        [426, 'Upgrade Required'],\n        [429, 'Too Many Requests'],\n        [500, 'Internal Server Error'],\n        [501, 'Not Implemented'],\n        [502, 'Bad Gateway'],\n        [503, 'Service Unavailable'],\n        [504, 'Gateway Timeout'],\n    ]);\n\n    /**\n     * SERVER: an exception in, the exact HTTP response out.\n     *\n     * The payload IS the answer. {@link ApiErrorBoundary.encode} has already applied both shared\n     * rules — a caller-local `ApiConnectionError` (and every non-`ApiError`) publishes as\n     * `implementation`, and only an `ApiEndUserError`'s own message is disclosed — and the payload\n     * carries everything HTTP needs after that: `kind`, `statusCode`, `edgeHttpStatus` and\n     * `retryAfterSeconds`. So there is no `instanceof` here and nothing re-derived from the raw\n     * error; unknown throws and caller-local failures come out as a 500 implementation failure\n     * because that is what the payload says.\n     *\n     * The one exception is an {@link OAuthProtocolError}: its caller is an OAuth client, so it is\n     * answered in the RFC shape by `OAuthErrorResponse`, not as a payload.\n     *\n     * An `ApiEndUserError` publishes 266 here, ALWAYS. Whether a particular REQUEST republishes that\n     * as a real 4xx is a property of the CALLER, not of the error, so it is decided once per request\n     * from `WebpiecesCoreHeaders.SURFACE` by the server boundary (`ExpressWrapper.handleError`) —\n     * see {@link SurfaceEndUserStatus}. That is why this class takes no constructor argument any\n     * more: the old `new ApiErrorHttpMapper('gui' | 'edge')` made every delegating app translator\n     * responsible for repeating its router's mode, and repeating it wrongly was silent.\n     */\n    toWire(error: Error): HttpResponseDto {\n        // An OAuth refusal is answered to an OAuth CLIENT, which parses the RFC 6749/6750 body and\n        // never the ApiError envelope (#1176). Same renderer as every other OAuth boundary.\n        if (error instanceof OAuthProtocolError) {\n            return OAuthErrorResponse.toResponse(error, undefined);\n        }\n        const payload = this.boundary.encode(error);\n        // The boundary never publishes kind 'connection' — that is the whole first rule above — so\n        // this is the published subset ApiErrorHttpStatus.codeFor accepts.\n        const kind = payload.kind as PublishedKind;\n        const status = ApiErrorHttpStatus.codeFor(kind, payload.statusCode);\n        const headers =\n            payload.retryAfterSeconds !== undefined\n                ? [new HttpHeader('retry-after', String(payload.retryAfterSeconds))]\n                : [];\n        return new HttpResponseDto(\n            new HttpResponseStatus(status, this.reasonPhrase(error, status)),\n            headers,\n            payload,\n        );\n    }\n\n    /**\n     * The reason phrase for `error`. An {@link ApiCallTimeoutError} is THIS process's own client\n     * deadline firing on an outbound call: no gateway was involved, so it is never titled\n     * 'Gateway Timeout' (issue #1170). It keeps its 504 status and `dependency-timeout` payload —\n     * retry semantics are unchanged — and only the human framing differs.\n     */\n    private reasonPhrase(error: Error, status: number): string {\n        if (error instanceof ApiCallTimeoutError) {\n            return WebpiecesDefaultErrorTranslator.CALL_TIMEOUT_REASON;\n        }\n        return this.genericMessage(status);\n    }\n\n    /**\n     * CLIENT: the response in, a THROW out — or a silent return for an ordinary success.\n     *\n     * Called for EVERY response, 2xx included (see {@link ErrorTranslator.fromWire}). A 2xx that is\n     * not 266 is exactly the case where webpieces has nothing to say, so it returns and the caller\n     * gets its DTO. Everything else throws, which is what lets `ProxyClient` call this and then simply\n     * stop — a failure response can never fall through to a typed caller.\n     *\n     * The rule applied is {@link ReceivedApiErrorRule}, shared verbatim with IPC: ordinary 4xx is MY\n     * bug, ordinary 5xx is THEIRS, retry-relevant statuses retain their specific timeout/gateway/\n     * backoff/unavailable meaning, 266 is the end user's own answer, a 426 `client-too-old` stays\n     * {@link ApiClientTooOldError}, and a 401 depends on `role` (see {@link ClientRole}).\n     *\n     * @param role - who is receiving, declared at the client's setup. No default.\n     */\n    fromWire(response: HttpResponseDto, role: ClientRole): void {\n        const code = response.status.code;\n        if (code >= 200 && code < 300 && code !== 266) {\n            return;\n        }\n        const decoded = this.decodeBody(response);\n        const message =\n            decoded?.message ?? this.fallbackMessage(response.body, response.status.reason);\n        throw ReceivedApiErrorRule.adapt(\n            role,\n            code,\n            message,\n            decoded,\n            this.retryAfterSeconds(response.headers),\n        );\n    }\n\n    /** The reason phrase webpieces writes beside a status it chose itself. */\n    genericMessage(code: number): string {\n        return this.genericMessages.get(code) ?? 'Request Failed';\n    }\n\n    /**\n     * A webpieces peer sends an {@link ApiErrorPayload}; a foreign responder sends anything at all.\n     * The status is only believed when it AGREES with the kind the body claims — a body saying\n     * `not-found` beside a 500 is a mismatched response, not a 404, and falls back to the status.\n     */\n    private decodeBody(response: HttpResponseDto): ApiError | undefined {\n        if (!ApiErrorCodec.isPayload(response.body)) {\n            return undefined;\n        }\n        const decoded = ApiErrorCodec.decode(response.body);\n        if (!ApiErrorHttpStatus.hasCode(decoded)) {\n            return undefined;\n        }\n        // `statusCode` is the 'coded' kind's own status, the one thing the shared table cannot know.\n        const statusCode = decoded instanceof ApiCodedError ? decoded.statusCode : undefined;\n        const declared = ApiErrorHttpStatus.codeFor(decoded.kind, statusCode);\n        return declared === response.status.code ? decoded : undefined;\n    }\n\n    // webpieces-disable no-any-unknown -- HTTP response bodies are app-owned until this boundary safely inspects them\n    private fallbackMessage(body: unknown, reason: string): string {\n        if (typeof body === 'object' && body !== null) {\n            const message = Object.getOwnPropertyDescriptor(body, 'message')?.value;\n            if (typeof message === 'string' && message.length > 0) return message.slice(0, 4096);\n        }\n        return reason || 'Request Failed';\n    }\n\n    /** Parse either legal Retry-After form and bound untrusted guidance to one day. */\n    private retryAfterSeconds(headers: readonly HttpHeader[]): number | undefined {\n        const raw = headers.find(\n            (header: HttpHeader) => header.name.toLowerCase() === 'retry-after',\n        )?.value;\n        if (raw === undefined) return undefined;\n        const seconds = Number(raw.trim());\n        if (Number.isFinite(seconds) && seconds >= 0) return Math.min(Math.ceil(seconds), 86_400);\n        const at = Date.parse(raw);\n        if (!Number.isFinite(at)) return undefined;\n        return Math.min(Math.max(Math.ceil((at - Date.now()) / 1_000), 0), 86_400);\n    }\n}\n\n/** Process-wide built-in instance — stateless, so one shared instance is enough. */\nexport const WEBPIECES_DEFAULT_ERROR_TRANSLATOR = new WebpiecesDefaultErrorTranslator();\n"]}

package/src/http/auth-mode.d.ts

@@ -104,10 +104,12 @@ export declare function oidcSameProject(): OidcAuthMethod;
 export declare function oidcSvcs(callers: OidcCallers): OidcAuthMethod;
 export declare function sharedSecret(secretKey: string): AuthMethod;
 /**
- * A credential in a VENDOR's scheme, on both ends of a hop: the app-bound `VendorAuthHook` (core-context)
- * mints it when WE call the vendor (and refreshes it once on a 401), and verifies it when the vendor
- * calls US. `name` selects the vendor. A served `vendorAuth(...)` endpoint requires
- * `@Endpoint(..., { rawBody: true })` so the hook has the exact bytes to verify.
+ * A credential in a VENDOR's scheme, on both ends of a hop, served by TWO independent app-bound DI
+ * roles (core-context): the `VendorAuthMinter` mints it when WE call the vendor (and refreshes it once
+ * on a 401), and the `VendorAuthVerifier` verifies it when the vendor calls US. The direction is
+ * decided by whether the runtime is sending or receiving, so one contract declaration serves both.
+ * `name` selects the vendor. A served `vendorAuth(...)` endpoint requires
+ * `@Endpoint(..., { rawBody: true })` so the verifier has the exact bytes to verify.
  */
 export declare function vendorAuth(name: string): AuthMethod;
 export declare function apiKey(regime: string, credentials: ApiKeyCredentials): AuthMethod;

package/src/http/auth-mode.js

@@ -146,10 +146,12 @@ function oidcSvcs(callers) { return { kind: 'oidc', callerScope: 'services', cal
 // webpieces-disable no-function-outside-class -- canonical credential descriptor factory
 function sharedSecret(secretKey) { return { kind: 'shared-secret', secretKey }; }
 /**
- * A credential in a VENDOR's scheme, on both ends of a hop: the app-bound `VendorAuthHook` (core-context)
- * mints it when WE call the vendor (and refreshes it once on a 401), and verifies it when the vendor
- * calls US. `name` selects the vendor. A served `vendorAuth(...)` endpoint requires
- * `@Endpoint(..., { rawBody: true })` so the hook has the exact bytes to verify.
+ * A credential in a VENDOR's scheme, on both ends of a hop, served by TWO independent app-bound DI
+ * roles (core-context): the `VendorAuthMinter` mints it when WE call the vendor (and refreshes it once
+ * on a 401), and the `VendorAuthVerifier` verifies it when the vendor calls US. The direction is
+ * decided by whether the runtime is sending or receiving, so one contract declaration serves both.
+ * `name` selects the vendor. A served `vendorAuth(...)` endpoint requires
+ * `@Endpoint(..., { rawBody: true })` so the verifier has the exact bytes to verify.
  */
 // webpieces-disable no-function-outside-class -- canonical credential descriptor factory
 function vendorAuth(name) { return { kind: 'vendorAuth', name }; }

package/src/http/auth-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-mode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/auth-mode.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AnyContextKey } from '../ContextKey';\n\n/**\n * WHERE one api-key credential rides.\n *\n * A header credential names the {@link AnyContextKey ContextKey} that carries it — NEVER a header-name\n * string. The key's `httpHeader` is the wire name, so the ONE definition of each header (the\n * ContextKey) is reused on every surface: `RequestContext` put/get, the client/server header\n * transfer, this declaration, and the published OpenAPI document. A string here was a second copy a\n * rename left stale (#1249). The key MUST declare an `httpHeader` — {@link AuthDeclaration} refuses\n * one that does not, and the OpenAPI generator reads the header name off the key's\n * `ContextKey.trusted(...)` / `ContextKey.untrusted(...)` definition.\n */\nexport type ApiKeyCredential =\n    | { in: 'header'; key: AnyContextKey; description?: string }\n    | { in: 'bearer'; key?: never; description?: string };\n\nexport type ApiKeyCredentials = readonly [ApiKeyCredential, ...ApiKeyCredential[]];\n\n/**\n * The service accounts an `oidcSvcs([...])` endpoint names, at least one: an empty list is not a\n * policy anybody could mean, so it does not compile. Each entry resolves as `'self'` (this service's\n * runtime SA), a bare id (`<id>@<project>.iam.gserviceaccount.com`) or a full email (verbatim).\n */\nexport type OidcCallers = readonly [string, ...string[]];\n\n/**\n * WHICH Google-signed callers an OIDC endpoint accepts, named by `callerScope`:\n * - `'same-project'` (`oidcSameProject()`): any service account of THIS GCP project. Off GCP there is\n *   no project, so the check is open.\n * - `'services'` (`oidcSvcs([...])`): exactly the listed service accounts, which may belong to other\n *   projects.\n * One endpoint may declare one of each; see {@link OidcAuthMethods}.\n */\nexport type OidcAuthMethod =\n    | { kind: 'oidc'; callerScope: 'same-project' }\n    | { kind: 'oidc'; callerScope: 'services'; callers: OidcCallers };\n\n/**\n * The OIDC methods ONE endpoint declares, in declaration order: one, or one per caller scope. They are\n * ONE bearer credential, so a verifier receives them together, checks the token's signature once, and\n * admits the call when ANY of them admits the caller.\n */\nexport type OidcAuthMethods = readonly [OidcAuthMethod, ...OidcAuthMethod[]];\n\n/** One concrete mechanism; user policy belongs exclusively to WpAuthorization. */\nexport type AuthMethod =\n    | { kind: 'jwt' }\n    | OidcAuthMethod\n    | { kind: 'shared-secret'; secretKey: string }\n    | { kind: 'vendorAuth'; name: string }\n    | { kind: 'apikey'; regime: string; credentials: ApiKeyCredentials };\n\nexport type AuthMethods = readonly [AuthMethod, ...AuthMethod[]];\nexport type AuthMode = AuthMethod | { kind: 'public' };\n\n/** Alternatives remain unresolved until a concrete mechanism is chosen for this hop. */\nexport class AuthMeta {\n    readonly methods: readonly [AuthMode, ...AuthMode[]];\n\n    constructor(\n        methods: readonly [AuthMode, ...AuthMode[]],\n        public readonly publicReason: string | undefined,\n    ) {\n        this.methods = methods;\n        AuthDeclaration.validate(this);\n        this.methods = Object.freeze(methods.map((method: AuthMode) => AuthMeta.snapshot(method))) as readonly [AuthMode, ...AuthMode[]];\n        Object.freeze(this);\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static snapshot(method: AuthMode): AuthMode {\n        switch (method.kind) {\n            case 'oidc': return method.callerScope === 'services'\n                ? Object.freeze({ ...method, callers: Object.freeze([...method.callers]) as OidcCallers })\n                : Object.freeze({ ...method });\n            case 'apikey': return Object.freeze({ ...method, credentials: Object.freeze(method.credentials.map((credential: ApiKeyCredential) => Object.freeze({ ...credential }))) as ApiKeyCredentials });\n            default: return Object.freeze({ ...method });\n        }\n    }\n}\n\nexport class AuthDeclaration {\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    static validate(meta: AuthMeta): void {\n        if (!Array.isArray(meta.methods) || meta.methods.length === 0) throw new Error('@WpAuth requires a nonempty methods tuple.');\n        const kinds = new Set<string>();\n        for (const method of meta.methods) {\n            if (!method || typeof method !== 'object' || kinds.has(this.uniquenessKey(method))) throw new Error('@WpAuth rejects duplicate or invalid credential methods.');\n            kinds.add(this.uniquenessKey(method));\n            this.validateMethod(method);\n        }\n        if (kinds.has('public')) {\n            if (meta.methods.length !== 1 || typeof meta.publicReason !== 'string' || !meta.publicReason.trim()) {\n                throw new Error('Public auth must be declared separately with @WpAuthPublic(reason).');\n            }\n        } else if (meta.publicReason !== undefined) throw new Error('Protected @WpAuth rejects public reasons.');\n    }\n\n    /**\n     * One method per credential kind, except OIDC: one per `callerScope`, so `oidcSameProject()` and\n     * `oidcSvcs([...])` may pair on one endpoint (this project's accounts OR the listed ones). They are\n     * still ONE bearer credential, which AuthFilter verifies once for both.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static uniquenessKey(method: AuthMode): string {\n        return method.kind === 'oidc' ? `oidc:${method.callerScope}` : method.kind;\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static validateMethod(method: AuthMode): void {\n        let keys: readonly string[];\n        switch (method.kind) {\n            case 'jwt':\n            case 'public': keys = ['kind']; break;\n            case 'oidc': keys = this.oidcKeys(method); break;\n            case 'shared-secret':\n                keys = ['kind', 'secretKey'];\n                this.requireText(method.secretKey, 'sharedSecret'); break;\n            case 'vendorAuth':\n                keys = ['kind', 'name'];\n                this.requireText(method.name, 'vendorAuth'); break;\n            case 'apikey':\n                keys = ['kind', 'regime', 'credentials'];\n                this.requireText(method.regime, 'apiKey');\n                if (!Array.isArray(method.credentials) || !method.credentials.length) throw new Error('apiKey(...) requires a nonempty credentials tuple.');\n                for (const credential of method.credentials) {\n                    if (credential.in === 'header') this.requireHeaderKey(credential.key);\n                    else if (credential.in !== 'bearer' || Object.hasOwn(credential, 'key')) throw new Error('Invalid API-key credential location.');\n                }\n                break;\n            default: throw new Error('Unknown @WpAuth method; use jwt/oidcSameProject/oidcSvcs/sharedSecret/vendorAuth/apiKey descriptors.');\n        }\n        for (const key of Object.keys(method)) {\n            if (!keys.includes(key)) throw new Error(`Auth method rejects '${key}'; operation policy belongs in @WpAuthorization.`);\n        }\n    }\n\n    /**\n     * The keys an OIDC descriptor may carry, after checking its scope. `OidcCallers` already makes an\n     * empty `oidcSvcs([])` a compile error; this is the backstop for a list that reached the decorator\n     * around the type (a cast, a spread of a runtime array, plain JS), so it fails when the decorator\n     * is evaluated instead of reaching a verifier.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static oidcKeys(method: OidcAuthMethod): readonly string[] {\n        if (method.callerScope === 'same-project') return ['kind', 'callerScope'];\n        if (method.callerScope !== 'services') throw new Error(\"Unknown OIDC callerScope; use oidcSameProject() or oidcSvcs(['svc-a']).\");\n        if (!Array.isArray(method.callers) || method.callers.length === 0 || !method.callers.every((caller: string) => typeof caller === 'string' && caller.trim().length > 0)) {\n            throw new Error(\"oidcSvcs([...]) requires at least one nonblank service account; use oidcSameProject() to accept this GCP project's service accounts.\");\n        }\n        return ['kind', 'callerScope', 'callers'];\n    }\n\n    /**\n     * A header credential's key must be a ContextKey that rides the wire. `httpHeader` is optional on\n     * ContextKey itself (most keys never leave the process), and the factories' explicit value-type\n     * argument (`ContextKey.untrusted<string>(...)`) stops TypeScript inferring whether one was\n     * passed, so the type cannot say \"a key WITH a header\". It is checked once, when the contract is\n     * decorated, and the OpenAPI generator refuses the same key statically.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static requireHeaderKey(key: AnyContextKey | undefined): void {\n        if (!key || typeof key !== 'object' || typeof key.name !== 'string') {\n            throw new Error(\"apiKey header credential requires `key`: the ContextKey carrying it, e.g. { in: 'header', key: MyKeys.API_KEY }.\");\n        }\n        if (typeof key.httpHeader !== 'string' || !key.httpHeader.trim()) {\n            throw new Error(`apiKey header credential key '${key.name}' declares no httpHeader; define it with ContextKey.trusted(name, provenance, '<header>') or ContextKey.untrusted(name, '<header>').`);\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static requireText(value: string, label: string): void {\n        if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} requires a nonempty name.`);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function jwt(): AuthMethod { return { kind: 'jwt' }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function oidcSameProject(): OidcAuthMethod { return { kind: 'oidc', callerScope: 'same-project' }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function oidcSvcs(callers: OidcCallers): OidcAuthMethod { return { kind: 'oidc', callerScope: 'services', callers }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function sharedSecret(secretKey: string): AuthMethod { return { kind: 'shared-secret', secretKey }; }\n/**\n * A credential in a VENDOR's scheme, on both ends of a hop: the app-bound `VendorAuthHook` (core-context)\n * mints it when WE call the vendor (and refreshes it once on a 401), and verifies it when the vendor\n * calls US. `name` selects the vendor. A served `vendorAuth(...)` endpoint requires\n * `@Endpoint(..., { rawBody: true })` so the hook has the exact bytes to verify.\n */\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function vendorAuth(name: string): AuthMethod { return { kind: 'vendorAuth', name }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function apiKey(regime: string, credentials: ApiKeyCredentials): AuthMethod { return { kind: 'apikey', regime, credentials }; }\n"]}
+{"version":3,"file":"auth-mode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/auth-mode.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AnyContextKey } from '../ContextKey';\n\n/**\n * WHERE one api-key credential rides.\n *\n * A header credential names the {@link AnyContextKey ContextKey} that carries it — NEVER a header-name\n * string. The key's `httpHeader` is the wire name, so the ONE definition of each header (the\n * ContextKey) is reused on every surface: `RequestContext` put/get, the client/server header\n * transfer, this declaration, and the published OpenAPI document. A string here was a second copy a\n * rename left stale (#1249). The key MUST declare an `httpHeader` — {@link AuthDeclaration} refuses\n * one that does not, and the OpenAPI generator reads the header name off the key's\n * `ContextKey.trusted(...)` / `ContextKey.untrusted(...)` definition.\n */\nexport type ApiKeyCredential =\n    | { in: 'header'; key: AnyContextKey; description?: string }\n    | { in: 'bearer'; key?: never; description?: string };\n\nexport type ApiKeyCredentials = readonly [ApiKeyCredential, ...ApiKeyCredential[]];\n\n/**\n * The service accounts an `oidcSvcs([...])` endpoint names, at least one: an empty list is not a\n * policy anybody could mean, so it does not compile. Each entry resolves as `'self'` (this service's\n * runtime SA), a bare id (`<id>@<project>.iam.gserviceaccount.com`) or a full email (verbatim).\n */\nexport type OidcCallers = readonly [string, ...string[]];\n\n/**\n * WHICH Google-signed callers an OIDC endpoint accepts, named by `callerScope`:\n * - `'same-project'` (`oidcSameProject()`): any service account of THIS GCP project. Off GCP there is\n *   no project, so the check is open.\n * - `'services'` (`oidcSvcs([...])`): exactly the listed service accounts, which may belong to other\n *   projects.\n * One endpoint may declare one of each; see {@link OidcAuthMethods}.\n */\nexport type OidcAuthMethod =\n    | { kind: 'oidc'; callerScope: 'same-project' }\n    | { kind: 'oidc'; callerScope: 'services'; callers: OidcCallers };\n\n/**\n * The OIDC methods ONE endpoint declares, in declaration order: one, or one per caller scope. They are\n * ONE bearer credential, so a verifier receives them together, checks the token's signature once, and\n * admits the call when ANY of them admits the caller.\n */\nexport type OidcAuthMethods = readonly [OidcAuthMethod, ...OidcAuthMethod[]];\n\n/** One concrete mechanism; user policy belongs exclusively to WpAuthorization. */\nexport type AuthMethod =\n    | { kind: 'jwt' }\n    | OidcAuthMethod\n    | { kind: 'shared-secret'; secretKey: string }\n    | { kind: 'vendorAuth'; name: string }\n    | { kind: 'apikey'; regime: string; credentials: ApiKeyCredentials };\n\nexport type AuthMethods = readonly [AuthMethod, ...AuthMethod[]];\nexport type AuthMode = AuthMethod | { kind: 'public' };\n\n/** Alternatives remain unresolved until a concrete mechanism is chosen for this hop. */\nexport class AuthMeta {\n    readonly methods: readonly [AuthMode, ...AuthMode[]];\n\n    constructor(\n        methods: readonly [AuthMode, ...AuthMode[]],\n        public readonly publicReason: string | undefined,\n    ) {\n        this.methods = methods;\n        AuthDeclaration.validate(this);\n        this.methods = Object.freeze(methods.map((method: AuthMode) => AuthMeta.snapshot(method))) as readonly [AuthMode, ...AuthMode[]];\n        Object.freeze(this);\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static snapshot(method: AuthMode): AuthMode {\n        switch (method.kind) {\n            case 'oidc': return method.callerScope === 'services'\n                ? Object.freeze({ ...method, callers: Object.freeze([...method.callers]) as OidcCallers })\n                : Object.freeze({ ...method });\n            case 'apikey': return Object.freeze({ ...method, credentials: Object.freeze(method.credentials.map((credential: ApiKeyCredential) => Object.freeze({ ...credential }))) as ApiKeyCredentials });\n            default: return Object.freeze({ ...method });\n        }\n    }\n}\n\nexport class AuthDeclaration {\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    static validate(meta: AuthMeta): void {\n        if (!Array.isArray(meta.methods) || meta.methods.length === 0) throw new Error('@WpAuth requires a nonempty methods tuple.');\n        const kinds = new Set<string>();\n        for (const method of meta.methods) {\n            if (!method || typeof method !== 'object' || kinds.has(this.uniquenessKey(method))) throw new Error('@WpAuth rejects duplicate or invalid credential methods.');\n            kinds.add(this.uniquenessKey(method));\n            this.validateMethod(method);\n        }\n        if (kinds.has('public')) {\n            if (meta.methods.length !== 1 || typeof meta.publicReason !== 'string' || !meta.publicReason.trim()) {\n                throw new Error('Public auth must be declared separately with @WpAuthPublic(reason).');\n            }\n        } else if (meta.publicReason !== undefined) throw new Error('Protected @WpAuth rejects public reasons.');\n    }\n\n    /**\n     * One method per credential kind, except OIDC: one per `callerScope`, so `oidcSameProject()` and\n     * `oidcSvcs([...])` may pair on one endpoint (this project's accounts OR the listed ones). They are\n     * still ONE bearer credential, which AuthFilter verifies once for both.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static uniquenessKey(method: AuthMode): string {\n        return method.kind === 'oidc' ? `oidc:${method.callerScope}` : method.kind;\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static validateMethod(method: AuthMode): void {\n        let keys: readonly string[];\n        switch (method.kind) {\n            case 'jwt':\n            case 'public': keys = ['kind']; break;\n            case 'oidc': keys = this.oidcKeys(method); break;\n            case 'shared-secret':\n                keys = ['kind', 'secretKey'];\n                this.requireText(method.secretKey, 'sharedSecret'); break;\n            case 'vendorAuth':\n                keys = ['kind', 'name'];\n                this.requireText(method.name, 'vendorAuth'); break;\n            case 'apikey':\n                keys = ['kind', 'regime', 'credentials'];\n                this.requireText(method.regime, 'apiKey');\n                if (!Array.isArray(method.credentials) || !method.credentials.length) throw new Error('apiKey(...) requires a nonempty credentials tuple.');\n                for (const credential of method.credentials) {\n                    if (credential.in === 'header') this.requireHeaderKey(credential.key);\n                    else if (credential.in !== 'bearer' || Object.hasOwn(credential, 'key')) throw new Error('Invalid API-key credential location.');\n                }\n                break;\n            default: throw new Error('Unknown @WpAuth method; use jwt/oidcSameProject/oidcSvcs/sharedSecret/vendorAuth/apiKey descriptors.');\n        }\n        for (const key of Object.keys(method)) {\n            if (!keys.includes(key)) throw new Error(`Auth method rejects '${key}'; operation policy belongs in @WpAuthorization.`);\n        }\n    }\n\n    /**\n     * The keys an OIDC descriptor may carry, after checking its scope. `OidcCallers` already makes an\n     * empty `oidcSvcs([])` a compile error; this is the backstop for a list that reached the decorator\n     * around the type (a cast, a spread of a runtime array, plain JS), so it fails when the decorator\n     * is evaluated instead of reaching a verifier.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static oidcKeys(method: OidcAuthMethod): readonly string[] {\n        if (method.callerScope === 'same-project') return ['kind', 'callerScope'];\n        if (method.callerScope !== 'services') throw new Error(\"Unknown OIDC callerScope; use oidcSameProject() or oidcSvcs(['svc-a']).\");\n        if (!Array.isArray(method.callers) || method.callers.length === 0 || !method.callers.every((caller: string) => typeof caller === 'string' && caller.trim().length > 0)) {\n            throw new Error(\"oidcSvcs([...]) requires at least one nonblank service account; use oidcSameProject() to accept this GCP project's service accounts.\");\n        }\n        return ['kind', 'callerScope', 'callers'];\n    }\n\n    /**\n     * A header credential's key must be a ContextKey that rides the wire. `httpHeader` is optional on\n     * ContextKey itself (most keys never leave the process), and the factories' explicit value-type\n     * argument (`ContextKey.untrusted<string>(...)`) stops TypeScript inferring whether one was\n     * passed, so the type cannot say \"a key WITH a header\". It is checked once, when the contract is\n     * decorated, and the OpenAPI generator refuses the same key statically.\n     */\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static requireHeaderKey(key: AnyContextKey | undefined): void {\n        if (!key || typeof key !== 'object' || typeof key.name !== 'string') {\n            throw new Error(\"apiKey header credential requires `key`: the ContextKey carrying it, e.g. { in: 'header', key: MyKeys.API_KEY }.\");\n        }\n        if (typeof key.httpHeader !== 'string' || !key.httpHeader.trim()) {\n            throw new Error(`apiKey header credential key '${key.name}' declares no httpHeader; define it with ContextKey.trusted(name, provenance, '<header>') or ContextKey.untrusted(name, '<header>').`);\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static requireText(value: string, label: string): void {\n        if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} requires a nonempty name.`);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function jwt(): AuthMethod { return { kind: 'jwt' }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function oidcSameProject(): OidcAuthMethod { return { kind: 'oidc', callerScope: 'same-project' }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function oidcSvcs(callers: OidcCallers): OidcAuthMethod { return { kind: 'oidc', callerScope: 'services', callers }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function sharedSecret(secretKey: string): AuthMethod { return { kind: 'shared-secret', secretKey }; }\n/**\n * A credential in a VENDOR's scheme, on both ends of a hop, served by TWO independent app-bound DI\n * roles (core-context): the `VendorAuthMinter` mints it when WE call the vendor (and refreshes it once\n * on a 401), and the `VendorAuthVerifier` verifies it when the vendor calls US. The direction is\n * decided by whether the runtime is sending or receiving, so one contract declaration serves both.\n * `name` selects the vendor. A served `vendorAuth(...)` endpoint requires\n * `@Endpoint(..., { rawBody: true })` so the verifier has the exact bytes to verify.\n */\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function vendorAuth(name: string): AuthMethod { return { kind: 'vendorAuth', name }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function apiKey(regime: string, credentials: ApiKeyCredentials): AuthMethod { return { kind: 'apikey', regime, credentials }; }\n"]}

package/src/http/decorators.d.ts

@@ -150,7 +150,7 @@ export declare function isExternalOutboundApi(apiClass: Function): boolean;
 export declare function isFormPost(apiClass: Function, methodName: string): boolean;
 /**
  * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the
- * verbatim bytes + absolute url for a `VendorAuthHook.verify` to check.
+ * verbatim bytes + absolute url for a `VendorAuthVerifier.verify` to check.
  */
 export declare function isRawBody(apiClass: Function, methodName: string): boolean;
 /**

package/src/http/decorators.js

@@ -373,7 +373,7 @@ function isFormPost(apiClass, methodName) {
 }
 /**
  * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the
- * verbatim bytes + absolute url for a `VendorAuthHook.verify` to check.
+ * verbatim bytes + absolute url for a `VendorAuthVerifier.verify` to check.
  */
 // webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost
 function isRawBody(apiClass, methodName) {
@@ -399,9 +399,9 @@ function assertEveryVendorAuthEndpointRetainsRawBody(apiClass) {
             isRawBody(apiClass, methodName))
             continue;
         throw new Error(`Endpoint '${methodName}' in ${apiClass.name || 'Unknown'} is vendorAuth(...) but its @Endpoint ` +
-            `does not declare { rawBody: true }. VendorAuthHook.verify checks a credential over the bytes and ` +
+            `does not declare { rawBody: true }. VendorAuthVerifier.verify checks a credential over the bytes and ` +
             `the url the SENDER transmitted, and without that option the transport parses the body and ` +
-            `throws them away — leaving the hook nothing to check.`);
+            `throws them away — leaving the verifier nothing to check.`);
     }
 }
 /**