lambder 4.4.1 → 4.6.1

package/Readme.md

@@ -2,6 +2,15 @@
 
 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).
+
 **New in 4.4:**
 
 - **`guardInputsProvider`** on `LambderCaller`: supply guardInput-mode guard values for every call from one place (the organization the UI is on, a device token) instead of at each call site; per-call `guardInputs` merge on top. Name the covered guards in the caller's second type parameter, `new LambderCaller<Contract, "orgPermission">({ guardInputsProvider, ... })`: calls to APIs whose guardInput guards are all covered no longer require the options argument, uncovered ones (a Turnstile token) still do, and naming guards makes the provider itself mandatory.
@@ -92,7 +101,7 @@ would silently widen the inferred policy types, which is why the curried
 creator is the canonical entry.
 
 ```typescript
-import { initLambder } from 'lambder';
+import { initLambder, LambderLocalFileSource } from 'lambder';
 import { z } from 'zod';
 import * as path from 'path';
 
@@ -100,7 +109,7 @@ interface SessionData { userId: string; }
 
 const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
-    publicPath: path.resolve(`./public`),
+    files: new LambderLocalFileSource({ root: path.resolve(`./public`) }),
     session: {
         tableName: "website-session",
         tableRegion: "us-east-1",
@@ -166,9 +175,9 @@ lambder
     .addRoute({ path: "/stripe-webhook", method: "POST" }, (ctx, res) => {
         return res.json({ received: true });
     })
-    // Serve real files (from publicPath by default; see "Public file sources"
-    // below for S3/R2). This is a terminal fallback slot, NOT a catch-all
-    // route, so it can never shadow routes registered after it.
+    // Serve real files from the files source (see "Public file sources"
+    // below). This is a terminal fallback slot, NOT a catch-all route, so it
+    // can never shadow routes registered after it.
     .servePublicFiles()
     // Serve the app shell for GET/HEAD page requests nothing else handled
     // (see "Hosting a frontend build" below).
@@ -216,7 +225,7 @@ For larger applications, split your APIs into separate modules:
 ```typescript
 // user-api.ts
 import { z } from "zod";
-import Lambder from "lambder";
+import Lambder, { LambderLocalFileSource } from "lambder";
 
 export const userApi = <T>(l: Lambder<T>) => {
     return l
@@ -237,7 +246,7 @@ export const userApi = <T>(l: Lambder<T>) => {
 // index.ts
 import { userApi } from "./user-api";
 
-const lambder = new Lambder({ publicPath: './public' })
+const lambder = new Lambder({ files: new LambderLocalFileSource({ root: './public' }) })
     .use(userApi);
 
 export type ApiContractType = typeof lambder.ApiContract;
@@ -331,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.
@@ -443,27 +458,31 @@ Lambder has no SPA-specific machinery; hosting a frontend build is a recipe buil
 
 #### Public file sources
 
-`servePublicFiles` reads through a `LambderPublicFileSource`, an object with one method, `read(relativePath)`, returning `{ body, mimeType? }` or `null` (the request then falls through). The handler does everything else for every source: traversal check, memory cache for warm invocations, mime fallback from the extension, Cache-Control (immutable for content-hashed names), ETag and compression. Built in:
+The `files` option at creation is a `LambderFileSource`, an object with one method, `read(relativePath)`, returning `{ body, mimeType? }` or `null`. The instance owns one reader over it, `lambder.files`, and `servePublicFiles`, `serveIndexHtml`, `res.file` and `res.templateFile` all go through that reader, which does everything else for every source: traversal check, in-memory file cache for warm invocations (default 32MB, 2MB per file), compiled-template cache, mime fallback from the extension. Cache-Control (immutable for content-hashed names), ETag and compression are applied by the serving slot and the response pipeline. Built in:
 
 ```typescript
-// Default: the publicPath folder bundled with the deployment.
-lambder.servePublicFiles();
+// A folder, typically the build output bundled with the deployment.
+initLambder().create({ files: new LambderLocalFileSource({ root: path.resolve("./public") }) });
 
 // S3. @aws-sdk/client-s3 is an optional peer dependency, loaded on first read.
-lambder.servePublicFiles({
-    source: new LambderS3FileSource({ bucket: "myapp-web", prefix: "v42/", clientConfig: { region: "eu-central-1" } }),
+initLambder().create({
+    files: new LambderS3FileSource({ bucket: "myapp-web", prefix: "v42/", clientConfig: { region: "eu-central-1" } }),
 });
 
 // Cloudflare R2, or any S3-compatible store: point the client at its endpoint.
-lambder.servePublicFiles({
-    source: new LambderS3FileSource({
+initLambder().create({
+    files: new LambderS3FileSource({
         bucket: "myapp-web",
         clientConfig: { region: "auto", endpoint: "https://<account>.r2.cloudflarestorage.com", credentials: { accessKeyId, secretAccessKey } },
     }),
 });
 
 // Anything else: implement read().
-lambder.servePublicFiles({ source: { read: async (relativePath) => myStore.get(relativePath) } });
+initLambder().create({ files: { read: async (relativePath) => myStore.get(relativePath) } });
+
+// The in-memory file cache, tuned or off, beside any source.
+initLambder().create({ files: { source: new LambderS3FileSource({ bucket: "myapp-web" }), memoryCache: { maxBytes: 64_000_000, maxFileBytes: 4_000_000 } } });
+initLambder().create({ files: { source: new LambderLocalFileSource({ root }), memoryCache: false } });
 ```
 
 A missing S3 object reads as null; grant `s3:ListBucket` besides `s3:GetObject`, otherwise S3 answers a missing key with AccessDenied, which propagates as an error instead of falling through. The object's Content-Type is used unless it is a generic octet-stream, in which case the extension decides. Lambda's ~6MB response cap still applies to anything proxied this way: redirect large downloads to the bucket or CDN URL instead of serving them.
@@ -496,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 | - |
@@ -509,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/Lambder.d.ts

@@ -9,6 +9,7 @@ import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionM
 import type { LambderCompressionOption } from "../stores/LambderDdbCompression.js";
 import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
+import { LambderFiles, type LambderFilesOption } from "./LambderFiles.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderRateLimitOption } from "../policies/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../policies/LambderApiIdempotency.js";
@@ -107,7 +108,14 @@ export type LambderSessionOptions<TSessionData = any> = {
  * instance type ever needs a name.
  */
 export type LambderCreateOptions<TSessionData = any> = {
-    publicPath?: string;
+    /**
+     * Where the app's files come from, for servePublicFiles, serveIndexHtml,
+     * res.file and res.templateFile: a LambderLocalFileSource over a folder
+     * (the build output bundled with the deployment), a LambderS3FileSource
+     * (S3, R2), or any LambderFileSource; or `{ source, memoryCache }` to
+     * tune or disable the in-memory file cache. Required by those features.
+     */
+    files?: LambderFilesOption;
     apiPath?: string;
     apiVersion?: string;
     /** Automatic gzip for compressible responses. `true` (the default) is `{ minBytes: 860 }`; `false` disables it. */
@@ -153,7 +161,8 @@ export type LambderCreateOptions<TSessionData = any> = {
 export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
-    publicPath: string;
+    /** The instance's file reader (source + caches), or null without the files option. */
+    files: LambderFiles | null;
     /**
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
@@ -194,9 +203,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     setSessionExpiredRouteHandler(handler: FallbackHandlerFunction): this;
     /**
      * Terminal public-file layer. Runs only when no route matched, so it can
-     * never shadow routes registered after it. Serves files from `source`
-     * (default: the publicPath folder; also LambderS3FileSource for S3 and
-     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * never shadow routes registered after it. Serves files from the `files`
+     * source configured at creation, traversal-safe, mime-typed,
      * memory-cached, with the immutable-cache heuristic for content-hashed
      * assets; when the source has no such file the request falls through to
      * setRouteFallbackHandler, where the app decides what remains (e.g.
@@ -209,8 +217,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * gone; everything left is an app route (option `skipFilePaths` opts back
      * into 404ing dotted paths). Only configured methods reach it, default
      * GET/HEAD. Gated-out requests fall through to setRouteFallbackHandler.
-     * Without a handler, publicPath/index.html is served via res.templateFile
-     * (markers optional) with no-cache.
+     * Without a handler, index.html from the files source is served via
+     * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler?: FallbackHandlerFunction, options?: LambderIndexHtmlOptions): this;
     /** Apply the serveIndexHtml gates; null means fall through. */

package/dist/core/Lambder.js

@@ -5,7 +5,8 @@ import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
-import { LambderPublicFilesHandler, LambderLocalFileSource } from "./LambderPublicFiles.js";
+import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
+import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
@@ -33,7 +34,8 @@ import { createContext, isV2HttpEvent } from "./LambderContext.js";
 export default class Lambder {
     apiPath;
     apiVersion;
-    publicPath;
+    /** The instance's file reader (source + caches), or null without the files option. */
+    files;
     /**
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
@@ -66,7 +68,7 @@ export default class Lambder {
     sessionTokenCookieKey = "LMDRSESSIONTKID";
     sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     constructor(options = {}) {
-        this.publicPath = options.publicPath || "/incorrect-path-not-found";
+        this.files = options.files ? new LambderFiles(options.files) : null;
         this.apiPath = options.apiPath ?? "/api";
         this.apiVersion = options.apiVersion ?? null;
         this.finalizeOptions = {
@@ -129,17 +131,17 @@ export default class Lambder {
     }
     /**
      * Terminal public-file layer. Runs only when no route matched, so it can
-     * never shadow routes registered after it. Serves files from `source`
-     * (default: the publicPath folder; also LambderS3FileSource for S3 and
-     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * never shadow routes registered after it. Serves files from the `files`
+     * source configured at creation, traversal-safe, mime-typed,
      * memory-cached, with the immutable-cache heuristic for content-hashed
      * assets; when the source has no such file the request falls through to
      * setRouteFallbackHandler, where the app decides what remains (e.g.
      * render an app shell with res.templateFile).
      */
     servePublicFiles(options = {}) {
-        const source = options.source ?? new LambderLocalFileSource({ root: this.publicPath });
-        this.publicFilesHandler = new LambderPublicFilesHandler(source, options);
+        if (!this.files)
+            throw new Error("servePublicFiles requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))");
+        this.publicFilesHandler = new LambderPublicFilesHandler(this.files, options);
         return this;
     }
     /**
@@ -148,8 +150,8 @@ export default class Lambder {
      * gone; everything left is an app route (option `skipFilePaths` opts back
      * into 404ing dotted paths). Only configured methods reach it, default
      * GET/HEAD. Gated-out requests fall through to setRouteFallbackHandler.
-     * Without a handler, publicPath/index.html is served via res.templateFile
-     * (markers optional) with no-cache.
+     * Without a handler, index.html from the files source is served via
+     * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler, options = {}) {
         this.indexHtmlConfig = { handler: handler ?? null, options };
@@ -331,7 +333,7 @@ export default class Lambder {
     }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
-            publicPath: this.publicPath,
+            files: this.files,
             apiVersion: this.apiVersion,
             ctx,
         });
@@ -339,7 +341,7 @@ export default class Lambder {
     ;
     getResolver(ctx) {
         return new LambderResolver({
-            publicPath: this.publicPath,
+            files: this.files,
             apiVersion: this.apiVersion,
             ctx,
         });

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/LambderFiles.d.ts

@@ -0,0 +1,85 @@
+import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+/** A file a source serves: its bytes, and its mime type when the source knows it (otherwise resolved from the extension). */
+export type LambderFile = {
+    body: Buffer;
+    mimeType?: string;
+};
+/**
+ * Where an app's files come from: the `files` option at creation, read by
+ * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike,
+ * through the instance's one reader (LambderFiles). Implement `read` over
+ * any backing store: LambderLocalFileSource (a folder), LambderS3FileSource
+ * (S3, or R2 and other S3-compatible stores), or your own. The reader does
+ * the rest for every source: traversal check, memory cache, mime fallback
+ * from the extension.
+ */
+export interface LambderFileSource {
+    /**
+     * The file at a relative path (no leading slash, no ".." segments: the
+     * reader rejects those before calling), or null when there is no such
+     * file, which lets a request fall through to the route fallback.
+     */
+    read(relativePath: string): Promise<LambderFile | null>;
+}
+/** In-memory cache of files for warm invocations. Default: { maxBytes: 32MB, maxFileBytes: 2MB }. false disables it. */
+export type LambderFileMemoryCacheOption = false | {
+    maxBytes?: number;
+    maxFileBytes?: number;
+};
+/** The `files` option at creation: a source, or a source with its memory cache tuned or off. */
+export type LambderFilesOption = LambderFileSource | {
+    source: LambderFileSource;
+    memoryCache?: LambderFileMemoryCacheOption;
+};
+/** A file as the reader hands it out: path normalized, mime type resolved. */
+export type LambderReadFile = {
+    body: Buffer;
+    mimeType: string;
+    relativePath: string;
+};
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root.
+ */
+export declare class LambderLocalFileSource implements LambderFileSource {
+    private root;
+    constructor({ root }: {
+        root: string;
+    });
+    read(relativePath: string): Promise<LambderFile | null>;
+}
+/**
+ * The path a source is asked for: leading slash stripped, traversal
+ * rejected; null for a path that names no file (empty, or a directory).
+ */
+export declare const toRelativePath: (target: string) => string | null;
+/**
+ * The app's file reader, owned by the Lambder instance: one source, one
+ * path rule, one memory cache and one compiled-template cache, shared by
+ * every feature that reads files. Both caches live as long as the instance,
+ * i.e. across warm invocations.
+ */
+export declare class LambderFiles {
+    private source;
+    private cache;
+    private cacheBytes;
+    private maxBytes;
+    private maxFileBytes;
+    private templates;
+    constructor(option: LambderFilesOption);
+    /**
+     * The file at a request or handler path (leading slash optional), mime
+     * type resolved; null when the path is invalid or the source has none.
+     */
+    read(path: string): Promise<LambderReadFile | null>;
+    /**
+     * The compiled template for an HTML file, compiled once per instance.
+     * A missing file throws: it is a server-side configuration error, not a
+     * client 404.
+     */
+    template(path: string, options?: {
+        htmlVirtualSlots?: boolean;
+    }): Promise<LambderTemplatingEngine>;
+    /** Cache small files within the byte budget, evicting the oldest entries first. */
+    private remember;
+}

package/dist/core/LambderFiles.js

@@ -0,0 +1,116 @@
+import mimeTypeResolver from "mime-types";
+import { getFS, getPath } from "../shared/node-polyfills.js";
+import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+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.
+ */
+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) };
+    }
+}
+/**
+ * The path a source is asked for: leading slash stripped, traversal
+ * rejected; null for a path that names no file (empty, or a directory).
+ */
+export 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;
+};
+/**
+ * The app's file reader, owned by the Lambder instance: one source, one
+ * path rule, one memory cache and one compiled-template cache, shared by
+ * every feature that reads files. Both caches live as long as the instance,
+ * i.e. across warm invocations.
+ */
+export class LambderFiles {
+    source;
+    cache;
+    cacheBytes = 0;
+    maxBytes;
+    maxFileBytes;
+    templates = new Map();
+    constructor(option) {
+        const { source, memoryCache } = "source" in option ? option : { source: option, memoryCache: undefined };
+        this.source = source;
+        this.cache = memoryCache === false ? null : new Map();
+        this.maxBytes = memoryCache === false ? 0 : (memoryCache?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES);
+        this.maxFileBytes = memoryCache === false ? 0 : (memoryCache?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES);
+    }
+    /**
+     * The file at a request or handler path (leading slash optional), mime
+     * type resolved; null when the path is invalid or the source has none.
+     */
+    async read(path) {
+        const relativePath = toRelativePath(path);
+        if (relativePath === null)
+            return null;
+        const cached = this.cache?.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",
+            relativePath,
+        };
+        this.remember(entry);
+        return entry;
+    }
+    /**
+     * The compiled template for an HTML file, compiled once per instance.
+     * A missing file throws: it is a server-side configuration error, not a
+     * client 404.
+     */
+    async template(path, options = {}) {
+        const key = `${toRelativePath(path)}|${options.htmlVirtualSlots ? "v" : ""}`;
+        const cached = this.templates.get(key);
+        if (cached)
+            return cached;
+        const file = await this.read(path);
+        if (!file)
+            throw new Error(`templateFile: file not found in the files source: ${path}`);
+        const template = new LambderTemplatingEngine(file.body.toString("utf8"), { htmlVirtualSlots: options.htmlVirtualSlots });
+        this.templates.set(key, template);
+        return template;
+    }
+    /** Cache small files within the byte budget, evicting the oldest entries first. */
+    remember(entry) {
+        if (!this.cache || entry.body.length > this.maxFileBytes)
+            return;
+        for (const [key, value] of this.cache) {
+            if (this.cacheBytes + entry.body.length <= this.maxBytes)
+                break;
+            this.cache.delete(key);
+            this.cacheBytes -= value.body.length;
+        }
+        if (this.cacheBytes + entry.body.length <= this.maxBytes) {
+            this.cache.set(entry.relativePath, entry);
+            this.cacheBytes += entry.body.length;
+        }
+    }
+}