lambder 14.1.1 → 15.0.2

package/dist/mock/lambderMockMswHandler.d.ts

@@ -1,6 +1,7 @@
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
-import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+import type { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+import { LAMBDER_MOCK_ADAPTER_DOOR, type LambderMockAdapterDoor } from "./LambderMockAdapterDoor.js";
 /** What a resolver of Lambder's adapters is: msw's, answering a Response, or `undefined` to hand the request on. */
 type LambderMswResolver = (info: {
     request: Request;
@@ -26,21 +27,23 @@ export type LambderMswModule = {
         error(): Response;
     };
 };
-/** What the adapter needs from the mock app: a parsed request in, an answer out, and the runtime's own bookkeeping. */
+/**
+ * What the adapter needs from the mock app: a parsed request in, an answer
+ * out, and the runtime's own bookkeeping behind the adapter door, which a
+ * LambderMockApp carries and nothing outside the package can name (see
+ * LAMBDER_MOCK_ADAPTER_DOOR). So in practice the target is a LambderMockApp.
+ */
 export type LambderMockMswTarget = {
     handleRequest(request: LambderApiRequest): Promise<LambderApiAnswer>;
+    /** Whether a name has an entry, a call handed on to the network, and an answer's readable cookies for the page. */
+    readonly [LAMBDER_MOCK_ADAPTER_DOOR]: LambderMockAdapterDoor;
     /**
-     * Whether this name would be answered from the registry, overrides and a
-     * registered rest entry included; asked once per request, so not a list to
-     * scan.
+     * The page's cookie jar, which this adapter carries its calls' cookies in
+     * unless it is given its own: the jar signIn and signOut use when given
+     * none, so a session signIn starts is the one these calls send, and the
+     * one reset() empties.
      */
-    hasRegisteredEntry(apiName: string): boolean;
-    /** Records a request this adapter handed on rather than answering. */
-    notePassthrough(request: LambderApiRequest): void;
-    /** Mirrors an answer's readable cookies into document.cookie, and remembers them for reset(). */
-    mirrorCookiesIntoDocument(setCookies: readonly string[]): void;
-    /** Takes the jar this adapter built as the runtime's own, so reset() empties it too. */
-    adoptCookieJar(jar: LambderCookieJar): void;
+    readonly pageCookieJar: LambderCookieJar;
     /** The IP a call carrying none is read as arriving from, so this adapter and the direct transport report one address. */
     readonly defaultClientIp: string;
     /**
@@ -66,7 +69,9 @@ export type LambderMockMswTarget = {
  * them, losing every cookie after the first. So the answer's cookies go into
  * the jar, the next request carries them back, and the ones a page's scripts
  * may see are mirrored into document.cookie. The Set-Cookie headers still
- * travel on the response, where the network panel shows them.
+ * travel on the response, where the network panel shows them. The jar is the
+ * runtime's page jar unless one is given, the one signIn plants into when it
+ * is given none, so `mockApp.signIn(key, data)` signs the page in.
  *
  * A request's cookies are therefore the jar's and document.cookie's, never
  * its Cookie header: MSW fills that from its own store, which captures the
@@ -86,6 +91,7 @@ export type LambderMockMswTarget = {
 export declare const lambderMockMswHandler: <M extends LambderMswModule>(mockApp: LambderMockMswTarget, options: {
     msw: M;
     apiPath: string;
+    /** The jar this adapter's calls carry their cookies in. Default: the runtime's pageCookieJar. One passed here stays the app's, and reset() leaves it alone. */
     cookieJar?: LambderCookieJar;
     /**
      * What happens to a call the runtime has no entry for. "refuse"

package/dist/mock/lambderMockMswHandler.js

@@ -1,9 +1,9 @@
 import { LambderMockTransportError } from "./LambderMockFailureInjector.js";
 import { apiNameOfCallPath } from "../shared/wire/LambderApiNames.js";
-import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { readApiEnvelopeText, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
-import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
+import { LAMBDER_MOCK_ADAPTER_DOOR } from "./LambderMockAdapterDoor.js";
 /**
  * ONE MSW request handler for the whole API path, over the mock app: the
  * opt-in that makes mocked calls appear in the browser's network panel as
@@ -17,7 +17,9 @@ import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
  * them, losing every cookie after the first. So the answer's cookies go into
  * the jar, the next request carries them back, and the ones a page's scripts
  * may see are mirrored into document.cookie. The Set-Cookie headers still
- * travel on the response, where the network panel shows them.
+ * travel on the response, where the network panel shows them. The jar is the
+ * runtime's page jar unless one is given, the one signIn plants into when it
+ * is given none, so `mockApp.signIn(key, data)` signs the page in.
  *
  * A request's cookies are therefore the jar's and document.cookie's, never
  * its Cookie header: MSW fills that from its own store, which captures the
@@ -39,12 +41,17 @@ export const lambderMockMswHandler = (mockApp, options) => {
     if (!msw?.http || !msw?.HttpResponse) {
         throw new Error('lambderMockMswHandler requires the msw module: lambderMockMswHandler(mockApp, { apiPath, msw: await import("msw") }). Install it with: npm install msw --save-dev');
     }
-    const jar = options.cookieJar ?? new LambderCookieJar();
-    // A jar the app passed stays the app's; the one built here is the
-    // runtime's, so its reset() empties it along with the sessions those
-    // cookies name.
-    if (!options.cookieJar)
-        mockApp.adoptCookieJar(jar);
+    // The runtime's bookkeeping is reached through the door a LambderMockApp
+    // carries; anything else would fail on its first call rather than here.
+    const door = mockApp?.[LAMBDER_MOCK_ADAPTER_DOOR];
+    if (typeof door?.hasRegisteredEntry !== "function") {
+        throw new Error("lambderMockMswHandler serves a LambderMockApp: pass the app initLambderMock().create() built, as lambderMockMswHandler(mockApp, { apiPath, msw }).");
+    }
+    // The page's jar unless the app passes its own: a jar of this adapter's
+    // alone would hold the session of the calls it serves and never the one
+    // signIn planted, and every session call behind the worker after a
+    // signIn would answer sessionExpired.
+    const jar = options.cookieJar ?? mockApp.pageCookieJar;
     // The runtime's default, not one of this adapter's own, so the direct
     // transport and the service worker agree on ctx.request.ip and a per-IP
     // rate limit counts one client as one. Normalized the way every other
@@ -54,13 +61,6 @@ export const lambderMockMswHandler = (mockApp, options) => {
     // Every call goes to `{apiPath}/{group}/{action}`; the endpoint is read
     // off the path as the server reads it (apiNameOfCallPath).
     const handler = msw.http.post(`${apiPath.replace(/\/+$/, "")}/:group/:action`, async ({ request }) => {
-        let post;
-        try {
-            post = await request.clone().json();
-        }
-        catch {
-            return undefined;
-        }
         // Through the one header map every adapter builds, on
         // Object.create(null): on a plain object, a header literally named
         // __proto__ would be dropped here though the server keeps it as an own
@@ -68,8 +68,8 @@ export const lambderMockMswHandler = (mockApp, options) => {
         // function where every other adapter gives undefined.
         const headers = lowercaseHeaderNames(Object.fromEntries(request.headers));
         // A POST of another type is no API call on the server either: it
-        // goes on to MSW's other handlers and the network, as a non-envelope
-        // body does below, rather than working here and not in production.
+        // goes on to MSW's other handlers and the network, rather than
+        // working here and not in production.
         if (!isApiCallContentType(headers))
             return undefined;
         // The cookies travel as `cookies` below, as the direct transport's do.
@@ -97,15 +97,18 @@ export const lambderMockMswHandler = (mockApp, options) => {
         const apiName = apiNameOfCallPath(new URL(apiPath, url).pathname, url.pathname);
         if (apiName === null)
             return undefined;
-        const parsed = readApiEnvelope(post, {
+        // Read from the text, as the server reads it: a body that is not a
+        // JSON object, or not JSON, is a call the pipeline refuses as the
+        // server does, not one handed on to the network.
+        const parsed = readApiEnvelopeText(await request.clone().text(), {
             headers, cookies, ip: clientIp, host: url.host, signal: request.signal,
         }, apiName);
         // Returning undefined hands the request back to MSW, which tries its
         // other handlers and then the network. Noted on the runtime first:
         // a passthrough that leaves no event and no call-log row is a
         // mistyped endpoint name reaching the real backend in silence.
-        if (options.onUnmocked === "passthrough" && !mockApp.hasRegisteredEntry(parsed.apiName)) {
-            mockApp.notePassthrough(parsed);
+        if (options.onUnmocked === "passthrough" && !door.hasRegisteredEntry(parsed.apiName)) {
+            door.notePassthrough(parsed);
             return undefined;
         }
         let answer;
@@ -126,7 +129,7 @@ export const lambderMockMswHandler = (mockApp, options) => {
         // this every session call fails its CSRF check. Done by the runtime,
         // which owns the one mirror implementation and remembers what was
         // planted for reset().
-        mockApp.mirrorCookiesIntoDocument(setCookies);
+        door.mirrorCookiesIntoDocument(setCookies);
         const responseHeaders = new Headers();
         for (const [key, values] of Object.entries(answer.headers)) {
             for (const value of values)

package/dist/mock.d.ts

@@ -13,6 +13,7 @@ export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMock
 export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
+export type { LambderApiSchemaEntries, LambderApiSchemaEntry, LambderJsonSchema } from "./shared/wire/LambderApiSchemaEntries.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export type { LambderMockConsoleLoggerOptions } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";

package/dist/secrets/LambderOneShotSecrets.d.ts

@@ -140,7 +140,7 @@ export declare class LambderOneShotSecrets<TKinds extends Record<string, Lambder
      * less than that ago is refused instead, with the second it may ask
      * again; of two callers racing past the cooldown, exactly one is issued.
      * `meta` is what the app wants back at redemption: an identity, an
-     * issuing organization, as small strings.
+     * issuing store, as small strings.
      *
      * A secret whose digest another scope holds is drawn again, up to
      * MAX_DRAWS times; past that the kind's alphabet and length leave too few

package/dist/secrets/LambderOneShotSecrets.js

@@ -1,4 +1,4 @@
-import { keyedDigest, randomSecret } from "../shared/util/LambderSignedClaims.js";
+import { assertCodeAlphabet, keyedDigest, randomCode, randomSecret } from "../shared/util/LambderSignedClaims.js";
 import { constantTimeEquals } from "../shared/util/LambderTextDigest.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { joinKeyFields } from "../shared/util/joinKeyFields.js";
@@ -54,12 +54,12 @@ export class LambderOneShotSecrets {
             if (kind.shape === "code") {
                 assertPositiveInteger(kind.length, `kinds.${name}.length`);
                 assertPositiveInteger(kind.maxAttempts, `kinds.${name}.maxAttempts`);
-                assertAlphabet(kind.alphabet ?? DIGITS, name);
+                assertCodeAlphabet(kind.alphabet ?? DIGITS, `kinds.${name}.alphabet`);
             }
             else if (kind.shape === "token") {
                 if (kind.alphabet !== undefined || kind.length !== undefined) {
                     assertPositiveInteger(kind.length, `kinds.${name}.length`);
-                    assertAlphabet(kind.alphabet ?? "", name);
+                    assertCodeAlphabet(kind.alphabet, `kinds.${name}.alphabet`);
                 }
                 else {
                     assertPositiveInteger(kind.bytes ?? 32, `kinds.${name}.bytes`);
@@ -100,7 +100,7 @@ export class LambderOneShotSecrets {
      * less than that ago is refused instead, with the second it may ask
      * again; of two callers racing past the cooldown, exactly one is issued.
      * `meta` is what the app wants back at redemption: an identity, an
-     * issuing organization, as small strings.
+     * issuing store, as small strings.
      *
      * A secret whose digest another scope holds is drawn again, up to
      * MAX_DRAWS times; past that the kind's alphabet and length leave too few
@@ -111,8 +111,8 @@ export class LambderOneShotSecrets {
         const cooldown = options.cooldownSeconds === undefined ? undefined : assertPositiveInteger(options.cooldownSeconds, "cooldownSeconds");
         const nowSeconds = this.nowSeconds();
         for (let draw = 0; draw < MAX_DRAWS; draw += 1) {
-            const plaintext = definition.shape === "code" ? drawCode(definition.alphabet ?? DIGITS, definition.length)
-                : definition.alphabet !== undefined ? drawCode(definition.alphabet, definition.length)
+            const plaintext = definition.shape === "code" ? randomCode(definition.alphabet ?? DIGITS, definition.length)
+                : definition.alphabet !== undefined ? randomCode(definition.alphabet, definition.length)
                     : randomSecret(definition.bytes ?? 32);
             const draft = {
                 kind,
@@ -185,33 +185,3 @@ export class LambderOneShotSecrets {
         return { state: "accepted", scope: record.scope, meta: { ...record.meta }, issuedAt: record.issuedAt };
     }
 }
-const assertAlphabet = (alphabet, name) => {
-    if (alphabet.length < 2 || alphabet.length > 256 || new Set(alphabet).size !== alphabet.length) {
-        throw new Error(`Lambder: kinds.${name}.alphabet must be 2 to 256 distinct characters.`);
-    }
-};
-/**
- * A code of `length` characters drawn uniformly from `alphabet`. Bytes at or
- * above the largest multiple of the alphabet's size are discarded, so the
- * modulo cannot favour the alphabet's first characters.
- */
-const drawCode = (alphabet, length) => {
-    const webCrypto = globalThis.crypto;
-    if (typeof webCrypto?.getRandomValues !== "function") {
-        throw new Error("Lambder needs crypto.getRandomValues in this runtime to draw a code. Every browser provides it; Node 20+ provides it as globalThis.crypto.");
-    }
-    const ceiling = Math.floor(256 / alphabet.length) * alphabet.length;
-    const characters = [];
-    const buffer = new Uint8Array(length * 2);
-    while (characters.length < length) {
-        webCrypto.getRandomValues(buffer);
-        for (const byte of buffer) {
-            if (byte >= ceiling)
-                continue;
-            characters.push(alphabet[byte % alphabet.length]);
-            if (characters.length === length)
-                break;
-        }
-    }
-    return characters.join("");
-};

package/dist/secrets/LambderPasswordHasher.d.ts

@@ -0,0 +1,56 @@
+/** The cost of a hash this instance writes. Every field is optional; the defaults are argon2id's widely used 64 MiB, 3 passes, 4 lanes. */
+export type LambderPasswordHasherOptions = {
+    /** Memory per hash, in KiB. At least 8 per lane. Default: 65536 (64 MiB). */
+    memoryKib?: number;
+    /** Passes over that memory. Default: 3. */
+    passes?: number;
+    /** Lanes computed in parallel. Default: 4. */
+    parallelism?: number;
+};
+/**
+ * Hashes passwords with argon2id and verifies them against stored PHC
+ * strings, its own and those other argon2 libraries wrote (argon2id, argon2i
+ * or argon2d, any parameter order).
+ *
+ * ```ts
+ * const passwords = new LambderPasswordHasher();
+ * const stored = await passwords.hash(newPassword);           // store this
+ * if(await passwords.verify(row?.passwordHash, attempt)){     // a missing row too, so it takes as long
+ *     if(passwords.needsRehash(row!.passwordHash)) await savePasswordHash(await passwords.hash(attempt));
+ * }
+ * ```
+ *
+ * The password is hashed as its UTF-8 bytes, as given: an app that wants one
+ * password typed on two keyboards to match normalizes it (`normalize("NFC")`)
+ * before both calls, the same way every time.
+ */
+export declare class LambderPasswordHasher {
+    #private;
+    /**
+     * Throws where the runtime has no argon2 (Node before 24.7, or a browser),
+     * here rather than on the first sign-in: a hasher that cannot hash would
+     * otherwise read as a wrong password for every account.
+     */
+    constructor(options?: LambderPasswordHasherOptions);
+    /** The PHC string of `password` under this instance's cost and a fresh random salt: the value to store. */
+    hash(password: string): Promise<string>;
+    /**
+     * Whether `password` is the one `stored` was made from, under the variant
+     * and cost `stored` names. False, never a throw, for anything that is not
+     * an argon2 PHC string within the cost ceilings: an account with no
+     * password stores null, and a value of another scheme or a corrupt one
+     * matches no password. Without a usable hash it still computes one under
+     * this instance's cost, so an account that does not exist (pass
+     * `undefined`) answers in the time a wrong password does, and the time
+     * says nothing about which accounts exist.
+     */
+    verify(stored: string | null | undefined, password: string): Promise<boolean>;
+    /**
+     * Whether `stored` was written under something other than what this
+     * instance writes: another variant, another cost, a shorter salt or tag,
+     * or no argon2 hash at all. Asked after a successful verify, when the
+     * plaintext is at hand to hash again; that is how a raised cost reaches
+     * the passwords stored before it.
+     */
+    needsRehash(stored: string): boolean;
+}

package/dist/secrets/LambderPasswordHasher.js

@@ -0,0 +1,168 @@
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+/** The only argon2 encoding version: 0x13. A string naming another is not an argon2 hash anything writes today. */
+const ARGON2_VERSION = 19;
+const SALT_BYTES = 16;
+const TAG_BYTES = 32;
+/**
+ * The most a cost may ask: 2 GiB of memory (RFC 9106's largest recommended
+ * setting), 4 GiB of memory over all passes (libsodium's strongest preset,
+ * 1 GiB over 4), and the PHC format's 255 lanes. A verify runs under the cost
+ * the stored string names, before anyone is signed in, so a string naming
+ * hours of passes or more memory than the function has (an imported hash, a
+ * corrupt row) would stall every sign-in attempt on its account. A string
+ * over them matches no password, and a hasher is not built with a cost over
+ * them, so it never writes one.
+ */
+const MAX_MEMORY_KIB = 2 * 1024 * 1024;
+const MAX_MEMORY_OVER_PASSES_KIB = 4 * 1024 * 1024;
+const MAX_PARALLELISM = 255;
+/** The salt of the hash a verify computes when there is no stored hash to check; its result is thrown away. */
+const NO_HASH_SALT = Buffer.alloc(SALT_BYTES);
+/**
+ * The PHC string. The parameter section is read as an unordered set: the PHC
+ * format fixes no order, and implementations differ (the `argon2` npm package
+ * writes `m,t,p`, others `m,p,t`).
+ */
+const PHC_PATTERN = /^\$(argon2id|argon2i|argon2d)\$v=(\d+)\$([a-z]+=\d+(?:,[a-z]+=\d+)*)\$([A-Za-z0-9+/]+)\$([A-Za-z0-9+/]+)$/;
+const toPhcBase64 = (bytes) => bytes.toString("base64").replace(/=+$/, "");
+/** What is wrong with a cost of positive integers, or null for one inside argon2's floor and the ceilings above. */
+const costProblemOf = ({ memoryKib, passes, parallelism }) => memoryKib < 8 * parallelism ? `memoryKib must be at least 8 per lane (${8 * parallelism} for parallelism ${parallelism}), got ${memoryKib}`
+    : parallelism > MAX_PARALLELISM ? `parallelism must be at most ${MAX_PARALLELISM}, got ${parallelism}`
+        : memoryKib > MAX_MEMORY_KIB ? `memoryKib must be at most ${MAX_MEMORY_KIB} (2 GiB), got ${memoryKib}`
+            : memoryKib * passes > MAX_MEMORY_OVER_PASSES_KIB ? `memoryKib times passes must be at most ${MAX_MEMORY_OVER_PASSES_KIB} (4 GiB over all passes), got ${memoryKib * passes}`
+                : null;
+const parseCost = (section) => {
+    const values = new Map();
+    for (const pair of section.split(",")) {
+        const [key, value] = pair.split("=");
+        if (!key || !value || values.has(key))
+            return null;
+        values.set(key, Number(value));
+    }
+    const memoryKib = values.get("m"), passes = values.get("t"), parallelism = values.get("p");
+    if (memoryKib === undefined || passes === undefined || parallelism === undefined || values.size !== 3)
+        return null;
+    if (![memoryKib, passes, parallelism].every((value) => Number.isSafeInteger(value) && value >= 1))
+        return null;
+    const cost = { memoryKib, passes, parallelism };
+    return costProblemOf(cost) === null ? cost : null;
+};
+const parsePasswordHash = (stored) => {
+    const match = PHC_PATTERN.exec(stored);
+    if (!match)
+        return null;
+    const [, variant, version, costSection, saltBase64, tagBase64] = match;
+    if (Number(version) !== ARGON2_VERSION)
+        return null;
+    const cost = parseCost(costSection);
+    if (!cost)
+        return null;
+    const salt = Buffer.from(saltBase64, "base64");
+    const tag = Buffer.from(tagBase64, "base64");
+    // argon2's own floors: an 8-byte salt and a 4-byte tag.
+    if (salt.length < 8 || tag.length < 4)
+        return null;
+    return { variant: variant, ...cost, salt, tag };
+};
+/**
+ * Hashes passwords with argon2id and verifies them against stored PHC
+ * strings, its own and those other argon2 libraries wrote (argon2id, argon2i
+ * or argon2d, any parameter order).
+ *
+ * ```ts
+ * const passwords = new LambderPasswordHasher();
+ * const stored = await passwords.hash(newPassword);           // store this
+ * if(await passwords.verify(row?.passwordHash, attempt)){     // a missing row too, so it takes as long
+ *     if(passwords.needsRehash(row!.passwordHash)) await savePasswordHash(await passwords.hash(attempt));
+ * }
+ * ```
+ *
+ * The password is hashed as its UTF-8 bytes, as given: an app that wants one
+ * password typed on two keyboards to match normalizes it (`normalize("NFC")`)
+ * before both calls, the same way every time.
+ */
+export class LambderPasswordHasher {
+    #crypto;
+    #cost;
+    /**
+     * Throws where the runtime has no argon2 (Node before 24.7, or a browser),
+     * here rather than on the first sign-in: a hasher that cannot hash would
+     * otherwise read as a wrong password for every account.
+     */
+    constructor(options = {}) {
+        const nodeCrypto = typeof process === "object" && typeof process.getBuiltinModule === "function"
+            ? process.getBuiltinModule("node:crypto")
+            : undefined;
+        if (typeof nodeCrypto?.argon2 !== "function") {
+            throw new Error("Lambder: LambderPasswordHasher needs argon2 from node:crypto, which Node 24.7 and later provide; this runtime has none.");
+        }
+        this.#crypto = nodeCrypto;
+        const memoryKib = assertPositiveInteger(options.memoryKib ?? 65536, "memoryKib");
+        const passes = assertPositiveInteger(options.passes ?? 3, "passes");
+        const parallelism = assertPositiveInteger(options.parallelism ?? 4, "parallelism");
+        const problem = costProblemOf({ memoryKib, passes, parallelism });
+        if (problem)
+            throw new Error(`Lambder: LambderPasswordHasher ${problem}.`);
+        this.#cost = { memoryKib, passes, parallelism };
+    }
+    /** The PHC string of `password` under this instance's cost and a fresh random salt: the value to store. */
+    async hash(password) {
+        if (typeof password !== "string")
+            throw new TypeError("Lambder: LambderPasswordHasher.hash takes the password as a string.");
+        const { memoryKib, passes, parallelism } = this.#cost;
+        const salt = this.#crypto.randomBytes(SALT_BYTES);
+        const tag = await this.#derive("argon2id", password, salt, this.#cost, TAG_BYTES);
+        return `$argon2id$v=${ARGON2_VERSION}$m=${memoryKib},t=${passes},p=${parallelism}$${toPhcBase64(salt)}$${toPhcBase64(tag)}`;
+    }
+    /**
+     * Whether `password` is the one `stored` was made from, under the variant
+     * and cost `stored` names. False, never a throw, for anything that is not
+     * an argon2 PHC string within the cost ceilings: an account with no
+     * password stores null, and a value of another scheme or a corrupt one
+     * matches no password. Without a usable hash it still computes one under
+     * this instance's cost, so an account that does not exist (pass
+     * `undefined`) answers in the time a wrong password does, and the time
+     * says nothing about which accounts exist.
+     */
+    async verify(stored, password) {
+        if (typeof password !== "string")
+            return false;
+        const parsed = typeof stored === "string" ? parsePasswordHash(stored) : null;
+        if (!parsed) {
+            await this.#derive("argon2id", password, NO_HASH_SALT, this.#cost, TAG_BYTES);
+            return false;
+        }
+        const actual = await this.#derive(parsed.variant, password, parsed.salt, parsed, parsed.tag.length);
+        return actual.length === parsed.tag.length && this.#crypto.timingSafeEqual(actual, parsed.tag);
+    }
+    /**
+     * Whether `stored` was written under something other than what this
+     * instance writes: another variant, another cost, a shorter salt or tag,
+     * or no argon2 hash at all. Asked after a successful verify, when the
+     * plaintext is at hand to hash again; that is how a raised cost reaches
+     * the passwords stored before it.
+     */
+    needsRehash(stored) {
+        const parsed = typeof stored === "string" ? parsePasswordHash(stored) : null;
+        if (!parsed)
+            return true;
+        return parsed.variant !== "argon2id"
+            || parsed.memoryKib !== this.#cost.memoryKib
+            || parsed.passes !== this.#cost.passes
+            || parsed.parallelism !== this.#cost.parallelism
+            || parsed.salt.length < SALT_BYTES
+            || parsed.tag.length !== TAG_BYTES;
+    }
+    #derive(variant, password, salt, cost, tagBytes) {
+        return new Promise((resolve, reject) => {
+            this.#crypto.argon2(variant, {
+                message: Buffer.from(password, "utf8"),
+                nonce: salt,
+                memory: cost.memoryKib,
+                passes: cost.passes,
+                parallelism: cost.parallelism,
+                tagLength: tagBytes,
+            }, (error, derived) => error ? reject(error) : resolve(Buffer.from(derived)));
+        });
+    }
+}

package/dist/session/LambderSessionController.d.ts

@@ -194,7 +194,22 @@ export default class LambderSessionController<TSessionData = any> {
      * invoke caller) needs the new one to keep calling.
      */
     reissueSession(): Promise<LambderCreatedSession<TSessionData>>;
-    fetchSession(): Promise<LambderSessionRecord<TSessionData>>;
+    /**
+     * The session the request's cookies name, checked against the posted
+     * CSRF token and renewed (its dataRefresh once due, its sliding write),
+     * onto ctx.session. Throws LambderSessionNotFoundError when there is
+     * none.
+     *
+     * `refreshData: true` renews the data on this read whatever its
+     * deadline, for a read that wants it fresh (a page load): the dataRefresh
+     * callback runs once and its result shares the read's one write. A read
+     * followed by refreshSessionData() runs both twice whenever the data was
+     * due. Requires dataRefresh, and throws without it once there is a
+     * session to renew.
+     */
+    fetchSession(options?: {
+        refreshData?: boolean;
+    }): Promise<LambderSessionRecord<TSessionData>>;
     /**
      * Re-issues both cookies at this session's expiry: after a sliding write
      * moved it, and beside the host-only eviction, which would otherwise
@@ -222,7 +237,10 @@ export default class LambderSessionController<TSessionData = any> {
      * sent. A dead cookie costs a store read per request until it expires.
      */
     private endWithNoSession;
-    fetchSessionIfExists(): Promise<LambderSessionRecord<TSessionData> | null>;
+    /** fetchSession, answering null where it throws LambderSessionNotFoundError; it takes the same `refreshData`. */
+    fetchSessionIfExists(options?: {
+        refreshData?: boolean;
+    }): Promise<LambderSessionRecord<TSessionData> | null>;
     /**
      * Writes new data onto the current session. Throws
      * LambderSessionNotFoundError when the session was ended while this
@@ -244,8 +262,14 @@ export default class LambderSessionController<TSessionData = any> {
      * Deletes every session of the given sessionKey (e.g. a user id): "log
      * this subject out everywhere". Unlike endSessionAll it needs no fetched
      * session and touches no cookies, so it works on any subject.
+     *
+     * Answers whether it is sure none is left. False means a client
+     * rotating its session in a tight loop raced every pass of the delete,
+     * so a session of the subject may still stand (it is logged too); running
+     * it again is the remedy, and a caller ending sessions because a
+     * credential changed must not report success on false.
      */
-    deleteSessionAllByKey(sessionKey: string): Promise<void>;
+    deleteSessionAllByKey(sessionKey: string): Promise<boolean>;
     /**
      * Marks the data of every session of the given sessionKey stale, so each
      * renews via dataRefresh on its next read: the way to apply a change to
@@ -254,5 +278,14 @@ export default class LambderSessionController<TSessionData = any> {
      */
     expireSessionDataAllByKey(sessionKey: string): Promise<void>;
     endSession(): Promise<void>;
-    endSessionAll(): Promise<void>;
+    /**
+     * Ends every session of this session's subject, this one included, and
+     * clears this request's cookies: "log out everywhere".
+     *
+     * Answers false on deleteSessionAllByKey's terms: a session of the
+     * subject may still stand, and running the delete again is the remedy.
+     * This request's own session is over either way, so the second run is
+     * deleteSessionAllByKey with the sessionKey read before this call.
+     */
+    endSessionAll(): Promise<boolean>;
 }

package/dist/session/LambderSessionController.js

@@ -286,7 +286,20 @@ export default class LambderSessionController {
         return created;
     }
     ;
-    async fetchSession() {
+    /**
+     * The session the request's cookies name, checked against the posted
+     * CSRF token and renewed (its dataRefresh once due, its sliding write),
+     * onto ctx.session. Throws LambderSessionNotFoundError when there is
+     * none.
+     *
+     * `refreshData: true` renews the data on this read whatever its
+     * deadline, for a read that wants it fresh (a page load): the dataRefresh
+     * callback runs once and its result shares the read's one write. A read
+     * followed by refreshSessionData() runs both twice whenever the data was
+     * due. Requires dataRefresh, and throws without it once there is a
+     * session to renew.
+     */
+    async fetchSession(options = {}) {
         const { sessionTokens: candidates, csrfTokens } = this.scanSessionCookies();
         if (!this.areRequestSessionTokensValid(candidates)) {
             throw new LambderSessionNotFoundError("Session tokens are invalid");
@@ -361,7 +374,7 @@ export default class LambderSessionController {
         // Renewed only once this session is known to be the caller's: a
         // slide or a dataRefresh is a write on their behalf.
         const expiresBefore = found.session.expiresAt;
-        const session = await this.manager.renewSession(found.session);
+        const session = await this.manager.renewSession(found.session, { refreshData: options.refreshData });
         // Ended while this request read it (a logout, a password change), or
         // by its own dataRefresh: no session either way.
         if (!session)
@@ -431,9 +444,10 @@ export default class LambderSessionController {
         throw new LambderSessionNotFoundError();
     }
     ;
-    async fetchSessionIfExists() {
+    /** fetchSession, answering null where it throws LambderSessionNotFoundError; it takes the same `refreshData`. */
+    async fetchSessionIfExists(options = {}) {
         try {
-            return await this.fetchSession();
+            return await this.fetchSession(options);
         }
         catch (err) {
             // Only a "no session" exit becomes null, the ambiguous one
@@ -486,9 +500,15 @@ export default class LambderSessionController {
      * Deletes every session of the given sessionKey (e.g. a user id): "log
      * this subject out everywhere". Unlike endSessionAll it needs no fetched
      * session and touches no cookies, so it works on any subject.
+     *
+     * Answers whether it is sure none is left. False means a client
+     * rotating its session in a tight loop raced every pass of the delete,
+     * so a session of the subject may still stand (it is logged too); running
+     * it again is the remedy, and a caller ending sessions because a
+     * credential changed must not report success on false.
      */
     async deleteSessionAllByKey(sessionKey) {
-        await this.manager.deleteSessionAllByKey(sessionKey);
+        return await this.manager.deleteSessionAllByKey(sessionKey);
     }
     ;
     /**
@@ -509,12 +529,22 @@ export default class LambderSessionController {
         this.ctx.session = null;
     }
     ;
+    /**
+     * Ends every session of this session's subject, this one included, and
+     * clears this request's cookies: "log out everywhere".
+     *
+     * Answers false on deleteSessionAllByKey's terms: a session of the
+     * subject may still stand, and running the delete again is the remedy.
+     * This request's own session is over either way, so the second run is
+     * deleteSessionAllByKey with the sessionKey read before this call.
+     */
     async endSessionAll() {
         if (!this.ctx.session)
             throw new LambderSessionNotFoundError();
-        await this.manager.deleteSessionAll(this.ctx.session);
+        const deletedAll = await this.manager.deleteSessionAll(this.ctx.session);
         this.clearSessionCookies();
         this.ctx.session = null;
+        return deletedAll;
     }
     ;
 }