lambder 4.3.2 → 4.5.1

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;
+        }
+    }
+}

package/dist/core/LambderPublicFiles.d.ts

@@ -1,23 +1,20 @@
 import type { LambderRenderContext } from "./LambderContext.js";
+import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse } from "./LambderResponse.js";
+/** Per-registration policy of servePublicFiles: how a request maps to a file and how the response is cached. */
 export type LambderPublicFilesOptions = {
     /**
-     * Map the request to a file path under publicPath (app-owned logic, e.g.
-     * per-tenant roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
+     * Map the request to a file path (app-owned logic, e.g. per-tenant
+     * roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
      * null/undefined to skip. Default: (ctx) => ctx.path.
      */
     path?: (ctx: LambderRenderContext) => string | null | undefined;
-    /** Cache-Control for served files. Default: "public, max-age=3600". */
-    cacheControl?: string | ((ctx: LambderRenderContext, filePath: string) => string);
+    /** Cache-Control for served files; the function receives the relative file path. Default: "public, max-age=3600". */
+    cacheControl?: string | ((ctx: LambderRenderContext, relativePath: string) => string);
     /** Filenames matching this get immutableCacheControl. Default: content-hash heuristic. Set false to disable. */
     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).
@@ -27,21 +24,16 @@ export type LambderPublicFilesOptions = {
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves real files under publicPath (traversal-safe, mime-typed,
- * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the file does not exist.
+ * 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 publicPath;
+    private files;
     private options;
-    private fileCache;
-    private fileCacheBytes;
-    constructor(publicPath: string, options: LambderPublicFilesOptions);
+    constructor(files: LambderFiles, options: LambderPublicFilesOptions);
     /** Serve the mapped file, or return null to fall through. */
     handle(ctx: LambderRenderContext): Promise<LambderResponse | null>;
-    /** Join base+target and require the result to stay under base. */
-    private resolveSafe;
-    /** Read a file, caching small files in memory for warm invocations. */
-    private readFileCached;
     private cacheControlFor;
 }

package/dist/core/LambderPublicFiles.js

@@ -1,43 +1,30 @@
-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;
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves real files under publicPath (traversal-safe, mime-typed,
- * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the file does not exist.
+ * 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 {
-    publicPath;
+    files;
     options;
-    fileCache = new Map();
-    fileCacheBytes = 0;
-    constructor(publicPath, options) {
-        this.publicPath = publicPath;
+    constructor(files, options) {
+        this.files = files;
         this.options = options;
     }
     /** Serve the mapped file, or return null to fall through. */
     async handle(ctx) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            throw new Error("servePublicFiles requires a Node.js environment.");
         const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
         if (!mappedPath)
             return null;
-        const publicRoot = path.resolve(this.publicPath);
-        const filePath = this.resolveSafe(path, publicRoot, mappedPath);
-        if (!filePath)
-            return null;
-        const file = await this.readFileCached(fs, filePath);
+        const file = await this.files.read(mappedPath);
         if (!file)
             return null;
         const compressOption = this.options.compress;
@@ -46,61 +33,20 @@ export class LambderPublicFilesHandler {
             statusCode: 200,
             headers: {
                 "Content-Type": file.mimeType,
-                "Cache-Control": this.cacheControlFor(ctx, filePath),
+                "Cache-Control": this.cacheControlFor(ctx, file.relativePath),
             },
             body: file.body,
             compress,
         });
     }
-    /** Join base+target and require the result to stay under base. */
-    resolveSafe(path, base, target) {
-        if (target.split("/").some((segment) => segment === ".."))
-            return null;
-        const normalizedTarget = target.startsWith("/") ? target.slice(1) : target;
-        const absolute = path.resolve(base, normalizedTarget);
-        if (absolute !== base && !absolute.startsWith(base + path.sep))
-            return null;
-        return absolute;
-    }
-    /** Read a file, caching small files in memory for warm invocations. */
-    async readFileCached(fs, filePath) {
-        const cached = this.fileCache.get(filePath);
-        if (cached)
-            return cached;
-        const stat = await fs.promises.stat(filePath).catch(() => null);
-        if (!stat?.isFile())
-            return null;
-        const body = await fs.promises.readFile(filePath);
-        const mimeType = mimeTypeResolver.lookup(filePath) || "application/octet-stream";
-        const entry = { body, mimeType };
-        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 (body.length <= maxFileBytes) {
-                // Evict oldest entries until the new file fits the budget.
-                for (const [key, value] of this.fileCache) {
-                    if (this.fileCacheBytes + body.length <= maxBytes)
-                        break;
-                    this.fileCache.delete(key);
-                    this.fileCacheBytes -= value.body.length;
-                }
-                if (this.fileCacheBytes + body.length <= maxBytes) {
-                    this.fileCache.set(filePath, entry);
-                    this.fileCacheBytes += body.length;
-                }
-            }
-        }
-        return entry;
-    }
-    cacheControlFor(ctx, filePath) {
+    cacheControlFor(ctx, relativePath) {
         const cacheOption = this.options.cacheControl;
         if (typeof cacheOption === "function")
-            return cacheOption(ctx, filePath);
+            return cacheOption(ctx, relativePath);
         const immutablePattern = this.options.immutablePattern === false
             ? null
             : (this.options.immutablePattern ?? DEFAULT_IMMUTABLE_PATTERN);
-        if (immutablePattern && immutablePattern.test(filePath)) {
+        if (immutablePattern && immutablePattern.test(relativePath)) {
             return this.options.immutableCacheControl ?? DEFAULT_IMMUTABLE_CACHE_CONTROL;
         }
         return cacheOption ?? DEFAULT_CACHE_CONTROL;

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,7 +1,8 @@
 import type { LambderRenderContext } from "./LambderContext.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,16 +25,17 @@ 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;
     logToApiResponse(input: any): void;
@@ -47,15 +49,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,10 @@
-import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "../shared/node-polyfills.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 +25,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");
@@ -130,41 +112,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) {
+        const file = await this.requireFiles("res.file").read(filePath);
+        if (!file)
             return this.status404("File not found", { etag: false });
-        }
-        const fs = await getFS();
-        if (!fs)
-            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

@@ -2,7 +2,7 @@ import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
@@ -17,6 +17,10 @@ export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/Lam
 export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.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";
 export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
 export type { LambderCompressionOption, LambderCompressionConfig } from "./stores/LambderDdbCompression.js";

package/dist/index.js

@@ -16,6 +16,8 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
 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)
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";

package/dist/session/LambderSessionController.d.ts

@@ -49,6 +49,13 @@ export default class LambderSessionController<TSessionData = any> {
      * session and touches no cookies, so it works on any subject.
      */
     deleteSessionAllByKey(sessionKey: string): Promise<void>;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: the way to apply a change to
+     * a subject's roles or permissions immediately, without logging them
+     * out. Needs no fetched session; requires dataRefresh.
+     */
+    expireSessionDataAllByKey(sessionKey: string): Promise<void>;
     endSession(): Promise<void>;
     endSessionAll(): Promise<void>;
 }

package/dist/session/LambderSessionController.js

@@ -151,6 +151,16 @@ export default class LambderSessionController {
         await this.lambderSessionManager.deleteSessionAllByKey(sessionKey);
     }
     ;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: the way to apply a change to
+     * a subject's roles or permissions immediately, without logging them
+     * out. Needs no fetched session; requires dataRefresh.
+     */
+    async expireSessionDataAllByKey(sessionKey) {
+        await this.lambderSessionManager.expireSessionDataAllByKey(sessionKey);
+    }
+    ;
     async endSession() {
         if (!this.ctx.session)
             throw new Error("Session not found.");

package/dist/session/LambderSessionManager.d.ts

@@ -111,6 +111,7 @@ export default class LambderSessionManager {
      */
     private ddbPutItem;
     private ddbDeleteItem;
+    /** Sort keys of every session under a partition (the callers only need the keys). */
     private ddbQueryAllByPartitionKey;
     private ddbDeleteAllByPartitionKey;
     createSession(sessionKey: string, data?: any, ttlInSeconds?: number, options?: {
@@ -135,5 +136,15 @@ export default class LambderSessionManager {
      * session record.
      */
     deleteSessionAllByKey(sessionKey: string): Promise<boolean>;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: "this subject's roles or
+     * permissions changed, apply it now", without logging the subject out
+     * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
+     * dataExpiresAt only, conditionally on the record still existing, so it
+     * neither resurrects a session deleted in between nor overwrites a
+     * concurrent write. Requires dataRefresh to be configured.
+     */
+    expireSessionDataAllByKey(sessionKey: string): Promise<boolean>;
     regenerateSession(session: LambderSessionContext): Promise<LambderCreatedSession>;
 }

package/dist/session/LambderSessionManager.js

@@ -1,6 +1,6 @@
 import crypto from "crypto";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand } from "@aws-sdk/lib-dynamodb";
+import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
 import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "../stores/LambderDdbCompression.js";
 /**
  * Session compression defaults: every record compressed (see
@@ -108,11 +108,13 @@ export default class LambderSessionManager {
         return await this.ddbDocumentClient.send(new DeleteCommand({ TableName: this.tableName, Key: key, }));
     }
     ;
+    /** Sort keys of every session under a partition (the callers only need the keys). */
     async ddbQueryAllByPartitionKey(partitionValue) {
         const params = {
             TableName: this.tableName,
             KeyConditionExpression: "#pk = :pv",
-            ExpressionAttributeNames: { "#pk": this.partitionKey },
+            ProjectionExpression: "#sk",
+            ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
             ExpressionAttributeValues: { ":pv": partitionValue },
         };
         const queryResults = [];
@@ -341,6 +343,40 @@ export default class LambderSessionManager {
         return true;
     }
     ;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: "this subject's roles or
+     * permissions changed, apply it now", without logging the subject out
+     * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
+     * dataExpiresAt only, conditionally on the record still existing, so it
+     * neither resurrects a session deleted in between nor overwrites a
+     * concurrent write. Requires dataRefresh to be configured.
+     */
+    async expireSessionDataAllByKey(sessionKey) {
+        if (!this.dataRefresh)
+            throw new Error("dataRefresh is not configured. Pass session.dataRefresh at creation to enable.");
+        const partitionValue = this.sessionUserKeyHasher(sessionKey);
+        const now = Math.floor(Date.now() / 1000);
+        for (const item of await this.ddbQueryAllByPartitionKey(partitionValue)) {
+            try {
+                await this.ddbDocumentClient.send(new UpdateCommand({
+                    TableName: this.tableName,
+                    Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] },
+                    UpdateExpression: "SET #dataExpiresAt = :now",
+                    ConditionExpression: "attribute_exists(#sk)",
+                    ExpressionAttributeNames: { "#dataExpiresAt": "dataExpiresAt", "#sk": this.sortKey },
+                    ExpressionAttributeValues: { ":now": now },
+                }));
+            }
+            catch (err) {
+                // Deleted between the query and the update: nothing left to expire.
+                if (err.name !== "ConditionalCheckFailedException")
+                    throw err;
+            }
+        }
+        return true;
+    }
+    ;
     async regenerateSession(session) {
         if (!session)
             throw new Error("Invalid session");

package/dist/stores/LambderS3FileSource.d.ts

@@ -0,0 +1,35 @@
+import type { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
+import type { LambderFile, LambderFileSource } from "../core/LambderFiles.js";
+export type LambderS3FileSourceOptions = {
+    bucket: string;
+    /** Literal key prefix the relative path is appended to, so include the trailing slash: "web/v42/". Default: none. */
+    prefix?: string;
+    /** A ready client, e.g. one shared with the rest of the app. */
+    client?: S3Client;
+    /**
+     * Otherwise the client is created from this on first read: `{ region }`
+     * for S3; for Cloudflare R2 or another S3-compatible store,
+     * `{ region: "auto", endpoint, credentials }`.
+     */
+    clientConfig?: S3ClientConfig;
+};
+/**
+ * Files from an S3 bucket, or any S3-compatible store such as Cloudflare
+ * R2 (pass its endpoint in clientConfig). Needs @aws-sdk/client-s3, an
+ * optional peer dependency loaded on first read, so apps that serve from a
+ * folder never load it. A missing object reads as null and the request
+ * falls through; grant s3:ListBucket besides s3:GetObject, otherwise S3
+ * answers a missing key with AccessDenied, which propagates as an error.
+ * An object's Content-Type is used unless it is a generic octet-stream, in
+ * which case the extension decides, as for local files.
+ */
+export declare class LambderS3FileSource implements LambderFileSource {
+    private readonly bucket;
+    private readonly prefix;
+    private readonly clientConfig;
+    private client;
+    private sdk;
+    constructor({ bucket, prefix, client, clientConfig }: LambderS3FileSourceOptions);
+    private loadSdk;
+    read(relativePath: string): Promise<LambderFile | null>;
+}