lambder 8.0.2 → 8.1.1

package/dist/shared/contracts/LambderUploadBucket.d.ts

@@ -0,0 +1,154 @@
+/** What an app accepts for one kind of upload, declared once and read by both sides. */
+export type LambderUploadRule = {
+    /** The largest file accepted, in bytes. */
+    maxBytes: number;
+    /** The accepted content types, exact, with no wildcards: `["application/pdf"]`. */
+    mimeTypes: readonly string[];
+};
+/** What the browser says about a file before any of its bytes move. */
+export type LambderUploadFileFacts = {
+    fileName: string;
+    mimeType: string;
+    byteSize: number;
+    /** SHA-256 of the file's bytes as base64, the form storage checks an upload against: 43 characters and one pad. */
+    sha256Base64: string;
+};
+/** Everything the browser needs to post one file to storage, and until when. */
+export type LambderUploadTicket = {
+    uploadUrl: string;
+    /** Sent as form fields ahead of the file, which storage wants last. */
+    formFields: Record<string, string>;
+    /** Epoch milliseconds after which storage refuses the ticket. */
+    expiresAt: number;
+};
+/** What a bucket holds under a key, compared with what the browser said it would upload. */
+export type LambderUploadVerdict = {
+    verified: true;
+}
+/** `objectMissing`: nothing was posted. `factsMismatch`: something else sits under the key. */
+ | {
+    verified: false;
+    reason: "objectMissing" | "factsMismatch";
+};
+/** How a browser presents an object it reads: in place (a PDF in its viewer) or saved as a file, under a name. */
+export type LambderUploadContentDisposition = {
+    disposition: "inline" | "attachment";
+    /** The name the file is saved or shown under; any characters, encoded for the header. Without one, the browser takes the key's last segment. */
+    fileName?: string;
+};
+/**
+ * What storage keeps beside an object's bytes. A ticket pins every one of
+ * these in its signed policy, so the browser posts them unchanged.
+ */
+export type LambderUploadObjectOptions = {
+    /**
+     * The object's tags, at most ten. They are how an object gets a time to
+     * live: S3 has no expiry per object, and a lifecycle rule keyed on a tag
+     * (`retention: "30d"` expiring after 30 days) deletes what carries it.
+     * Keys up to 128 characters, values up to 256.
+     */
+    tags?: Record<string, string>;
+    /** User metadata, kept as `x-amz-meta-<name>` and returned with every read of the object. Names are lowercased; printable ASCII, 2 KB in all. */
+    metadata?: Record<string, string>;
+    /** The Cache-Control every read of the object answers with, for one served through a CDN. */
+    cacheControl?: string;
+    /** How a browser presents the object by default; a download link can say otherwise. */
+    contentDisposition?: LambderUploadContentDisposition;
+};
+/** The longest a ticket or a download link may live: S3's limit for a signature, seven days. */
+export declare const UPLOAD_SIGNATURE_MAX_SECONDS: number;
+/** Throws unless a lifetime is a positive number of seconds within S3's seven days. */
+export declare const assertSignatureLifetime: (seconds: number, name: string) => void;
+/** Throws when object options break a limit S3 holds them to, so the mistake shows where the app wrote it rather than as a refused post. */
+export declare const assertObjectOptions: (options: LambderUploadObjectOptions | undefined) => void;
+/** What a rule holds against a file, known before any of it is sent. */
+export type LambderUploadRuleVerdict = "fileEmpty" | "fileTypeRejected" | "fileTooLarge";
+/** A rule's verdict on a file, or null when it may be uploaded: the check the browser makes before hashing and the bucket makes before signing. */
+export declare const checkUploadRule: (rule: LambderUploadRule, file: {
+    mimeType: string;
+    byteSize: number;
+}) => LambderUploadRuleVerdict | null;
+/**
+ * Throws when an object key would not pin the key a ticket writes to: S3
+ * substitutes the uploaded file's own name for `${filename}` in a presigned
+ * POST's key, so a key holding it lets the browser choose where under it the
+ * file lands. A key is the app's, built from its own ids, so this is a
+ * programming error rather than a refusal.
+ */
+export declare const assertPinnedObjectKey: (objectKey: string) => void;
+/**
+ * Object storage a browser uploads to directly, with tickets the server
+ * signs, and that the server reads, writes and deletes through for the rest
+ * of an object's life. One instance per bucket. LambderS3UploadBucket in
+ * production; LambderMemoryUploadBucket in tests and the mock runtime.
+ *
+ * The object key is always chosen by the app from its own ids. It never
+ * comes from the browser, and a ticket pins it, so a ticket cannot be used to
+ * write anywhere else.
+ */
+export interface LambderUploadBucket {
+    /**
+     * Signs a ticket for exactly the file the browser described, or refuses
+     * (a LambderApiRefusal, code `lambder/upload-empty`,
+     * `lambder/upload-type-rejected` or `lambder/upload-too-large`) when the
+     * rule does not accept it. Storage then enforces every fact: the post
+     * fails unless the body has that byte size, that content type and that
+     * SHA-256, so what verifies later is what was described here. `object`
+     * is what the stored object carries besides, pinned the same way, and
+     * `lifetimeSeconds` overrides the bucket's ticket lifetime for this one.
+     */
+    issueUploadTicket(options: {
+        objectKey: string;
+        fileFacts: LambderUploadFileFacts;
+        uploadRule: LambderUploadRule;
+        lifetimeSeconds?: number;
+        object?: LambderUploadObjectOptions;
+    }): Promise<LambderUploadTicket>;
+    /**
+     * Asks storage what it holds under the key. The browser saying "done"
+     * proves nothing, so an app calls this before its record counts as
+     * uploaded.
+     */
+    verifyUploadedObject(options: {
+        objectKey: string;
+        fileFacts: Pick<LambderUploadFileFacts, "byteSize" | "sha256Base64">;
+    }): Promise<LambderUploadVerdict>;
+    /**
+     * A link the browser can read the object with (a preview, a download)
+     * until it expires: `lifetimeSeconds`, or the bucket's link lifetime.
+     * `contentDisposition` decides for this link whether the browser shows
+     * the file or saves it, and under what name.
+     */
+    issueDownloadUrl(options: {
+        objectKey: string;
+        lifetimeSeconds?: number;
+        contentDisposition?: LambderUploadContentDisposition;
+    }): Promise<string>;
+    /** The object's bytes, for work the server does on a file itself. Throws when the key holds nothing. */
+    readObject(objectKey: string): Promise<Uint8Array>;
+    /**
+     * Stores bytes the server produced, with their SHA-256 checked by storage
+     * on the way in, as a ticket checks a browser's upload. Pass the digest
+     * when it is already known; otherwise it is computed. `object` is what
+     * the object carries besides, as for a ticket.
+     */
+    writeObject(options: {
+        objectKey: string;
+        body: Uint8Array;
+        mimeType: string;
+        sha256Base64?: string;
+        object?: LambderUploadObjectOptions;
+    }): Promise<void>;
+    /**
+     * A second object with the same bytes, made inside storage: nothing is
+     * read into the function, so a file of any size copies in one call. For
+     * records that must each own their file, so deleting one never takes the
+     * other's. The copy carries the source's type, metadata and tags.
+     */
+    copyObject(options: {
+        fromObjectKey: string;
+        toObjectKey: string;
+    }): Promise<void>;
+    /** Removes the object. Deleting a key that holds nothing is not an error. */
+    deleteObject(objectKey: string): Promise<void>;
+}

package/dist/shared/contracts/LambderUploadBucket.js

@@ -0,0 +1,74 @@
+/*
+ * Direct uploads: a file that travels from the browser straight to object
+ * storage, never through the app's function.
+ *
+ * An API payload tops out near a few megabytes once a file is base64, and a
+ * Lambda's request body at six, so anything larger (a scanned lease, a
+ * signed PDF, a video) is posted by the browser to the bucket itself, with a
+ * ticket the server signed beforehand. The ticket pins everything about the
+ * upload: the key, the exact byte size, the content type and the SHA-256 of
+ * the bytes, all enforced by the storage, so the browser can only ever store
+ * the one file it described.
+ *
+ * The conversation is the same three steps whatever the app stores: the
+ * browser describes the file (LambderUploadFileFacts), the app's endpoint
+ * answers with a ticket (LambderUploadTicket), and after the post the app's
+ * confirm endpoint asks the bucket what arrived before its record counts as
+ * uploaded. The server half is a LambderUploadBucket, the browser half is
+ * LambderUploadRunner.
+ *
+ * This module is the vocabulary both halves share and the contract a bucket
+ * implements, and it imports nothing: the zod schemas an endpoint declares
+ * its input and output with are in wire/LambderUploadSchemas.ts.
+ */
+/** The longest a ticket or a download link may live: S3's limit for a signature, seven days. */
+export const UPLOAD_SIGNATURE_MAX_SECONDS = 7 * 24 * 60 * 60;
+/** Throws unless a lifetime is a positive number of seconds within S3's seven days. */
+export const assertSignatureLifetime = (seconds, name) => {
+    if (!(Number.isFinite(seconds) && seconds > 0 && seconds <= UPLOAD_SIGNATURE_MAX_SECONDS)) {
+        throw new RangeError(`${name} must be a number of seconds above 0 and at most ${UPLOAD_SIGNATURE_MAX_SECONDS} (seven days): ${seconds}`);
+    }
+};
+/** Throws when object options break a limit S3 holds them to, so the mistake shows where the app wrote it rather than as a refused post. */
+export const assertObjectOptions = (options) => {
+    const tags = Object.entries(options?.tags ?? {});
+    if (tags.length > 10)
+        throw new RangeError(`An object carries at most 10 tags: ${tags.length}`);
+    for (const [key, value] of tags) {
+        if (!key || key.length > 128 || value.length > 256)
+            throw new RangeError(`A tag's key is 1 to 128 characters and its value at most 256: ${key}`);
+    }
+    let metadataBytes = 0;
+    for (const [name, value] of Object.entries(options?.metadata ?? {})) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name))
+            throw new RangeError(`A metadata name is letters, digits, "-" and "_": ${name}`);
+        if (!/^[\x20-\x7e]*$/.test(value))
+            throw new RangeError(`A metadata value is printable ASCII: ${name}`);
+        metadataBytes += name.length + value.length;
+    }
+    if (metadataBytes > 2048)
+        throw new RangeError(`An object's metadata is at most 2 KB: ${metadataBytes} bytes`);
+};
+/** A rule's verdict on a file, or null when it may be uploaded: the check the browser makes before hashing and the bucket makes before signing. */
+export const checkUploadRule = (rule, file) => {
+    if (file.byteSize <= 0)
+        return "fileEmpty";
+    if (!rule.mimeTypes.includes(file.mimeType))
+        return "fileTypeRejected";
+    if (file.byteSize > rule.maxBytes)
+        return "fileTooLarge";
+    return null;
+};
+/**
+ * Throws when an object key would not pin the key a ticket writes to: S3
+ * substitutes the uploaded file's own name for `${filename}` in a presigned
+ * POST's key, so a key holding it lets the browser choose where under it the
+ * file lands. A key is the app's, built from its own ids, so this is a
+ * programming error rather than a refusal.
+ */
+export const assertPinnedObjectKey = (objectKey) => {
+    if (!objectKey)
+        throw new Error("An upload's object key is empty");
+    if (objectKey.includes("${filename}"))
+        throw new Error(`An upload's object key may not hold \${filename}, which storage replaces with the uploaded file's name: ${objectKey}`);
+};

package/dist/shared/util/LambderContentDisposition.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A Content-Disposition header for a file name of any characters: an ASCII
+ * `filename` for old clients, and the exact name as UTF-8 in `filename*`
+ * (RFC 6266). A character a header cannot carry never reaches it, so a name
+ * holding a quote or a line break cannot end the header early.
+ */
+export declare const contentDispositionHeader: ({ disposition, fileName }: {
+    disposition: "inline" | "attachment";
+    fileName?: string;
+}) => string;

package/dist/shared/util/LambderContentDisposition.js

@@ -0,0 +1,13 @@
+/**
+ * A Content-Disposition header for a file name of any characters: an ASCII
+ * `filename` for old clients, and the exact name as UTF-8 in `filename*`
+ * (RFC 6266). A character a header cannot carry never reaches it, so a name
+ * holding a quote or a line break cannot end the header early.
+ */
+export const contentDispositionHeader = ({ disposition, fileName }) => {
+    if (fileName === undefined)
+        return disposition;
+    const fallback = fileName.replace(/[^\x20-\x7e]|["\\%]/g, "_");
+    const encoded = encodeURIComponent(fileName).replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encoded}`;
+};

package/dist/shared/util/LambderTextDigest.d.ts

@@ -1,9 +1,9 @@
 /**
- * SHA-256 over text through WebCrypto, as hex: the one digest every layer
- * shares. The session crypto hashes bearer secrets with it and the
- * rate-limit engine folds an over-long tracker key with it, so both key
- * spaces are built from the same primitive on every runtime (browsers on a
- * secure context, Node 20+, edge runtimes).
+ * SHA-256 through WebCrypto: the one digest every layer shares. The session
+ * crypto hashes bearer secrets with it and the rate-limit engine folds an
+ * over-long tracker key with it, so both key spaces are built from the same
+ * primitive on every runtime (browsers on a secure context, Node 20+, edge
+ * runtimes); an upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export declare const bytesToHexString: (bytes: Uint8Array) => string;
@@ -15,3 +15,5 @@ export declare const bytesToHexString: (bytes: Uint8Array) => string;
 export declare const resolveWebCrypto: () => Promise<Crypto>;
 /** The SHA-256 digest of `text` (UTF-8), as 64 lowercase hex characters. */
 export declare const sha256HexOf: (text: string) => Promise<string>;
+/** The SHA-256 digest of `bytes`, as base64: the form object storage checks an upload's checksum in. */
+export declare const sha256Base64Of: (bytes: Uint8Array) => Promise<string>;

package/dist/shared/util/LambderTextDigest.js

@@ -1,10 +1,11 @@
+import { bytesToBase64 } from "./LambderBase64.js";
 import { getCrypto } from "./LambderNodeModules.js";
 /**
- * SHA-256 over text through WebCrypto, as hex: the one digest every layer
- * shares. The session crypto hashes bearer secrets with it and the
- * rate-limit engine folds an over-long tracker key with it, so both key
- * spaces are built from the same primitive on every runtime (browsers on a
- * secure context, Node 20+, edge runtimes).
+ * SHA-256 through WebCrypto: the one digest every layer shares. The session
+ * crypto hashes bearer secrets with it and the rate-limit engine folds an
+ * over-long tracker key with it, so both key spaces are built from the same
+ * primitive on every runtime (browsers on a secure context, Node 20+, edge
+ * runtimes); an upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export const bytesToHexString = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -32,3 +33,8 @@ export const sha256HexOf = async (text) => {
     const digest = await webCrypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
     return bytesToHexString(new Uint8Array(digest));
 };
+/** The SHA-256 digest of `bytes`, as base64: the form object storage checks an upload's checksum in. */
+export const sha256Base64Of = async (bytes) => {
+    const webCrypto = await resolveWebCrypto();
+    return bytesToBase64(new Uint8Array(await webCrypto.subtle.digest("SHA-256", bytes)));
+};

package/dist/shared/wire/LambderApiContract.d.ts

@@ -148,49 +148,19 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 }) & ([Idempotency] extends [never] ? {} : {
     idempotency: Idempotency;
 });
-/** Helper type for merging a new entry into the contract during chaining. */
-export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
-    [K in Name]: Entry;
-};
 /**
- * The contract as one object type, for the `export interface` a consuming
- * app declares its contract through:
- *
- * ```ts
- * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
- * ```
+ * Merges a new entry into the contract during chaining.
  *
- * Chaining leaves the contract an intersection one member deep per endpoint
- * (LambderMergeContract above), and every `C[K]` against a type parameter
- * resolves the property across all of them. The reading helpers below are
- * built on that lookup, so each pays it again per endpoint: in a 182-endpoint
- * app one indexed access costs ~3,000 type instantiations and one mock
- * registration ~18,000.
- *
- * An interface's members are declared, so they resolve once for the whole
- * declaration: the same access costs ~6 instantiations instead, roughly
- * halving such an app's frontend type check time. The alias form
- * (`type C = LambderFlattenContract<...>`) does NOT do this: a mapped type
- * stays deferred and each lookup pays in full, so the `interface ... extends`
- * spelling is the point. Diagnostics also print the interface by name rather
- * than a truncated spill of entries.
- *
- * Every endpoint name must be a string literal for an interface to extend
- * the result, which registration through addApi/addSessionApi guarantees.
- *
- * Two things that look like tidying undo it:
- *
- * - `@typescript-eslint/no-empty-object-type` reports the empty body as
- *   "equivalent to its supertype" and its fix is a type alias, the one
- *   spelling that collapses nothing. Disable the rule on the line instead.
- * - Extending anything but a mapped type loses the inferable index signature.
- *   A hand-written `interface C { ... }` has none, so it is not assignable to
- *   LambderApiContractShape, and initLambderMock<C>, LambderCaller<C> and
- *   LambderInvokeCaller<C> reject it. api-contract.test.ts pins this, and
- *   that the flattened contract is the same type member for member.
+ * The contract is therefore an intersection one member deep per endpoint, and
+ * every `C[K]` read generically (a typed caller, a mock registry, a test
+ * visitor) resolves the property across all of them. That costs nothing
+ * worth measuring in a small app and most of a large client's type check,
+ * which is what writeApiContract (lambder/build) is for: it writes the
+ * contract out as one object type with plain members, for clients to import
+ * instead of the server.
  */
-export type LambderFlattenContract<C> = {
-    [K in keyof C]: C[K];
+export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
+    [K in Name]: Entry;
 };
 /** Guard names referenced by a guards option, whichever of its three forms is used. */
 export type LambderGuardNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;

package/dist/shared/wire/LambderApiRefusal.d.ts

@@ -123,6 +123,12 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly invalidRequestPayload: "lambder/invalid-request-payload";
     /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
     readonly notMocked: "lambder/not-mocked";
+    /** An upload bucket would not sign a ticket for a file with no bytes. */
+    readonly uploadEmpty: "lambder/upload-empty";
+    /** An upload bucket would not sign a ticket for a content type the rule does not accept. */
+    readonly uploadTypeRejected: "lambder/upload-type-rejected";
+    /** An upload bucket would not sign a ticket for a file larger than the rule accepts. */
+    readonly uploadTooLarge: "lambder/upload-too-large";
 };
 export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {

package/dist/shared/wire/LambderApiRefusal.js

@@ -86,6 +86,12 @@ export const LAMBDER_REFUSAL_CODES = {
     invalidRequestPayload: "lambder/invalid-request-payload",
     /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
     notMocked: "lambder/not-mocked",
+    /** An upload bucket would not sign a ticket for a file with no bytes. */
+    uploadEmpty: "lambder/upload-empty",
+    /** An upload bucket would not sign a ticket for a content type the rule does not accept. */
+    uploadTypeRejected: "lambder/upload-type-rejected",
+    /** An upload bucket would not sign a ticket for a file larger than the rule accepts. */
+    uploadTooLarge: "lambder/upload-too-large",
 };
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid

package/dist/shared/wire/LambderUploadObjectFields.d.ts

@@ -0,0 +1,10 @@
+import type { LambderUploadObjectOptions } from "../contracts/LambderUploadBucket.js";
+/**
+ * What a ticket's form carries for the stored object, in the fields S3's
+ * presigned POST reads them from: the tag set as the XML `tagging` field,
+ * each metadata entry as `x-amz-meta-<name>` (lowercased, as S3 keeps it),
+ * `Cache-Control` and `Content-Disposition`. Both buckets build their
+ * tickets' fields with this, so a post carries the same form to either, and
+ * every field is pinned by the ticket like the key and the checksum.
+ */
+export declare const uploadObjectFormFields: (object: LambderUploadObjectOptions | undefined) => Record<string, string>;

package/dist/shared/wire/LambderUploadObjectFields.js

@@ -0,0 +1,24 @@
+import { contentDispositionHeader } from "../util/LambderContentDisposition.js";
+const escapeXml = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);
+/**
+ * What a ticket's form carries for the stored object, in the fields S3's
+ * presigned POST reads them from: the tag set as the XML `tagging` field,
+ * each metadata entry as `x-amz-meta-<name>` (lowercased, as S3 keeps it),
+ * `Cache-Control` and `Content-Disposition`. Both buckets build their
+ * tickets' fields with this, so a post carries the same form to either, and
+ * every field is pinned by the ticket like the key and the checksum.
+ */
+export const uploadObjectFormFields = (object) => {
+    const fields = {};
+    const tags = Object.entries(object?.tags ?? {});
+    if (tags.length) {
+        fields.tagging = `<Tagging><TagSet>${tags.map(([key, value]) => `<Tag><Key>${escapeXml(key)}</Key><Value>${escapeXml(value)}</Value></Tag>`).join("")}</TagSet></Tagging>`;
+    }
+    for (const [name, value] of Object.entries(object?.metadata ?? {}))
+        fields[`x-amz-meta-${name.toLowerCase()}`] = value;
+    if (object?.cacheControl !== undefined)
+        fields["Cache-Control"] = object.cacheControl;
+    if (object?.contentDisposition)
+        fields["Content-Disposition"] = contentDispositionHeader(object.contentDisposition);
+    return fields;
+};

package/dist/shared/wire/LambderUploadRefusal.d.ts

@@ -0,0 +1,9 @@
+import { type LambderUploadFileFacts, type LambderUploadRule } from "../contracts/LambderUploadBucket.js";
+/**
+ * Refuses the API call signing a ticket when the rule does not accept the
+ * file, with the refusal code a client branches and translates on. Both of
+ * Lambder's buckets sign through this, and a bucket of an app's own (another
+ * store behind LambderUploadBucket) calls it the same way, so a file is
+ * refused alike whichever storage an app runs on.
+ */
+export declare const refuseUnacceptedUpload: (uploadRule: LambderUploadRule, fileFacts: Pick<LambderUploadFileFacts, "mimeType" | "byteSize">) => void;

package/dist/shared/wire/LambderUploadRefusal.js

@@ -0,0 +1,18 @@
+import { checkUploadRule } from "../contracts/LambderUploadBucket.js";
+import { LAMBDER_REFUSAL_CODES, refuse } from "./LambderApiRefusal.js";
+/**
+ * Refuses the API call signing a ticket when the rule does not accept the
+ * file, with the refusal code a client branches and translates on. Both of
+ * Lambder's buckets sign through this, and a bucket of an app's own (another
+ * store behind LambderUploadBucket) calls it the same way, so a file is
+ * refused alike whichever storage an app runs on.
+ */
+export const refuseUnacceptedUpload = (uploadRule, fileFacts) => {
+    const verdict = checkUploadRule(uploadRule, fileFacts);
+    if (verdict === "fileEmpty")
+        refuse("This file is empty.", { code: LAMBDER_REFUSAL_CODES.uploadEmpty });
+    if (verdict === "fileTypeRejected")
+        refuse("This type of file is not accepted.", { code: LAMBDER_REFUSAL_CODES.uploadTypeRejected });
+    if (verdict === "fileTooLarge")
+        refuse("This file is too large.", { code: LAMBDER_REFUSAL_CODES.uploadTooLarge });
+};

package/dist/shared/wire/LambderUploadSchemas.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const LambderUploadFileFactsSchema: z.ZodObject<{
+    fileName: z.ZodString;
+    mimeType: z.ZodString;
+    byteSize: z.ZodNumber;
+    sha256Base64: z.ZodString;
+}, z.core.$strip>;
+export declare const LambderUploadTicketSchema: z.ZodObject<{
+    uploadUrl: z.ZodURL;
+    formFields: z.ZodRecord<z.ZodString, z.ZodString>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;

package/dist/shared/wire/LambderUploadSchemas.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/*
+ * The two shapes of a direct upload that cross an app's own API, as schemas
+ * an endpoint declares its input and output with: the file facts the browser
+ * posts to the ticket endpoint, and the ticket it answers.
+ *
+ * ```ts
+ * .addSessionApi("documents.requestUpload", {
+ *     input: z.object({ folderId: z.uuid(), fileFacts: LambderUploadFileFactsSchema }),
+ *     output: z.object({ ticket: LambderUploadTicketSchema, documentId: z.uuid() }),
+ * }, ...)
+ * ```
+ *
+ * The types they infer are the contract's own (contracts/LambderUploadBucket.ts),
+ * which the compiler holds them to below in both directions.
+ */
+export const LambderUploadFileFactsSchema = z.object({
+    fileName: z.string().min(1).max(255),
+    mimeType: z.string().min(1).max(100),
+    byteSize: z.number().int().positive(),
+    /** SHA-256 of the file's bytes as base64: 32 bytes are always 43 characters and one pad. */
+    sha256Base64: z.string().regex(/^[A-Za-z0-9+/]{43}=$/),
+});
+export const LambderUploadTicketSchema = z.object({
+    uploadUrl: z.url(),
+    /** Sent as form fields ahead of the file, which storage wants last. */
+    formFields: z.record(z.string(), z.string()),
+    /** Epoch milliseconds after which storage refuses the ticket. */
+    expiresAt: z.number().int(),
+});

package/dist/stores/LambderDdbSdk.js

@@ -15,13 +15,9 @@
  * too: a conditional write's refusal is an answer rather than a failure, and
  * a partition key has a limit that keys built from caller data can pass.
  */
+import { withInstallHint } from "./LambderSdkInstallHint.js";
 let clientSdk;
 let documentSdk;
-const withInstallHint = (loading, packageName, user, reset) => loading.catch((cause) => {
-    // Not memoized: the package may be installed later in the same process (tests), and the next caller names itself.
-    reset();
-    throw new Error(`${user} requires ${packageName}: npm install ${packageName}`, { cause });
-});
 /** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
 const loadDynamoClientSdk = (user) => {
     clientSdk ??= withInstallHint(import("@aws-sdk/client-dynamodb"), "@aws-sdk/client-dynamodb", user, () => { clientSdk = undefined; });

package/dist/stores/LambderMemoryUploadBucket.d.ts

@@ -0,0 +1,99 @@
+import { type LambderUploadBucket, type LambderUploadContentDisposition, type LambderUploadFileFacts, type LambderUploadObjectOptions, type LambderUploadRule, type LambderUploadTicket, type LambderUploadVerdict } from "../shared/contracts/LambderUploadBucket.js";
+export type LambderMemoryUploadBucketOptions = {
+    /**
+     * The URL tickets and download links point under, which a mock's MSW
+     * handler (lambderMockUploadMswHandler) or a test's fetch stub answers
+     * for. Default: a URL of its own per bucket, on a host that cannot
+     * resolve (`https://upload-bucket-<id>.invalid/`), so a request nothing
+     * intercepts fails rather than reaching the network.
+     */
+    baseUrl?: string;
+    /** How long a ticket stays usable, unless a ticket says otherwise. Default: 600 seconds, as LambderS3UploadBucket. */
+    ticketLifetimeSeconds?: number;
+    /** How long a download link reads the object, unless a link says otherwise. Default: 300 seconds, as LambderS3UploadBucket. */
+    downloadLifetimeSeconds?: number;
+    /** The clock tickets and links expire by, injectable so a test can move past an expiry without waiting. Default: Date.now. */
+    now?: () => number;
+};
+/** What the memory bucket holds under a key, for a test to assert on: the object's facts and what it carries. */
+export type LambderMemoryUploadObject = {
+    byteSize: number;
+    mimeType: string;
+    sha256Base64: string;
+} & LambderUploadObjectOptions;
+/**
+ * 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 declare class LambderMemoryUploadBucket implements LambderUploadBucket {
+    /** Where tickets and download links point, always ending in a slash. */
+    readonly baseUrl: string;
+    private readonly ticketLifetimeSeconds;
+    private readonly downloadLifetimeSeconds;
+    private readonly now;
+    private readonly objects;
+    private readonly tickets;
+    private readonly links;
+    constructor({ baseUrl, ticketLifetimeSeconds, downloadLifetimeSeconds, now }?: LambderMemoryUploadBucketOptions);
+    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>;
+    /** The keys that hold an object, sorted, for a test to assert on. */
+    listObjectKeys(): string[];
+    /** What is held under a key (its facts, tags, metadata and headers), for a test to assert on; null when nothing is. */
+    inspectObject(objectKey: string): LambderMemoryUploadObject | null;
+    /** Forgets every object, ticket and link. */
+    reset(): void;
+    /**
+     * 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.
+     */
+    handleStorageRequest(request: Request): Promise<Response | null>;
+    private acceptUpload;
+    private serveDownload;
+}