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

package/dist/mfa/module.d.mts

@@ -0,0 +1,27 @@
+/**
+ * The module that keeps a subject's MFA factors in the Store:
+ * `foundation-mfa-factor-store` provides `mfaFactorStore` as an
+ * `HttpMfaFactorStore`, built at boot whether or not anything requires it.
+ *
+ * Guarantees: the section's four URLs are read first, so a composition that
+ * installs the module with any of them unset refuses the boot; the Store's
+ * credential, deadline and response cap are the Store transport settings the
+ * composition root must hand it — the user repository's HTTP settings, read
+ * as that repository's builder reads them — so one token goes to every Store
+ * endpoint, and settings absent or not a section of keys refuse the boot
+ * rather than send no credential. It requires no slot.
+ */
+import { type Module } from "@o3co/auth-provider-core";
+export interface FoundationMfaFactorStoreModuleOptions {
+    /**
+     * The Store transport settings: the user repository's HTTP settings as the
+     * configuration holds them (`repositories.user.http` in the standalone
+     * template, which hands them here), whose `bearerToken`,
+     * `timeout` and `maxResponseBytes` are the Store's, text read as numbers.
+     * `{}` states none: no credential is sent, and the defaults apply.
+     */
+    readonly storeTransport: unknown;
+}
+/** The module, over the Store transport settings `options` hands it. */
+export declare function foundationMfaFactorStoreModule(options: FoundationMfaFactorStoreModuleOptions): Module;
+//# sourceMappingURL=module.d.mts.map

package/dist/mfa/module.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.mts","sourceRoot":"","sources":["../../src/mfa/module.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,0BAA0B,CAAC;AASrE,MAAM,WAAW,qCAAqC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CACjC;AAYD,wEAAwE;AACxE,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qCAAqC,GAC5C,MAAM,CAeR"}

package/dist/mfa/module.mjs

@@ -0,0 +1,56 @@
+/*
+ * 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 module that keeps a subject's MFA factors in the Store:
+ * `foundation-mfa-factor-store` provides `mfaFactorStore` as an
+ * `HttpMfaFactorStore`, built at boot whether or not anything requires it.
+ *
+ * Guarantees: the section's four URLs are read first, so a composition that
+ * installs the module with any of them unset refuses the boot; the Store's
+ * credential, deadline and response cap are the Store transport settings the
+ * composition root must hand it — the user repository's HTTP settings, read
+ * as that repository's builder reads them — so one token goes to every Store
+ * endpoint, and settings absent or not a section of keys refuse the boot
+ * rather than send no credential. It requires no slot.
+ */
+import { defineModule } from "@o3co/auth-provider-core";
+import { readStoreTransportConfig } from "../storeTransport.mjs";
+import { HttpMfaFactorStore } from "./HttpMfaFactorStore.mjs";
+import { foundationMfaFactorStoreLifecycle, foundationMfaFactorStoreSection, readFoundationMfaFactorStoreUrls, } from "./section.mjs";
+/** The settings as a section of keys, or a refusal for anything else, absent included. */
+function settingsOf(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new RangeError("foundation-mfa-factor-store: storeTransport, the Store transport settings, must be a section of keys ({} for none)");
+    }
+    return value;
+}
+/** The module, over the Store transport settings `options` hands it. */
+export function foundationMfaFactorStoreModule(options) {
+    return defineModule({
+        name: "foundation-mfa-factor-store",
+        section: foundationMfaFactorStoreSection,
+        provides: {
+            mfaFactorStore: ({ section }) => {
+                const urls = readFoundationMfaFactorStoreUrls(section);
+                return new HttpMfaFactorStore({
+                    ...urls,
+                    ...readStoreTransportConfig(settingsOf(options?.storeTransport)),
+                });
+            },
+        },
+        lifecycle: foundationMfaFactorStoreLifecycle,
+    });
+}

package/dist/mfa/section.d.mts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/** The section's name: the module's. */
+export declare const FOUNDATION_MFA_FACTOR_STORE_SECTION = "foundation-mfa-factor-store";
+/** The section: the four URLs, each optional here, and no other key. */
+declare const schema: z.ZodObject<{
+    listUrl: z.ZodOptional<z.ZodString>;
+    createUrl: z.ZodOptional<z.ZodString>;
+    updateUrl: z.ZodOptional<z.ZodString>;
+    deleteUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The section as the module declares it: its schema, and the package's reference. */
+export declare const foundationMfaFactorStoreSection: {
+    readonly schema: z.ZodObject<{
+        listUrl: z.ZodOptional<z.ZodString>;
+        createUrl: z.ZodOptional<z.ZodString>;
+        updateUrl: z.ZodOptional<z.ZodString>;
+        deleteUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly reference: import("node:url").URL;
+};
+/**
+ * The lifecycle of a module that reads the section: its store is built at
+ * boot whether or not anything requires it, so the reader always runs.
+ */
+export declare const foundationMfaFactorStoreLifecycle: {
+    readonly mfaFactorStore: {
+        readonly eager: true;
+    };
+};
+/** The section as its schema reads it. */
+export type FoundationMfaFactorStoreSection = z.output<typeof schema>;
+/** The Store's four MFA factor endpoints. */
+export interface FoundationMfaFactorStoreUrls {
+    readonly listUrl: string;
+    readonly createUrl: string;
+    readonly updateUrl: string;
+    readonly deleteUrl: string;
+}
+/**
+ * The four URLs of a parsed section, or a `RangeError` naming each one
+ * missing by its path and its variable.
+ */
+export declare function readFoundationMfaFactorStoreUrls(section: FoundationMfaFactorStoreSection): FoundationMfaFactorStoreUrls;
+export {};
+//# sourceMappingURL=section.d.mts.map

package/dist/mfa/section.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.mts","sourceRoot":"","sources":["../../src/mfa/section.mts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wCAAwC;AACxC,eAAO,MAAM,mCAAmC,gCAAgC,CAAC;AA2BjF,wEAAwE;AACxE,QAAA,MAAM,MAAM;;;;;kBAeX,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,+BAA+B;;;;;;;;CAGK,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,iCAAiC;;;;CAEpC,CAAC;AAEX,0CAA0C;AAC1C,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC;AAEtE,6CAA6C;AAC7C,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC/C,OAAO,EAAE,+BAA+B,GACtC,4BAA4B,CAe9B"}

package/dist/mfa/section.mjs

@@ -0,0 +1,99 @@
+/*
+ * 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 configuration section of the module that keeps a subject's MFA factors
+ * in the Store: `foundation-mfa-factor-store`, named after that module, its
+ * four factor endpoints bound in the package's `config/reference.conf`
+ * without a default.
+ *
+ * Guarantees: the schema refuses an unknown key and a URL that is not https
+ * or loopback http, naming the key in printable characters and quoting no
+ * value; a URL left out passes the schema — the reference binds each one to
+ * a variable that may be unset — and {@link readFoundationMfaFactorStoreUrls}
+ * refuses it. A module that reads the section provides its store eagerly
+ * ({@link foundationMfaFactorStoreLifecycle}) and calls the reader first, so
+ * a composition that installs it with any URL missing refuses the boot,
+ * whether or not anything requires the store.
+ */
+import { auditErrorText } from "@o3co/auth-provider-core";
+import { z } from "zod";
+import { checkSecureEndpoint, describeEndpointRejection } from "../endpointUrl.mjs";
+/** The section's name: the module's. */
+export const FOUNDATION_MFA_FACTOR_STORE_SECTION = "foundation-mfa-factor-store";
+/** The four endpoints, in the order a refusal names them. */
+const URL_KEYS = ["listUrl", "createUrl", "updateUrl", "deleteUrl"];
+/** Each key's variable, named after its path. */
+const VARIABLES = {
+    listUrl: "FOUNDATION_MFA_FACTOR_STORE_LIST_URL",
+    createUrl: "FOUNDATION_MFA_FACTOR_STORE_CREATE_URL",
+    updateUrl: "FOUNDATION_MFA_FACTOR_STORE_UPDATE_URL",
+    deleteUrl: "FOUNDATION_MFA_FACTOR_STORE_DELETE_URL",
+};
+const SECTION_MISSING = "is missing: layer @o3co/auth-provider-foundation/reference.conf beneath the composition's configuration";
+/** A Store endpoint, when present: the rule the user repository holds its URLs to. */
+const storeUrl = z
+    .string({ error: "must be a string" })
+    .superRefine((value, ctx) => {
+    const rejection = checkSecureEndpoint(value);
+    if (rejection !== null) {
+        ctx.addIssue({ code: "custom", message: describeEndpointRejection(rejection) });
+    }
+})
+    .optional();
+/** The section: the four URLs, each optional here, and no other key. */
+const schema = z.strictObject({
+    listUrl: storeUrl,
+    createUrl: storeUrl,
+    updateUrl: storeUrl,
+    deleteUrl: storeUrl,
+}, {
+    error: (issue) => {
+        if (issue.code === "unrecognized_keys") {
+            return `has a key it does not know: ${issue.keys.map((key) => `"${auditErrorText(key)}"`).join(", ")}`;
+        }
+        return issue.input === undefined ? SECTION_MISSING : "must be a section of keys";
+    },
+});
+/** The section as the module declares it: its schema, and the package's reference. */
+export const foundationMfaFactorStoreSection = {
+    schema,
+    reference: new URL("../../config/reference.conf", import.meta.url),
+};
+/**
+ * The lifecycle of a module that reads the section: its store is built at
+ * boot whether or not anything requires it, so the reader always runs.
+ */
+export const foundationMfaFactorStoreLifecycle = {
+    mfaFactorStore: { eager: true },
+};
+/**
+ * The four URLs of a parsed section, or a `RangeError` naming each one
+ * missing by its path and its variable.
+ */
+export function readFoundationMfaFactorStoreUrls(section) {
+    const missing = URL_KEYS.filter((key) => section[key] === undefined);
+    if (missing.length > 0) {
+        throw new RangeError(`${missing
+            .map((key) => `${FOUNDATION_MFA_FACTOR_STORE_SECTION}.${key} (${VARIABLES[key]})`)
+            .join(", ")} must be set: the Store keeps the MFA factors only with all four endpoints`);
+    }
+    return {
+        listUrl: section.listUrl,
+        createUrl: section.createUrl,
+        updateUrl: section.updateUrl,
+        deleteUrl: section.deleteUrl,
+    };
+}

package/dist/mfa/storeFailure.d.mts

@@ -0,0 +1,52 @@
+import type { StoreRequestMessages } from "../storeTransport.mjs";
+/** The Store's MFA endpoints, by what the provider asks of each. */
+export type MfaStoreOperation = "list" | "create" | "update" | "delete" | "markMfaEnrolled";
+/** Why an answer is not one the contract gives the operation. */
+export type MfaStoreFailure = 
+/** A status the contract does not give the operation. */
+"unexpected_status"
+/** `markMfaEnrolled` answered `404`: the Store holds no such subject. */
+ | "unknown_subject"
+/** A `2xx` whose body is not the contract's. */
+ | "malformed_answer"
+/** A list holding a record the provider cannot read: the list is refused, never read as none. */
+ | "unreadable_record"
+/** An update answered a version other than the expected one plus one. */
+ | "version_skipped";
+/** An MFA endpoint answered outside the contract. `name`, `reason`, `operation` and `storeStatus` are part of the contract. */
+export declare class MfaStoreError extends Error {
+    readonly reason: MfaStoreFailure;
+    readonly operation: MfaStoreOperation;
+    /** The Store's status, for a status the contract does not give the operation. */
+    readonly storeStatus: number | undefined;
+    constructor(message: string, reason: MfaStoreFailure, operation: MfaStoreOperation, storeStatus?: number);
+}
+/**
+ * What a transport failure of `operation` at `url` says, for the client
+ * `owner` that sends it: one wording for every client of these endpoints,
+ * naming the endpoint by origin and path.
+ */
+export declare function mfaStoreRequestMessages(owner: string, operation: MfaStoreOperation, url: string): StoreRequestMessages;
+/**
+ * `response`'s status as an error, when the contract does not give it to
+ * `operation`: `unknown_subject` for `markMfaEnrolled`'s `404`,
+ * `unexpected_status` for any other. Reads the status alone and releases the
+ * body without awaiting it, which a Store could otherwise hold open.
+ */
+export declare function mfaStoreStatusError(operation: MfaStoreOperation, url: string, response: Response): MfaStoreError;
+/** A `2xx` from `operation` whose body is not the contract's. */
+export declare function mfaStoreMalformedAnswer(operation: MfaStoreOperation, url: string): MfaStoreError;
+/** A list holding a record the provider cannot read. */
+export declare function mfaStoreUnreadableRecord(url: string): MfaStoreError;
+/**
+ * An update of `(subject, id)` at `expectedVersion` answered another version
+ * than `expectedVersion + 1`. The subject and the factor id lead the
+ * message, so a log line that cuts it (`loggableError`, 256 characters) still
+ * names both.
+ */
+export declare function mfaStoreVersionSkipped(url: string, update: {
+    readonly subject: string;
+    readonly id: string;
+    readonly expectedVersion: number;
+}): MfaStoreError;
+//# sourceMappingURL=storeFailure.d.mts.map

package/dist/mfa/storeFailure.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeFailure.d.mts","sourceRoot":"","sources":["../../src/mfa/storeFailure.mts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,CAAC;AAE5F,iEAAiE;AACjE,MAAM,MAAM,eAAe;AAC1B,yDAAyD;AACvD,mBAAmB;AACrB,yEAAyE;GACvE,iBAAiB;AACnB,gDAAgD;GAC9C,kBAAkB;AACpB,iGAAiG;GAC/F,mBAAmB;AACrB,yEAAyE;GACvE,iBAAiB,CAAC;AAErB,+HAA+H;AAC/H,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,iBAAiB,EAC5B,WAAW,CAAC,EAAE,MAAM;CAQrB;AAKD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,GAAG,EAAE,MAAM,GACT,oBAAoB,CAStB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,iBAAiB,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,GAChB,aAAa,CAiBf;AAED,iEAAiE;AACjE,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAMhG;AAED,wDAAwD;AACxD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAMnE;AAgBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACzF,aAAa,CAOf"}

package/dist/mfa/storeFailure.mjs

@@ -0,0 +1,107 @@
+/*
+ * 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.
+ */
+/**
+ * What the Store adapter throws when an MFA endpoint answers outside the
+ * contract (README, "The Store's MFA endpoints"). Transport failures, a
+ * deadline and a refused credential are `StoreTransportError`,
+ * `TimeoutError` and `StoreCredentialRefusedError`, as for the user
+ * repository.
+ *
+ * Guarantees: an error is built from an allowlist — the operation, the
+ * endpoint by origin and path, the Store's status as a number, and for an
+ * unexpected version the subject and factor id through `auditErrorText`, at
+ * most 64 characters each and ahead of the rest —
+ * never from a body, a status text or a header the Store sent, and a body is
+ * released unread. No `status`, `statusCode`, `expose` or `cause`: an HTTP
+ * layer reading one would answer with the Store's status, and the client
+ * gets the provider's generic answer for an outage, whatever went wrong.
+ */
+import { auditErrorText } from "@o3co/auth-provider-core";
+import { endpointForMessage } from "../endpointUrl.mjs";
+/** An MFA endpoint answered outside the contract. `name`, `reason`, `operation` and `storeStatus` are part of the contract. */
+export class MfaStoreError extends Error {
+    reason;
+    operation;
+    /** The Store's status, for a status the contract does not give the operation. */
+    storeStatus;
+    constructor(message, reason, operation, storeStatus) {
+        super(message);
+        this.name = "MfaStoreError";
+        this.reason = reason;
+        this.operation = operation;
+        this.storeStatus = storeStatus;
+    }
+}
+const endpointOf = (operation, url) => `the Store's MFA ${operation} endpoint at ${endpointForMessage(url)}`;
+/**
+ * What a transport failure of `operation` at `url` says, for the client
+ * `owner` that sends it: one wording for every client of these endpoints,
+ * naming the endpoint by origin and path.
+ */
+export function mfaStoreRequestMessages(owner, operation, url) {
+    const endpoint = endpointOf(operation, url);
+    return {
+        owner,
+        unreachable: `${owner}: ${endpoint} could not be reached`,
+        closed: `${owner}: the connection to ${endpoint} closed before a complete response arrived`,
+        malformed: `${owner}: ${endpoint} answered with a malformed HTTP response`,
+        unreadable: `${owner}: the answer of ${endpoint} could not be read`,
+    };
+}
+/**
+ * `response`'s status as an error, when the contract does not give it to
+ * `operation`: `unknown_subject` for `markMfaEnrolled`'s `404`,
+ * `unexpected_status` for any other. Reads the status alone and releases the
+ * body without awaiting it, which a Store could otherwise hold open.
+ */
+export function mfaStoreStatusError(operation, url, response) {
+    const status = response.status;
+    response.body?.cancel().catch(() => { });
+    if (operation === "markMfaEnrolled" && status === 404) {
+        return new MfaStoreError(`${endpointOf(operation, url)} answered HTTP 404: it holds no such subject`, "unknown_subject", operation, status);
+    }
+    return new MfaStoreError(`${endpointOf(operation, url)} answered HTTP ${status}`, "unexpected_status", operation, status);
+}
+/** A `2xx` from `operation` whose body is not the contract's. */
+export function mfaStoreMalformedAnswer(operation, url) {
+    return new MfaStoreError(`${endpointOf(operation, url)} answered a body that is not the contract's`, "malformed_answer", operation);
+}
+/** A list holding a record the provider cannot read. */
+export function mfaStoreUnreadableRecord(url) {
+    return new MfaStoreError(`${endpointOf("list", url)} answered a factor record the provider cannot read: the subject's factors are unavailable, never read as none`, "unreadable_record", "list");
+}
+/** The most characters of a subject or a factor id an error names. */
+const IDENTIFIER_MAX_LENGTH = 64;
+/**
+ * `text` as an error names it: `auditErrorText`'s printable ASCII, cut at
+ * {@link IDENTIFIER_MAX_LENGTH} with `...`.
+ */
+const identifier = (text) => {
+    const safe = auditErrorText(text);
+    return safe.length <= IDENTIFIER_MAX_LENGTH
+        ? safe
+        : `${safe.slice(0, IDENTIFIER_MAX_LENGTH - 3)}...`;
+};
+/**
+ * An update of `(subject, id)` at `expectedVersion` answered another version
+ * than `expectedVersion + 1`. The subject and the factor id lead the
+ * message, so a log line that cuts it (`loggableError`, 256 characters) still
+ * names both.
+ */
+export function mfaStoreVersionSkipped(url, update) {
+    return new MfaStoreError(`subject ${identifier(update.subject)}, factor ${identifier(update.id)}: ` +
+        `${endpointOf("update", url)} answered a version other than ${update.expectedVersion + 1}`, "version_skipped", "update");
+}

package/dist/repositories/HttpUserRepository.d.mts

@@ -1,20 +1,14 @@
-import { type FederatedIdentityLink, type FederatedIdentityLookup, type FederatedIdentityLookupResult, type FederatedIdentityRegistration, type LinkFederatedIdentityResult, type User, type UserRepository } from "@o3co/auth-provider-core";
+import type { FederatedIdentityLink, FederatedIdentityLookup, FederatedIdentityLookupResult, FederatedIdentityRegistration, LinkFederatedIdentityResult, User, UserRepository } from "@o3co/auth-provider-core";
+import { DEFAULT_MAX_RESPONSE_BYTES } from "../storeTransport.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES };
 /**
- * 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 (#285).
- */
-export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
-/**
- * What the Store declares it can place (#613): identities issued under one
- * registration — the federation's name, the issuer and the client, exactly as
- * a federation-grant connection is configured — given at least these claims
- * from the verified id_token. The synchronous probe D7 check 5 asks at boot
- * cannot reach the Store, so the operator relays the Store's own claim here;
- * boot then holds every connection to it. `requiredClaims = []` is a strategy
- * on the registration and the `sub` alone.
+ * What the Store declares it can place: identities issued under one
+ * registration (the federation's name, the issuer and the client, exactly as
+ * a federation-grant connection is configured), given at least these claims
+ * from the verified id_token. The boot probe is synchronous and cannot reach
+ * the Store, so the operator relays the Store's own claim here; boot then
+ * holds every connection to it. `requiredClaims = []` is a strategy on the
+ * registration and the `sub` alone.
  */
 export interface FederatedIdentityLookupCoverage {
     readonly provider: string;
@@ -23,41 +17,19 @@ export interface FederatedIdentityLookupCoverage {
     readonly requiredClaims: readonly string[];
 }
 /**
- * `UserRepository` backed by "the Store" — the upstream user service defined
+ * `UserRepository` backed by "the Store", the upstream user service defined
  * on core's `User` doc (`@o3co/auth-provider-core`, `src/repositories/types.mts`).
+ * See README, The wire contract and Constructor validation.
  *
  * Every endpoint receives a plaintext credential or a verified identity, so
- * each is validated at **construction**: a deployment configured with an
- * `http://` Store URL fails at boot rather than leaking the first user's
- * password (#285). `http://` is accepted for loopback hosts only — see
- * `src/endpointUrl.mts` for the carve-out and its rationale.
- *
- * No request follows a redirect, so a URL that passed that check is the only
- * place its body is ever sent and the only one whose answer is taken: a `3xx`
- * from the Store is an upstream failure, thrown like any other unexpected
- * status, and its `Location` is never contacted.
- *
- * With `bearerToken` configured, every request — authentication, linking and
- * the identity lookup alike — carries `Authorization: Bearer <token>`, so the
- * Store can refuse a caller that is not this deployment; without it, no
- * request carries an `Authorization` header. The Store says it refused THIS
- * deployment by answering `401` or `403` with a `Bearer` challenge (RFC 6750
- * §3), and that answer, while a token was sent, throws a
- * {@link StoreCredentialRefusedError} on every request — never "no such user"
- * or a refused link, which is what either status without the challenge still
- * means.
- *
- * A transport's own error is never thrown: undici's parser errors quote the
- * bytes they rejected, and a peer that reflects the request puts the
- * `Authorization` header — or a password — there. A request that cannot be
- * made, or an answer that cannot be read, throws a `StoreTransportError`
- * (`src/repositories/storeErrors.mts`): a fixed message naming the endpoint
- * and what failed, at most an allowlisted transport code, no cause.
- *
- * Every message names an endpoint by its origin and path alone
- * (`endpointForMessage`, `src/endpointUrl.mts`): a Store URL may carry a
- * query string, and a query may carry a credential, while every caller logs
- * what this throws.
+ * each is validated at **construction** (`src/endpointUrl.mts`), and no
+ * request follows a redirect. With `bearerToken`, every request carries
+ * `Authorization: Bearer <token>`, and a `401` or `403` with a `Bearer`
+ * challenge throws a `StoreCredentialRefusedError`. A transport's own
+ * error is never thrown, because it may quote the request: a failure throws a
+ * `StoreTransportError` with a fixed message, at most an allowlisted transport
+ * code, and no cause. Every message names an endpoint by origin and path
+ * alone.
  */
 export declare class HttpUserRepository implements UserRepository {
     #private;
@@ -69,30 +41,39 @@ export declare class HttpUserRepository implements UserRepository {
     private findSubjectByFederatedIdentityUrl?;
     private readonly coverage;
     /**
-     * #482 — see {@link UserRepository.linkFederatedIdentity}. Present only when
+     * See {@link UserRepository.linkFederatedIdentity}. Present only when
      * `linkFederatedIdentityUrl` is configured, which is how the federation routes
      * know to refuse `?link=1` up front instead of at the callback.
      */
     readonly linkFederatedIdentity?: (userId: string, identity: FederatedIdentityLink) => Promise<LinkFederatedIdentityResult>;
     /**
-     * #613 — see {@link UserRepository.supportsFederatedIdentityLookup}. Present
+     * See {@link UserRepository.supportsFederatedIdentityLookup}. Present
      * together with the lookup, only when `findSubjectByFederatedIdentityUrl` is
      * configured: absent, a deployment that requires the lookup is refused at
      * boot by the method's name, which is the message that says what to set.
      * Answers from the declaration alone — the Store is not asked at boot.
      */
     readonly supportsFederatedIdentityLookup?: (registration: FederatedIdentityRegistration, identityClaims: readonly string[]) => boolean;
-    /** #613 — see {@link UserRepository.findSubjectByFederatedIdentity}. Present with the probe. */
+    /** See {@link UserRepository.findSubjectByFederatedIdentity}. Present with the probe. */
     readonly findSubjectByFederatedIdentity?: (identity: FederatedIdentityLookup) => Promise<FederatedIdentityLookupResult>;
-    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, bearerToken, timeout, maxResponseBytes, }: {
+    /**
+     * See {@link UserRepository.markMfaEnrolled}. Present only when
+     * `markMfaEnrolledUrl` is configured, which is how
+     * `supportsMfaEnrollmentWitness` detects it; written as the Store's MFA
+     * endpoints are (`src/mfa/markEnrolled.mts`).
+     */
+    readonly markMfaEnrolled?: (subject: string, enrolled: boolean) => Promise<void>;
+    constructor({ authenticateUrl, authenticateByTokenUrl, linkFederatedIdentityUrl, findSubjectByFederatedIdentityUrl, federatedIdentityLookupCoverage, markMfaEnrolledUrl, bearerToken, timeout, maxResponseBytes, }: {
         authenticateUrl: string;
         authenticateByTokenUrl: string;
-        /** #482: optional; the Store's link endpoint. Same https rule as the other two. */
+        /** Optional; the Store's link endpoint. Same https rule as the other two. */
         linkFederatedIdentityUrl?: string;
-        /** #613: optional; the Store's identity lookup. Same https rule; carries a verified identity. */
+        /** Optional; the Store's identity lookup. Same https rule; carries a verified identity. */
         findSubjectByFederatedIdentityUrl?: string;
-        /** #613: which registrations the Store's lookup covers. Needs the URL; `[]` covers none. */
+        /** Which registrations the Store's lookup covers. Needs the URL; `[]` covers none. */
         federatedIdentityLookupCoverage?: readonly FederatedIdentityLookupCoverage[];
+        /** Optional; the Store's MFA enrollment witness endpoint. Same https rule. */
+        markMfaEnrolledUrl?: string;
         /**
          * Optional; sent to the Store on every request as `Authorization: Bearer
          * <token>`. A bare RFC 6750 token (no scheme) of at least
@@ -102,24 +83,20 @@ export declare class HttpUserRepository implements UserRepository {
         timeout: number;
         maxResponseBytes?: number;
     });
-    /** What every request carries: the body's type and, when configured, the credential. */
-    private headers;
     /**
-     * Throws {@link StoreCredentialRefusedError} when a non-`2xx` answer is the
-     * Store refusing this deployment's credential: a `401` or `403` with a
-     * `Bearer` challenge, to a request that carried the token. Read before any
-     * other reading of the status — without it a token the Store does not
-     * accept is every login "no such user" and every link "refused", with
-     * nothing logged. Without a token sent, a challenge is not about one, and a
-     * Store whose stack challenges every refusal keeps the wire meaning it has
-     * always had.
+     * What every request is sent with: the credential, when configured, the
+     * deadline and the cap. A `401` or `403` with a `Bearer` challenge to a
+     * request that carried the credential throws `StoreCredentialRefusedError`
+     * before any other reading of the status (`postToStore`): otherwise a
+     * token the Store does not accept is every login "no such user" and every
+     * link "refused", with nothing logged.
      */
-    private assertCredentialAccepted;
+    private settings;
     authenticate(username: string, password: string): Promise<User | null>;
     authenticateByToken(token: string): Promise<User | null>;
     /**
-     * POST `{ userId, provider, sub, token, claims }` to the Store's link endpoint
-     * (#482). A `2xx` `User` is the linked account; `401` / `403` is the Store's
+     * POST `{ userId, provider, sub, token, claims }` to the Store's link
+     * endpoint. A `2xx` `User` is the linked account; `401` / `403` is the Store's
      * refusal (policy — an unverified or relay address, one identity per
      * provider, …); `409` says the identity is already someone else's.
      */
@@ -128,7 +105,7 @@ export declare class HttpUserRepository implements UserRepository {
     private declared;
     /**
      * POST `{ provider, issuer, clientId, sub, claims }` to the Store's lookup
-     * (#613) and read one of the port's three answers. Answered locally, with
+     * and read one of the port's three answers. Answered locally, with
      * no request, where the declaration already decides: a registration nobody
      * declared is `registration_not_covered`, and a declared one arriving
      * without a claim its strategy needs is `identity_not_resolvable`. Every
@@ -138,16 +115,14 @@ export declare class HttpUserRepository implements UserRepository {
     private lookupViaHttp;
     /**
      * The lookup's transport: the same deadline, cap and abort as {@link post},
-     * and like it never follows a redirect — the body carries a verified
-     * identity, and a `Location` is not a configured endpoint. None of
-     * {@link post}'s readings, though. A `401`/`403` is not "nobody", a `409` is
-     * not a conflict, a `404` is not an absence: only a `2xx` carrying one of the
-     * three answers is an answer, and everything else throws — as an outage,
-     * which is what a lookup that could not be made is — a `401` or `403` with a
-     * `Bearer` challenge, to a request that carried the token, as the refused
-     * credential it is. What is thrown names the endpoint by origin and path — and, for an answer
-     * with a status, the status; for a transport failure, at most its code — and
-     * never the body, the identity, a status text or an underlying cause.
+     * and like it never follows a redirect (the body carries a verified identity,
+     * and a `Location` is not a configured endpoint). None of {@link post}'s
+     * readings: only a `2xx` carrying one of the three answers is an answer.
+     * Everything else throws as an outage, except a `401` or `403` with a
+     * `Bearer` challenge to a request that carried the token, which throws as the
+     * refused credential it is. What is thrown names the endpoint by origin and
+     * path, plus the status for an answer or at most the code for a transport
+     * failure, and never the body, the identity, a status text or a cause.
      */
     private postLookup;
     private post;

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

@@ -1 +1 @@
-{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,EAEN,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAGhC,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,MAAM,0BAA0B,CAAC;AAQlC;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AA8BtD;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AA4RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAOxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,OAAO,CAAC,iCAAiC,CAAC,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,KAC3B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAC1C,YAAY,EAAE,6BAA6B,EAC3C,cAAc,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC;IACb,gGAAgG;IAChG,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CACzC,QAAQ,EAAE,uBAAuB,KAC7B,OAAO,CAAC,6BAA6B,CAAC,CAAC;gBAEhC,EACX,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,EAC/B,WAAW,EACX,OAAO,EACP,gBAA6C,GAC7C,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mFAAmF;QACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,iGAAiG;QACjG,iCAAiC,CAAC,EAAE,MAAM,CAAC;QAC3C,4FAA4F;QAC5F,+BAA+B,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;QAC7E;;;;WAIG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IAmDD,wFAAwF;IACxF,OAAO,CAAC,OAAO;IAMf;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IAU1B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKtE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAI9D;;;;;OAKG;YACW,WAAW;IAWzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAWhB;;;;;;;;OAQG;YACW,aAAa;IAoB3B;;;;;;;;;;;;OAYG;YACW,UAAU;YA8EV,IAAI;CAiHlB"}
+{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACX,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,IAAI,EACJ,cAAc,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAIN,0BAA0B,EAG1B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,0BAA0B,EAAE,CAAC;AA6BtC;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAwHD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAOxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,OAAO,CAAC,iCAAiC,CAAC,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,KAC3B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAC1C,YAAY,EAAE,6BAA6B,EAC3C,cAAc,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC;IACb,yFAAyF;IACzF,QAAQ,CAAC,8BAA8B,CAAC,EAAE,CACzC,QAAQ,EAAE,uBAAuB,KAC7B,OAAO,CAAC,6BAA6B,CAAC,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;gBAErE,EACX,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,EAC/B,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,gBAA6C,GAC7C,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,6EAA6E;QAC7E,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,2FAA2F;QAC3F,iCAAiC,CAAC,EAAE,MAAM,CAAC;QAC3C,sFAAsF;QACtF,+BAA+B,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;QAC7E,8EAA8E;QAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B;;;;WAIG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IA8CD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ;IAQV,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKtE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAI9D;;;;;OAKG;YACW,WAAW;IAWzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAWhB;;;;;;;;OAQG;YACW,aAAa;IAoB3B;;;;;;;;;;OAUG;YACW,UAAU;YAqCV,IAAI;CAgDlB"}