lambder 4.4.1 → 4.6.1

package/dist/core/LambderPublicFiles.d.ts

@@ -1,28 +1,8 @@
 import type { LambderRenderContext } from "./LambderContext.js";
+import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse } from "./LambderResponse.js";
-/** A file a source serves: its bytes, and its mime type when the source knows it (otherwise resolved from the extension). */
-export type LambderPublicFile = {
-    body: Buffer;
-    mimeType?: string;
-};
-/**
- * Where servePublicFiles gets its files. Implement `read` over any backing
- * store: LambderLocalFileSource (a folder, the default), LambderS3FileSource
- * (S3, or R2 and other S3-compatible stores), or your own. The handler does
- * the rest for every source: traversal check, memory cache, mime fallback
- * from the extension, Cache-Control, ETag and compression.
- */
-export interface LambderPublicFileSource {
-    /**
-     * The file at a relative path (no leading slash, no ".." segments: the
-     * handler rejects those before calling), or null when there is no such
-     * file, which lets the request fall through to the route fallback.
-     */
-    read(relativePath: string): Promise<LambderPublicFile | null>;
-}
+/** Per-registration policy of servePublicFiles: how a request maps to a file and how the response is cached. */
 export type LambderPublicFilesOptions = {
-    /** Where files come from. Default: LambderLocalFileSource over publicPath. */
-    source?: LambderPublicFileSource;
     /**
      * Map the request to a file path (app-owned logic, e.g. per-tenant
      * roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
@@ -35,45 +15,25 @@ export type LambderPublicFilesOptions = {
     immutablePattern?: RegExp | false;
     /** Default: "public, max-age=31536000, immutable". */
     immutableCacheControl?: string;
-    /** In-memory cache of files for warm invocations. Default: { maxBytes: 32MB, maxFileBytes: 2MB }. Set false to disable. */
-    memoryCache?: false | {
-        maxBytes?: number;
-        maxFileBytes?: number;
-    };
     /**
      * Compression per file: "auto" (default: compressible mime + size threshold),
      * true/false, or a function, e.g. (ctx) => /\.(css|js|svg)$/.test(ctx.path).
      */
     compress?: boolean | "auto" | ((ctx: LambderRenderContext) => boolean | "auto");
 };
-/**
- * Files from a folder on the Lambda's filesystem, typically the build output
- * bundled into the deployment package. Reads stay under root. The default
- * source of servePublicFiles, over publicPath.
- */
-export declare class LambderLocalFileSource implements LambderPublicFileSource {
-    private root;
-    constructor({ root }: {
-        root: string;
-    });
-    read(relativePath: string): Promise<LambderPublicFile | null>;
-}
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves files from its source (traversal-safe, mime-typed,
- * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the source has no such file.
+ * after it. Serves files through the instance's reader (traversal-safe,
+ * mime-typed, memory-cached) with the immutable-cache heuristic for
+ * content-hashed assets, and falls through to the route fallback when the
+ * source has no such file.
  */
 export declare class LambderPublicFilesHandler {
-    private source;
+    private files;
     private options;
-    private fileCache;
-    private fileCacheBytes;
-    constructor(source: LambderPublicFileSource, options: LambderPublicFilesOptions);
+    constructor(files: LambderFiles, options: LambderPublicFilesOptions);
     /** Serve the mapped file, or return null to fall through. */
     handle(ctx: LambderRenderContext): Promise<LambderResponse | null>;
-    /** Read from the source, caching small files in memory for warm invocations. */
-    private readCached;
     private cacheControlFor;
 }

package/dist/core/LambderPublicFiles.js

@@ -1,61 +1,22 @@
-import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
 // Content-hashed build outputs (Vite/webpack/Rollup): a [-.] separated run of
 // 8+ hash chars containing at least one digit, before the extension.
 const DEFAULT_IMMUTABLE_PATTERN = /[-.](?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
 const DEFAULT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 const DEFAULT_CACHE_CONTROL = "public, max-age=3600";
-const DEFAULT_MEMORY_CACHE_MAX_BYTES = 32 * 1024 * 1024;
-const DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES = 2 * 1024 * 1024;
-/**
- * Files from a folder on the Lambda's filesystem, typically the build output
- * bundled into the deployment package. Reads stay under root. The default
- * source of servePublicFiles, over publicPath.
- */
-export class LambderLocalFileSource {
-    root;
-    constructor({ root }) {
-        this.root = root;
-    }
-    async read(relativePath) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            throw new Error("LambderLocalFileSource requires a Node.js environment.");
-        const base = path.resolve(this.root);
-        const absolute = path.resolve(base, relativePath);
-        if (absolute !== base && !absolute.startsWith(base + path.sep))
-            return null;
-        const stat = await fs.promises.stat(absolute).catch(() => null);
-        if (!stat?.isFile())
-            return null;
-        return { body: await fs.promises.readFile(absolute) };
-    }
-}
-/** Strip the leading slash and reject traversal; null for a path that names no file (empty, or a directory). */
-const toRelativePath = (target) => {
-    if (target.split("/").some((segment) => segment === ".."))
-        return null;
-    const relative = target.startsWith("/") ? target.slice(1) : target;
-    if (relative === "" || relative.endsWith("/"))
-        return null;
-    return relative;
-};
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves files from its source (traversal-safe, mime-typed,
- * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the source has no such file.
+ * after it. Serves files through the instance's reader (traversal-safe,
+ * mime-typed, memory-cached) with the immutable-cache heuristic for
+ * content-hashed assets, and falls through to the route fallback when the
+ * source has no such file.
  */
 export class LambderPublicFilesHandler {
-    source;
+    files;
     options;
-    fileCache = new Map();
-    fileCacheBytes = 0;
-    constructor(source, options) {
-        this.source = source;
+    constructor(files, options) {
+        this.files = files;
         this.options = options;
     }
     /** Serve the mapped file, or return null to fall through. */
@@ -63,10 +24,7 @@ export class LambderPublicFilesHandler {
         const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
         if (!mappedPath)
             return null;
-        const relativePath = toRelativePath(mappedPath);
-        if (relativePath === null)
-            return null;
-        const file = await this.readCached(relativePath);
+        const file = await this.files.read(mappedPath);
         if (!file)
             return null;
         const compressOption = this.options.compress;
@@ -75,44 +33,12 @@ export class LambderPublicFilesHandler {
             statusCode: 200,
             headers: {
                 "Content-Type": file.mimeType,
-                "Cache-Control": this.cacheControlFor(ctx, relativePath),
+                "Cache-Control": this.cacheControlFor(ctx, file.relativePath),
             },
             body: file.body,
             compress,
         });
     }
-    /** Read from the source, caching small files in memory for warm invocations. */
-    async readCached(relativePath) {
-        const cached = this.fileCache.get(relativePath);
-        if (cached)
-            return cached;
-        const file = await this.source.read(relativePath);
-        if (!file)
-            return null;
-        const entry = {
-            body: file.body,
-            mimeType: file.mimeType || mimeTypeResolver.lookup(relativePath) || "application/octet-stream",
-        };
-        const cacheConfig = this.options.memoryCache;
-        if (cacheConfig !== false) {
-            const maxBytes = cacheConfig?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES;
-            const maxFileBytes = cacheConfig?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES;
-            if (entry.body.length <= maxFileBytes) {
-                // Evict oldest entries until the new file fits the budget.
-                for (const [key, value] of this.fileCache) {
-                    if (this.fileCacheBytes + entry.body.length <= maxBytes)
-                        break;
-                    this.fileCache.delete(key);
-                    this.fileCacheBytes -= value.body.length;
-                }
-                if (this.fileCacheBytes + entry.body.length <= maxBytes) {
-                    this.fileCache.set(relativePath, entry);
-                    this.fileCacheBytes += entry.body.length;
-                }
-            }
-        }
-        return entry;
-    }
     cacheControlFor(ctx, relativePath) {
         const cacheOption = this.options.cacheControl;
         if (typeof cacheOption === "function")

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,7 +1,9 @@
 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";
-import { type LambderTemplateData } from "./LambderTemplatingEngine.js";
+import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
 import type { LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type { LambderApiResponse, LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type LambderResponseOptions = {
@@ -24,18 +26,32 @@ export type LambderRawResponseInit = {
     etag?: boolean | "auto";
 };
 export default class LambderResponseBuilder<TResponse = any> {
-    protected publicPath: string;
+    protected files: LambderFiles | null;
     protected apiVersion: string | null;
     protected ctx?: LambderRenderContext;
-    constructor({ publicPath, apiVersion, ctx }: {
-        publicPath: string;
+    constructor({ files, apiVersion, ctx }: {
+        files?: LambderFiles | null;
         apiVersion?: string | null;
         ctx?: LambderRenderContext;
     });
     private buildResponse;
-    private resolvePublicFilePath;
+    /** The instance's file reader, which res.file and res.templateFile need. */
+    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;
@@ -47,15 +63,15 @@ export default class LambderResponseBuilder<TResponse = any> {
     redirect(url: string, statusCode?: HttpStatusCode, options?: LambderResponseOptions): LambderResponse;
     versionExpired(options?: LambderResponseOptions): LambderResponse;
     fileBase64(fileBase64: string, mimeType: string, options?: LambderResponseOptions): LambderResponse;
-    file(filePath: string, options?: LambderResponseOptions & {
-        fallback?: string;
-    }): Promise<LambderResponse>;
+    /** A file from the files source as a response; 404 when there is none. */
+    file(filePath: string, options?: LambderResponseOptions): Promise<LambderResponse>;
     /**
-     * Render an HTML file under publicPath through LambderTemplatingEngine
-     * (comment-based slots/conditionals) and return it as an HTML response.
-     * The compiled template is cached across warm invocations; a missing file
-     * throws (it is a server-side configuration error, not a client 404).
-     * Set htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * Render an HTML file from the files source through
+     * LambderTemplatingEngine (comment-based slots/conditionals) and return
+     * it as an HTML response. The compiled template is cached on the
+     * instance across warm invocations; a missing file throws (it is a
+     * server-side configuration error, not a client 404). Set
+     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
      */
     templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
         htmlVirtualSlots?: boolean;

package/dist/core/LambderResponseBuilder.js

@@ -1,15 +1,11 @@
-import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "../shared/node-polyfills.js";
+import { serializeCookie, serializeClearCookie } from "./LambderCookie.js";
 import { LambderResponse } from "./LambderResponse.js";
-import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
-// Compiled templates survive across requests (builder instances are per-request).
-const templateFileCache = new Map();
 export default class LambderResponseBuilder {
-    publicPath;
+    files;
     apiVersion;
     ctx;
-    constructor({ publicPath, apiVersion, ctx }) {
-        this.publicPath = publicPath;
+    constructor({ files, apiVersion, ctx }) {
+        this.files = files ?? null;
         this.apiVersion = apiVersion ?? null;
         this.ctx = ctx;
     }
@@ -30,25 +26,12 @@ export default class LambderResponseBuilder {
             response.setHeader("Cache-Control", options.cacheControl);
         return response;
     }
-    async resolvePublicFilePath(filePath) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            return null;
-        const publicPath = path.resolve(this.publicPath);
-        const normalizedFilePath = filePath.startsWith('/') ? filePath.slice(1) : filePath;
-        const absolutePath = path.resolve(publicPath, normalizedFilePath);
-        if (absolutePath !== publicPath && !absolutePath.startsWith(publicPath + path.sep))
-            return null;
-        try {
-            const stat = await fs.promises.stat(absolutePath);
-            return stat.isFile() ? absolutePath : null;
-        }
-        catch {
-            return null;
-        }
+    /** The instance's file reader, which res.file and res.templateFile need. */
+    requireFiles(method) {
+        if (!this.files)
+            throw new Error(`${method} requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))`);
+        return this.files;
     }
-    ;
     addHeader(key, value) {
         if (!this.ctx)
             throw new Error(".addHeader function is not available within this hook");
@@ -63,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");
@@ -130,41 +136,24 @@ export default class LambderResponseBuilder {
         return response;
     }
     ;
+    /** A file from the files source as a response; 404 when there is none. */
     async file(filePath, options) {
-        let resolvedPath = await this.resolvePublicFilePath(filePath);
-        let effectivePath = filePath;
-        if (!resolvedPath && options?.fallback) {
-            resolvedPath = await this.resolvePublicFilePath(options.fallback);
-            effectivePath = options.fallback;
-        }
-        if (!resolvedPath) {
-            return this.status404("File not found", { etag: false });
-        }
-        const fs = await getFS();
-        if (!fs)
+        const file = await this.requireFiles("res.file").read(filePath);
+        if (!file)
             return this.status404("File not found", { etag: false });
-        const body = await fs.promises.readFile(resolvedPath);
-        const mimeType = mimeTypeResolver.lookup(effectivePath) || "application/octet-stream";
-        return this.buildResponse(200, mimeType, body, options);
+        return this.buildResponse(200, file.mimeType, file.body, options);
     }
     ;
     /**
-     * Render an HTML file under publicPath through LambderTemplatingEngine
-     * (comment-based slots/conditionals) and return it as an HTML response.
-     * The compiled template is cached across warm invocations; a missing file
-     * throws (it is a server-side configuration error, not a client 404).
-     * Set htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * Render an HTML file from the files source through
+     * LambderTemplatingEngine (comment-based slots/conditionals) and return
+     * it as an HTML response. The compiled template is cached on the
+     * instance across warm invocations; a missing file throws (it is a
+     * server-side configuration error, not a client 404). Set
+     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
      */
     async templateFile(filePath, data, options) {
-        const resolvedPath = await this.resolvePublicFilePath(filePath);
-        if (!resolvedPath)
-            throw new Error(`templateFile: file not found under publicPath: ${filePath}`);
-        const cacheKey = `${resolvedPath}|${options?.htmlVirtualSlots ? "v" : ""}`;
-        let template = templateFileCache.get(cacheKey);
-        if (!template) {
-            template = await LambderTemplatingEngine.fromFile(resolvedPath, { htmlVirtualSlots: options?.htmlVirtualSlots });
-            templateFileCache.set(cacheKey, template);
-        }
+        const template = await this.requireFiles("res.templateFile").template(filePath, { htmlVirtualSlots: options?.htmlVirtualSlots });
         return this.buildResponse(200, "text/html; charset=utf-8", template.render(data), options);
     }
     ;

package/dist/core/LambderTemplatingEngine.d.ts

@@ -4,7 +4,7 @@ import { type LambderHtmlValue } from "../shared/LambderHtml.js";
  *
  * Fully standalone: it has no dependency on Lambder routing or file serving,
  * and can template any HTML: app shells, emails, error pages. res.templateFile
- * uses it internally to render HTML files from publicPath per request.
+ * uses it internally to render HTML files from the files source per request.
  *
  * Every construct is an HTML comment. That is the whole point: templates
  * survive HTML build pipelines (e.g. Vite) untouched, and are invisible in the

package/dist/index.d.ts

@@ -15,8 +15,10 @@ export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
 export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.js";
-export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
-export type { LambderPublicFilesOptions, LambderPublicFileSource, LambderPublicFile } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
+export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
+export type { LambderFileSource, LambderFile, LambderFilesOption, LambderFileMemoryCacheOption, LambderReadFile } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
@@ -39,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

@@ -15,7 +15,8 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 // Comment-based HTML templating engine (build-pipeline-safe slots and conditionals, standalone)
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
-export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
@@ -31,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);
         }
     }