@o3co/auth-provider-foundation 0.15.0 → 0.16.0

package/dist/repositories/storeErrors.mjs

@@ -0,0 +1,193 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The failures `HttpUserRepository` throws about the exchange with the Store
+ * rather than about a user: the Store refusing this deployment's credential,
+ * and a transport that failed. Each is built from an allowlist — the
+ * endpoint (origin and path), a status, a transport code — and never from
+ * what the Store or the transport said, which may quote the request.
+ */
+import { endpointForMessage } from "../endpointUrl.mjs";
+/**
+ * The Store refused the credential this deployment presented: a `401` or a
+ * `403` carrying a `Bearer` challenge (RFC 6750 §3 — `invalid_token`,
+ * `insufficient_scope`) to a request that sent `bearerToken`. An outage, not
+ * an answer about the user: thrown, so every caller answers it as it answers
+ * any Store failure.
+ *
+ * `name` is part of the contract. A caller that does not depend on this
+ * package recognises the refusal by it — an operator reading the
+ * federation-grants callback's `federation_grant_callback_unavailable` line
+ * finds it as the projected error's `name`. The message names the endpoint —
+ * its origin and path, never a query or fragment, however it is handed one —
+ * the status and the option to check; never the token, and nothing the Store
+ * wrote.
+ *
+ * The Store's status is `storeStatus`, never `status` or `statusCode`: those
+ * are what Express's finalhandler, http-errors and the standalone's terminal
+ * handler read as the status to ANSWER with, and a 4xx there is taken for a
+ * client error — the Store's 401 would reach the browser as its own, and go
+ * unlogged.
+ */
+export class StoreCredentialRefusedError extends Error {
+    storeStatus;
+    constructor(url, status) {
+        super(`HttpUserRepository: the Store at ${endpointForMessage(url)} refused this deployment's credential ` +
+            `(HTTP ${status} with a Bearer challenge) — bearerToken (CLIENT_USER_BEARER_TOKEN) is ` +
+            "not a token the Store accepts");
+        this.name = "StoreCredentialRefusedError";
+        this.storeStatus = status;
+    }
+}
+/**
+ * The Store could not be reached, or what it answered could not be read — a
+ * transport failure rather than an answer. Thrown so every caller answers it
+ * as it answers any Store failure; `name` is part of the contract (the
+ * federation-grants callback's outage line carries it as the projected
+ * error's `name`), as are `reason` and `code`.
+ *
+ * Built only from what an operator can act on: a fixed message naming the
+ * endpoint and the failure, and `code` — a transport code from the allowlist
+ * below, when there is one. Never a `cause`: the transport's own error may
+ * quote what was sent or received. And no `status` (see
+ * {@link StoreCredentialRefusedError}).
+ */
+export class StoreTransportError extends Error {
+    reason;
+    code;
+    constructor(message, reason, code) {
+        super(message);
+        this.name = "StoreTransportError";
+        this.reason = reason;
+        this.code = code;
+    }
+}
+/**
+ * Transport codes an operator can act on. A transport's error is never passed
+ * on: undici's parser errors carry the bytes they choked on as `data`, and a
+ * peer that reflects the request — a broken proxy, a debugging echo — puts the
+ * `Authorization` header there. A code from this list, or of one of the
+ * closed families below, found on the error or its causes, is all that is
+ * kept of one.
+ */
+const TRANSPORT_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ECONNABORTED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "EPROTO",
+    "CERT_HAS_EXPIRED",
+    "CERT_NOT_YET_VALID",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+/**
+ * Families of codes, each a closed vocabulary of its producer: undici's own
+ * (`UND_ERR_SOCKET`, `UND_ERR_HEADERS_OVERFLOW`, …), llhttp's parser errors
+ * (`HPE_INVALID_HEADER_TOKEN`, … — where the runtime sets them), and
+ * OpenSSL's (`ERR_SSL_WRONG_VERSION_NUMBER` — an https URL on a port that
+ * speaks plain HTTP; `ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE` — OpenSSL 3's
+ * name for a TLS 1.2 handshake the Store refused, one slash in it). Bounded,
+ * so a value that merely starts like one is not kept whole.
+ */
+const CODE_FAMILIES = [
+    /^UND_ERR_[A-Z_]{1,48}$/,
+    /^HPE_[A-Z_]{1,48}$/,
+    /^ERR_SSL_[A-Z0-9_]{1,64}(?:\/[A-Z0-9_]{1,64})?$/,
+];
+const MAX_CAUSE_DEPTH = 4;
+/** Each of `err` and its causes, a few levels deep. */
+function* causes(err) {
+    let current = err;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
+        yield current;
+        current = current.cause;
+    }
+}
+/** The first allowlisted `code` on `err` or its causes. */
+export function transportCode(err) {
+    for (const error of causes(err)) {
+        const code = error.code;
+        if (typeof code === "string" &&
+            (TRANSPORT_CODES.has(code) || CODE_FAMILIES.some((family) => family.test(code)))) {
+            return code;
+        }
+    }
+    return undefined;
+}
+/** Codes that say the connection closed or was reset under the request. */
+const CLOSED_CODES = new Set([
+    "UND_ERR_SOCKET",
+    "ECONNRESET",
+    "EPIPE",
+    "ECONNABORTED",
+]);
+/**
+ * Which failure a rejected request is, read by the error's name and code
+ * only. A head the transport cannot take — an `HTTPParserError` (an `HPE_*`
+ * code where the runtime sets one), `UND_ERR_HEADERS_OVERFLOW` — is
+ * `malformed_response`. A connection closed or reset under the request —
+ * undici's `UND_ERR_SOCKET` ("other side closed"), `ECONNRESET`, `EPIPE` — is
+ * `connection_closed`, whatever the socket had read: undici counts bytes over
+ * the socket's life, and fetch reuses keep-alive connections, so a pooled
+ * connection closed between two requests has read an entire earlier answer.
+ * Anything else is `unreachable`.
+ */
+function requestFailureReason(err) {
+    let closed = false;
+    for (const error of causes(err)) {
+        const { name, code } = error;
+        if (name === "HTTPParserError")
+            return "malformed_response";
+        if (typeof code !== "string")
+            continue;
+        if (code.startsWith("HPE_") || code === "UND_ERR_HEADERS_OVERFLOW") {
+            return "malformed_response";
+        }
+        if (CLOSED_CODES.has(code))
+            closed = true;
+    }
+    return closed ? "connection_closed" : "unreachable";
+}
+const withCode = (message, code) => code === undefined ? message : `${message} (${code})`;
+/**
+ * A request that failed before a response could be taken, as its reason's
+ * message — `unreachable`, `closed` or `malformed` — with the code, when
+ * there is one. Only `unreachable` points an operator at the network.
+ */
+export function requestFailure(err, messages) {
+    const code = transportCode(err);
+    const reason = requestFailureReason(err);
+    const message = reason === "malformed_response"
+        ? messages.malformed
+        : reason === "connection_closed"
+            ? messages.closed
+            : messages.unreachable;
+    return new StoreTransportError(withCode(message, code), reason, code);
+}
+/** An answer whose body broke before it was read. */
+export function readFailure(err, message) {
+    const code = transportCode(err);
+    return new StoreTransportError(withCode(message, code), "unreadable", code);
+}

package/dist/repositories/wwwAuthenticate.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Whether a `WWW-Authenticate` value carries a `Bearer` challenge (RFC 6750
+ * §3). Quoted strings are blanked first, so `realm="… Bearer …"` is not one;
+ * several header lines arrive joined by `, `, which this reads as the
+ * challenge list it is. A malformed line — a quoted string never closed —
+ * hides whatever follows it, including a challenge on a later line: the
+ * answer is then read as it would be without one, never the other way.
+ */
+export declare function hasBearerChallenge(value: string | null): boolean;
+//# sourceMappingURL=wwwAuthenticate.d.mts.map

package/dist/repositories/wwwAuthenticate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wwwAuthenticate.d.mts","sourceRoot":"","sources":["../../src/repositories/wwwAuthenticate.mts"],"names":[],"mappings":"AAmDA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEhE"}

package/dist/repositories/wwwAuthenticate.mjs

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Reading a `WWW-Authenticate` answer from the Store (RFC 9110 §11.6.1).
+ *
+ * `HttpUserRepository` asks one question of it: does the answer carry a
+ * `Bearer` challenge (RFC 6750 §3) — the Store saying it refused the
+ * credential this deployment presented, not the user. Only the scheme is
+ * read; nothing the Store wrote after it is kept, so nothing it wrote can
+ * reach an error this adapter throws.
+ */
+/**
+ * A quoted-string (RFC 9110 §5.6.4), escapes included — and one left
+ * unterminated runs to the end of the value, so what follows its opening
+ * quote is its content, never a challenge. Each character is consumed once
+ * (a backslash with the character after it, when there is one), so a value
+ * of escaped quotes with no closing one costs a scan: matching up to a
+ * closing quote that never comes retried from every quote, which a 64 KiB
+ * value turned into seconds per answer.
+ */
+const QUOTED_STRING = /"(?:[^"\\]|\\[\s\S]?)*(?:"|$)/g;
+/**
+ * An auth-scheme `Bearer`, case-insensitive (RFC 9110 §11.1), where a
+ * challenge begins — the value's start or after a comma — and followed by the
+ * value's end, a comma, or whitespace that does not lead to `=` (which would
+ * make `bearer` a parameter's name, not a scheme: `bearer  = 1` is one).
+ *
+ * The whitespace after the scheme is taken whole, once: the lookahead
+ * captures the entire run and the backreference consumes exactly it, and a
+ * lookahead is never re-entered, so a long run followed by `=` is not
+ * retried from every shorter run. `(?<=[ \t])` then requires that the run
+ * was not empty, so `bearerish` is not the scheme.
+ */
+const BEARER_CHALLENGE = /(?:^|,)[ \t]*bearer(?=([ \t]*))\1(?:$|,|(?<=[ \t])(?!=))/i;
+/**
+ * Whether a `WWW-Authenticate` value carries a `Bearer` challenge (RFC 6750
+ * §3). Quoted strings are blanked first, so `realm="… Bearer …"` is not one;
+ * several header lines arrive joined by `, `, which this reads as the
+ * challenge list it is. A malformed line — a quoted string never closed —
+ * hides whatever follows it, including a challenge on a later line: the
+ * answer is then read as it would be without one, never the other way.
+ */
+export function hasBearerChallenge(value) {
+    return value !== null && BEARER_CHALLENGE.test(value.replace(QUOTED_STRING, '""'));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@o3co/auth-provider-foundation",
   "description": "Production HTTP user-authentication adapter for auth.provider",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22.0.0"
@@ -17,8 +17,7 @@
   },
   "files": [
     "dist",
-    "README.md",
-    "LICENSE"
+    "README.md"
   ],
   "repository": {
     "type": "git",
@@ -32,15 +31,14 @@
     }
   },
   "peerDependencies": {
-    "@o3co/auth-provider-core": "^0.15.0"
+    "@o3co/auth-provider-core": "^0.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.5.1",
     "msw": "^2.15.0",
-    "pino": "^10.3.1",
     "vitest": "^5.0.0",
     "@vitest/coverage-v8": "^5.0.0",
-    "@o3co/auth-provider-core": "0.15.0"
+    "@o3co/auth-provider-core": "0.16.0"
   },
   "scripts": {
     "prebuild": "rimraf dist",