lambder 6.0.1 → 7.0.1

package/dist/mock/lambderMockMswHandler.d.ts

@@ -0,0 +1,99 @@
+import { type LambderApiRequest } from "../api/LambderApiRequest.js";
+import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
+import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+/**
+ * The parts of the msw module the adapter uses: `import * as msw from "msw"`.
+ *
+ * Written so the real package satisfies it, which is the whole point of a
+ * structural declaration and was not true of the previous one. msw's resolver
+ * answers a Response, or `undefined` to hand the request back (its
+ * AsyncResponseResolverReturnType), and a resolver declared to return
+ * `Promise<unknown>` is not assignable to that, so `http.post` did not fit
+ * here and the handler this returned did not fit `setupWorker`. Both errors
+ * landed on the documented five-line wiring.
+ */
+export type LambderMswModule = {
+    http: {
+        post: (path: string, resolver: (info: {
+            request: Request;
+        }) => Promise<Response | undefined>) => unknown;
+    };
+    HttpResponse: {
+        new (body?: BodyInit | null, init?: ResponseInit): Response;
+        error(): Response;
+    };
+};
+/** What the adapter needs from the mock app: a parsed request in, an answer out, and the runtime's own bookkeeping. */
+export type LambderMockMswTarget = {
+    handleRequest(request: LambderApiRequest): Promise<LambderApiAnswer>;
+    /**
+     * 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.
+     */
+    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;
+    /** The IP a call carrying none is read as arriving from, so this adapter and the direct transport report one address. */
+    readonly defaultClientIp: string;
+    /**
+     * The host the runtime's cookies belong to, which this adapter's jar is
+     * scoped by. The runtime's value, not the request URL's: signIn plants at
+     * the app's cookieHost and the direct transport's jar sends from there, so
+     * an adapter scoping by whatever host the page is served from held the
+     * session cookies at a host it never sent them to, and every session call
+     * behind the worker answered sessionExpired with a full jar.
+     */
+    readonly cookieHost: string;
+};
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare const lambderMockMswHandler: <M extends LambderMswModule>(mockApp: LambderMockMswTarget, options: {
+    msw: M;
+    apiPath: string;
+    cookieJar?: LambderCookieJar;
+    /**
+     * What happens to a call the runtime has no entry for. "refuse"
+     * (the default) answers the apiNotFound refusal, which is what an
+     * exhaustive `register` is for. "passthrough" leaves the request to
+     * MSW's other handlers and, failing those, to the network: the shape
+     * a partially mocked app runs in while its remaining endpoints still
+     * come from a real backend.
+     *
+     * This and `mockApp.restNotMocked(reason)` are the two answers to the
+     * same question, and the rest entry wins: it leaves the runtime with
+     * an entry for every name, so nothing is ever unmocked here and a call
+     * that would have gone to the network is answered notMocked instead.
+     * Pick the rest entry for an app with no backend to reach, and this
+     * for one whose remaining endpoints are served by a real one.
+     */
+    onUnmocked?: "refuse" | "passthrough";
+    /** The client IP its calls are read as arriving from. Default: the runtime's own defaultClientIp. */
+    clientIp?: string;
+}) => ReturnType<M["http"]["post"]>;

package/dist/mock/lambderMockMswHandler.js

@@ -0,0 +1,126 @@
+import { LambderMockTransportError } from "./LambderMockFailureInjector.js";
+import { readApiEnvelope, cookieValuesByName, 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";
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export const lambderMockMswHandler = (mockApp, options) => {
+    const { msw, apiPath } = 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 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.
+    const clientIp = normalizeClientIp(options.clientIp ?? mockApp.defaultClientIp);
+    const handler = msw.http.post(apiPath, async ({ request }) => {
+        let post;
+        try {
+            post = await request.clone().json();
+        }
+        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.
+        const headers = lowercaseHeaderNames(Object.fromEntries(request.headers));
+        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.
+        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(";")))) {
+            for (const value of values) {
+                if (!cookies[name]?.includes(value))
+                    (cookies[name] ??= []).push(value);
+            }
+        }
+        const parsed = readApiEnvelope(post, {
+            headers, cookies, ip: clientIp, host: url.host, signal: request.signal,
+        });
+        if (!parsed)
+            return undefined;
+        // 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);
+            return undefined;
+        }
+        let answer;
+        try {
+            answer = await mockApp.handleRequest(parsed);
+        }
+        catch (err) {
+            if (err instanceof LambderMockTransportError)
+                return msw.HttpResponse.error();
+            throw err;
+        }
+        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().
+        mockApp.mirrorCookiesIntoDocument(setCookies);
+        const responseHeaders = new Headers();
+        for (const [key, values] of Object.entries(answer.headers)) {
+            for (const value of values)
+                responseHeaders.append(key, value);
+        }
+        return new msw.HttpResponse(answer.body, { status: answer.statusCode, headers: responseHeaders });
+    });
+    // The call above is resolved against the constraint, which says `unknown`;
+    // what the module actually hands back is its own handler type, and naming
+    // it is the whole reason this function is generic.
+    return handler;
+};

package/dist/mock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Mock entry point (`import ... from "lambder/mock"`).
+ *
+ * The mock runtime: the API core over memory stores, serving a typed
+ * contract from mock handlers in development and in tests, in a browser or
+ * in Node. Browser-safe like `lambder/client`, and never part of a
+ * production bundle by construction: nothing else imports it.
+ */
+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 { 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 { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
+export type { LambderMockInvokeEvent, LambderMockInvokeResult } from "./mock/lambderMockInvokeTransport.js";
+export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
+export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
+export type { LambderApiTransport, LambderApiTransportRequest } from "./shared/transport/LambderApiTransport.js";
+export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
+export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSessionCrypto.js";
+export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
+export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderRefusalMessage } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderApiRequest } from "./api/LambderApiRequest.js";
+export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";
+export type { LambderSessionRecord } from "./shared/contracts/LambderSessionStore.js";
+export type { LambderCreatedSession } from "./session/LambderSessionManager.js";
+export type { default as LambderSessionManager } from "./session/LambderSessionManager.js";
+export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";

package/dist/mock.js

@@ -0,0 +1,27 @@
+/**
+ * Mock entry point (`import ... from "lambder/mock"`).
+ *
+ * The mock runtime: the API core over memory stores, serving a typed
+ * contract from mock handlers in development and in tests, in a browser or
+ * in Node. Browser-safe like `lambder/client`, and never part of a
+ * production bundle by construction: nothing else imports it.
+ */
+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.
+export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
+export { lambderMockConsoleLogger } from "./mock/lambderMockConsoleLogger.js";
+export { lambderMockMswHandler } from "./mock/lambderMockMswHandler.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.
+export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
+export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
+export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
+export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSessionCrypto.js";
+export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/dist/session/LambderSessionController.d.ts

@@ -1,7 +1,19 @@
-import { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
-import { type LambderCookieOptions } from "../core/LambderCookie.js";
+import { type LambderCookieOptions } from "../shared/wire/LambderCookie.js";
+import type { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import type LambderSessionManager from "./LambderSessionManager.js";
-import { type LambderSessionContext } 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.
+ */
+export type LambderSessionCallSurface<TSessionData = any> = {
+    session: LambderSessionRecord<TSessionData> | null;
+    responseHeaders: LambderAnswerHeaders;
+};
 /**
  * Scope of the session cookies. `domain` is e.g. ".example.com" to share
  * sessions across subdomains, or a function of the request hostname when
@@ -9,49 +21,206 @@ import { type LambderSessionContext } from "./LambderSessionManager.js";
  * 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
- * trying every copy and evicting the stale host-only twin; a copy at a
- * parent domain this host cannot name outlives its own Expires.
+ * 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.
  */
 export type LambderSessionCookieOptions = Pick<LambderCookieOptions, "domain" | "path" | "sameSite" | "secure">;
-export default class LambderSessionController<TSessionData = any> {
-    lambderSessionManager: LambderSessionManager;
-    sessionTokenCookieKey: string;
-    sessionCsrfCookieKey: string;
+/**
+ * What the controller reads off the request: the host (cookie domain
+ * resolution), every value of every cookie, and the CSRF token the caller
+ * posted, or null when the request is not an API call (a route), in which
+ * case no CSRF check applies.
+ */
+export type LambderSessionRequestInfo = {
+    host: string;
+    cookies: Record<string, string[]>;
+    csrfToken: string | null;
+};
+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.
+     */
+    tokenCookieKey: string;
+    /** Name of the CSRF cookie, required on the same terms as tokenCookieKey. */
+    csrfCookieKey: string;
+    cookieOptions?: LambderSessionCookieOptions;
+    /** The call context the session is read onto and whose responseHeaders receive the cookies. */
+    ctx: LambderSessionCallSurface<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.
+ *
+ * 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.
+ */
+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.
+ */
+export declare class LambderSessionAmbiguousError extends Error {
+    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.
+ *
+ * Session policy, so it lives beside the controller that writes the cookies
+ * rather than in the pipeline that happens to call it.
+ */
+export declare const assertSessionCookiePrefixes: (sessions: {
+    tokenCookieKey: string;
+    csrfCookieKey: string;
     cookieOptions: LambderSessionCookieOptions;
-    ctx: LambderRenderContext<any> | LambderSessionRenderContext<any, TSessionData>;
-    constructor({ lambderSessionManager, sessionTokenCookieKey, sessionCsrfCookieKey, cookieOptions, ctx, }: {
-        lambderSessionManager: LambderSessionManager;
-        sessionTokenCookieKey: string;
-        sessionCsrfCookieKey: string;
-        cookieOptions?: LambderSessionCookieOptions;
-        ctx: LambderRenderContext<any> | LambderSessionRenderContext<any, TSessionData>;
-    });
+}) => 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.
+ */
+export default class LambderSessionController<TSessionData = any> {
+    readonly manager: LambderSessionManager<TSessionData>;
+    readonly tokenCookieKey: string;
+    readonly csrfCookieKey: string;
+    readonly cookieOptions: LambderSessionCookieOptions;
+    private readonly ctx;
+    private readonly request;
+    constructor({ manager, tokenCookieKey, csrfCookieKey, cookieOptions, ctx, request }: LambderSessionControllerOptions<TSessionData>);
     /** The configured scope with the domain resolved for this request, or the host-only scope. */
     private cookieScope;
-    /** Raw secrets exist only on the LambderCreatedSession result and in these cookies; the record stores hashes. */
+    /**
+     * 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.
+     */
+    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.
+     */
+    private addClearCookiePair;
     private clearSessionCookies;
     /**
-     * Every well-formed value the request carried under the session cookie
-     * name. More than one means the browser holds the cookie at several
-     * scopes, and the order says nothing about which copy is current.
+     * 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.
+     */
+    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.
+     */
+    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.
+     *
+     * 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
+     * copy planted at a deeper path stays out of reach. A `__Host-` cookie
+     * name is the structural answer, since the prefix forbids Domain and
+     * pins Path to "/"; see docs/sessions.md.
      */
-    private sessionTokenCandidates;
+    private refuseAmbiguousSession;
+    /**
+     * 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
+     * with a deeper Path decides which token every call posts, and the count
+     * is the only thing that shows it.
+     */
+    private scanSessionCookies;
+    /** An API call must also carry a CSRF token; a route only needs the cookie. */
     private areRequestSessionTokensValid;
-    createSession(sessionKey: string, data?: TSessionData, ttlInSeconds?: number): Promise<LambderSessionContext<TSessionData>>;
-    regenerateSession(): Promise<LambderSessionContext<TSessionData>>;
-    fetchSession(): Promise<LambderSessionContext<TSessionData>>;
-    fetchSessionIfExists(): Promise<LambderSessionContext<TSessionData> | null>;
-    /** Checks the record against a presented token (the request's first session cookie by default) and, on API calls, the posted CSRF token. */
-    isSessionValid(session: any, sessionToken?: string | undefined): boolean;
-    updateSessionData(newData: any): Promise<LambderSessionContext>;
+    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.
+     */
+    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.
+     */
+    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.
+     *
+     * 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.
+     */
+    private slideSessionCookies;
+    fetchSessionIfExists(): Promise<LambderSessionRecord<TSessionData> | null>;
+    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.
      */
-    refreshSessionData(): Promise<LambderSessionContext<TSessionData> | null>;
+    refreshSessionData(): Promise<LambderSessionRecord<TSessionData> | null>;
     /**
      * Deletes every session of the given sessionKey (e.g. a user id): "log
      * this subject out everywhere". Unlike endSessionAll it needs no fetched