lambder 7.3.1 → 8.1.1

package/dist/mock/lambderMockMswHandler.js

@@ -1,5 +1,5 @@
 import { LambderMockTransportError } from "./LambderMockFailureInjector.js";
-import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { readApiEnvelope, 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";
@@ -7,25 +7,31 @@ import { normalizeClientIp } from "../shared/util/LambderClientIp.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
  * genuine requests, with real method, status, timing and bodies. The request
- * is read the way the server reads it, its headers and Cookie header
- * included.
+ * is read the way the server reads it, headers included, with the cookies a
+ * browser would send.
  *
- * Session cookies are held in a jar here rather than by the browser, because
- * the browser will not hold them: a response a service worker synthesizes
- * never reaches the cookie store, and MSW's own jar comma-joins the
- * Set-Cookie headers before parsing them, which loses 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.
+ * Session cookies are held in a jar here, because the browser will not hold
+ * them: a response a service worker synthesizes never reaches the cookie
+ * store, and MSW's own jar comma-joins the Set-Cookie headers before parsing
+ * 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.
+ *
+ * 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
+ * HttpOnly session cookie off those Set-Cookie headers and keeps it in
+ * localStorage across reloads. Reading it would send a second session after
+ * a user switch (every call answering sessionExpired), keep a cleared jar
+ * signed in, and put the raw token into request events.
  *
  * Lambder never depends on msw: the app installs it and passes the module
  * in. An injected network failure answers MSW's network error. A POST whose
  * body is not an API envelope is left to other handlers.
  *
  * Generic over the module so the handler keeps msw's own handler type, which
- * is what `setupWorker(...)` and `setupServer(...)` take. Returning `unknown`
- * made the documented wiring an error at the consumer.
+ * is what `setupWorker(...)` and `setupServer(...)` take; typed `unknown`,
+ * the documented wiring would be a type error at the consumer.
  */
 export const lambderMockMswHandler = (mockApp, options) => {
     const { msw, apiPath } = options;
@@ -38,13 +44,11 @@ export const lambderMockMswHandler = (mockApp, options) => {
     // cookies name.
     if (!options.cookieJar)
         mockApp.adoptCookieJar(jar);
-    // The runtime's default, not a second one of this adapter's own: an app
-    // that set defaultClientIp saw its address through the direct transport
-    // and 127.0.0.1 through the service worker, so a per-IP rate limit counted
-    // two clients where there was one and the two adapters disagreed about
-    // what ctx.request.ip is.
-    // Normalized the way every other adapter's is, so one address is one
-    // counter under a `per: "ip"` limit however it was spelled.
+    // 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
+    // adapter's is, so one address is one counter under a `per: "ip"` limit
+    // however it was spelled.
     const clientIp = normalizeClientIp(options.clientIp ?? mockApp.defaultClientIp);
     const handler = msw.http.post(apiPath, async ({ request }) => {
         let post;
@@ -54,27 +58,34 @@ export const lambderMockMswHandler = (mockApp, options) => {
         catch {
             return undefined;
         }
-        // Through the one header map every adapter builds, which is built on
-        // Object.create(null): a header literally named __proto__ was dropped
-        // here and landed as an own key on the server, and headers["toString"]
-        // handed a guard an inherited function where every other adapter gives
-        // 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
+        // key, and headers["toString"] would hand a guard an inherited
+        // 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.
+        if (!isApiCallContentType(headers))
+            return undefined;
+        // The cookies travel as `cookies` below, as the direct transport's do.
+        delete headers.cookie;
         const url = new URL(request.url);
         // Only the cookies whose scope covers this call, as a browser would
-        // send: reading the whole jar sent one host's session to another as
-        // soon as a jar was shared across hosts, and read cookies the request
-        // path was never in scope for. The host is the runtime's own, the path
-        // the one this call is going to. The jar's copies come first: where a
-        // name is in both, the jar holds what this runtime last set and the
-        // document's copy is the mirror of it, so the jar is the one to
-        // believe.
+        // send: the whole jar would send one host's session to another once a
+        // jar is shared across hosts, and cookies the request path is not in
+        // scope for. The host is the runtime's own, the path the one this call
+        // is going to. The jar's copies come first: where a name is in both,
+        // the jar holds what this runtime last set and the document's copy
+        // mirrors it, so the jar is the one to believe.
         const cookieScope = { host: mockApp.cookieHost, path: url.pathname };
         const cookies = cookieValuesByName(jar.cookiePairs(cookieScope));
         // Pair by pair, so a name the document holds at two scopes keeps both
         // values and the session controller can weigh them, as it does on
         // the server.
-        for (const [name, values] of Object.entries(cookieValuesByName((request.headers.get("cookie") ?? "").split(";")))) {
+        const pageCookies = typeof document === "undefined" ? "" : document.cookie;
+        for (const [name, values] of Object.entries(cookieValuesByName(pageCookies.split(";")))) {
             for (const value of values) {
                 if (!cookies[name]?.includes(value))
                     (cookies[name] ??= []).push(value);
@@ -105,12 +116,12 @@ export const lambderMockMswHandler = (mockApp, options) => {
         const setCookies = getAnswerHeader(answer.headers, "Set-Cookie") ?? [];
         jar.storeSetCookies(setCookies, cookieScope);
         // The cookies a page's own scripts may see are mirrored into
-        // document.cookie, so it reads the same in mocked development as it
-        // does against the real backend. Not decoration: the browser caller
-        // reads the CSRF token from there and posts it on the envelope, so
-        // without this every session call fails its CSRF check. Through the
-        // runtime, which is where the one mirror implementation lives and
-        // where what was planted is remembered for reset().
+        // document.cookie, so it reads the same in mocked development as
+        // against the real backend. Not decoration: the browser caller reads
+        // the CSRF token from there and posts it on the envelope, so without
+        // 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);
         const responseHeaders = new Headers();
         for (const [key, values] of Object.entries(answer.headers)) {

package/dist/mock/lambderMockUploadMswHandler.d.ts

@@ -0,0 +1,26 @@
+import type { LambderMemoryUploadBucket } from "../stores/LambderMemoryUploadBucket.js";
+import type { LambderMswModule } from "./lambderMockMswHandler.js";
+/**
+ * The MSW handler that makes a LambderMemoryUploadBucket the storage a mock
+ * app's browser uploads to: every request under the bucket's baseUrl (a
+ * LambderUploadRunner's post, a download link's GET) is answered by the
+ * bucket, the way S3 would answer it. Register it beside the API handler:
+ *
+ * ```ts
+ * const documents = new LambderMemoryUploadBucket();
+ * setupWorker(
+ *     lambderMockMswHandler(mockApp, { apiPath: "/api", msw }),
+ *     lambderMockUploadMswHandler(documents, { msw }),
+ * );
+ * ```
+ *
+ * The mock's ticket and confirm handlers then call `documents` as the
+ * server's call the real bucket, so the runner's whole conversation runs, the
+ * checks storage makes on a post included.
+ *
+ * Lambder never depends on msw: the app installs it and passes the module
+ * in. Generic over the module so the handler keeps msw's own handler type.
+ */
+export declare const lambderMockUploadMswHandler: <M extends LambderMswModule>(bucket: LambderMemoryUploadBucket, options: {
+    msw: M;
+}) => ReturnType<M["http"]["all"]>;

package/dist/mock/lambderMockUploadMswHandler.js

@@ -0,0 +1,28 @@
+/**
+ * The MSW handler that makes a LambderMemoryUploadBucket the storage a mock
+ * app's browser uploads to: every request under the bucket's baseUrl (a
+ * LambderUploadRunner's post, a download link's GET) is answered by the
+ * bucket, the way S3 would answer it. Register it beside the API handler:
+ *
+ * ```ts
+ * const documents = new LambderMemoryUploadBucket();
+ * setupWorker(
+ *     lambderMockMswHandler(mockApp, { apiPath: "/api", msw }),
+ *     lambderMockUploadMswHandler(documents, { msw }),
+ * );
+ * ```
+ *
+ * The mock's ticket and confirm handlers then call `documents` as the
+ * server's call the real bucket, so the runner's whole conversation runs, the
+ * checks storage makes on a post included.
+ *
+ * Lambder never depends on msw: the app installs it and passes the module
+ * in. Generic over the module so the handler keeps msw's own handler type.
+ */
+export const lambderMockUploadMswHandler = (bucket, options) => {
+    const { msw } = options;
+    if (!msw?.http?.all) {
+        throw new Error('lambderMockUploadMswHandler requires the msw module: lambderMockUploadMswHandler(bucket, { msw: await import("msw") }). Install it with: npm install msw --save-dev');
+    }
+    return msw.http.all(`${bucket.baseUrl}*`, async ({ request }) => (await bucket.handleStorageRequest(request)) ?? undefined);
+};

package/dist/mock.d.ts

@@ -8,12 +8,15 @@
  */
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
-export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
+export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
 export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export type { LambderMockConsoleLoggerOptions } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";
 export type { LambderMswModule, LambderMockMswTarget } from "./mock/lambderMockMswHandler.js";
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
+export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
 export type { LambderMockInvokeEvent, LambderMockInvokeResult } from "./mock/lambderMockInvokeTransport.js";
 export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";

package/dist/mock.js

@@ -9,12 +9,15 @@
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 // The four collaborators behind LambderMockApp (the entry registry, the call
 // recorder, the failure injector, the browser cookies) are deliberately not
-// exported: the runtime is reached through the app, and its surface did not
-// change when they moved out of it. Only the error a transport rejects with is
-// public, as before.
+// exported: the runtime is reached through the app. Only the error a
+// transport rejects with is public.
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
 export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.js";
+// The storage a mock app's uploads go to: a memory bucket the mock's ticket and
+// confirm handlers call, and the MSW handler that answers its storage requests.
+export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
+export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
 // What a mock setup reaches for beside the app: the stores it runs on, the
 // jar its transport carries, and the refusal a handler says no with.

package/dist/session/LambderSessionController.d.ts

@@ -5,10 +5,10 @@ import type LambderSessionManager from "./LambderSessionManager.js";
 import type { LambderCreatedSession } from "./LambderSessionManager.js";
 /**
  * The part of a call this controller touches: the session it reads and
- * writes, and the headers it puts Set-Cookie on. Declaring it here is what
- * keeps the session layer under the API core rather than beside it: the
- * pipeline and both adapters pass their own full call context, which is
- * structurally this plus the fields the controller never reads.
+ * writes, and the headers it puts Set-Cookie on. Declared here so the session
+ * layer sits under the API core rather than beside it: the pipeline and both
+ * adapters pass their full call context, which is structurally this plus
+ * fields the controller never reads.
  */
 export type LambderSessionCallSurface<TSessionData = any> = {
     session: LambderSessionRecord<TSessionData> | null;
@@ -20,10 +20,9 @@ export type LambderSessionCallSurface<TSessionData = any> = {
  * one deployment serves several apex domains (return undefined for a
  * host-only cookie). Changing `domain` or `path` on a live deployment is a
  * migration: browsers keep the cookie under the old scope beside the new
- * one, and both arrive on every request. fetchSession tolerates that by
- * scanning every copy for the one live session and evicting the stale
- * host-only twin; a copy at a parent domain this host cannot name outlives
- * its own Expires.
+ * one, and both arrive on every request. fetchSession scans every copy for
+ * the one live session and evicts the stale host-only twin; a copy at a
+ * parent domain this host cannot name lives until its own Expires.
  */
 export type LambderSessionCookieOptions = Pick<LambderCookieOptions, "domain" | "path" | "sameSite" | "secure">;
 /**
@@ -41,10 +40,9 @@ export type LambderSessionControllerOptions<TSessionData> = {
     manager: LambderSessionManager<TSessionData>;
     /**
      * Name of the session cookie. Required rather than defaulted here: the
-     * defaults live in shared/wire/LambderSessionCookieNames.ts and are applied
-     * once, where the app's session options are read, so a second copy of
-     * them in this constructor would be a second place for them to drift and
-     * would let a controller read a cookie name the app never writes.
+     * defaults (shared/wire/LambderSessionCookieNames.ts) are applied once,
+     * where the app's session options are read. A second copy here could
+     * drift and have a controller read a cookie name the app never writes.
      */
     tokenCookieKey: string;
     /** Name of the CSRF cookie, required on the same terms as tokenCookieKey. */
@@ -55,40 +53,46 @@ export type LambderSessionControllerOptions<TSessionData> = {
     request: LambderSessionRequestInfo;
 };
 /**
- * No session for this request: the cookies named none, or the single session
- * they named did not pair with the posted CSRF token.
+ * No session for this request: the cookies named none, the single session
+ * they named did not pair with the posted CSRF token, they cannot be
+ * resolved to one session (LambderSessionAmbiguousError, the one case with a
+ * type of its own), or the session was ended while the request held it (a
+ * logout or a password change elsewhere, or the dataRefresh callback).
  *
- * Typed rather than a bare Error because fetchSessionIfExists has to tell
- * "there is no session here" apart from "something broke". Everything else,
- * a TypeError from a custom store, a bug in an app's dataRefresh callback,
- * propagates and becomes a crash: answering sessionExpired for a defect makes
- * the client clear its cookies and turns somebody's bug into a logout.
+ * Typed so fetchSessionIfExists can tell "no session here" from "something
+ * broke", and so can every place that answers a request which needed a
+ * session and has none (the API pipeline, a route or a hook on the server):
+ * each tests for this class, and the ambiguous case with it. Everything else
+ * (a TypeError from a custom store, a bug in a dataRefresh callback)
+ * propagates as a crash: answering sessionExpired for a defect makes the
+ * client clear its cookies and turns a bug into a logout.
  */
 export declare class LambderSessionNotFoundError extends Error {
     constructor(message?: string);
 }
 /**
  * The request's session cookies cannot be resolved to one session, so none of
- * them is used and every scope this host can write is cleared. Also a "no
- * session" answer to the caller, and deliberately a different type: this one
- * carries the clearing Set-Cookie headers that heal the state, and it is the
- * one worth finding in a log.
+ * them is used and every scope this host can write is cleared. A request with
+ * no usable session, so it is a LambderSessionNotFoundError and is answered
+ * as one wherever that is (a 401 or the session-expired route answer, the
+ * sessionExpired envelope on an API call). The subclass keeps it apart for
+ * whoever wants to tell: this case carries the clearing Set-Cookie headers
+ * that heal the state, and it is the one worth finding in a log.
  */
-export declare class LambderSessionAmbiguousError extends Error {
+export declare class LambderSessionAmbiguousError extends LambderSessionNotFoundError {
     constructor(message?: string);
 }
 /**
  * A `__Host-` cookie is the browser's own answer to a sibling subdomain
  * planting a session cookie at a parent domain: it refuses one that carries a
  * Domain, so no other host can write it. `__Secure-` is the weaker sibling,
- * accepted only on a Secure cookie. Both protections fail silently, though: a
- * browser handed a prefixed name with an attribute the prefix forbids simply
- * discards the cookie, and the app looks like it has no sessions at all
- * rather than like it is misconfigured. So the combinations are rejected at
- * creation instead.
+ * accepted only on a Secure cookie. Both fail silently: a browser discards a
+ * prefixed cookie with an attribute the prefix forbids, and the app looks
+ * like it has no sessions rather than like it is misconfigured. So the
+ * combinations are rejected at creation.
  *
  * Session policy, so it lives beside the controller that writes the cookies
- * rather than in the pipeline that happens to call it.
+ * rather than in the pipeline that calls it.
  */
 export declare const assertSessionCookiePrefixes: (sessions: {
     tokenCookieKey: string;
@@ -97,11 +101,11 @@ export declare const assertSessionCookiePrefixes: (sessions: {
 }) => void;
 /**
  * Sessions as one request sees them: reads the session the request's
- * cookies name onto the context, and writes the cookies a created,
- * rotated or ended session needs into the context's response headers.
- * Server handlers reach it through lambder.getSessionController(ctx); mock
- * handlers through ctx.sessions. It works on the call context and the
- * request info alone, so it is one class for both.
+ * cookies name onto the context, and writes the cookies a created, rotated
+ * or ended session needs into the context's response headers. Server and
+ * mock handlers reach it as ctx.sessionController (the server's also through
+ * lambder.getSessionController(ctx)); it needs only the call context and
+ * request info, so one class serves both.
  */
 export default class LambderSessionController<TSessionData = any> {
     readonly manager: LambderSessionManager<TSessionData>;
@@ -114,48 +118,44 @@ export default class LambderSessionController<TSessionData = any> {
     /** The configured scope with the domain resolved for this request, or the host-only scope. */
     private cookieScope;
     /**
-     * Both cookies at one expiry, with the raw secrets. They exist only on the
-     * LambderCreatedSession result, in these cookies and in the request that
-     * carried them back; the record stores hashes. `csrfToken` is null where
-     * the raw CSRF value is not known to this request, in which case only the
-     * session cookie is written: writing a CSRF cookie whose value does not
-     * pair with the session would break the very session it is refreshing.
+     * Both cookies at one expiry, with the raw secrets, which exist only on
+     * the LambderCreatedSession result, in these cookies and in requests that
+     * carry them back; the record stores hashes. `csrfToken` is null when this
+     * request does not know the raw CSRF value, and then only the session
+     * cookie is written: a CSRF cookie that does not pair with the session
+     * would break the session it is refreshing.
      */
     private writeSessionCookies;
     private setSessionCookies;
     /**
-     * The deleting pair for one scope. Written once because a deletion only
-     * reaches a cookie carrying the same Domain and Path, so the pair is
-     * emitted per scope and the two callers differ in nothing but which
-     * scopes they walk.
+     * The deleting pair for one scope. A deletion only reaches a cookie with
+     * the same Domain and Path, so the pair is emitted per scope; the two
+     * callers differ only in which scopes they walk.
      */
     private addClearCookiePair;
     private clearSessionCookies;
     /**
      * Every Domain this host is allowed to write the session cookies at: the
      * host-only scope, the configured one, and each parent domain of the
-     * request host. A deletion matches only a cookie carrying the same
-     * Domain, so evicting a copy the app itself never set needs all of them.
-     * A browser ignores a Domain it will not accept, which is why a suffix
-     * the registry owns can be offered without checking a public-suffix list.
+     * request host. A deletion matches only a cookie with the same Domain, so
+     * evicting a copy the app never set needs all of them. A browser ignores
+     * a Domain it will not accept, so a registry-owned suffix can be offered
+     * without checking a public-suffix list.
      */
     private cookieClearDomains;
     /**
-     * Clears the session cookies at every scope this host can reach, rather
-     * than at the one the app configured. Used when a request carries more
-     * than one live session: the copy that has to go may sit at a parent
-     * domain a sibling host planted it at, and clearing the configured scope
-     * alone would evict this visitor's own cookie and leave the planted one
-     * as the only survivor, which completes the takeover instead of stopping
-     * it.
+     * Clears the session cookies at every scope this host can reach, not just
+     * the configured one. Used when a request carries more than one live
+     * session: the copy that has to go may sit at a parent domain where a
+     * sibling host planted it, and clearing only the configured scope would
+     * evict the visitor's own cookie and leave the planted one as the sole
+     * survivor, completing the takeover instead of stopping it.
      */
     private clearSessionCookiesEverywhere;
     /**
      * Refuses a request whose session cookies cannot be resolved to one
-     * session, clearing every scope this host can write. Clearing only the
-     * configured scope would be worse than picking one: a deletion matches
-     * only a cookie carrying the same Domain, so it would evict the visitor's
-     * own copy and leave a planted one as the sole survivor.
+     * session, clearing every scope this host can write (see
+     * clearSessionCookiesEverywhere for why not just the configured one).
      *
      * Path is the one dimension this cannot sweep: the request info carries
      * no path, and a deletion matches only a cookie at the same Path, so a
@@ -168,12 +168,11 @@ export default class LambderSessionController<TSessionData = any> {
      * Both session cookie names read in one pass: every well-formed value
      * under the token name, and every value under the CSRF name.
      *
-     * The CSRF cookie is counted here rather than looked at only when a token
-     * is checked against it, because it is plantable exactly like the session
-     * cookie and the browser picks between copies without telling anyone: the
-     * client reads its CSRF token with js-cookie's Cookies.get, which returns
-     * the FIRST copy in document.cookie, and a browser orders a longer Path
-     * first. So a sibling host that plants one CSRF cookie at a parent domain
+     * The CSRF cookie is counted, not just checked against a token, because
+     * it is plantable like the session cookie and the browser picks between
+     * copies silently: the client reads it with js-cookie's Cookies.get, which
+     * returns the FIRST copy in document.cookie, and browsers order a longer
+     * Path first. A sibling host that plants a CSRF cookie at a parent domain
      * with a deeper Path decides which token every call posts, and the count
      * is the only thing that shows it.
      */
@@ -182,45 +181,65 @@ export default class LambderSessionController<TSessionData = any> {
     private areRequestSessionTokensValid;
     createSession(sessionKey: string, data?: TSessionData, ttlInSeconds?: number): Promise<LambderSessionRecord<TSessionData>>;
     /**
-     * createSession, handing back the raw tokens beside the session: what a
-     * test or a mock runtime needs to plant the cookies somewhere else (a
-     * cookie jar) than this call's response.
+     * createSession, handing back the raw tokens beside the session, for a
+     * test or mock runtime that plants the cookies somewhere other than this
+     * call's response (a cookie jar).
      */
     issueSession(sessionKey: string, data?: TSessionData, ttlInSeconds?: number): Promise<LambderCreatedSession<TSessionData>>;
     regenerateSession(): Promise<LambderSessionRecord<TSessionData>>;
     /**
-     * regenerateSession, handing back the raw tokens beside the session, the
-     * way issueSession does for a new one. Rotating the session mints a new
-     * CSRF token, and a client that holds its token rather than reading
-     * document.cookie (a native app, an invoke caller) needs the new one to
-     * keep calling.
+     * regenerateSession, handing back the raw tokens beside the session as
+     * issueSession does. Rotation mints a new CSRF token, and a client that
+     * holds its token rather than reading document.cookie (a native app, an
+     * invoke caller) needs the new one to keep calling.
      */
     reissueSession(): Promise<LambderCreatedSession<TSessionData>>;
     fetchSession(): Promise<LambderSessionRecord<TSessionData>>;
     /**
      * Re-issues both cookies at this session's expiry: after a sliding write
-     * moved it, and beside the host-only eviction above, which would
-     * otherwise delete a cookie without replacing it.
+     * moved it, and beside the host-only eviction, which would otherwise
+     * delete a cookie without replacing it.
      *
-     * The raw CSRF value is the posted one on an API call, which the pairing
-     * check above has just matched against this session. A route posts none,
-     * so the single arriving CSRF cookie stands in, and only once it is known
-     * to pair: re-issuing an unpaired value would overwrite this visitor's
-     * real CSRF cookie with a planted one, at the app's own scope, which is
-     * the takeover the scan exists to prevent. Where neither is available the
-     * session cookie slides alone, which is the half that decides whether the
-     * session survives.
+     * On an API call the raw CSRF value is the posted one, which the pairing
+     * check just matched. A route posts none, so the single arriving CSRF
+     * cookie stands in, but only once it is known to pair: re-issuing an
+     * unpaired value would overwrite the visitor's real CSRF cookie with a
+     * planted one at the app's own scope, the takeover the scan exists to
+     * prevent. Where neither is available the session cookie slides alone;
+     * it is the half that decides whether the session survives.
      */
     private slideSessionCookies;
+    /**
+     * "No session" for a request whose session cookie names none, or whose
+     * session ended while it held it: the context holds none.
+     *
+     * The cookies are left alone. A deletion matches a cookie by name, not by
+     * value, so clearing here would also delete a session another response
+     * has just set: a poll sent with the old cookie, answering after a login,
+     * a rotation or a password change, would sign the person straight out of
+     * the new session. It also keeps the client's own check working, which
+     * clears the CSRF cookie only while it still holds the token the call
+     * sent. A dead cookie costs a store read per request until it expires.
+     */
+    private endWithNoSession;
     fetchSessionIfExists(): Promise<LambderSessionRecord<TSessionData> | null>;
+    /**
+     * Writes new data onto the current session. Throws
+     * LambderSessionNotFoundError when the session was ended while this
+     * request held it: the write does not bring it back, and an API call
+     * answers sessionExpired.
+     */
     updateSessionData(newData: TSessionData): Promise<LambderSessionRecord<TSessionData>>;
     /**
-     * Force-runs the dataRefresh callback now (see the session option of create) and
-     * persists the result onto the current session. Returns the updated
-     * session, or null when the callback ended it: the record is deleted and
-     * the session cookies are cleared.
+     * Force-runs the dataRefresh callback now (see the session option of
+     * create) and persists the result onto the current session. Throws
+     * LambderSessionNotFoundError when the session is over, because the
+     * callback ended it (the record is deleted) or because it was ended while
+     * this request held it: the same "no session" a read gives for either,
+     * with the cookies left alone (see endWithNoSession), and what an API
+     * call answers as sessionExpired.
      */
-    refreshSessionData(): Promise<LambderSessionRecord<TSessionData> | null>;
+    refreshSessionData(): Promise<LambderSessionRecord<TSessionData>>;
     /**
      * Deletes every session of the given sessionKey (e.g. a user id): "log
      * this subject out everywhere". Unlike endSessionAll it needs no fetched