@o3co/auth-provider-foundation 0.16.0 → 0.17.0-rc.2

package/dist/repositories/storeErrors.d.mts

@@ -1,27 +1,20 @@
 /**
  * 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.
+ * `403` carrying a `Bearer` challenge (RFC 6750 §3) to a request that sent
+ * `bearerToken`. An outage, not an answer about a user or a factor. See
+ * README, The wire contract.
  *
- * `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.
+ * `name` and `storeStatus` are part of the contract. The message leads with
+ * the client that was refused, and names the endpoint's origin and path, the
+ * status and the option to check; never the
+ * token, and nothing the Store wrote. Not `status` or `statusCode`: Express's
+ * finalhandler, http-errors and the standalone's terminal handler read those
+ * as the status to ANSWER with, so the Store's 401 would reach the browser as
+ * its own, unlogged.
  */
 export declare class StoreCredentialRefusedError extends Error {
     readonly storeStatus: 401 | 403;
-    constructor(url: string, status: 401 | 403);
+    constructor(url: string, status: 401 | 403, owner?: string);
 }
 /** What went wrong with the exchange, when it was not the Store's answer. */
 export type StoreTransportFailure = 
@@ -47,17 +40,15 @@ export type StoreTransportFailure =
 /** An HTTP answer arrived, and its body broke before it was read. */
  | "unreadable";
 /**
- * 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`.
+ * 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`, `reason` and `code` are part of the
+ * contract.
  *
  * 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}).
+ * endpoint and the failure, and `code`, an allowlisted transport code 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 declare class StoreTransportError extends Error {
     readonly reason: StoreTransportFailure;

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

@@ -1 +1 @@
-{"version":3,"file":"storeErrors.d.mts","sourceRoot":"","sources":["../../src/repositories/storeErrors.mts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACrD,QAAQ,CAAC,WAAW,EAAE,GAAG,GAAG,GAAG,CAAC;gBAEpB,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG;CAS1C;AAED,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB;AAChC;;;GAGG;AACD,aAAa;AACf;;;;;;GAMG;GACD,mBAAmB;AACrB;;;;GAIG;GACD,oBAAoB;AACtB,qEAAqE;GACnE,YAAY,CAAC;AAEhB;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,IAAI,CAAC,EAAE,MAAM;CAMzE;AA4DD,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW9D;AAwCD;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE;IACT,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,GACC,mBAAmB,CAUrB;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAG9E"}
+{"version":3,"file":"storeErrors.d.mts","sourceRoot":"","sources":["../../src/repositories/storeErrors.mts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;GAaG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACrD,QAAQ,CAAC,WAAW,EAAE,GAAG,GAAG,GAAG,CAAC;gBAEpB,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,SAAuB;CASxE;AAED,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB;AAChC;;;GAGG;AACD,aAAa;AACf;;;;;;GAMG;GACD,mBAAmB;AACrB;;;;GAIG;GACD,oBAAoB;AACtB,qEAAqE;GACnE,YAAY,CAAC;AAEhB;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,IAAI,CAAC,EAAE,MAAM;CAMzE;AA4DD,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW9D;AAsCD;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE;IACT,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,GACC,mBAAmB,CAUrB;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAG9E"}

package/dist/repositories/storeErrors.mjs

@@ -14,8 +14,9 @@
  * 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,
+ * The failures the Store clients — `HttpUserRepository` and
+ * `HttpMfaFactorStore` — throw about the exchange with the Store rather than
+ * about what they asked: 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.
@@ -23,47 +24,38 @@
 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.
+ * `403` carrying a `Bearer` challenge (RFC 6750 §3) to a request that sent
+ * `bearerToken`. An outage, not an answer about a user or a factor. See
+ * README, The wire contract.
  *
- * `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.
+ * `name` and `storeStatus` are part of the contract. The message leads with
+ * the client that was refused, and names the endpoint's origin and path, the
+ * status and the option to check; never the
+ * token, and nothing the Store wrote. Not `status` or `statusCode`: Express's
+ * finalhandler, http-errors and the standalone's terminal handler read those
+ * as the status to ANSWER with, so the Store's 401 would reach the browser as
+ * its own, 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 ` +
+    constructor(url, status, owner = "HttpUserRepository") {
+        super(`${owner}: the Store at ${endpointForMessage(url)} refused this deployment's credential ` +
+            `(HTTP ${status} with a Bearer challenge) — bearerToken (REPOSITORIES_USER_HTTP_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`.
+ * 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`, `reason` and `code` are part of the
+ * contract.
  *
  * 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}).
+ * endpoint and the failure, and `code`, an allowlisted transport code 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;
@@ -144,15 +136,13 @@ const CLOSED_CODES = new Set([
     "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`.
+ * Which failure a rejected request is, read by the error's name and code only.
+ * A head the transport cannot take (`HTTPParserError`, an `HPE_*` code,
+ * `UND_ERR_HEADERS_OVERFLOW`) is `malformed_response`. A connection closed or
+ * reset under the request (`CLOSED_CODES`) is `connection_closed`, whatever the
+ * socket had read: undici counts bytes over the socket's life, and a pooled
+ * keep-alive connection closed between two requests has read an entire
+ * earlier answer. Anything else is `unreachable`.
  */
 function requestFailureReason(err) {
     let closed = false;

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

@@ -1 +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"}
+{"version":3,"file":"wwwAuthenticate.d.mts","sourceRoot":"","sources":["../../src/repositories/wwwAuthenticate.mts"],"names":[],"mappings":"AA+CA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEhE"}

package/dist/repositories/wwwAuthenticate.mjs

@@ -23,26 +23,22 @@
  * 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.
+ * A quoted-string (RFC 9110 §5.6.4), escapes included; 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 one scan rather than a retry from every
+ * quote, which on a 64 KiB value takes 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.
+ * challenge begins (the value's start or after a comma), followed by the
+ * value's end, a comma, or whitespace that does not lead to `=` (then `bearer`
+ * is a parameter's name, as in `bearer  = 1`). The lookahead captures the
+ * whole whitespace run and the backreference consumes exactly it, so a long
+ * run followed by `=` is not retried from every shorter run; `(?<=[ \t])`
+ * requires the run was not empty, so `bearerish` is not the scheme.
  */
 const BEARER_CHALLENGE = /(?:^|,)[ \t]*bearer(?=([ \t]*))\1(?:$|,|(?<=[ \t])(?!=))/i;
 /**

package/dist/storeTransport.d.mts

@@ -0,0 +1,97 @@
+/**
+ * Default ceiling on an upstream response body, in bytes.
+ *
+ * A `User` record is a few hundred bytes; 1 MiB is generous for one carrying
+ * custom claims and small enough that a hostile or broken Store cannot walk the
+ * process out of memory one login at a time.
+ */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * The credential presented to the Store, checked when `owner` is built (so
+ * an unusable one fails at boot) and turned into the `Authorization` value;
+ * `undefined` when none is configured, which sends no `Authorization` header.
+ *
+ * The shape is refused here, not left to `fetch`, which QUOTES a header value
+ * it refuses in the `TypeError` it throws, where the session routes log it.
+ * The strength is core's shared-secret floor (`MIN_SECRET_ENTROPY_BYTES`, on
+ * the decoded length): whoever holds this token speaks to the Store as
+ * auth.provider. No message quotes the value.
+ */
+export declare function bearerAuthorization(value: unknown, owner: string): string | undefined;
+/** `timeout`, the whole exchange's deadline in milliseconds, or an error naming it for `owner`. */
+export declare function checkStoreTimeout(timeout: unknown, owner: string): number;
+/** `maxResponseBytes`, the response cap, or an error naming it for `owner`. */
+export declare function checkStoreResponseCap(maxResponseBytes: unknown, owner: string): number;
+/**
+ * The transport settings of a Store client's configuration block — the user
+ * repository's `http` block — as a client is built from them: `timeout` and
+ * `maxResponseBytes` read from text too and defaulted only when absent, and
+ * `bearerToken` forwarded whenever set, whatever it holds. The client's
+ * constructor refuses what the transport cannot honour.
+ */
+export declare function readStoreTransportConfig(block: Readonly<Record<string, unknown>>): {
+    readonly bearerToken?: string;
+    readonly timeout: number;
+    readonly maxResponseBytes: number;
+};
+/**
+ * Releases a response body we are not going to read. Left unconsumed, undici
+ * holds the socket until the response is garbage collected instead of
+ * returning it to the keep-alive pool: a slow leak on the failure path.
+ *
+ * Deliberately not awaited: that would hand a hostile Store a second way to
+ * stall the caller, the one the request deadline exists to close, and some
+ * interceptors never settle it at all.
+ */
+export declare function discardBody(res: Response): void;
+/**
+ * Reads at most `limit` bytes of `res` as text, throwing once it is passed.
+ * `Content-Length` refuses an honest oversized response before a byte is read,
+ * but the streaming count is the load-bearing half: a hostile Store omits the
+ * header or lies, and chunked encoding has none. Everything it throws is the
+ * adapter's own (the cap, the deadline's rejection, what `unreadable` makes of
+ * a transport error mid-read), never the transport's error as it is.
+ */
+export declare function readBodyCapped(res: Response, limit: number, endpoint: string, deadline: Promise<never>, unreadable: (err: unknown) => Error, owner: string): Promise<string>;
+/**
+ * Whether `err` is the abort our own deadline raised on the `fetch` itself,
+ * where the response headers never arrive. Deliberately shallow: an aborted
+ * `fetch` rejects with the `AbortError` directly. A runtime that wrapped one
+ * would still fail the request, as a `StoreTransportError` rather than a
+ * `TimeoutError`: misnamed, not missed. A stalled *body* is the deadline race
+ * in `readBodyCapped`.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/** What a request to the Store is sent with. */
+export interface StoreRequestSettings {
+    /** `Bearer <token>`, or `undefined` to send no `Authorization` header. */
+    readonly authorization: string | undefined;
+    /** The whole exchange's deadline, in milliseconds. */
+    readonly timeout: number;
+    /** The most bytes of a body read. */
+    readonly maxResponseBytes: number;
+}
+/** What a failure of the exchange says, each naming the endpoint. */
+export interface StoreRequestMessages {
+    /** Who is asking, leading every message. */
+    readonly owner: string;
+    readonly unreachable: string;
+    readonly closed: string;
+    readonly malformed: string;
+    readonly unreadable: string;
+}
+/** An answer: the response, whose body is released, and the body as text when it was read. */
+export interface StoreAnswer {
+    readonly response: Response;
+    readonly text: string | undefined;
+}
+/**
+ * `POST`s `body` as JSON to `url` and answers what came back, the body read
+ * (up to the cap, within the deadline) only when `readsBody` says so for the
+ * status, and released otherwise. A `401` or `403` with a `Bearer` challenge
+ * to a request that carried the credential throws
+ * `StoreCredentialRefusedError`; a deadline passed throws an error named
+ * `TimeoutError`; a transport failure throws a `StoreTransportError`.
+ */
+export declare function postToStore(url: string, body: unknown, settings: StoreRequestSettings, messages: StoreRequestMessages, readsBody: (status: number) => boolean): Promise<StoreAnswer>;
+//# sourceMappingURL=storeTransport.d.mts.map

package/dist/storeTransport.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeTransport.d.mts","sourceRoot":"","sources":["../src/storeTransport.mts"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAqBtD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA2BrF;AAOD,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQzE;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAkBD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC,CASA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAI/C;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CACnC,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,EACxB,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,EACnC,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMlD;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GACpC,OAAO,CAAC,WAAW,CAAC,CAqEtB"}

package/dist/storeTransport.mjs

@@ -0,0 +1,290 @@
+/*
+ * 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 transport every request to the Store rides on: the credential it
+ * presents, the deadline, the response cap, and a `POST` of JSON that
+ * follows no redirect.
+ *
+ * Guarantees: a setting the transport cannot honour is refused when the
+ * client is built, naming the setting and quoting no value; one deadline
+ * covers a whole exchange, the body read included; a body is read up to the
+ * cap and no further, and a body not read is released unawaited; what is
+ * thrown is the adapter's own — never a transport's error, which may quote
+ * the request — and names an endpoint by origin and path alone.
+ */
+import { describeWeakSecret, MIN_SECRET_ENTROPY_BYTES, measureSecretEntropyBytes, wholeNumberFromEnv, } from "@o3co/auth-provider-core";
+import { z } from "zod";
+import { endpointForMessage } from "./endpointUrl.mjs";
+import { readFailure, requestFailure, StoreCredentialRefusedError, } from "./repositories/storeErrors.mjs";
+import { hasBearerChallenge } from "./repositories/wwwAuthenticate.mjs";
+/**
+ * Default ceiling on an upstream response body, in bytes.
+ *
+ * A `User` record is a few hundred bytes; 1 MiB is generous for one carrying
+ * custom claims and small enough that a hostile or broken Store cannot walk the
+ * process out of memory one login at a time.
+ */
+export const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+/** Default request deadline, in milliseconds, when the configuration names none. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Largest delay Node's timer subsystem represents. Anything above it is
+ * silently clamped to 1ms — so an operator writing a very large number meaning
+ * "be patient" would otherwise get the most impatient timeout possible.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * RFC 6750 §2.1 `b64token` — the characters a bearer credential may carry.
+ * Nothing in it is whitespace or a control character, so a token that
+ * matches cannot break the header it rides in.
+ */
+const B64TOKEN = /^[A-Za-z0-9\-._~+/]+=*$/;
+const BEARER_TOKEN_FIELD = "bearerToken";
+/**
+ * The credential presented to the Store, checked when `owner` is built (so
+ * an unusable one fails at boot) and turned into the `Authorization` value;
+ * `undefined` when none is configured, which sends no `Authorization` header.
+ *
+ * The shape is refused here, not left to `fetch`, which QUOTES a header value
+ * it refuses in the `TypeError` it throws, where the session routes log it.
+ * The strength is core's shared-secret floor (`MIN_SECRET_ENTROPY_BYTES`, on
+ * the decoded length): whoever holds this token speaks to the Store as
+ * auth.provider. No message quotes the value.
+ */
+export function bearerAuthorization(value, owner) {
+    if (value === undefined)
+        return undefined;
+    const refuse = (problem) => new Error(`${owner}: "${BEARER_TOKEN_FIELD}" ${problem}`);
+    if (typeof value !== "string")
+        throw refuse("must be a string");
+    if (value === "") {
+        throw refuse('must not be empty — HOCON substitutes an exported-but-empty variable as ""; ' +
+            "leave it unset to send no Authorization header");
+    }
+    if (!B64TOKEN.test(value)) {
+        throw refuse("must be a bare RFC 6750 token: letters, digits and - . _ ~ + /, then optional = padding — " +
+            'no whitespace, no line break, and no "Bearer " prefix (the scheme is added)');
+    }
+    const actualBytes = measureSecretEntropyBytes(value);
+    if (actualBytes < MIN_SECRET_ENTROPY_BYTES) {
+        throw new Error(`${owner}: ${describeWeakSecret(actualBytes, {
+            configKey: "repositories.user.http.bearerToken",
+            envVar: "REPOSITORIES_USER_HTTP_BEARER_TOKEN",
+        })}`);
+    }
+    return `Bearer ${value}`;
+}
+/** Whether `value` is a positive integer that fits `bound`. */
+function isPositiveIntegerWithin(value, bound) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= bound;
+}
+/** `timeout`, the whole exchange's deadline in milliseconds, or an error naming it for `owner`. */
+export function checkStoreTimeout(timeout, owner) {
+    if (!isPositiveIntegerWithin(timeout, MAX_TIMEOUT_MS)) {
+        throw new Error(`${owner}: "timeout" must be a positive integer no greater than ` +
+            `${MAX_TIMEOUT_MS} milliseconds`);
+    }
+    return timeout;
+}
+/** `maxResponseBytes`, the response cap, or an error naming it for `owner`. */
+export function checkStoreResponseCap(maxResponseBytes, owner) {
+    if (!isPositiveIntegerWithin(maxResponseBytes, Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`${owner}: "maxResponseBytes" must be a positive integer`);
+    }
+    return maxResponseBytes;
+}
+/** A number, or a string of decimal digits as an environment variable carries one. */
+const numberOrDecimalDigits = wholeNumberFromEnv(z.number());
+/**
+ * A numeric config value that may arrive as a string (HOCON environment
+ * substitution yields strings), read as core reads one: a number, or decimal
+ * digits. Only an *absent* key takes `fallback`. Anything else present (a
+ * blank variable, `"0x10"`, `"1e3"`, `"5.0"`, `"+5"`, a boolean) becomes `NaN`
+ * for the constructor to reject: a boot failure, not a silent default.
+ */
+const toNumber = (value, fallback) => {
+    if (value === undefined || value === null)
+        return fallback;
+    const read = numberOrDecimalDigits.safeParse(value);
+    return read.success ? read.data : Number.NaN;
+};
+/**
+ * The transport settings of a Store client's configuration block — the user
+ * repository's `http` block — as a client is built from them: `timeout` and
+ * `maxResponseBytes` read from text too and defaulted only when absent, and
+ * `bearerToken` forwarded whenever set, whatever it holds. The client's
+ * constructor refuses what the transport cannot honour.
+ */
+export function readStoreTransportConfig(block) {
+    return {
+        // Forwarded whenever SET, not only when well-typed: a token that vanished
+        // would be a deployment that believes its Store calls authenticated and
+        // sends them bare.
+        ...(block.bearerToken !== undefined ? { bearerToken: block.bearerToken } : {}),
+        timeout: toNumber(block.timeout, DEFAULT_TIMEOUT_MS),
+        maxResponseBytes: toNumber(block.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES),
+    };
+}
+/**
+ * Releases a response body we are not going to read. Left unconsumed, undici
+ * holds the socket until the response is garbage collected instead of
+ * returning it to the keep-alive pool: a slow leak on the failure path.
+ *
+ * Deliberately not awaited: that would hand a hostile Store a second way to
+ * stall the caller, the one the request deadline exists to close, and some
+ * interceptors never settle it at all.
+ */
+export function discardBody(res) {
+    res.body?.cancel().catch(() => {
+        // Already consumed, already errored, or aborted — nothing to release.
+    });
+}
+/**
+ * Reads at most `limit` bytes of `res` as text, throwing once it is passed.
+ * `Content-Length` refuses an honest oversized response before a byte is read,
+ * but the streaming count is the load-bearing half: a hostile Store omits the
+ * header or lies, and chunked encoding has none. Everything it throws is the
+ * adapter's own (the cap, the deadline's rejection, what `unreadable` makes of
+ * a transport error mid-read), never the transport's error as it is.
+ */
+export async function readBodyCapped(res, limit, endpoint, deadline, unreadable, owner) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        discardBody(res);
+        throw new Error(`${owner}: upstream ${endpoint} response exceeds the ${limit}-byte cap ` +
+            `(Content-Length: ${declared})`);
+    }
+    if (res.body === null)
+        return "";
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let read = 0;
+    try {
+        for (;;) {
+            // Raced against the deadline rather than relying on `signal` alone:
+            // aborting a request does not reliably interrupt a `read()` already
+            // in flight, which is exactly the slow-loris shape — headers arrive
+            // promptly, then the body dribbles or stops. One absolute deadline
+            // for the whole exchange, not a fresh one per chunk.
+            const { done, value } = await Promise.race([
+                reader.read().catch((err) => {
+                    throw unreadable(err);
+                }),
+                deadline,
+            ]);
+            if (done)
+                break;
+            read += value.byteLength;
+            if (read > limit) {
+                throw new Error(`${owner}: upstream ${endpoint} response exceeds the ${limit}-byte cap`);
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        // Tears down the connection when we bail out early; a no-op once the
+        // stream has completed on its own. Not awaited, for the reason given on
+        // `discardBody`.
+        reader.cancel().catch(() => { });
+    }
+    return text + decoder.decode();
+}
+/**
+ * Whether `err` is the abort our own deadline raised on the `fetch` itself,
+ * where the response headers never arrive. Deliberately shallow: an aborted
+ * `fetch` rejects with the `AbortError` directly. A runtime that wrapped one
+ * would still fail the request, as a `StoreTransportError` rather than a
+ * `TimeoutError`: misnamed, not missed. A stalled *body* is the deadline race
+ * in `readBodyCapped`.
+ */
+export function isAbortError(err) {
+    // Optional chaining rather than a `typeof` guard: it covers `null`,
+    // `undefined` and a thrown primitive in the same expression, with no
+    // branch that only a contrived throw could reach.
+    const name = err?.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/**
+ * `POST`s `body` as JSON to `url` and answers what came back, the body read
+ * (up to the cap, within the deadline) only when `readsBody` says so for the
+ * status, and released otherwise. A `401` or `403` with a `Bearer` challenge
+ * to a request that carried the credential throws
+ * `StoreCredentialRefusedError`; a deadline passed throws an error named
+ * `TimeoutError`; a transport failure throws a `StoreTransportError`.
+ */
+export async function postToStore(url, body, settings, messages, readsBody) {
+    const endpoint = endpointForMessage(url);
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeoutError = () => {
+        const error = new Error(`${messages.owner}: request to ${endpoint} timed out after ${settings.timeout}ms`);
+        error.name = "TimeoutError";
+        return error;
+    };
+    let fireDeadline = () => { };
+    const deadline = new Promise((_resolve, reject) => {
+        fireDeadline = () => reject(timeoutError());
+    });
+    deadline.catch(() => { });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        fireDeadline();
+    }, settings.timeout);
+    try {
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers: settings.authorization === undefined
+                    ? { "Content-Type": "application/json" }
+                    : { "Content-Type": "application/json", Authorization: settings.authorization },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+                // Never followed: a redirect would re-send the body to a `Location`
+                // no endpoint check has seen, and take its answer as the Store's.
+                redirect: "manual",
+            });
+        }
+        catch (err) {
+            if (timedOut && isAbortError(err))
+                throw timeoutError();
+            throw requestFailure(err, messages);
+        }
+        if (!readsBody(response.status)) {
+            discardBody(response);
+            if (settings.authorization !== undefined &&
+                (response.status === 401 || response.status === 403) &&
+                hasBearerChallenge(response.headers.get("www-authenticate"))) {
+                throw new StoreCredentialRefusedError(url, response.status, messages.owner);
+            }
+            return { response, text: undefined };
+        }
+        try {
+            const text = await readBodyCapped(response, settings.maxResponseBytes, endpoint, deadline, (err) => readFailure(err, messages.unreadable), messages.owner);
+            return { response, text };
+        }
+        catch (err) {
+            if (timedOut)
+                throw timeoutError();
+            throw err;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/testing/index.d.mts

@@ -0,0 +1,28 @@
+/**
+ * `@o3co/auth-provider-foundation/testing`: what a test uses to configure
+ * this package's modules. Test code imports it; production code never does.
+ */
+import { FOUNDATION_MFA_FACTOR_STORE_SECTION, type FoundationMfaFactorStoreUrls } from "../mfa/section.mjs";
+/** The Store URLs the `"http"` user adapter's builder reads (`registerBuiltinAdapters`). */
+declare const USER_REPOSITORY_URL_KEYS: readonly ["authenticateUrl", "authenticateByTokenUrl", "linkFederatedIdentityUrl", "findSubjectByFederatedIdentityUrl", "markMfaEnrolledUrl"];
+/** The user repository's Store URLs, as the `"http"` builder names them. */
+export type FoundationUserRepositoryUrls = Readonly<Record<(typeof USER_REPOSITORY_URL_KEYS)[number], unknown>>;
+/**
+ * The `foundation-mfa-factor-store` section as a configuration fragment to
+ * lay over a test's configuration: the four URLs `urls` holds — a fake
+ * Store's `urls` included, its other endpoints left behind — and `extra`
+ * as given.
+ */
+export declare function foundationMfaFactorStoreConfig(urls: Partial<Readonly<Record<keyof FoundationMfaFactorStoreUrls, unknown>>>, extra?: Readonly<Record<string, unknown>>): {
+    readonly [FOUNDATION_MFA_FACTOR_STORE_SECTION]: Readonly<Record<string, unknown>>;
+};
+/**
+ * The user repository's `http` block, as the `"http"` builder reads it: the
+ * Store URLs `urls` holds — a fake Store's `urls` included, its MFA factor
+ * endpoints left behind — and `extra` as given. A test hands it to the
+ * `"http"` builder, or to `foundationMfaFactorStoreModule` as its
+ * `storeTransport`.
+ */
+export declare function foundationUserRepositoryHttpConfig(urls: Partial<FoundationUserRepositoryUrls>, extra?: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+export {};
+//# sourceMappingURL=index.d.mts.map