lambder 7.3.1 → 8.1.1

package/dist/stores/LambderMemoryUploadBucket.js

@@ -0,0 +1,219 @@
+import { assertObjectOptions, assertPinnedObjectKey, assertSignatureLifetime, } from "../shared/contracts/LambderUploadBucket.js";
+import { contentDispositionHeader } from "../shared/util/LambderContentDisposition.js";
+import { uploadObjectFormFields } from "../shared/wire/LambderUploadObjectFields.js";
+import { refuseUnacceptedUpload } from "../shared/wire/LambderUploadRefusal.js";
+import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
+/** The form field that names the ticket a post was signed with: the memory bucket's stand-in for S3's signed policy. */
+const TICKET_FIELD = "x-lambder-upload-ticket";
+/** The query parameter that names the link a download was issued with: the stand-in for S3's presigned query string. */
+const LINK_PARAMETER = "x-lambder-download-link";
+/**
+ * An upload bucket in memory (see LambderUploadBucket), for tests and the
+ * mock runtime.
+ *
+ * It holds a post to the rules S3 holds a presigned POST to: every field the
+ * ticket carries, each with the ticket's value, and no other, all ahead of
+ * the file (as S3 does, anything after the file is ignored); a ticket it
+ * issued and not yet expired; a body of exactly the size described; and bytes
+ * whose SHA-256 is the one described. It refuses otherwise with the status
+ * and the XML error S3 answers with (AccessDenied for a policy, and "Policy
+ * expired" for a late one, EntityTooSmall, EntityTooLarge, BadDigest), so any
+ * client, a LambderUploadRunner or another, takes the same path against it as
+ * against S3: an expired ticket is asked for again, a wrong file is refused.
+ * A download link reads the object until it expires.
+ *
+ * Storage requests reach it through handleStorageRequest(), which answers a
+ * fetch Request with a Response: lambderMockUploadMswHandler plugs that into
+ * MSW, and a test can route a stubbed fetch to it directly. Everything it
+ * uses is a web API (fetch's Request and Response, FormData, WebCrypto), so it
+ * runs in a browser, a service worker and Node alike.
+ */
+export class LambderMemoryUploadBucket {
+    /** Where tickets and download links point, always ending in a slash. */
+    baseUrl;
+    ticketLifetimeSeconds;
+    downloadLifetimeSeconds;
+    now;
+    objects = new Map();
+    tickets = new Map();
+    links = new Map();
+    constructor({ baseUrl, ticketLifetimeSeconds = 600, downloadLifetimeSeconds = 300, now = Date.now } = {}) {
+        assertSignatureLifetime(ticketLifetimeSeconds, "ticketLifetimeSeconds");
+        assertSignatureLifetime(downloadLifetimeSeconds, "downloadLifetimeSeconds");
+        const url = new URL(baseUrl ?? `https://upload-bucket-${crypto.randomUUID()}.invalid/`);
+        url.search = "";
+        url.hash = "";
+        this.baseUrl = url.href.endsWith("/") ? url.href : `${url.href}/`;
+        this.ticketLifetimeSeconds = ticketLifetimeSeconds;
+        this.downloadLifetimeSeconds = downloadLifetimeSeconds;
+        this.now = now;
+    }
+    async issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds = this.ticketLifetimeSeconds, object = {} }) {
+        assertPinnedObjectKey(objectKey);
+        assertSignatureLifetime(lifetimeSeconds, "lifetimeSeconds");
+        assertObjectOptions(object);
+        refuseUnacceptedUpload(uploadRule, fileFacts);
+        const ticketId = crypto.randomUUID();
+        const expiresAt = this.now() + lifetimeSeconds * 1000;
+        // The fields S3's ticket carries, so a client posts the same form to either.
+        const formFields = {
+            key: objectKey,
+            "Content-Type": fileFacts.mimeType,
+            "x-amz-checksum-algorithm": "SHA256",
+            "x-amz-checksum-sha256": fileFacts.sha256Base64,
+            ...uploadObjectFormFields(object),
+            [TICKET_FIELD]: ticketId,
+        };
+        this.tickets.set(ticketId, { objectKey, mimeType: fileFacts.mimeType, byteSize: fileFacts.byteSize, sha256Base64: fileFacts.sha256Base64, expiresAt, formFields, object });
+        return { uploadUrl: this.baseUrl, formFields, expiresAt };
+    }
+    async verifyUploadedObject({ objectKey, fileFacts }) {
+        const object = this.objects.get(objectKey);
+        if (!object)
+            return { verified: false, reason: "objectMissing" };
+        const matches = object.body.byteLength === fileFacts.byteSize && object.sha256Base64 === fileFacts.sha256Base64;
+        return matches ? { verified: true } : { verified: false, reason: "factsMismatch" };
+    }
+    async issueDownloadUrl({ objectKey, lifetimeSeconds = this.downloadLifetimeSeconds, contentDisposition }) {
+        assertSignatureLifetime(lifetimeSeconds, "lifetimeSeconds");
+        const linkId = crypto.randomUUID();
+        this.links.set(linkId, { objectKey, expiresAt: this.now() + lifetimeSeconds * 1000, contentDisposition });
+        // Appended rather than resolved against the base, so a key that starts
+        // with a slash stays under it.
+        const url = new URL(`${this.baseUrl}${encodeObjectKey(objectKey)}`);
+        url.searchParams.set(LINK_PARAMETER, linkId);
+        return url.href;
+    }
+    async readObject(objectKey) {
+        const object = this.objects.get(objectKey);
+        if (!object)
+            throw new Error(`LambderMemoryUploadBucket.readObject: nothing is stored under ${objectKey}`);
+        return object.body.slice();
+    }
+    async writeObject({ objectKey, body, mimeType, sha256Base64, object = {} }) {
+        assertObjectOptions(object);
+        const computed = await sha256Base64Of(body);
+        // S3 refuses a body whose checksum is not the one sent (BadDigest), and so does this.
+        if (sha256Base64 !== undefined && sha256Base64 !== computed) {
+            throw new Error(`LambderMemoryUploadBucket.writeObject: the SHA-256 given for ${objectKey} is not the body's`);
+        }
+        this.objects.set(objectKey, { body: body.slice(), mimeType, sha256Base64: computed, object });
+    }
+    async copyObject({ fromObjectKey, toObjectKey }) {
+        const object = this.objects.get(fromObjectKey);
+        if (!object)
+            throw new Error(`LambderMemoryUploadBucket.copyObject: nothing is stored under ${fromObjectKey}`);
+        this.objects.set(toObjectKey, { ...object, body: object.body.slice() });
+    }
+    async deleteObject(objectKey) {
+        this.objects.delete(objectKey);
+    }
+    /** The keys that hold an object, sorted, for a test to assert on. */
+    listObjectKeys() {
+        return [...this.objects.keys()].sort();
+    }
+    /** What is held under a key (its facts, tags, metadata and headers), for a test to assert on; null when nothing is. */
+    inspectObject(objectKey) {
+        const stored = this.objects.get(objectKey);
+        return stored ? { byteSize: stored.body.byteLength, mimeType: stored.mimeType, sha256Base64: stored.sha256Base64, ...stored.object } : null;
+    }
+    /** Forgets every object, ticket and link. */
+    reset() {
+        this.objects.clear();
+        this.tickets.clear();
+        this.links.clear();
+    }
+    /**
+     * Answers a request to storage the way S3 answers it: a post under a
+     * ticket stores its file, a GET or HEAD through a download link reads an
+     * object. A request outside baseUrl answers null, for the caller to hand
+     * on.
+     */
+    async handleStorageRequest(request) {
+        const url = new URL(request.url);
+        if (!`${url.origin}${url.pathname}`.startsWith(this.baseUrl))
+            return null;
+        let objectKey;
+        try {
+            objectKey = decodeObjectKey(url.pathname.slice(new URL(this.baseUrl).pathname.length));
+        }
+        catch {
+            return storageError(400, "InvalidURI", "Couldn't parse the specified URI.");
+        }
+        if (request.method === "POST" && objectKey === "")
+            return this.acceptUpload(request);
+        if (request.method === "GET" || request.method === "HEAD")
+            return this.serveDownload(objectKey, url.searchParams.get(LINK_PARAMETER), request.method === "HEAD");
+        return storageError(405, "MethodNotAllowed", "The specified method is not allowed against this resource.");
+    }
+    async acceptUpload(request) {
+        let form;
+        try {
+            form = await request.formData();
+        }
+        catch {
+            return storageError(400, "MalformedPOSTRequest", "The body of your POST request is not well-formed multipart/form-data.");
+        }
+        // S3 reads the form up to the file and ignores everything after it.
+        const fields = new Map();
+        let file;
+        for (const [name, value] of form.entries()) {
+            if (typeof value !== "string") {
+                if (name === "file") {
+                    file = value;
+                    break;
+                }
+                continue;
+            }
+            fields.set(name, value);
+        }
+        if (!file)
+            return storageError(400, "InvalidArgument", "POST requires exactly one file upload per request.");
+        const ticketId = fields.get(TICKET_FIELD);
+        const ticket = ticketId === undefined ? undefined : this.tickets.get(ticketId);
+        if (!ticket)
+            return storageError(403, "AccessDenied", "Invalid according to Policy: Policy Condition failed");
+        if (this.now() >= ticket.expiresAt)
+            return storageError(403, "AccessDenied", "Invalid according to Policy: Policy expired.");
+        const extra = [...fields.keys()].filter((name) => !(name in ticket.formFields));
+        if (extra.length)
+            return storageError(403, "AccessDenied", `Invalid according to Policy: Extra input fields: ${extra.join(", ")}`);
+        const pinned = Object.entries(ticket.formFields).every(([name, value]) => fields.get(name) === value);
+        if (!pinned)
+            return storageError(403, "AccessDenied", "Invalid according to Policy: Policy Condition failed");
+        const body = new Uint8Array(await file.arrayBuffer());
+        if (body.byteLength < ticket.byteSize)
+            return storageError(400, "EntityTooSmall", "Your proposed upload is smaller than the minimum allowed size");
+        if (body.byteLength > ticket.byteSize)
+            return storageError(400, "EntityTooLarge", "Your proposed upload exceeds the maximum allowed size");
+        const sha256Base64 = await sha256Base64Of(body);
+        if (sha256Base64 !== ticket.sha256Base64)
+            return storageError(400, "BadDigest", "The SHA256 you specified did not match the calculated checksum.");
+        this.objects.set(ticket.objectKey, { body, mimeType: ticket.mimeType, sha256Base64, object: ticket.object });
+        return new Response(null, { status: 204 });
+    }
+    serveDownload(objectKey, linkId, headOnly) {
+        const link = linkId === null ? undefined : this.links.get(linkId);
+        if (!link || link.objectKey !== objectKey)
+            return storageError(403, "AccessDenied", "Access Denied");
+        if (this.now() >= link.expiresAt)
+            return storageError(403, "AccessDenied", "Request has expired");
+        const stored = this.objects.get(objectKey);
+        if (!stored)
+            return storageError(404, "NoSuchKey", "The specified key does not exist.");
+        const headers = { "content-type": stored.mimeType, "content-length": String(stored.body.byteLength) };
+        if (stored.object.cacheControl !== undefined)
+            headers["cache-control"] = stored.object.cacheControl;
+        // The link's own disposition over the object's, as S3 answers a presigned read.
+        const disposition = link.contentDisposition ?? stored.object.contentDisposition;
+        if (disposition)
+            headers["content-disposition"] = contentDispositionHeader(disposition);
+        return new Response(headOnly ? null : new Blob([stored.body]), { status: 200, headers });
+    }
+}
+/** A key as a URL path: each segment escaped, the slashes kept, as S3 addresses an object. */
+const encodeObjectKey = (objectKey) => objectKey.split("/").map(encodeURIComponent).join("/");
+const decodeObjectKey = (path) => path.split("/").map(decodeURIComponent).join("/");
+const escapeXml = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);
+/** An error the way S3 writes one: the status, and `<Error><Code/><Message/></Error>` as XML. */
+const storageError = (status, code, message) => new Response(`<?xml version="1.0" encoding="UTF-8"?>\n<Error><Code>${escapeXml(code)}</Code><Message>${escapeXml(message)}</Message></Error>`, { status, headers: { "content-type": "application/xml" } });

package/dist/stores/LambderS3FileSource.d.ts

@@ -12,24 +12,39 @@ export type LambderS3FileSourceOptions = {
      * `{ region: "auto", endpoint, credentials }`.
      */
     clientConfig?: S3ClientConfig;
+    /**
+     * The S3 error names that mean "no such file", read as null so the
+     * request falls through. Default: NoSuchKey and NotFound (the key does
+     * not exist), AccessDenied (what S3 answers a reader without
+     * s3:ListBucket for a missing key, since it will not say whether the key
+     * exists), and the refusals of a key S3 will not look up at all:
+     * KeyTooLongError and InvalidURI from S3, InvalidObjectName from R2. A
+     * reader granted s3:ListBucket gets NoSuchKey for a missing key, so a
+     * list without AccessDenied makes a refused credential surface as the
+     * error it is.
+     */
+    notFoundErrorNames?: readonly string[];
 };
 /**
  * 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.
+ * folder never load it. A missing object (see `notFoundErrorNames`) reads as
+ * null and the request falls through; any other failure throws. A request
+ * path names the key, so a key that is missing or that S3 refuses to look
+ * up is the visitor's doing, and reading it as an error would answer every
+ * such path with a 500 before an SPA's shell could be served. 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 readonly notFoundErrorNames;
     private client;
     private sdk;
-    constructor({ bucket, prefix, client, clientConfig }: LambderS3FileSourceOptions);
+    constructor({ bucket, prefix, client, clientConfig, notFoundErrorNames }: LambderS3FileSourceOptions);
     private loadSdk;
     read(relativePath: string): Promise<LambderFile | null>;
 }

package/dist/stores/LambderS3FileSource.js

@@ -1,27 +1,32 @@
 import { remoteStoreFile } from "../shared/contracts/LambderFileSource.js";
+const DEFAULT_NOT_FOUND_ERROR_NAMES = ["NoSuchKey", "NotFound", "AccessDenied", "KeyTooLongError", "InvalidURI", "InvalidObjectName"];
 /**
  * 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.
+ * folder never load it. A missing object (see `notFoundErrorNames`) reads as
+ * null and the request falls through; any other failure throws. A request
+ * path names the key, so a key that is missing or that S3 refuses to look
+ * up is the visitor's doing, and reading it as an error would answer every
+ * such path with a 500 before an SPA's shell could be served. 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 class LambderS3FileSource {
     bucket;
     prefix;
     clientConfig;
+    notFoundErrorNames;
     client;
     sdk;
-    constructor({ bucket, prefix = "", client, clientConfig }) {
+    constructor({ bucket, prefix = "", client, clientConfig, notFoundErrorNames = DEFAULT_NOT_FOUND_ERROR_NAMES }) {
         if (!bucket.trim())
             throw new Error("bucket is required");
         this.bucket = bucket;
         this.prefix = prefix;
         this.client = client;
         this.clientConfig = clientConfig;
+        this.notFoundErrorNames = notFoundErrorNames;
     }
     loadSdk() {
         if (!this.sdk) {
@@ -41,7 +46,7 @@ export class LambderS3FileSource {
         }
         catch (err) {
             const name = err.name;
-            if (name === "NoSuchKey" || name === "NotFound")
+            if (typeof name === "string" && this.notFoundErrorNames.includes(name))
                 return null;
             throw err;
         }

package/dist/stores/LambderS3UploadBucket.d.ts

@@ -0,0 +1,73 @@
+import type { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
+import { type LambderUploadBucket, type LambderUploadContentDisposition, type LambderUploadFileFacts, type LambderUploadObjectOptions, type LambderUploadRule, type LambderUploadTicket, type LambderUploadVerdict } from "../shared/contracts/LambderUploadBucket.js";
+export type LambderS3UploadBucketOptions = {
+    bucket: 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 use: `{ region }`. */
+    clientConfig?: S3ClientConfig;
+    /** How long a ticket stays usable, unless a ticket says otherwise. Default: 600 seconds, enough for a large file on a slow phone. */
+    ticketLifetimeSeconds?: number;
+    /** How long a download link reads the object, unless a link says otherwise. Default: 300 seconds. */
+    downloadLifetimeSeconds?: number;
+};
+/**
+ * An S3 bucket browsers upload to directly (see LambderUploadBucket).
+ *
+ * A ticket is an S3 presigned POST whose policy pins the key, the content
+ * type, the exact byte size and the SHA-256 checksum, so S3 itself refuses
+ * any other file. That needs S3's POST policies with checksum fields: S3, or
+ * a store that implements them; Cloudflare R2 does not take presigned POSTs.
+ *
+ * Signing a ticket or a download link is arithmetic over the function's
+ * credentials and reaches nothing; verifying, reading, writing, copying and
+ * deleting are calls to the bucket. A signature lives at most seven days,
+ * and never past the credentials that made it: a Lambda's role credentials
+ * last hours, so a link meant to outlive them needs long-lived keys. Needs @aws-sdk/client-s3,
+ * @aws-sdk/s3-presigned-post and @aws-sdk/s3-request-presigner, optional peer
+ * dependencies each loaded the first time a call needs it, so an app that
+ * never uploads never loads them.
+ */
+export declare class LambderS3UploadBucket implements LambderUploadBucket {
+    private readonly bucket;
+    private readonly ticketLifetimeSeconds;
+    private readonly downloadLifetimeSeconds;
+    private readonly clientConfig;
+    private client;
+    private clientSdk;
+    private presignedPostSdk;
+    private requestPresignerSdk;
+    constructor({ bucket, client, clientConfig, ticketLifetimeSeconds, downloadLifetimeSeconds }: LambderS3UploadBucketOptions);
+    issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds, object }: {
+        objectKey: string;
+        fileFacts: LambderUploadFileFacts;
+        uploadRule: LambderUploadRule;
+        lifetimeSeconds?: number;
+        object?: LambderUploadObjectOptions;
+    }): Promise<LambderUploadTicket>;
+    verifyUploadedObject({ objectKey, fileFacts }: {
+        objectKey: string;
+        fileFacts: Pick<LambderUploadFileFacts, "byteSize" | "sha256Base64">;
+    }): Promise<LambderUploadVerdict>;
+    issueDownloadUrl({ objectKey, lifetimeSeconds, contentDisposition }: {
+        objectKey: string;
+        lifetimeSeconds?: number;
+        contentDisposition?: LambderUploadContentDisposition;
+    }): Promise<string>;
+    readObject(objectKey: string): Promise<Uint8Array>;
+    writeObject({ objectKey, body, mimeType, sha256Base64, object }: {
+        objectKey: string;
+        body: Uint8Array;
+        mimeType: string;
+        sha256Base64?: string;
+        object?: LambderUploadObjectOptions;
+    }): Promise<void>;
+    copyObject({ fromObjectKey, toObjectKey }: {
+        fromObjectKey: string;
+        toObjectKey: string;
+    }): Promise<void>;
+    deleteObject(objectKey: string): Promise<void>;
+    private s3;
+    private loadPresignedPostSdk;
+    private loadRequestPresignerSdk;
+}

package/dist/stores/LambderS3UploadBucket.js

@@ -0,0 +1,144 @@
+import { assertObjectOptions, assertPinnedObjectKey, assertSignatureLifetime, } from "../shared/contracts/LambderUploadBucket.js";
+import { contentDispositionHeader } from "../shared/util/LambderContentDisposition.js";
+import { uploadObjectFormFields } from "../shared/wire/LambderUploadObjectFields.js";
+import { refuseUnacceptedUpload } from "../shared/wire/LambderUploadRefusal.js";
+import { withInstallHint } from "./LambderSdkInstallHint.js";
+/** The S3 error names that mean nothing is stored under the key: HeadObject answers NotFound, the other calls NoSuchKey. */
+const MISSING_OBJECT_ERROR_NAMES = ["NotFound", "NoSuchKey"];
+/**
+ * An S3 bucket browsers upload to directly (see LambderUploadBucket).
+ *
+ * A ticket is an S3 presigned POST whose policy pins the key, the content
+ * type, the exact byte size and the SHA-256 checksum, so S3 itself refuses
+ * any other file. That needs S3's POST policies with checksum fields: S3, or
+ * a store that implements them; Cloudflare R2 does not take presigned POSTs.
+ *
+ * Signing a ticket or a download link is arithmetic over the function's
+ * credentials and reaches nothing; verifying, reading, writing, copying and
+ * deleting are calls to the bucket. A signature lives at most seven days,
+ * and never past the credentials that made it: a Lambda's role credentials
+ * last hours, so a link meant to outlive them needs long-lived keys. Needs @aws-sdk/client-s3,
+ * @aws-sdk/s3-presigned-post and @aws-sdk/s3-request-presigner, optional peer
+ * dependencies each loaded the first time a call needs it, so an app that
+ * never uploads never loads them.
+ */
+export class LambderS3UploadBucket {
+    bucket;
+    ticketLifetimeSeconds;
+    downloadLifetimeSeconds;
+    clientConfig;
+    client;
+    clientSdk;
+    presignedPostSdk;
+    requestPresignerSdk;
+    constructor({ bucket, client, clientConfig, ticketLifetimeSeconds = 600, downloadLifetimeSeconds = 300 }) {
+        if (!bucket.trim())
+            throw new Error("bucket is required");
+        assertSignatureLifetime(ticketLifetimeSeconds, "ticketLifetimeSeconds");
+        assertSignatureLifetime(downloadLifetimeSeconds, "downloadLifetimeSeconds");
+        this.bucket = bucket;
+        this.client = client;
+        this.clientConfig = clientConfig;
+        this.ticketLifetimeSeconds = ticketLifetimeSeconds;
+        this.downloadLifetimeSeconds = downloadLifetimeSeconds;
+    }
+    async issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds = this.ticketLifetimeSeconds, object }) {
+        assertPinnedObjectKey(objectKey);
+        assertSignatureLifetime(lifetimeSeconds, "lifetimeSeconds");
+        assertObjectOptions(object);
+        refuseUnacceptedUpload(uploadRule, fileFacts);
+        const [{ client }, { createPresignedPost }] = await Promise.all([this.s3(), this.loadPresignedPostSdk()]);
+        const post = await createPresignedPost(client, {
+            Bucket: this.bucket,
+            Key: objectKey,
+            Expires: lifetimeSeconds,
+            // Each field is also an exact-match condition of the signed policy.
+            Fields: {
+                "Content-Type": fileFacts.mimeType,
+                "x-amz-checksum-algorithm": "SHA256",
+                "x-amz-checksum-sha256": fileFacts.sha256Base64,
+                ...uploadObjectFormFields(object),
+            },
+            Conditions: [["content-length-range", fileFacts.byteSize, fileFacts.byteSize]],
+        });
+        return { uploadUrl: post.url, formFields: post.fields, expiresAt: Date.now() + lifetimeSeconds * 1000 };
+    }
+    async verifyUploadedObject({ objectKey, fileFacts }) {
+        const { sdk, client } = await this.s3();
+        let head;
+        try {
+            head = await client.send(new sdk.HeadObjectCommand({ Bucket: this.bucket, Key: objectKey, ChecksumMode: "ENABLED" }));
+        }
+        catch (err) {
+            if (MISSING_OBJECT_ERROR_NAMES.includes(err.name ?? ""))
+                return { verified: false, reason: "objectMissing" };
+            throw err;
+        }
+        const matches = head.ContentLength === fileFacts.byteSize && head.ChecksumSHA256 === fileFacts.sha256Base64;
+        return matches ? { verified: true } : { verified: false, reason: "factsMismatch" };
+    }
+    async issueDownloadUrl({ objectKey, lifetimeSeconds = this.downloadLifetimeSeconds, contentDisposition }) {
+        assertSignatureLifetime(lifetimeSeconds, "lifetimeSeconds");
+        const [{ sdk, client }, { getSignedUrl }] = await Promise.all([this.s3(), this.loadRequestPresignerSdk()]);
+        return getSignedUrl(client, new sdk.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: objectKey,
+            // Signed into the link: S3 answers with this header for its reads alone.
+            ...(contentDisposition ? { ResponseContentDisposition: contentDispositionHeader(contentDisposition) } : {}),
+        }), { expiresIn: lifetimeSeconds });
+    }
+    async readObject(objectKey) {
+        const { sdk, client } = await this.s3();
+        const object = await client.send(new sdk.GetObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+        if (!object.Body)
+            throw new Error(`LambderS3UploadBucket.readObject: no body under ${objectKey}`);
+        return object.Body.transformToByteArray();
+    }
+    async writeObject({ objectKey, body, mimeType, sha256Base64, object }) {
+        assertObjectOptions(object);
+        const { sdk, client } = await this.s3();
+        const tags = Object.entries(object?.tags ?? {});
+        const metadata = Object.entries(object?.metadata ?? {});
+        await client.send(new sdk.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: objectKey,
+            Body: body,
+            ContentType: mimeType,
+            ...(tags.length ? { Tagging: new URLSearchParams(tags).toString() } : {}),
+            ...(metadata.length ? { Metadata: Object.fromEntries(metadata.map(([name, value]) => [name.toLowerCase(), value])) } : {}),
+            ...(object?.cacheControl !== undefined ? { CacheControl: object.cacheControl } : {}),
+            ...(object?.contentDisposition ? { ContentDisposition: contentDispositionHeader(object.contentDisposition) } : {}),
+            // A digest the caller already has is sent as it is; otherwise the
+            // SDK computes it. Either way S3 checks the body against it and
+            // stores it, which is what verifyUploadedObject reads back.
+            ...(sha256Base64 !== undefined ? { ChecksumSHA256: sha256Base64 } : { ChecksumAlgorithm: "SHA256" }),
+        }));
+    }
+    async copyObject({ fromObjectKey, toObjectKey }) {
+        const { sdk, client } = await this.s3();
+        await client.send(new sdk.CopyObjectCommand({
+            Bucket: this.bucket,
+            // The source is named as a URL path, so a key's own characters are escaped and its slashes kept.
+            CopySource: `${this.bucket}/${fromObjectKey.split("/").map(encodeURIComponent).join("/")}`,
+            Key: toObjectKey,
+        }));
+    }
+    async deleteObject(objectKey) {
+        const { sdk, client } = await this.s3();
+        await client.send(new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+    }
+    async s3() {
+        this.clientSdk ??= withInstallHint(import("@aws-sdk/client-s3"), "@aws-sdk/client-s3", "LambderS3UploadBucket", () => { this.clientSdk = undefined; });
+        const sdk = await this.clientSdk;
+        this.client ??= new sdk.S3Client(this.clientConfig ?? {});
+        return { sdk, client: this.client };
+    }
+    loadPresignedPostSdk() {
+        this.presignedPostSdk ??= withInstallHint(import("@aws-sdk/s3-presigned-post"), "@aws-sdk/s3-presigned-post", "LambderS3UploadBucket", () => { this.presignedPostSdk = undefined; });
+        return this.presignedPostSdk;
+    }
+    loadRequestPresignerSdk() {
+        this.requestPresignerSdk ??= withInstallHint(import("@aws-sdk/s3-request-presigner"), "@aws-sdk/s3-request-presigner", "LambderS3UploadBucket", () => { this.requestPresignerSdk = undefined; });
+        return this.requestPresignerSdk;
+    }
+}

package/dist/stores/LambderSdkInstallHint.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An optional peer package loaded on first use, failing with the install hint.
+ *
+ * The AWS SDK packages a store or bucket talks through are optional peer
+ * dependencies, so an app that never uses one neither installs it nor pays
+ * for loading it. A package that fails to load fails that first call with a
+ * message naming the class that needed it and the command that installs it.
+ * The failure is not remembered: the package may be installed later in the
+ * same process (tests do), and the next caller names itself.
+ */
+export declare const withInstallHint: <T>(loading: Promise<T>, packageName: string, user: string, reset: () => void) => Promise<T>;

package/dist/stores/LambderSdkInstallHint.js

@@ -0,0 +1,14 @@
+/**
+ * An optional peer package loaded on first use, failing with the install hint.
+ *
+ * The AWS SDK packages a store or bucket talks through are optional peer
+ * dependencies, so an app that never uses one neither installs it nor pays
+ * for loading it. A package that fails to load fails that first call with a
+ * message naming the class that needed it and the command that installs it.
+ * The failure is not remembered: the package may be installed later in the
+ * same process (tests do), and the next caller names itself.
+ */
+export const withInstallHint = (loading, packageName, user, reset) => loading.catch((cause) => {
+    reset();
+    throw new Error(`${user} requires ${packageName}: npm install ${packageName}`, { cause });
+});

package/dist/testing/LambderTestApp.d.ts

@@ -23,9 +23,9 @@ export type LambderTestAppOptions = {
     /**
      * The gateway shape the handler is called with: "v2" (an HTTP API, a
      * Function URL) or "v1" (a REST API). Default: "v2". A handler answers
-     * both alike through its context, so this matters to code that reads the
-     * raw `ctx.event`, and to anyone who wants the suite to run on exactly
-     * what production delivers.
+     * both alike through its context, so this matters only to code that reads
+     * the raw `ctx.event`, or to a suite that should run on exactly what
+     * production delivers.
      */
     eventFormat?: LambderHttpEventFormat;
     /** Default: a fresh LambderMemorySessionStore. Pass your own to run the suite over another store (DynamoDB Local, say). */
@@ -46,10 +46,10 @@ export type LambderTestAppOptions = {
 /**
  * A Lambder instance as a test app takes it: any instance, read for its
  * session data type and, through the ApiContract property rather than the
- * class parameter, for its contract. The property is what lets a large app
- * name its flattened contract interface explicitly
- * (`lambderTestApp<SessionData, ApiContractType>(lambder)`) and keep the
- * cheap type check that interface exists for.
+ * class parameter, for its contract. The property lets a large app name the
+ * contract writeApiContract generated for its clients
+ * (`lambderTestApp<SessionData, ApiContractType>(lambder)`), so the tests type
+ * their calls against plain members rather than the chained intersection.
  */
 export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any> & {
     readonly ApiContract: TContract;
@@ -59,17 +59,17 @@ export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionDat
  * stores put under it in place, and as many simulated browsers in front of it
  * as a test needs. No HTTP, no AWS, and nothing in the app restructured.
  *
- * The app's own declarations all run as written: its guards, its named
- * rate-limit policies, its idempotency settings, its session salt, cookie
- * options and dataRefresh, its hooks and error handlers. Only where things
- * rest is replaced, and from the moment this is created the stores the app
- * was configured with are out of the instance's reach, so a test cannot touch
- * a production table even by mistake. What the app reaches on its own (its
- * database, a mailer) is the app's to replace.
+ * The app's own declarations all run as written: guards, named rate-limit
+ * policies, idempotency settings, session salt, cookie options and
+ * dataRefresh, hooks and error handlers. Only where things rest is replaced:
+ * once this is created, the stores the app was configured with are out of the
+ * instance's reach, so a test cannot touch a production table by mistake.
+ * What the app reaches on its own (its database, a mailer) is the app's to
+ * replace.
  *
  * The sibling of LambderMockApp, which serves a contract from mock handlers:
  * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
- * real handlers instead.
+ * real handlers.
  *
  * Time is not this class's: fake `Date` with the test runner
  * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
@@ -97,22 +97,20 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     private resetCount;
     private readonly crashList;
     /**
-     * The call a crash happened under. The app answers a crash with a 500
-     * that says nothing about it, so the error has to travel beside the
-     * answer, and with calls running concurrently (a duplicate sent while
-     * the original is in flight is an ordinary idempotency test) only the
-     * async context says which call a crash belongs to.
+     * The call a crash happened under. The app's 500 says nothing about the
+     * crash, so the error travels beside the answer, and with concurrent
+     * calls (a duplicate sent while the original is in flight is an ordinary
+     * idempotency test) only the async context says which call it belongs to.
      */
     private readonly crashScope;
     constructor(lambder: LambderTestedInstance<TSessionData, TContract>, options?: LambderTestAppOptions);
     /**
      * Every error the app threw while answering a request since the last
      * reset, in order: what reached its global error handler, or the
-     * framework's last-resort 500. The answers themselves say nothing about
-     * what was thrown, so this is where a test reads it, and
-     * `expect(app.crashes).toEqual([])` is how one says nothing crashed.
-     * A refusal is not a crash, and neither is an error an `event()` rejects
-     * with, which the test already holds.
+     * framework's last-resort 500. The answers say nothing about what was
+     * thrown, so a test reads it here; `expect(app.crashes).toEqual([])`
+     * says nothing crashed. A refusal is not a crash, and neither is an
+     * error an `event()` rejects with, which the test already holds.
      */
     get crashes(): readonly Error[];
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */