@webpieces/core-util 0.4.880 → 0.4.882

package/src/oauth/OAuthErrorResponse.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthErrorResponse = exports.OAuthErrorBody = void 0;
+const HttpResponseDto_1 = require("../http/HttpResponseDto");
+const OAuthBearerChallenge_1 = require("./OAuthBearerChallenge");
+const OAuthErrorCode_1 = require("./OAuthErrorCode");
+/**
+ * The RFC 6749 §5.2 / RFC 6750 §3 error body: `{ "error": "...", "error_description"?: "...",
+ * "error_uri"?: "..." }`. The property names ARE the wire names, snake_case, because an OAuth client
+ * parses exactly these keys. An absent optional is left off the JSON entirely.
+ */
+class OAuthErrorBody {
+    error;
+    error_description;
+    error_uri;
+    constructor(error, description, errorUri) {
+        this.error = error;
+        if (description !== undefined)
+            this.error_description = OAuthErrorCode_1.OAuthText.sanitize(description);
+        if (errorUri !== undefined)
+            this.error_uri = errorUri;
+    }
+}
+exports.OAuthErrorBody = OAuthErrorBody;
+/**
+ * {@link OAuthProtocolError} -> the exact HTTP response. ONE renderer, used by every boundary that
+ * can meet one (`WebpiecesDefaultErrorTranslator`, `OAuthExpressErrorHandler`, the MCP bearer
+ * boundary), so an OAuth client gets the same bytes whichever path the refusal took.
+ *
+ * Headers: the error's `WWW-Authenticate` when it has one; otherwise `defaultChallenge` for a 401
+ * (the MCP boundary passes its own challenge, which carries `resource_metadata`); otherwise, for
+ * `invalid_token` / `insufficient_scope`, the minimal Bearer challenge RFC 6750 §3 requires. Every
+ * response also carries `Cache-Control: no-store` and `Pragma: no-cache` (RFC 6749 §5.1), so no
+ * intermediary caches an answer about a credential.
+ */
+class OAuthErrorResponse {
+    static REASONS = new Map([
+        [400, 'Bad Request'],
+        [401, 'Unauthorized'],
+        [403, 'Forbidden'],
+        [500, 'Internal Server Error'],
+        [503, 'Service Unavailable'],
+    ]);
+    /**
+     * @param defaultChallenge - the boundary's own `WWW-Authenticate` for a 401 whose error carries
+     *   none, or `undefined` when the boundary has no challenge of its own.
+     */
+    // webpieces-disable no-function-outside-class -- pure error -> response mapping shared by every boundary
+    static toResponse(error, defaultChallenge) {
+        const headers = [
+            new HttpResponseDto_1.HttpHeader('Cache-Control', 'no-store'),
+            new HttpResponseDto_1.HttpHeader('Pragma', 'no-cache'),
+        ];
+        const challenge = OAuthErrorResponse.challengeFor(error, defaultChallenge);
+        if (challenge !== undefined) {
+            headers.push(new HttpResponseDto_1.HttpHeader('WWW-Authenticate', challenge));
+        }
+        return new HttpResponseDto_1.HttpResponseDto(new HttpResponseDto_1.HttpResponseStatus(error.status, OAuthErrorResponse.REASONS.get(error.status) ?? ''), headers, new OAuthErrorBody(error.error, error.description, error.errorUri));
+    }
+    // webpieces-disable no-function-outside-class -- pure header choice owned by this renderer
+    static challengeFor(error, defaultChallenge) {
+        if (error.wwwAuthenticate !== undefined)
+            return error.wwwAuthenticate;
+        if (error.status === 401 && defaultChallenge !== undefined)
+            return defaultChallenge;
+        if (error.error === OAuthErrorCode_1.OAuthErrorCode.INVALID_TOKEN ||
+            error.error === OAuthErrorCode_1.OAuthErrorCode.INSUFFICIENT_SCOPE) {
+            return new OAuthBearerChallenge_1.OAuthBearerChallenge(error.error, error.description).toHeaderValue();
+        }
+        return undefined;
+    }
+}
+exports.OAuthErrorResponse = OAuthErrorResponse;
+//# sourceMappingURL=OAuthErrorResponse.js.map

package/src/oauth/OAuthErrorResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthErrorResponse.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/oauth/OAuthErrorResponse.ts"],"names":[],"mappings":";;;AAAA,6DAA0F;AAC1F,iEAA8D;AAC9D,qDAA8E;AAG9E;;;;GAIG;AACH,MAAa,cAAc;IACd,KAAK,CAAiB;IACtB,iBAAiB,CAAU;IAC3B,SAAS,CAAU;IAE5B,YAAY,KAAqB,EAAE,WAAoB,EAAE,QAAiB;QACtE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,iBAAiB,GAAG,0BAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACxF,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC1D,CAAC;CACJ;AAVD,wCAUC;AAED;;;;;;;;;;GAUG;AACH,MAAa,kBAAkB;IACnB,MAAM,CAAU,OAAO,GAAyC,IAAI,GAAG,CAG7E;QACE,CAAC,GAAG,EAAE,aAAa,CAAC;QACpB,CAAC,GAAG,EAAE,cAAc,CAAC;QACrB,CAAC,GAAG,EAAE,WAAW,CAAC;QAClB,CAAC,GAAG,EAAE,uBAAuB,CAAC;QAC9B,CAAC,GAAG,EAAE,qBAAqB,CAAC;KAC/B,CAAC,CAAC;IAEH;;;OAGG;IACH,yGAAyG;IACzG,MAAM,CAAC,UAAU,CACb,KAAyB,EACzB,gBAAoC;QAEpC,MAAM,OAAO,GAAG;YACZ,IAAI,4BAAU,CAAC,eAAe,EAAE,UAAU,CAAC;YAC3C,IAAI,4BAAU,CAAC,QAAQ,EAAE,UAAU,CAAC;SACvC,CAAC;QACF,MAAM,SAAS,GAAG,kBAAkB,CAAC,YAAY,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;QAC3E,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,4BAAU,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,iCAAe,CACtB,IAAI,oCAAkB,CAClB,KAAK,CAAC,MAAM,EACZ,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CACrD,EACD,OAAO,EACP,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CACrE,CAAC;IACN,CAAC;IAED,2FAA2F;IACnF,MAAM,CAAC,YAAY,CACvB,KAAyB,EACzB,gBAAoC;QAEpC,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,eAAe,CAAC;QACtE,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,gBAAgB,KAAK,SAAS;YAAE,OAAO,gBAAgB,CAAC;QACpF,IACI,KAAK,CAAC,KAAK,KAAK,+BAAc,CAAC,aAAa;YAC5C,KAAK,CAAC,KAAK,KAAK,+BAAc,CAAC,kBAAkB,EACnD,CAAC;YACC,OAAO,IAAI,2CAAoB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,aAAa,EAAE,CAAC;QACpF,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;;AArDL,gDAsDC","sourcesContent":["import { HttpHeader, HttpResponseDto, HttpResponseStatus } from '../http/HttpResponseDto';\nimport { OAuthBearerChallenge } from './OAuthBearerChallenge';\nimport { OAuthErrorCode, OAuthHttpStatus, OAuthText } from './OAuthErrorCode';\nimport { OAuthProtocolError } from './OAuthProtocolError';\n\n/**\n * The RFC 6749 §5.2 / RFC 6750 §3 error body: `{ \"error\": \"...\", \"error_description\"?: \"...\",\n * \"error_uri\"?: \"...\" }`. The property names ARE the wire names, snake_case, because an OAuth client\n * parses exactly these keys. An absent optional is left off the JSON entirely.\n */\nexport class OAuthErrorBody {\n    readonly error: OAuthErrorCode;\n    readonly error_description?: string;\n    readonly error_uri?: string;\n\n    constructor(error: OAuthErrorCode, description?: string, errorUri?: string) {\n        this.error = error;\n        if (description !== undefined) this.error_description = OAuthText.sanitize(description);\n        if (errorUri !== undefined) this.error_uri = errorUri;\n    }\n}\n\n/**\n * {@link OAuthProtocolError} -> the exact HTTP response. ONE renderer, used by every boundary that\n * can meet one (`WebpiecesDefaultErrorTranslator`, `OAuthExpressErrorHandler`, the MCP bearer\n * boundary), so an OAuth client gets the same bytes whichever path the refusal took.\n *\n * Headers: the error's `WWW-Authenticate` when it has one; otherwise `defaultChallenge` for a 401\n * (the MCP boundary passes its own challenge, which carries `resource_metadata`); otherwise, for\n * `invalid_token` / `insufficient_scope`, the minimal Bearer challenge RFC 6750 §3 requires. Every\n * response also carries `Cache-Control: no-store` and `Pragma: no-cache` (RFC 6749 §5.1), so no\n * intermediary caches an answer about a credential.\n */\nexport class OAuthErrorResponse {\n    private static readonly REASONS: ReadonlyMap<OAuthHttpStatus, string> = new Map<\n        OAuthHttpStatus,\n        string\n    >([\n        [400, 'Bad Request'],\n        [401, 'Unauthorized'],\n        [403, 'Forbidden'],\n        [500, 'Internal Server Error'],\n        [503, 'Service Unavailable'],\n    ]);\n\n    /**\n     * @param defaultChallenge - the boundary's own `WWW-Authenticate` for a 401 whose error carries\n     *   none, or `undefined` when the boundary has no challenge of its own.\n     */\n    // webpieces-disable no-function-outside-class -- pure error -> response mapping shared by every boundary\n    static toResponse(\n        error: OAuthProtocolError,\n        defaultChallenge: string | undefined,\n    ): HttpResponseDto<OAuthErrorBody> {\n        const headers = [\n            new HttpHeader('Cache-Control', 'no-store'),\n            new HttpHeader('Pragma', 'no-cache'),\n        ];\n        const challenge = OAuthErrorResponse.challengeFor(error, defaultChallenge);\n        if (challenge !== undefined) {\n            headers.push(new HttpHeader('WWW-Authenticate', challenge));\n        }\n        return new HttpResponseDto(\n            new HttpResponseStatus(\n                error.status,\n                OAuthErrorResponse.REASONS.get(error.status) ?? '',\n            ),\n            headers,\n            new OAuthErrorBody(error.error, error.description, error.errorUri),\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- pure header choice owned by this renderer\n    private static challengeFor(\n        error: OAuthProtocolError,\n        defaultChallenge: string | undefined,\n    ): string | undefined {\n        if (error.wwwAuthenticate !== undefined) return error.wwwAuthenticate;\n        if (error.status === 401 && defaultChallenge !== undefined) return defaultChallenge;\n        if (\n            error.error === OAuthErrorCode.INVALID_TOKEN ||\n            error.error === OAuthErrorCode.INSUFFICIENT_SCOPE\n        ) {\n            return new OAuthBearerChallenge(error.error, error.description).toHeaderValue();\n        }\n        return undefined;\n    }\n}\n"]}

package/src/oauth/OAuthProtocolError.d.ts

@@ -0,0 +1,61 @@
+import { InvalidClientStatus, OAuthErrorCode, OAuthFixedStatusErrorCode, OAuthHttpStatus } from './OAuthErrorCode';
+/**
+ * The optional RFC extras of an {@link OAuthProtocolError}. Data only, so a class.
+ *
+ * - `errorUri` — RFC 6749 `error_uri`: a page a client DEVELOPER can read about the error.
+ * - `wwwAuthenticate` — the `WWW-Authenticate` value to send. Build the Bearer form with
+ *   `OAuthBearerChallenge`. When it is omitted for `invalid_token` / `insufficient_scope`, the
+ *   renderer derives the minimal `Bearer error="..."` challenge RFC 6750 requires.
+ * - `cause` — the underlying failure, for the operator log only; it never reaches the caller.
+ */
+export declare class OAuthErrorExtras {
+    readonly errorUri?: string | undefined;
+    readonly wwwAuthenticate?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(errorUri?: string | undefined, wwwAuthenticate?: string | undefined, cause?: Error | undefined);
+}
+/**
+ * A refusal from an app-hosted OAuth endpoint (token, registration, a bearer-protected resource),
+ * answered in the RFC shape `{ error, error_description?, error_uri? }` and NOT in the webpieces
+ * `ApiError` envelope (#1176).
+ *
+ * WHY A SEPARATE TYPE: the caller of an OAuth endpoint is an OAuth CLIENT (an MCP client, Claude,
+ * any RFC 6749 library), which parses the RFC body and nothing else. And a refused grant is the
+ * protocol working as designed, so it is logged as an expected refusal, not as a server ERROR. It is
+ * deliberately not an `ApiError`: its wire shape, status rules and audience are all different.
+ *
+ * THE STATUS IS DERIVED FROM THE CODE ({@link OAuthErrorStatus}); a throw site never types one. The
+ * single exception is the single one the RFCs make: `invalid_client` may be 400 or 401 (default 401).
+ * That is enforced by the OVERLOADS, not by a runtime check — a status argument only compiles for
+ * `invalid_client`, and only 400 or 401 (`OAuthProtocolErrorCompileAssertions` pins both):
+ *
+ * ```ts
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'authorization code expired');
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'unknown client', undefined, 400);
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'x', undefined, 401); // does not compile
+ * ```
+ *
+ * `description` is the RFC `error_description`: SENT to the caller, and meant for the client
+ * developer — never put a secret or an end-user sentence in it. It also forms `message`, which is
+ * what the operator log shows.
+ *
+ * Rendered by `OAuthErrorResponse` — which `WebpiecesDefaultErrorTranslator` (webpieces routes),
+ * `OAuthExpressErrorHandler` (raw express routes, @webpieces/http-server) and the MCP server's bearer
+ * boundary all use, so every path answers the same bytes.
+ */
+export declare class OAuthProtocolError extends Error {
+    /** The RFC `error` code. */
+    readonly error: OAuthErrorCode;
+    /** The HTTP status, derived from `error` (see the class doc). */
+    readonly status: OAuthHttpStatus;
+    /** The RFC `error_description`, sent to the caller. */
+    readonly description?: string;
+    /** The RFC `error_uri`, sent to the caller. */
+    readonly errorUri?: string;
+    /** The `WWW-Authenticate` header value, when the caller must be challenged. */
+    readonly wwwAuthenticate?: string;
+    constructor(error: OAuthFixedStatusErrorCode, description?: string, extras?: OAuthErrorExtras);
+    constructor(error: OAuthErrorCode.INVALID_CLIENT, description?: string, extras?: OAuthErrorExtras, status?: InvalidClientStatus);
+    /** True for a refusal of the CALLER (every 4xx); false for `server_error` / `temporarily_unavailable`. */
+    isCallerError(): boolean;
+}

package/src/oauth/OAuthProtocolError.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthProtocolError = exports.OAuthErrorExtras = void 0;
+const OAuthErrorCode_1 = require("./OAuthErrorCode");
+/**
+ * The optional RFC extras of an {@link OAuthProtocolError}. Data only, so a class.
+ *
+ * - `errorUri` — RFC 6749 `error_uri`: a page a client DEVELOPER can read about the error.
+ * - `wwwAuthenticate` — the `WWW-Authenticate` value to send. Build the Bearer form with
+ *   `OAuthBearerChallenge`. When it is omitted for `invalid_token` / `insufficient_scope`, the
+ *   renderer derives the minimal `Bearer error="..."` challenge RFC 6750 requires.
+ * - `cause` — the underlying failure, for the operator log only; it never reaches the caller.
+ */
+class OAuthErrorExtras {
+    errorUri;
+    wwwAuthenticate;
+    cause;
+    constructor(errorUri, wwwAuthenticate, cause) {
+        this.errorUri = errorUri;
+        this.wwwAuthenticate = wwwAuthenticate;
+        this.cause = cause;
+    }
+}
+exports.OAuthErrorExtras = OAuthErrorExtras;
+/**
+ * A refusal from an app-hosted OAuth endpoint (token, registration, a bearer-protected resource),
+ * answered in the RFC shape `{ error, error_description?, error_uri? }` and NOT in the webpieces
+ * `ApiError` envelope (#1176).
+ *
+ * WHY A SEPARATE TYPE: the caller of an OAuth endpoint is an OAuth CLIENT (an MCP client, Claude,
+ * any RFC 6749 library), which parses the RFC body and nothing else. And a refused grant is the
+ * protocol working as designed, so it is logged as an expected refusal, not as a server ERROR. It is
+ * deliberately not an `ApiError`: its wire shape, status rules and audience are all different.
+ *
+ * THE STATUS IS DERIVED FROM THE CODE ({@link OAuthErrorStatus}); a throw site never types one. The
+ * single exception is the single one the RFCs make: `invalid_client` may be 400 or 401 (default 401).
+ * That is enforced by the OVERLOADS, not by a runtime check — a status argument only compiles for
+ * `invalid_client`, and only 400 or 401 (`OAuthProtocolErrorCompileAssertions` pins both):
+ *
+ * ```ts
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'authorization code expired');
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'unknown client', undefined, 400);
+ * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'x', undefined, 401); // does not compile
+ * ```
+ *
+ * `description` is the RFC `error_description`: SENT to the caller, and meant for the client
+ * developer — never put a secret or an end-user sentence in it. It also forms `message`, which is
+ * what the operator log shows.
+ *
+ * Rendered by `OAuthErrorResponse` — which `WebpiecesDefaultErrorTranslator` (webpieces routes),
+ * `OAuthExpressErrorHandler` (raw express routes, @webpieces/http-server) and the MCP server's bearer
+ * boundary all use, so every path answers the same bytes.
+ */
+class OAuthProtocolError extends Error {
+    /** The RFC `error` code. */
+    error;
+    /** The HTTP status, derived from `error` (see the class doc). */
+    status;
+    /** The RFC `error_description`, sent to the caller. */
+    description;
+    /** The RFC `error_uri`, sent to the caller. */
+    errorUri;
+    /** The `WWW-Authenticate` header value, when the caller must be challenged. */
+    wwwAuthenticate;
+    constructor(error, description, extras = new OAuthErrorExtras(), status) {
+        super(description === undefined ? `OAuth ${error}` : `OAuth ${error}: ${description}`, {
+            cause: extras.cause,
+        });
+        this.name = 'OAuthProtocolError';
+        this.error = error;
+        this.status =
+            error === OAuthErrorCode_1.OAuthErrorCode.INVALID_CLIENT ? (status ?? 401) : OAuthErrorCode_1.OAuthErrorStatus.of(error);
+        this.description = description;
+        this.errorUri = extras.errorUri;
+        this.wwwAuthenticate = extras.wwwAuthenticate;
+    }
+    /** True for a refusal of the CALLER (every 4xx); false for `server_error` / `temporarily_unavailable`. */
+    isCallerError() {
+        return this.status < 500;
+    }
+}
+exports.OAuthProtocolError = OAuthProtocolError;
+//# sourceMappingURL=OAuthProtocolError.js.map

package/src/oauth/OAuthProtocolError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProtocolError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/oauth/OAuthProtocolError.ts"],"names":[],"mappings":";;;AAAA,qDAM0B;AAE1B;;;;;;;;GAQG;AACH,MAAa,gBAAgB;IAEL;IACA;IACA;IAHpB,YACoB,QAAiB,EACjB,eAAwB,EACxB,KAAa;QAFb,aAAQ,GAAR,QAAQ,CAAS;QACjB,oBAAe,GAAf,eAAe,CAAS;QACxB,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AAND,4CAMC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IACzC,4BAA4B;IACnB,KAAK,CAAiB;IAC/B,iEAAiE;IACxD,MAAM,CAAkB;IACjC,uDAAuD;IAC9C,WAAW,CAAU;IAC9B,+CAA+C;IACtC,QAAQ,CAAU;IAC3B,+EAA+E;IACtE,eAAe,CAAU;IASlC,YACI,KAAqB,EACrB,WAAoB,EACpB,SAA2B,IAAI,gBAAgB,EAAE,EACjD,MAA4B;QAE5B,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,KAAK,WAAW,EAAE,EAAE;YACnF,KAAK,EAAE,MAAM,CAAC,KAAK;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM;YACP,KAAK,KAAK,+BAAc,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,iCAAgB,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QAC3F,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAClD,CAAC;IAED,0GAA0G;IAC1G,aAAa;QACT,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;IAC7B,CAAC;CACJ;AAzCD,gDAyCC","sourcesContent":["import {\n    InvalidClientStatus,\n    OAuthErrorCode,\n    OAuthErrorStatus,\n    OAuthFixedStatusErrorCode,\n    OAuthHttpStatus,\n} from './OAuthErrorCode';\n\n/**\n * The optional RFC extras of an {@link OAuthProtocolError}. Data only, so a class.\n *\n * - `errorUri` — RFC 6749 `error_uri`: a page a client DEVELOPER can read about the error.\n * - `wwwAuthenticate` — the `WWW-Authenticate` value to send. Build the Bearer form with\n *   `OAuthBearerChallenge`. When it is omitted for `invalid_token` / `insufficient_scope`, the\n *   renderer derives the minimal `Bearer error=\"...\"` challenge RFC 6750 requires.\n * - `cause` — the underlying failure, for the operator log only; it never reaches the caller.\n */\nexport class OAuthErrorExtras {\n    constructor(\n        public readonly errorUri?: string,\n        public readonly wwwAuthenticate?: string,\n        public readonly cause?: Error,\n    ) {}\n}\n\n/**\n * A refusal from an app-hosted OAuth endpoint (token, registration, a bearer-protected resource),\n * answered in the RFC shape `{ error, error_description?, error_uri? }` and NOT in the webpieces\n * `ApiError` envelope (#1176).\n *\n * WHY A SEPARATE TYPE: the caller of an OAuth endpoint is an OAuth CLIENT (an MCP client, Claude,\n * any RFC 6749 library), which parses the RFC body and nothing else. And a refused grant is the\n * protocol working as designed, so it is logged as an expected refusal, not as a server ERROR. It is\n * deliberately not an `ApiError`: its wire shape, status rules and audience are all different.\n *\n * THE STATUS IS DERIVED FROM THE CODE ({@link OAuthErrorStatus}); a throw site never types one. The\n * single exception is the single one the RFCs make: `invalid_client` may be 400 or 401 (default 401).\n * That is enforced by the OVERLOADS, not by a runtime check — a status argument only compiles for\n * `invalid_client`, and only 400 or 401 (`OAuthProtocolErrorCompileAssertions` pins both):\n *\n * ```ts\n * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'authorization code expired');\n * throw new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'unknown client', undefined, 400);\n * throw new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'x', undefined, 401); // does not compile\n * ```\n *\n * `description` is the RFC `error_description`: SENT to the caller, and meant for the client\n * developer — never put a secret or an end-user sentence in it. It also forms `message`, which is\n * what the operator log shows.\n *\n * Rendered by `OAuthErrorResponse` — which `WebpiecesDefaultErrorTranslator` (webpieces routes),\n * `OAuthExpressErrorHandler` (raw express routes, @webpieces/http-server) and the MCP server's bearer\n * boundary all use, so every path answers the same bytes.\n */\nexport class OAuthProtocolError extends Error {\n    /** The RFC `error` code. */\n    readonly error: OAuthErrorCode;\n    /** The HTTP status, derived from `error` (see the class doc). */\n    readonly status: OAuthHttpStatus;\n    /** The RFC `error_description`, sent to the caller. */\n    readonly description?: string;\n    /** The RFC `error_uri`, sent to the caller. */\n    readonly errorUri?: string;\n    /** The `WWW-Authenticate` header value, when the caller must be challenged. */\n    readonly wwwAuthenticate?: string;\n\n    constructor(error: OAuthFixedStatusErrorCode, description?: string, extras?: OAuthErrorExtras);\n    constructor(\n        error: OAuthErrorCode.INVALID_CLIENT,\n        description?: string,\n        extras?: OAuthErrorExtras,\n        status?: InvalidClientStatus,\n    );\n    constructor(\n        error: OAuthErrorCode,\n        description?: string,\n        extras: OAuthErrorExtras = new OAuthErrorExtras(),\n        status?: InvalidClientStatus,\n    ) {\n        super(description === undefined ? `OAuth ${error}` : `OAuth ${error}: ${description}`, {\n            cause: extras.cause,\n        });\n        this.name = 'OAuthProtocolError';\n        this.error = error;\n        this.status =\n            error === OAuthErrorCode.INVALID_CLIENT ? (status ?? 401) : OAuthErrorStatus.of(error);\n        this.description = description;\n        this.errorUri = extras.errorUri;\n        this.wwwAuthenticate = extras.wwwAuthenticate;\n    }\n\n    /** True for a refusal of the CALLER (every 4xx); false for `server_error` / `temporarily_unavailable`. */\n    isCallerError(): boolean {\n        return this.status < 500;\n    }\n}\n"]}

package/src/oauth/OAuthProtocolErrorCompileAssertions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * COMPILE-TIME assertions for {@link OAuthProtocolError}'s status rule: only `invalid_client` takes
+ * a status, and only 400 or 401. Each `@ts-expect-error` fails the build (TS2578) if its line ever
+ * starts compiling. A non-spec file on purpose: vitest strips types and tsconfig.lib.json excludes
+ * specs, so only a compiled file makes these assertions real.
+ */
+export declare class OAuthProtocolErrorCompileAssertions {
+    legitimate(): void;
+    illegal(): void;
+}

package/src/oauth/OAuthProtocolErrorCompileAssertions.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthProtocolErrorCompileAssertions = void 0;
+const OAuthAuthorizationErrorRedirect_1 = require("./OAuthAuthorizationErrorRedirect");
+const OAuthBearerChallenge_1 = require("./OAuthBearerChallenge");
+const OAuthErrorCode_1 = require("./OAuthErrorCode");
+const OAuthProtocolError_1 = require("./OAuthProtocolError");
+/**
+ * COMPILE-TIME assertions for {@link OAuthProtocolError}'s status rule: only `invalid_client` takes
+ * a status, and only 400 or 401. Each `@ts-expect-error` fails the build (TS2578) if its line ever
+ * starts compiling. A non-spec file on purpose: vitest strips types and tsconfig.lib.json excludes
+ * specs, so only a compiled file makes these assertions real.
+ */
+class OAuthProtocolErrorCompileAssertions {
+    legitimate() {
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_GRANT);
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_GRANT, 'code expired');
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_TOKEN, 'expired', new OAuthProtocolError_1.OAuthErrorExtras());
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_CLIENT, 'unknown client');
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 400);
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 401);
+        void new OAuthBearerChallenge_1.OAuthBearerChallenge(OAuthErrorCode_1.OAuthErrorCode.INSUFFICIENT_SCOPE, 'x', 'tools:write');
+        void new OAuthAuthorizationErrorRedirect_1.OAuthAuthorizationErrorRedirect('https://c/cb', OAuthErrorCode_1.OAuthErrorCode.ACCESS_DENIED, 's');
+    }
+    illegal() {
+        // @ts-expect-error -- the RFCs fix invalid_grant's status; a status argument does not compile
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_GRANT, 'x', undefined, 401);
+        // @ts-expect-error -- invalid_client may only be 400 or 401
+        void new OAuthProtocolError_1.OAuthProtocolError(OAuthErrorCode_1.OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 403);
+        // @ts-expect-error -- a code outside the RFC vocabulary does not compile
+        void new OAuthProtocolError_1.OAuthProtocolError('invalid_credential', 'x');
+        // @ts-expect-error -- invalid_grant is a token-endpoint code, not a Bearer challenge code
+        void new OAuthBearerChallenge_1.OAuthBearerChallenge(OAuthErrorCode_1.OAuthErrorCode.INVALID_GRANT);
+        // @ts-expect-error -- invalid_token is not an authorization-endpoint redirect code
+        void new OAuthAuthorizationErrorRedirect_1.OAuthAuthorizationErrorRedirect('https://c/cb', OAuthErrorCode_1.OAuthErrorCode.INVALID_TOKEN, 's');
+    }
+}
+exports.OAuthProtocolErrorCompileAssertions = OAuthProtocolErrorCompileAssertions;
+//# sourceMappingURL=OAuthProtocolErrorCompileAssertions.js.map

package/src/oauth/OAuthProtocolErrorCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProtocolErrorCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/oauth/OAuthProtocolErrorCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,uFAAoF;AACpF,iEAA8D;AAC9D,qDAAkD;AAClD,6DAA4E;AAE5E;;;;;GAKG;AACH,MAAa,mCAAmC;IAC5C,UAAU;QACN,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,aAAa,CAAC,CAAC;QAC1D,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;QAC1E,KAAK,IAAI,uCAAkB,CACvB,+BAAc,CAAC,aAAa,EAC5B,SAAS,EACT,IAAI,qCAAgB,EAAE,CACzB,CAAC;QACF,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;QAC7E,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAChF,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAChF,KAAK,IAAI,2CAAoB,CAAC,+BAAc,CAAC,kBAAkB,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;QACrF,KAAK,IAAI,iEAA+B,CAAC,cAAc,EAAE,+BAAc,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAChG,CAAC;IAED,OAAO;QACH,8FAA8F;QAC9F,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAC/E,4DAA4D;QAC5D,KAAK,IAAI,uCAAkB,CAAC,+BAAc,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAChF,yEAAyE;QACzE,KAAK,IAAI,uCAAkB,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;QACvD,0FAA0F;QAC1F,KAAK,IAAI,2CAAoB,CAAC,+BAAc,CAAC,aAAa,CAAC,CAAC;QAC5D,mFAAmF;QACnF,KAAK,IAAI,iEAA+B,CAAC,cAAc,EAAE,+BAAc,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAChG,CAAC;CACJ;AA5BD,kFA4BC","sourcesContent":["import { OAuthAuthorizationErrorRedirect } from './OAuthAuthorizationErrorRedirect';\nimport { OAuthBearerChallenge } from './OAuthBearerChallenge';\nimport { OAuthErrorCode } from './OAuthErrorCode';\nimport { OAuthErrorExtras, OAuthProtocolError } from './OAuthProtocolError';\n\n/**\n * COMPILE-TIME assertions for {@link OAuthProtocolError}'s status rule: only `invalid_client` takes\n * a status, and only 400 or 401. Each `@ts-expect-error` fails the build (TS2578) if its line ever\n * starts compiling. A non-spec file on purpose: vitest strips types and tsconfig.lib.json excludes\n * specs, so only a compiled file makes these assertions real.\n */\nexport class OAuthProtocolErrorCompileAssertions {\n    legitimate(): void {\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT);\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'code expired');\n        void new OAuthProtocolError(\n            OAuthErrorCode.INVALID_TOKEN,\n            'expired',\n            new OAuthErrorExtras(),\n        );\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'unknown client');\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 400);\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 401);\n        void new OAuthBearerChallenge(OAuthErrorCode.INSUFFICIENT_SCOPE, 'x', 'tools:write');\n        void new OAuthAuthorizationErrorRedirect('https://c/cb', OAuthErrorCode.ACCESS_DENIED, 's');\n    }\n\n    illegal(): void {\n        // @ts-expect-error -- the RFCs fix invalid_grant's status; a status argument does not compile\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_GRANT, 'x', undefined, 401);\n        // @ts-expect-error -- invalid_client may only be 400 or 401\n        void new OAuthProtocolError(OAuthErrorCode.INVALID_CLIENT, 'x', undefined, 403);\n        // @ts-expect-error -- a code outside the RFC vocabulary does not compile\n        void new OAuthProtocolError('invalid_credential', 'x');\n        // @ts-expect-error -- invalid_grant is a token-endpoint code, not a Bearer challenge code\n        void new OAuthBearerChallenge(OAuthErrorCode.INVALID_GRANT);\n        // @ts-expect-error -- invalid_token is not an authorization-endpoint redirect code\n        void new OAuthAuthorizationErrorRedirect('https://c/cb', OAuthErrorCode.INVALID_TOKEN, 's');\n    }\n}\n"]}