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

package/config/reference.conf

@@ -0,0 +1,20 @@
+# Foundation defaults -- @o3co/auth-provider-foundation
+#
+# The section of the module that keeps a subject's MFA factors in the Store,
+# `foundation-mfa-factor-store`: the Store's four MFA factor endpoints, each
+# a POST of JSON (the package README, "The Store's MFA endpoints"). A
+# composition root that installs a module reading the section layers this
+# file between its own configuration and core's reference.conf.
+#
+# None has a default, and each is required: a module reading the section
+# refuses the boot with any of them unset, naming each one missing. Each
+# must be https, or http to a loopback host (localhost, 127.0.0.0/8, [::1]),
+# and the endpoint that answers: no request follows a redirect. Each key has
+# its variable, FOUNDATION_MFA_FACTOR_STORE_<KEY>.
+
+foundation-mfa-factor-store {
+  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}
+}

package/dist/endpointUrl.d.mts

@@ -1,41 +1,17 @@
 /**
- * Transport validation for the Store endpoints `HttpUserRepository` posts to.
- *
- * These endpoints receive **plaintext user credentials** — a password on
- * `authenticateUrl`, a bearer-ish token on `authenticateByTokenUrl`. An
- * `http://` URL therefore does not merely weaken the connection, it publishes
- * the credential to every hop on the path. A single mistyped environment
- * variable was enough to do that, and nothing anywhere refused it (#285).
- *
- * ## The loopback carve-out
- *
- * `http://` is accepted for **loopback hosts only** — `localhost`, anything in
- * `127.0.0.0/8`, and `[::1]`. Traffic to a loopback address never leaves the
- * machine, so there is no path to eavesdrop on, and requiring TLS there would
- * force every local development setup and every in-process test fixture to
- * provision a certificate for no security gain. Any other host — including a
- * private-range address such as `10.0.0.5` or a service name on a container
- * network — must use `https://`: those cross a network the deployment does not
- * control end to end, and "internal" is not a synonym for "encrypted".
- *
- * The rule matches `oauth.jwt.issuer`'s (`checkCanonicalIssuer` in
- * `@o3co/auth-provider-core`) so operators meet one policy, not two. It is kept
- * separate rather than reused because the constraints genuinely differ: an
- * issuer may not carry a query string or fragment (OIDC Discovery derives the
- * metadata URL from it), while a Store endpoint is an ordinary POST target for
- * which `?tenant=acme` is legitimate. The loopback *predicate* the carve-out
- * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
- * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
- * session redirect policy consumes, so the carve-outs cannot drift apart.
- *
- * ## What a message names of an endpoint
- *
- * Every failure the repository throws names the endpoint it was talking to,
- * and every caller logs what it throws. A message names the endpoint by its
- * origin and path alone ({@link endpointForMessage}): a query string is
- * accepted in a Store URL, and a deployment may carry a credential there
- * (`?api_key=…`) despite the README's advice, so the query never reaches a
- * message — nor does a fragment, which no request sends anyway.
+ * Transport validation for the Store endpoints the Store clients post to —
+ * `HttpUserRepository`'s and `HttpMfaFactorStore`'s: `https://`, or
+ * `http://` to a loopback host only (`localhost`, `127.0.0.0/8`, `[::1]`),
+ * because what they carry — credentials, verified identities, sealed factor
+ * records — must not cross a network in the clear. See README, Constructor
+ * validation.
+ *
+ * Kept separate from `oauth.jwt.issuer`'s rule (core's `checkCanonicalIssuer`)
+ * because an issuer may not carry a query string, while a Store endpoint may.
+ * The loopback predicate is core's `isLoopbackHostname`, the session redirect
+ * policy's too, so the carve-outs cannot drift apart. A message names an
+ * endpoint by origin and path alone ({@link endpointForMessage}): a query may
+ * carry a credential, and every caller logs what a client throws.
  */
 import { isLoopbackHostname } from "@o3co/auth-provider-core";
 export { isLoopbackHostname };
@@ -58,22 +34,20 @@ export declare function checkSecureEndpoint(value: unknown): EndpointRejection |
 export declare function describeEndpointRejection(reason: EndpointRejection): string;
 /**
  * Returns `value` when it is a usable Store endpoint, otherwise throws naming
- * `field` and the reason.
+ * `owner`, `field` and the reason.
  *
  * The rejected value is deliberately **not** echoed into the message: it is
  * operator-supplied configuration that may embed a secret, and a boot error
  * lands in logs.
  */
-export declare function assertSecureEndpoint(value: unknown, field: string): string;
+export declare function assertSecureEndpoint(value: unknown, field: string, owner?: string): string;
 /**
- * `url` as a message names it: its origin and path — `https://store.example
- * /authenticate`, as the WHATWG URL parser normalises them (a default port
- * dropped, scheme and host lower-cased, an IPv6 literal in brackets) — and
- * never its query or fragment, which may carry a credential. Anything that is
- * not an http or https URL is named by what it is not: its origin would be
- * `"null"` and its "path" the rest of it (`data:…`, `mailto:…`), and the
- * constructor refuses such a Store URL anyway — but a caller can hand
- * `StoreCredentialRefusedError` anything.
+ * `url` as a message names it: its origin and path, as the WHATWG URL parser
+ * normalises them (`https://store.example/authenticate`), and never its query
+ * or fragment, which may carry a credential. Anything that is not an http or
+ * https URL is named by what it is not, since its origin would be `"null"` and
+ * its path the rest of it (`data:…`): the constructor refuses such a Store URL,
+ * but a caller can hand `StoreCredentialRefusedError` anything.
  */
 export declare function endpointForMessage(url: string): string;
 //# sourceMappingURL=endpointUrl.d.mts.map

package/dist/endpointUrl.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"endpointUrl.d.mts","sourceRoot":"","sources":["../src/endpointUrl.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAC1B,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,CAAC;AAKrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQtD"}
+{"version":3,"file":"endpointUrl.d.mts","sourceRoot":"","sources":["../src/endpointUrl.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAC1B,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,CAAC;AAKrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,KAAK,SAAuB,GAC1B,MAAM,CAQR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQtD"}

package/dist/endpointUrl.mjs

@@ -14,48 +14,24 @@
  * limitations under the License.
  */
 /**
- * Transport validation for the Store endpoints `HttpUserRepository` posts to.
+ * Transport validation for the Store endpoints the Store clients post to —
+ * `HttpUserRepository`'s and `HttpMfaFactorStore`'s: `https://`, or
+ * `http://` to a loopback host only (`localhost`, `127.0.0.0/8`, `[::1]`),
+ * because what they carry — credentials, verified identities, sealed factor
+ * records — must not cross a network in the clear. See README, Constructor
+ * validation.
  *
- * These endpoints receive **plaintext user credentials** — a password on
- * `authenticateUrl`, a bearer-ish token on `authenticateByTokenUrl`. An
- * `http://` URL therefore does not merely weaken the connection, it publishes
- * the credential to every hop on the path. A single mistyped environment
- * variable was enough to do that, and nothing anywhere refused it (#285).
- *
- * ## The loopback carve-out
- *
- * `http://` is accepted for **loopback hosts only** — `localhost`, anything in
- * `127.0.0.0/8`, and `[::1]`. Traffic to a loopback address never leaves the
- * machine, so there is no path to eavesdrop on, and requiring TLS there would
- * force every local development setup and every in-process test fixture to
- * provision a certificate for no security gain. Any other host — including a
- * private-range address such as `10.0.0.5` or a service name on a container
- * network — must use `https://`: those cross a network the deployment does not
- * control end to end, and "internal" is not a synonym for "encrypted".
- *
- * The rule matches `oauth.jwt.issuer`'s (`checkCanonicalIssuer` in
- * `@o3co/auth-provider-core`) so operators meet one policy, not two. It is kept
- * separate rather than reused because the constraints genuinely differ: an
- * issuer may not carry a query string or fragment (OIDC Discovery derives the
- * metadata URL from it), while a Store endpoint is an ordinary POST target for
- * which `?tenant=acme` is legitimate. The loopback *predicate* the carve-out
- * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
- * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
- * session redirect policy consumes, so the carve-outs cannot drift apart.
- *
- * ## What a message names of an endpoint
- *
- * Every failure the repository throws names the endpoint it was talking to,
- * and every caller logs what it throws. A message names the endpoint by its
- * origin and path alone ({@link endpointForMessage}): a query string is
- * accepted in a Store URL, and a deployment may carry a credential there
- * (`?api_key=…`) despite the README's advice, so the query never reaches a
- * message — nor does a fragment, which no request sends anyway.
+ * Kept separate from `oauth.jwt.issuer`'s rule (core's `checkCanonicalIssuer`)
+ * because an issuer may not carry a query string, while a Store endpoint may.
+ * The loopback predicate is core's `isLoopbackHostname`, the session redirect
+ * policy's too, so the carve-outs cannot drift apart. A message names an
+ * endpoint by origin and path alone ({@link endpointForMessage}): a query may
+ * carry a credential, and every caller logs what a client throws.
  */
 import { isLoopbackHostname } from "@o3co/auth-provider-core";
 // Re-exported unchanged: this module's callers (and its tests) read the
 // predicate as part of the endpoint-validation surface. The definition lives
-// in core (#364) — re-exporting is the sanctioned way to surface it.
+// in core.
 export { isLoopbackHostname };
 /** Matches `scheme://` — the shape that distinguishes an absolute URL from a bare host. */
 const ABSOLUTE_URL_PREFIX = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
@@ -114,7 +90,7 @@ export function describeEndpointRejection(reason) {
             return ("must use https, or http for a loopback host (localhost, 127.0.0.0/8, [::1]) — " +
                 "no other scheme is accepted");
         case "insecure-scheme":
-            return ("must use https — it carries plaintext user credentials; http is accepted only for " +
+            return ("must use https — what it carries must not cross a network in the clear; http is accepted only for " +
                 "a loopback host (localhost, 127.0.0.0/8, [::1])");
         case "has-credentials":
             return "must not embed credentials in the URL";
@@ -122,29 +98,26 @@ export function describeEndpointRejection(reason) {
 }
 /**
  * Returns `value` when it is a usable Store endpoint, otherwise throws naming
- * `field` and the reason.
+ * `owner`, `field` and the reason.
  *
  * The rejected value is deliberately **not** echoed into the message: it is
  * operator-supplied configuration that may embed a secret, and a boot error
  * lands in logs.
  */
-export function assertSecureEndpoint(value, field) {
+export function assertSecureEndpoint(value, field, owner = "HttpUserRepository") {
     const rejection = checkSecureEndpoint(value);
     if (rejection !== null) {
-        throw new Error(`HttpUserRepository: "${field}" ${describeEndpointRejection(rejection)} ` +
-            `(reason: ${rejection})`);
+        throw new Error(`${owner}: "${field}" ${describeEndpointRejection(rejection)} (reason: ${rejection})`);
     }
     return value;
 }
 /**
- * `url` as a message names it: its origin and path — `https://store.example
- * /authenticate`, as the WHATWG URL parser normalises them (a default port
- * dropped, scheme and host lower-cased, an IPv6 literal in brackets) — and
- * never its query or fragment, which may carry a credential. Anything that is
- * not an http or https URL is named by what it is not: its origin would be
- * `"null"` and its "path" the rest of it (`data:…`, `mailto:…`), and the
- * constructor refuses such a Store URL anyway — but a caller can hand
- * `StoreCredentialRefusedError` anything.
+ * `url` as a message names it: its origin and path, as the WHATWG URL parser
+ * normalises them (`https://store.example/authenticate`), and never its query
+ * or fragment, which may carry a credential. Anything that is not an http or
+ * https URL is named by what it is not, since its origin would be `"null"` and
+ * its path the rest of it (`data:…`): the constructor refuses such a Store URL,
+ * but a caller can hand `StoreCredentialRefusedError` anything.
  */
 export function endpointForMessage(url) {
     try {

package/dist/index.d.mts

@@ -2,6 +2,10 @@ import type { AdapterFactory, UserRepository } from "@o3co/auth-provider-core";
 export declare const registerBuiltinAdapters: (factories: {
     userFactory: AdapterFactory<UserRepository>;
 }) => void;
-export { DEFAULT_MAX_RESPONSE_BYTES, type FederatedIdentityLookupCoverage, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+export { HttpMfaFactorStore, type HttpMfaFactorStoreOptions, } from "./mfa/HttpMfaFactorStore.mjs";
+export { type FoundationMfaFactorStoreModuleOptions, foundationMfaFactorStoreModule, } from "./mfa/module.mjs";
+export { MfaStoreError, type MfaStoreFailure, type MfaStoreOperation, } from "./mfa/storeFailure.mjs";
+export { type FederatedIdentityLookupCoverage, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
 export { StoreCredentialRefusedError, StoreTransportError, type StoreTransportFailure, } from "./repositories/storeErrors.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES } from "./storeTransport.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AA8B/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IA0CH,CAAC;AAEF,OAAO,EACN,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,kBAAkB,GAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACN,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,qBAAqB,GAC1B,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IA4CH,CAAC;AAEF,OAAO,EACN,kBAAkB,EAClB,KAAK,yBAAyB,GAC9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACN,KAAK,qCAAqC,EAC1C,8BAA8B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,KAAK,+BAA+B,EACpC,kBAAkB,GAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACN,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,qBAAqB,GAC1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.mjs

@@ -13,31 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
-/** Default request deadline, in milliseconds, when the config names none. */
-const DEFAULT_TIMEOUT_MS = 5000;
-/**
- * Coerces a numeric config value that may arrive as a string.
- *
- * HOCON environment substitution yields strings, so `CLIENT_USER_TIMEOUT=1234`
- * reaches the builder as `"1234"`. An *absent* key takes `fallback`; anything
- * present but unreadable becomes `NaN` and is rejected by the constructor,
- * which owns the range rules and names the field in its message.
- *
- * The distinction matters because HOCON substitutes a **blank** environment
- * variable as `""` — a very ordinary shape in a `.env` file or an empty
- * ConfigMap key — and `Number("")` is `0`. This used to fall back to the
- * default, hiding the misconfiguration; it is now a boot failure (#285).
- */
-const toNumber = (value, fallback) => {
-    if (value === undefined || value === null)
-        return fallback;
-    if (typeof value === "number")
-        return value;
-    if (typeof value === "string")
-        return Number(value.trim());
-    return Number.NaN;
-};
+import { HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+import { readStoreTransportConfig } from "./storeTransport.mjs";
 export const registerBuiltinAdapters = (factories) => {
     factories.userFactory.register("http", (config) => {
         if (typeof config.authenticateUrl !== "string") {
@@ -52,11 +29,11 @@ export const registerBuiltinAdapters = (factories) => {
         return new HttpUserRepository({
             authenticateUrl: config.authenticateUrl,
             authenticateByTokenUrl: config.authenticateByTokenUrl,
-            // #482: optional. Present → the repository can link a federated identity.
+            // Optional. Present → the repository can link a federated identity.
             ...(typeof config.linkFederatedIdentityUrl === "string"
                 ? { linkFederatedIdentityUrl: config.linkFederatedIdentityUrl }
                 : {}),
-            // #613: optional. Forwarded whenever SET, not only when well-typed —
+            // Optional. Forwarded whenever SET, not only when well-typed —
             // the link URL above vanishes when misspelt, and for the lookup a value
             // that vanishes is a deployment that believes itself covered and is
             // not. The constructor refuses what is not a URL, or not a list.
@@ -65,20 +42,26 @@ export const registerBuiltinAdapters = (factories) => {
                     findSubjectByFederatedIdentityUrl: config.findSubjectByFederatedIdentityUrl,
                 }
                 : {}),
+            // Optional, forwarded whenever SET for the same reason: a witness URL
+            // that vanished leaves the MFA enrollment witness unwritten.
+            ...(config.markMfaEnrolledUrl !== undefined
+                ? { markMfaEnrolledUrl: config.markMfaEnrolledUrl }
+                : {}),
             ...(config.federatedIdentityLookupCoverage !== undefined
                 ? {
                     federatedIdentityLookupCoverage: config.federatedIdentityLookupCoverage,
                 }
                 : {}),
-            // Optional, and forwarded whenever SET for the lookup URL's reason: a
-            // token that vanished would be a deployment that believes its Store
-            // calls authenticated and sends them bare. The constructor refuses
-            // what is not a string, and what is blank, malformed or too weak.
-            ...(config.bearerToken !== undefined ? { bearerToken: config.bearerToken } : {}),
-            timeout: toNumber(config.timeout, DEFAULT_TIMEOUT_MS),
-            maxResponseBytes: toNumber(config.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES),
+            // The bearer token, the deadline and the response cap. The constructor
+            // refuses a token that is not a string, or is blank, malformed or too
+            // weak, and a deadline or cap that is not a positive integer.
+            ...readStoreTransportConfig(config),
         });
     });
 };
-export { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+export { HttpMfaFactorStore, } from "./mfa/HttpMfaFactorStore.mjs";
+export { foundationMfaFactorStoreModule, } from "./mfa/module.mjs";
+export { MfaStoreError, } from "./mfa/storeFailure.mjs";
+export { HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
 export { StoreCredentialRefusedError, StoreTransportError, } from "./repositories/storeErrors.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES } from "./storeTransport.mjs";

package/dist/mfa/HttpMfaFactorStore.d.mts

@@ -0,0 +1,55 @@
+/**
+ * `MfaFactorStore` kept by the Store, over its four MFA factor endpoints
+ * (README, "The Store's MFA endpoints"), on the user repository's transport.
+ *
+ * Guarantees: every answer the contract does not give an operation throws —
+ * a list is never answered as fewer records, an update never as written; a
+ * list is read whole or refused (a record the provider cannot read, one of
+ * another subject, an id twice); an update's answer must be the record named,
+ * with the changes sent, at the expected version plus one; what is thrown is
+ * built from an allowlist (`storeFailure.mts`, `storeErrors.mts`) and carries
+ * nothing the Store sent; the sealed `data` it is handed is sent as it is,
+ * and nothing is sent that the wire codec would not read back.
+ *
+ * A record is created or removed only conditionally: every create and every
+ * single-record removal it sends carries `expectedGeneration`, and only the
+ * whole set's reset (`removeAllForSubject`) is sent without one.
+ *
+ * The factor set's members (`listVersioned`, `createIf`, `removeIf`) read
+ * every answer through core's codec alone, once: a status the operation does
+ * not give is `unexpected_status`, read before any body, and whatever the
+ * codec refuses — a `404` or `409` without its outcome body among them — is
+ * `malformed_answer`. A conditional write states its deadline on the wire
+ * (`deadlineMs`, the request timeout from just before it is sent), at or
+ * before the moment the transport gives up, whose timer starts after it: a
+ * write past it is never applied after the adapter stopped waiting. A Store
+ * that reads it as passed answers `408`, which is `unexpected_status`. A conditional write that is sent and then fails,
+ * its deadline included, is unknown: it may have committed.
+ */
+import { type ConditionalCreateAnswer, type ConditionalSetRemoveAnswer, type MfaFactorRecord, type MfaFactorRecordUpdate, type MfaFactorStore, type StoreGeneration, type VersionedSet } from "@o3co/auth-provider-core";
+export interface HttpMfaFactorStoreOptions {
+    /** The Store's four MFA factor endpoints, each https or loopback http. */
+    readonly listUrl: string;
+    readonly createUrl: string;
+    readonly updateUrl: string;
+    readonly deleteUrl: string;
+    /** The user repository's credential: sent as `Authorization: Bearer <token>`. */
+    readonly bearerToken?: string;
+    /** The whole exchange's deadline, in milliseconds. */
+    readonly timeout: number;
+    /** The most bytes of an answer read. Default `DEFAULT_MAX_RESPONSE_BYTES`. */
+    readonly maxResponseBytes?: number;
+}
+export declare class HttpMfaFactorStore implements MfaFactorStore {
+    #private;
+    readonly kind = "store";
+    constructor({ listUrl, createUrl, updateUrl, deleteUrl, bearerToken, timeout, maxResponseBytes, }: HttpMfaFactorStoreOptions);
+    list(subject: string): Promise<readonly MfaFactorRecord[]>;
+    listVersioned(subject: string): Promise<VersionedSet<MfaFactorRecord>>;
+    createIf(record: MfaFactorRecord, expected: StoreGeneration | null): Promise<ConditionalCreateAnswer>;
+    removeIf(subject: string, id: string, expected: StoreGeneration): Promise<ConditionalSetRemoveAnswer>;
+    update(subject: string, id: string, expectedVersion: number, next: MfaFactorRecordUpdate): Promise<MfaFactorRecord | null>;
+    /** The subject's whole set reset: done on a `2xx` or a `404`. */
+    removeAllForSubject(subject: string): Promise<void>;
+}
+//# sourceMappingURL=HttpMfaFactorStore.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HttpMfaFactorStore.d.mts","sourceRoot":"","sources":["../../src/mfa/HttpMfaFactorStore.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAE/B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EAUnB,KAAK,eAAe,EAIpB,KAAK,YAAY,EACjB,MAAM,0BAA0B,CAAC;AA6BlC,MAAM,WAAW,yBAAyB;IACzC,0EAA0E;IAC1E,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;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACnC;AAqBD,qBAAa,kBAAmB,YAAW,cAAc;;IACxD,QAAQ,CAAC,IAAI,WAAW;gBAKZ,EACX,OAAO,EACP,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,OAAO,EACP,gBAA6C,GAC7C,EAAE,yBAAyB;IActB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;IAc1D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IAOtE,QAAQ,CACb,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,eAAe,GAAG,IAAI,GAC9B,OAAO,CAAC,uBAAuB,CAAC;IAU7B,QAAQ,CACb,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,0BAA0B,CAAC;IAUhC,MAAM,CACX,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,eAAe,EAAE,MAAM,EACvB,IAAI,EAAE,qBAAqB,GACzB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAyBlC,iEAAiE;IAC3D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAsDzD"}

package/dist/mfa/HttpMfaFactorStore.mjs

@@ -0,0 +1,183 @@
+/*
+ * 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.
+ */
+/**
+ * `MfaFactorStore` kept by the Store, over its four MFA factor endpoints
+ * (README, "The Store's MFA endpoints"), on the user repository's transport.
+ *
+ * Guarantees: every answer the contract does not give an operation throws —
+ * a list is never answered as fewer records, an update never as written; a
+ * list is read whole or refused (a record the provider cannot read, one of
+ * another subject, an id twice); an update's answer must be the record named,
+ * with the changes sent, at the expected version plus one; what is thrown is
+ * built from an allowlist (`storeFailure.mts`, `storeErrors.mts`) and carries
+ * nothing the Store sent; the sealed `data` it is handed is sent as it is,
+ * and nothing is sent that the wire codec would not read back.
+ *
+ * A record is created or removed only conditionally: every create and every
+ * single-record removal it sends carries `expectedGeneration`, and only the
+ * whole set's reset (`removeAllForSubject`) is sent without one.
+ *
+ * The factor set's members (`listVersioned`, `createIf`, `removeIf`) read
+ * every answer through core's codec alone, once: a status the operation does
+ * not give is `unexpected_status`, read before any body, and whatever the
+ * codec refuses — a `404` or `409` without its outcome body among them — is
+ * `malformed_answer`. A conditional write states its deadline on the wire
+ * (`deadlineMs`, the request timeout from just before it is sent), at or
+ * before the moment the transport gives up, whose timer starts after it: a
+ * write past it is never applied after the adapter stopped waiting. A Store
+ * that reads it as passed answers `408`, which is `unexpected_status`. A conditional write that is sent and then fails,
+ * its deadline included, is unknown: it may have committed.
+ */
+import { fromMfaStoreFactor, readMfaStoreCreateIfAnswer, readMfaStoreFactor, readMfaStoreListAnswer, readMfaStoreRemoveIfAnswer, readMfaStoreVersionedListAnswer, toMfaStoreCreateIfRequest, toMfaStoreRemoveIfRequest, toMfaStoreUpdateRequest, } from "@o3co/auth-provider-core";
+import { assertSecureEndpoint } from "../endpointUrl.mjs";
+import { bearerAuthorization, checkStoreResponseCap, checkStoreTimeout, DEFAULT_MAX_RESPONSE_BYTES, postToStore, } from "../storeTransport.mjs";
+import { mfaStoreMalformedAnswer, mfaStoreRequestMessages, mfaStoreStatusError, mfaStoreUnreadableRecord, mfaStoreVersionSkipped, } from "./storeFailure.mjs";
+/** What this adapter's messages lead with. */
+const OWNER = "HttpMfaFactorStore";
+/** The statuses a conditional create is answered with, each with its outcome body. */
+const CREATE_IF_STATUSES = new Set([200, 409]);
+/** The statuses a conditional removal is answered with, each with its outcome body. */
+const REMOVE_IF_STATUSES = new Set([200, 404, 409]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** What JSON text parses to, or `NOT_JSON`. */
+const NOT_JSON = Symbol("not JSON");
+function parsed(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return NOT_JSON;
+    }
+}
+/** Whether `factor` holds exactly the changes an update sent. */
+const wrote = (factor, changes) => factor.data === changes.data &&
+    factor.label === changes.label &&
+    factor.lastUsedAtMs === changes.lastUsedAtMs;
+export class HttpMfaFactorStore {
+    kind = "store";
+    /** Private fields: `inspect()` and `JSON.stringify` of the store show neither the credential nor the endpoints. */
+    #urls;
+    #settings;
+    constructor({ listUrl, createUrl, updateUrl, deleteUrl, bearerToken, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
+        this.#urls = Object.freeze({
+            list: assertSecureEndpoint(listUrl, "listUrl", OWNER),
+            create: assertSecureEndpoint(createUrl, "createUrl", OWNER),
+            update: assertSecureEndpoint(updateUrl, "updateUrl", OWNER),
+            delete: assertSecureEndpoint(deleteUrl, "deleteUrl", OWNER),
+        });
+        this.#settings = Object.freeze({
+            authorization: bearerAuthorization(bearerToken, OWNER),
+            timeout: checkStoreTimeout(timeout, OWNER),
+            maxResponseBytes: checkStoreResponseCap(maxResponseBytes, OWNER),
+        });
+    }
+    async list(subject) {
+        const url = this.#urls.list;
+        const body = { subject };
+        const { response, text } = await this.#post("list", body, (status) => status === 200);
+        if (text === undefined)
+            throw mfaStoreStatusError("list", url, response);
+        const reading = readMfaStoreListAnswer(parsed(text), subject);
+        if (!reading.ok) {
+            throw reading.reason === "malformed"
+                ? mfaStoreMalformedAnswer("list", url)
+                : mfaStoreUnreadableRecord(url);
+        }
+        return reading.factors.map(fromMfaStoreFactor);
+    }
+    async listVersioned(subject) {
+        const body = { subject };
+        const { response, text } = await this.#post("list", body, (status) => status === 200);
+        if (text === undefined)
+            throw mfaStoreStatusError("list", this.#urls.list, response);
+        return this.#read("list", () => readMfaStoreVersionedListAnswer(parsed(text), subject));
+    }
+    async createIf(record, expected) {
+        const { response, text } = await this.#postConditional("create", (deadlineMs) => toMfaStoreCreateIfRequest(record, expected, deadlineMs), (status) => CREATE_IF_STATUSES.has(status));
+        if (text === undefined)
+            throw mfaStoreStatusError("create", this.#urls.create, response);
+        return this.#read("create", () => readMfaStoreCreateIfAnswer(response.status, parsed(text)));
+    }
+    async removeIf(subject, id, expected) {
+        const { response, text } = await this.#postConditional("delete", (deadlineMs) => toMfaStoreRemoveIfRequest(subject, id, expected, deadlineMs), (status) => REMOVE_IF_STATUSES.has(status));
+        if (text === undefined)
+            throw mfaStoreStatusError("delete", this.#urls.delete, response);
+        return this.#read("delete", () => readMfaStoreRemoveIfAnswer(response.status, parsed(text)));
+    }
+    async update(subject, id, expectedVersion, next) {
+        const url = this.#urls.update;
+        const body = toMfaStoreUpdateRequest(subject, id, expectedVersion, next);
+        const { response, text } = await this.#post("update", body, (status) => status === 200);
+        if (response.status === 409 || response.status === 404)
+            return null;
+        if (text === undefined)
+            throw mfaStoreStatusError("update", url, response);
+        const answer = parsed(text);
+        const factor = isRecord(answer) && Object.hasOwn(answer, "factor")
+            ? readMfaStoreFactor(answer.factor)
+            : undefined;
+        if (factor === undefined ||
+            factor.subject !== subject ||
+            factor.id !== id ||
+            !wrote(factor, body.changes)) {
+            throw mfaStoreMalformedAnswer("update", url);
+        }
+        if (factor.version !== expectedVersion + 1) {
+            throw mfaStoreVersionSkipped(url, { subject, id, expectedVersion });
+        }
+        return fromMfaStoreFactor(factor);
+    }
+    /** The subject's whole set reset: done on a `2xx` or a `404`. */
+    async removeAllForSubject(subject) {
+        const body = { subject, all: true };
+        const { response } = await this.#post("delete", body, () => false);
+        if (response.ok || response.status === 404)
+            return;
+        throw mfaStoreStatusError("delete", this.#urls.delete, response);
+    }
+    /**
+     * A conditional write to `operation`'s endpoint, its body built by
+     * `build` with its `deadlineMs`: the request timeout from now, taken just
+     * before the request is sent. Nothing yields between this and the
+     * transport's timer, which starts after it, so the deadline is at or
+     * before the moment the adapter gives up.
+     */
+    #postConditional(operation, build, readsBody) {
+        const deadlineMs = Date.now() + this.#settings.timeout;
+        return this.#post(operation, build(deadlineMs), readsBody);
+    }
+    /**
+     * What `read`, a reader of core's codec, makes of an answer of
+     * `operation`; the `TypeError` it throws for an answer outside the
+     * contract is `malformed_answer`, carrying none of the reader's words.
+     */
+    #read(operation, read) {
+        try {
+            return read();
+        }
+        catch (error) {
+            if (error instanceof TypeError) {
+                throw mfaStoreMalformedAnswer(operation, this.#urls[operation]);
+            }
+            throw error;
+        }
+    }
+    /** `body` to `operation`'s endpoint, its answer read when `readsBody` says so. */
+    #post(operation, body, readsBody) {
+        const url = this.#urls[operation];
+        return postToStore(url, body, this.#settings, mfaStoreRequestMessages(OWNER, operation, url), readsBody);
+    }
+}

package/dist/mfa/markEnrolled.d.mts

@@ -0,0 +1,4 @@
+import { type StoreRequestSettings } from "../storeTransport.mjs";
+/** Posts `{ subject, enrolled }` to `url`; resolves on a `204` and throws on anything else. */
+export declare function markMfaEnrolledAtStore(url: string, settings: StoreRequestSettings, owner: string, subject: string, enrolled: boolean): Promise<void>;
+//# sourceMappingURL=markEnrolled.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markEnrolled.d.mts","sourceRoot":"","sources":["../../src/mfa/markEnrolled.mts"],"names":[],"mappings":"AA8BA,OAAO,EAAe,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG/E,+FAA+F;AAC/F,wBAAsB,sBAAsB,CAC3C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/mfa/markEnrolled.mjs

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+import { postToStore } from "../storeTransport.mjs";
+import { mfaStoreRequestMessages, mfaStoreStatusError } from "./storeFailure.mjs";
+/** Posts `{ subject, enrolled }` to `url`; resolves on a `204` and throws on anything else. */
+export async function markMfaEnrolledAtStore(url, settings, owner, subject, enrolled) {
+    if (typeof subject !== "string" || subject.length === 0) {
+        throw new RangeError(`${owner}: markMfaEnrolled takes a non-empty subject`);
+    }
+    if (typeof enrolled !== "boolean") {
+        throw new RangeError(`${owner}: markMfaEnrolled takes enrolled as a boolean`);
+    }
+    const body = { subject, enrolled };
+    const { response } = await postToStore(url, body, settings, mfaStoreRequestMessages(owner, "markMfaEnrolled", url), () => false);
+    if (response.status === 204)
+        return;
+    throw mfaStoreStatusError("markMfaEnrolled", url, response);
+}