lambder 4.5.1 → 4.6.1

package/Readme.md

@@ -2,6 +2,11 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
+**New in 4.6:**
+
+- **Cookies as a first-class concern**: `res.setCookie(name, value, options)` and `res.clearCookie(name, options)` serialize Set-Cookie headers through the `cookie` package (defaults Path=/, SameSite=Lax, Secure; a function-form `domain` resolves against the request hostname, the same option the session takes), replacing hand-built header strings; `serializeCookie`/`serializeClearCookie` are exported for code holding a response. `ctx.cookieList` keeps every value a cookie name arrived with beside the first-wins `ctx.cookie`.
+- **Session cookie scope changes heal**: a cookie's identity is (name, domain, path), so changing the session's `cookie.domain` or `path` on a live deployment leaves the old copy in every browser beside the new one, and a whole-header parse silently picks whichever the browser lists first. The controller now tries every copy of the session cookie (record and CSRF pairing checked per copy), logs the ambiguity, and evicts the stale host-only twin from the response, so a migrated browser recovers on its first request instead of answering `sessionExpired` until the old cookie expires.
+
 **New in 4.5:**
 
 - **`files` at creation replaces `publicPath`** (and `servePublicFiles({ source })`): one `LambderFileSource` configured once, `files: new LambderLocalFileSource({ root: path.resolve("./public") })` for the folder bundled with the deployment, `new LambderS3FileSource({...})` for S3 or R2, or your own `{ read(relativePath) }`. The instance owns one reader over it (`lambder.files`): path rule, in-memory file cache and compiled-template cache in one place, shared by `servePublicFiles`, `serveIndexHtml`, `res.file` and `res.templateFile`, so a build hosted from a bucket serves its index.html and templates from the bucket too, cached the same way as its assets. The cache is tuned or disabled beside the source, `files: { source, memoryCache }`, and `memoryCache` leaves `servePublicFiles`; `res.file` loses its SPA-era `fallback` option (the fallback chain replaced it).
@@ -335,6 +340,12 @@ const lambder = initLambder<SessionData>().create({
 
 See [docs/DYNAMODB_SETUP.md](docs/DYNAMODB_SETUP.md) for detailed setup instructions.
 
+#### Cookie scope
+
+`session.cookie` sets the scope of the two session cookies: `{ domain: ".example.com" }` shares a login across subdomains, and `domain` may be a `(hostname) => string | undefined` function when one deployment serves several apex domains (return undefined for a host-only cookie); `path`, `sameSite` (default `Lax`) and `secure` (default true) complete it. `LambderCaller` takes the same `sessionCookieDomain` so it can clear the CSRF cookie where the server set it.
+
+Changing `domain` or `path` on a live deployment is a migration, because a browser identifies a cookie by (name, domain, path): the old copy stays beside the new one, both arrive on every request, and the browser's order says nothing about which is current. The controller handles the overlap: when the session cookie name arrives more than once it tries every copy (record lookup and CSRF pairing per copy), takes the live one, logs the ambiguity, and evicts the stale host-only twin from the response when a domain is configured. The reverse move, from a domain cookie back to host-only, cannot be evicted (this host cannot name the parent domain), so that copy is tolerated on every request until its own expiry. Renaming the cookies (`tokenCookieKey`, `csrfCookieKey`) alongside the scope change avoids the overlap entirely.
+
 #### How the secrets are stored
 
 The session cookie is `pkHash:secret`: `pkHash = sha256(sessionKey + sessionSalt)` and `secret` is 256 random bits. At rest the record stores only HASHES of the bearer secrets: the range key is `sha256(secret)` (so the lookup itself proves possession of the raw secret) and the CSRF token is stored as `csrfTokenHash`. The raw values exist only in the client's cookies and, transiently, on the `LambderCreatedSession` result the manager returns at creation; a read of the session table (backup leak, over-broad IAM, insider) therefore yields no usable cookies. Fast sha256 is the correct construction here rather than a password KDF: the secrets are 256-bit random, so there is nothing to brute-force, while `sessionSalt` peppers the identity-to-partition-key mapping so partition keys and cookie prefixes cannot be derived from (or linked to) known user ids.
@@ -504,7 +515,8 @@ The `ctx` object provides access to request data:
 | `rawBody` | Decoded request body as received (webhook signatures) | `'{"a":1}'` |
 | `ip` | Client IP (CF-Connecting-IP / X-Forwarded-For / source IP) | `"1.2.3.4"` |
 | `header(name)` | Case-insensitive request header lookup | `ctx.header("accept-language")` |
-| `cookie` | Cookies | `{ rememberMe: "true" }` |
+| `cookie` | Cookies (the first value when a name arrived more than once) | `{ rememberMe: "true" }` |
+| `cookieList` | Every value per cookie name, in header order (a name held at several scopes arrives several times) | `{ rememberMe: ["true"] }` |
 | `headers` | Request headers | `{ "Content-Type": "..." }` |
 | `event` | Raw Lambda event (APIGatewayProxyEvent or APIGatewayProxyEventV2) | - |
 | `lambdaContext` | AWS Lambda Context | - |
@@ -517,6 +529,8 @@ The `ctx` object provides access to request data:
 **Header Manipulation** (call before returning response):
 - `res.addHeader(key, value)` - Adds a header value (can be called multiple times for same key)
 - `res.setHeader(key, value)` - Sets a header (replaces existing values)
+- `res.setCookie(name, value, options?)` - Adds a Set-Cookie header. Options: `domain` (a string, or a `(hostname) => string | undefined` function resolved against the request host), `path` (default `/`), `sameSite` (default `Lax`), `secure` (default true), `httpOnly`, `maxAge` (seconds), `expires` (Date), `encode` (default encodeURIComponent, which `ctx.cookie` reverses)
+- `res.clearCookie(name, options?)` - Adds a Set-Cookie header that deletes the cookie. Pass the `domain` and `path` it was set with: a cookie's identity is (name, domain, path), so a deletion under another scope deletes nothing
 - `res.logToApiResponse(data)` - Adds data to logList in API responses (debugging)
 
 **Response Methods** (all accept an options object: `{ statusCode?, headers?, cacheControl?, compress?, etag? }`):

package/dist/client/LambderCaller.js

@@ -101,6 +101,9 @@ export default class LambderCaller {
         const resolvedDomain = typeof domainOption === "function" ? domainOption(hostname) : domainOption;
         for (const key of [this.sessionTokenCookieKey, this.sessionCsrfCookieKey]) {
             // Host-only and domain-scoped cookies are distinct entries; clear both.
+            // Only the CSRF cookie is reachable from here: the token cookie is
+            // HttpOnly, so its removal is the server's (a Set-Cookie on the
+            // session-expired or logout response).
             Cookies.remove(key);
             if (resolvedDomain)
                 Cookies.remove(key, { domain: resolvedDomain, path: "/" });

package/dist/core/LambderContext.d.ts

@@ -11,7 +11,16 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     method: string;
     get: Record<string, string | undefined>;
     post: Record<string, any>;
+    /** Cookies by name (the first value when a name arrived more than once; see cookieList). */
     cookie: Record<string, string>;
+    /**
+     * Every value the request carried per cookie name, in header order. A
+     * name normally maps to one value; several arrive when the browser holds
+     * that name at more than one scope (host-only beside Domain=, or two
+     * paths), typically after a cookie's Domain or Path was changed. The
+     * browser's order says nothing about which copy is current.
+     */
+    cookieList: Record<string, string[]>;
     session: null;
     apiName: string | null;
     apiPayload: TApiPayload;

package/dist/core/LambderContext.js

@@ -10,7 +10,7 @@ export const createContext = (event, lambdaContext, apiPath) => {
     let path;
     let method;
     let get;
-    let cookieHeader;
+    let cookiePairs;
     let sourceIp;
     const headers = event.headers ?? {};
     if (isV2HttpEvent(event)) {
@@ -26,7 +26,8 @@ export const createContext = (event, lambdaContext, apiPath) => {
         for (const [key, value] of new URLSearchParams(event.rawQueryString ?? "").entries()) {
             get[key] = value;
         }
-        cookieHeader = (event.cookies ?? []).join("; ");
+        // v2 delivers the Cookie header pre-split into name=value pairs.
+        cookiePairs = event.cookies ?? [];
         sourceIp = event.requestContext.http.sourceIp || "";
     }
     else {
@@ -34,10 +35,19 @@ export const createContext = (event, lambdaContext, apiPath) => {
         path = event.path;
         method = event.httpMethod;
         get = event.queryStringParameters || {};
-        cookieHeader = headers.Cookie || headers.cookie || "";
+        cookiePairs = (headers.Cookie || headers.cookie || "").split(";");
         sourceIp = event.requestContext?.identity?.sourceIp || "";
     }
-    const cookie = cookieParser.parse(cookieHeader);
+    // Parsed pair by pair so a name that arrived more than once keeps every
+    // value; a whole-header parse keeps only the first.
+    const cookieList = {};
+    for (const pair of cookiePairs) {
+        for (const [name, value] of Object.entries(cookieParser.parse(pair))) {
+            if (value !== undefined)
+                (cookieList[name] ??= []).push(value);
+        }
+    }
+    const cookie = Object.fromEntries(Object.entries(cookieList).map(([name, values]) => [name, values[0]]));
     const lowercasedHeaders = {};
     for (const [key, value] of Object.entries(headers)) {
         if (value !== undefined)
@@ -74,7 +84,7 @@ export const createContext = (event, lambdaContext, apiPath) => {
     const requestVersion = isApiCall ? (post.version ?? null) : null;
     return {
         host, path, pathParams: {}, method,
-        get, post, cookie, event,
+        get, post, cookie, cookieList, event,
         session: null,
         apiName, apiPayload,
         guardData: {},

package/dist/core/LambderCookie.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A cookie's Domain attribute: a fixed value such as ".example.com", or a
+ * function of the request hostname for one deployment serving several apex
+ * domains. Return undefined (or null) for a host-only cookie.
+ */
+export type LambderCookieDomain = string | ((hostname: string) => string | undefined | null);
+/**
+ * Attributes of a Set-Cookie header. A cookie's identity in the browser is
+ * (name, domain, path): a write under a different domain or path creates a
+ * second cookie beside the first instead of replacing it, and a deletion
+ * only reaches the cookie whose domain and path it names.
+ */
+export type LambderCookieOptions = {
+    domain?: LambderCookieDomain;
+    /** Default "/". */
+    path?: string;
+    /** Default "Lax". */
+    sameSite?: "Strict" | "Lax" | "None";
+    /** Default true. */
+    secure?: boolean;
+    /** Default false. */
+    httpOnly?: boolean;
+    /** Lifetime in seconds (Max-Age). A cookie with neither maxAge nor expires lasts the browser session. */
+    maxAge?: number;
+    /** Absolute expiry (Expires). */
+    expires?: Date;
+    /** Value encoder. Default encodeURIComponent, which ctx.cookie reverses on the way back in. */
+    encode?: (value: string) => string;
+};
+/** Options of a deleting Set-Cookie: only the scope matters. */
+export type LambderClearCookieOptions = Omit<LambderCookieOptions, "maxAge" | "expires" | "encode">;
+/** The Domain attribute for this request, or undefined for a host-only cookie. */
+export declare const resolveCookieDomain: (domain: LambderCookieDomain | undefined, host?: string) => string | undefined;
+/**
+ * One Set-Cookie header value. `host` resolves a function-form domain; a
+ * string domain needs none.
+ */
+export declare const serializeCookie: (name: string, value: string, options?: LambderCookieOptions, host?: string) => string;
+/**
+ * A Set-Cookie header value that deletes the cookie. Domain and path must
+ * match the cookie being deleted: a mismatch targets a different cookie and
+ * deletes nothing.
+ */
+export declare const serializeClearCookie: (name: string, options?: LambderClearCookieOptions, host?: string) => string;

package/dist/core/LambderCookie.js

@@ -0,0 +1,28 @@
+import cookieParser from "cookie";
+/** The Domain attribute for this request, or undefined for a host-only cookie. */
+export const resolveCookieDomain = (domain, host = "") => {
+    // Host header can carry a port; browsers match the Domain attribute on hostname only.
+    const hostname = host.split(":")[0] ?? "";
+    const resolved = typeof domain === "function" ? domain(hostname) : domain;
+    return resolved || undefined;
+};
+/**
+ * One Set-Cookie header value. `host` resolves a function-form domain; a
+ * string domain needs none.
+ */
+export const serializeCookie = (name, value, options = {}, host) => cookieParser.serialize(name, value, {
+    domain: resolveCookieDomain(options.domain, host),
+    path: options.path ?? "/",
+    sameSite: (options.sameSite ?? "Lax").toLowerCase(),
+    secure: options.secure ?? true,
+    httpOnly: options.httpOnly ?? false,
+    maxAge: options.maxAge,
+    expires: options.expires,
+    encode: options.encode,
+});
+/**
+ * A Set-Cookie header value that deletes the cookie. Domain and path must
+ * match the cookie being deleted: a mismatch targets a different cookie and
+ * deletes nothing.
+ */
+export const serializeClearCookie = (name, options = {}, host) => serializeCookie(name, "", { ...options, maxAge: 0, expires: new Date(0) }, host);

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,4 +1,5 @@
 import type { LambderRenderContext } from "./LambderContext.js";
+import { type LambderCookieOptions, type LambderClearCookieOptions } from "./LambderCookie.js";
 import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse, type HttpStatusCode, type LambderHeadersInput } from "./LambderResponse.js";
 import { LambderSafeHtml } from "../shared/LambderHtml.js";
@@ -38,6 +39,19 @@ export default class LambderResponseBuilder<TResponse = any> {
     private requireFiles;
     addHeader(key: string, value: string): void;
     setHeader(key: string, value: string | string[]): void;
+    /**
+     * Adds a Set-Cookie header. A function-form `domain` is resolved against
+     * the request hostname. Defaults: Path=/, SameSite=Lax, Secure, not
+     * HttpOnly, browser-session lifetime.
+     */
+    setCookie(name: string, value: string, options?: LambderCookieOptions): void;
+    /**
+     * Adds a Set-Cookie header that deletes the cookie. Pass the same
+     * `domain` and `path` the cookie was set with: a cookie's identity is
+     * (name, domain, path), and a deletion under a different scope targets a
+     * different cookie and deletes nothing.
+     */
+    clearCookie(name: string, options?: LambderClearCookieOptions): void;
     logToApiResponse(input: any): void;
     raw(init: LambderRawResponseInit): LambderResponse;
     json(data: Record<string, any>, options?: LambderResponseOptions): LambderResponse;

package/dist/core/LambderResponseBuilder.js

@@ -1,3 +1,4 @@
+import { serializeCookie, serializeClearCookie } from "./LambderCookie.js";
 import { LambderResponse } from "./LambderResponse.js";
 export default class LambderResponseBuilder {
     files;
@@ -45,6 +46,29 @@ export default class LambderResponseBuilder {
         this.ctx._otherInternal.setHeaderFnAccumulator.push({ key, value });
     }
     ;
+    /**
+     * Adds a Set-Cookie header. A function-form `domain` is resolved against
+     * the request hostname. Defaults: Path=/, SameSite=Lax, Secure, not
+     * HttpOnly, browser-session lifetime.
+     */
+    setCookie(name, value, options) {
+        if (!this.ctx)
+            throw new Error(".setCookie function is not available within this hook");
+        this.addHeader("Set-Cookie", serializeCookie(name, value, options, this.ctx.host));
+    }
+    ;
+    /**
+     * Adds a Set-Cookie header that deletes the cookie. Pass the same
+     * `domain` and `path` the cookie was set with: a cookie's identity is
+     * (name, domain, path), and a deletion under a different scope targets a
+     * different cookie and deletes nothing.
+     */
+    clearCookie(name, options) {
+        if (!this.ctx)
+            throw new Error(".clearCookie function is not available within this hook");
+        this.addHeader("Set-Cookie", serializeClearCookie(name, options, this.ctx.host));
+    }
+    ;
     logToApiResponse(input) {
         if (!this.ctx)
             throw new Error(".logToApiResponse function is not available within this hook");

package/dist/index.d.ts

@@ -41,3 +41,5 @@ export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, Lambd
 export { type ApiContractShape, type LambderApiResponse, type LambderApiResponseConfig, } from "./shared/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./core/LambderContext.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
+export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./core/LambderCookie.js";
+export type { LambderCookieOptions, LambderClearCookieOptions, LambderCookieDomain } from "./core/LambderCookie.js";

package/dist/index.js

@@ -32,3 +32,5 @@ export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
+// Cookies (res.setCookie / res.clearCookie build on these; exported for code holding a LambderResponse)
+export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./core/LambderCookie.js";

package/dist/session/LambderSessionController.d.ts

@@ -1,17 +1,18 @@
 import { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
+import { type LambderCookieOptions } from "../core/LambderCookie.js";
 import type LambderSessionManager from "./LambderSessionManager.js";
 import { type LambderSessionContext } from "./LambderSessionManager.js";
-export type LambderSessionCookieOptions = {
-    /**
-     * e.g. ".example.com" to share sessions across subdomains. Pass a function to
-     * derive it from the request hostname when one deployment serves several
-     * apex domains; return undefined for a host-only cookie.
-     */
-    domain?: string | ((hostname: string) => string | undefined | null);
-    path?: string;
-    sameSite?: "Strict" | "Lax" | "None";
-    secure?: boolean;
-};
+/**
+ * Scope of the session cookies. `domain` is e.g. ".example.com" to share
+ * sessions across subdomains, or a function of the request hostname when
+ * 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
+ * trying every copy 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;
@@ -25,16 +26,24 @@ export default class LambderSessionController<TSessionData = any> {
         cookieOptions?: LambderSessionCookieOptions;
         ctx: LambderRenderContext<any> | LambderSessionRenderContext<any, TSessionData>;
     });
-    private buildCookie;
+    /** 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. */
     private setSessionCookies;
     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.
+     */
+    private sessionTokenCandidates;
     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>;
-    isSessionValid(session: any): boolean;
+    /** 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>;
     /**
      * Force-runs the dataRefresh callback now (see the session option of create) and

package/dist/session/LambderSessionController.js

@@ -1,4 +1,7 @@
+import { resolveCookieDomain, serializeCookie, serializeClearCookie } from "../core/LambderCookie.js";
 import { LambderSessionDataRefreshError, LambderSessionReadError } from "./LambderSessionManager.js";
+/** The tokens are hex, so the cookie carries them as they are (the format existing browsers hold). */
+const rawValue = (value) => value;
 export default class LambderSessionController {
     lambderSessionManager;
     sessionTokenCookieKey;
@@ -13,39 +16,37 @@ export default class LambderSessionController {
         this.ctx = ctx;
     }
     ;
-    buildCookie(key, value, expiresAtMs, httpOnly) {
-        const { domain, path = "/", sameSite = "Lax", secure = true } = this.cookieOptions;
-        // Host header can carry a port; browsers match the Domain attribute on hostname only.
-        const hostname = (this.ctx.host || "").split(":")[0];
-        const resolvedDomain = typeof domain === "function" ? domain(hostname) : domain;
-        const parts = [
-            `${key}=${value}`,
-            `Expires=${new Date(expiresAtMs).toUTCString()}`,
-            `Path=${path}`,
-            ...(resolvedDomain ? [`Domain=${resolvedDomain}`] : []),
-            ...(httpOnly ? ["HttpOnly"] : []),
-            `SameSite=${sameSite}`,
-            ...(secure ? ["Secure"] : []),
-        ];
-        return parts.join("; ");
+    /** The configured scope with the domain resolved for this request, or the host-only scope. */
+    cookieScope(hostOnly = false) {
+        const { domain, path, sameSite, secure } = this.cookieOptions;
+        return { domain: hostOnly ? undefined : resolveCookieDomain(domain, this.ctx.host), path, sameSite, secure };
     }
     ;
     /** Raw secrets exist only on the LambderCreatedSession result and in these cookies; the record stores hashes. */
     setSessionCookies(created) {
-        const expiresAtMs = created.session.expiresAt * 1000;
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionTokenCookieKey, created.sessionToken, expiresAtMs, true) });
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionCsrfCookieKey, created.csrfToken, expiresAtMs, false) });
+        const scope = this.cookieScope();
+        const expires = new Date(created.session.expiresAt * 1000);
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: serializeCookie(this.sessionTokenCookieKey, created.sessionToken, { ...scope, expires, httpOnly: true, encode: rawValue }) });
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: serializeCookie(this.sessionCsrfCookieKey, created.csrfToken, { ...scope, expires, encode: rawValue }) });
     }
     ;
-    clearSessionCookies() {
-        const expired = Date.now() - 100000;
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionTokenCookieKey, "0", expired, true) });
-        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: this.buildCookie(this.sessionCsrfCookieKey, "0", expired, false) });
+    clearSessionCookies(hostOnly = false) {
+        const scope = this.cookieScope(hostOnly);
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: serializeClearCookie(this.sessionTokenCookieKey, { ...scope, httpOnly: true }) });
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: serializeClearCookie(this.sessionCsrfCookieKey, scope) });
+    }
+    ;
+    /**
+     * 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.
+     */
+    sessionTokenCandidates() {
+        return (this.ctx.cookieList?.[this.sessionTokenCookieKey] ?? []).filter((token) => token.split(":").length === 2);
     }
     ;
     areRequestSessionTokensValid() {
-        const sessionToken = this.ctx.cookie?.[this.sessionTokenCookieKey];
-        const isSessionTokenValid = !!sessionToken && sessionToken.split(":").length === 2;
+        const isSessionTokenValid = this.sessionTokenCandidates().length > 0;
         if (this.ctx._otherInternal.isApiCall) {
             const csrfToken = this.ctx.post?.token;
             const isCsrfTokenValid = typeof csrfToken === "string" && csrfToken.length > 0;
@@ -76,16 +77,23 @@ export default class LambderSessionController {
         if (!this.areRequestSessionTokensValid()) {
             throw new Error("Session tokens are invalid");
         }
-        const sessionToken = this.ctx.cookie?.[this.sessionTokenCookieKey];
-        if (!sessionToken)
-            throw new Error("Session token not found");
-        const session = await this.lambderSessionManager.getSession(sessionToken);
-        if (!session)
-            throw new Error("Session not found");
-        if (!this.isSessionValid(session))
-            throw new Error("Invalid session");
-        this.ctx.session = session;
-        return session;
+        const candidates = this.sessionTokenCandidates();
+        if (candidates.length > 1) {
+            console.warn(`Lambder session: ${candidates.length} "${this.sessionTokenCookieKey}" cookies arrived from ${this.ctx.host}; the browser holds the cookie at several scopes and a stale copy may shadow the live one. Trying each.`);
+        }
+        for (const sessionToken of candidates) {
+            const session = await this.lambderSessionManager.getSession(sessionToken);
+            if (!session || !this.isSessionValid(session, sessionToken))
+                continue;
+            // The other copies are stale. This response can evict the
+            // host-only twin of a Domain= cookie; a copy at a parent domain
+            // this host cannot name is out of reach and expires on its own.
+            if (candidates.length > 1 && this.cookieScope().domain)
+                this.clearSessionCookies(true);
+            this.ctx.session = session;
+            return session;
+        }
+        throw new Error("Session not found");
     }
     ;
     async fetchSessionIfExists() {
@@ -104,14 +112,13 @@ export default class LambderSessionController {
         }
     }
     ;
-    isSessionValid(session) {
+    /** 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, sessionToken = this.ctx.cookie?.[this.sessionTokenCookieKey]) {
         if (this.ctx._otherInternal.isApiCall) {
-            const sessionToken = this.ctx.cookie?.[this.sessionTokenCookieKey];
             const csrfToken = this.ctx.post?.token;
             return this.lambderSessionManager.isSessionValid(session, sessionToken, csrfToken);
         }
         else {
-            const sessionToken = this.ctx.cookie?.[this.sessionTokenCookieKey];
             return this.lambderSessionManager.isSessionValid(session, sessionToken, null, true);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "4.5.1",
+  "version": "4.6.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",