lambder 7.3.1 → 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/transport/LambderApiTransport.d.ts

@@ -16,9 +16,9 @@ export type LambderApiTransportRequest = {
     token: string;
     /**
      * The cookie name the caller reads that token from. A transport that
-     * fills the token in itself (the cookie-jar decorator, where there is no
-     * document to read) needs the same name, and taking it from the caller is
-     * what keeps the two from being configured apart.
+     * fills the token in itself (the cookie-jar decorator, with no document
+     * to read) needs the same name; taking it from the caller keeps the two
+     * from being configured apart.
      */
     csrfCookieKey?: string;
     siteHost: string;
@@ -36,10 +36,9 @@ export type LambderApiTransportRequest = {
 };
 /**
  * Why a transport could not deliver a call. `network` is the default reading
- * of a rejection: nothing came back. `protocol` says the call reached the
- * callee and no answer came of it, either because what came back was not one
- * or because the callee threw instead of answering, which is a server or
- * wiring fault and should not be reported to a developer as flaky
+ * of a rejection: nothing came back. `protocol` means the call reached the
+ * callee but produced no answer (what came back was not one, or the callee
+ * threw): a server or wiring fault, not to be reported as flaky
  * connectivity. `timeout` belongs to the caller, which knows whether its own
  * abort fired.
  */
@@ -60,27 +59,28 @@ export declare class LambderTransportFailure extends Error {
 export declare const isLambderTransportFailure: (err: unknown) => err is LambderTransportFailure;
 /**
  * Delivers one call and hands back the answer in the accessor form
- * resolveApiOutcome() reads. What a transport owes its caller, since nothing
- * but this contract stands between a call and a wrong outcome:
+ * resolveApiOutcome() reads. What a transport owes its caller:
  *
  * - **Any HTTP status is an answer.** A 4xx or 5xx resolves, status and body
  *   included, because resolveApiOutcome() is the one place that reads what a
- *   status means. A transport that rejects on a status throws away the
- *   envelope a refusal, a validation failure or a crash arrived in.
+ *   status means. Rejecting on a status would throw away the envelope a
+ *   refusal, a validation failure or a crash arrived in.
  * - **A rejection is a transport failure.** The caller reports it as
- *   `network` unless the transport threw a LambderTransportFailure naming
- *   another reason, or `timeout` when the caller's own abort fired. That is
- *   the channel for the real cause too: a LambderTransportFailure keeps it as
- *   `cause`, where the caller's `outcome.error` carries it.
+ *   `network`, as `timeout` when its own abort fired, or as the reason a
+ *   thrown LambderTransportFailure names. That failure's `cause` carries the
+ *   real error through to the caller's `outcome.error`.
  * - **`request.signal` must be honoured**, by rejecting as soon as it aborts.
- *   It is the only thing that makes the caller's `timeoutMs` and its per-call
- *   `signal` mean anything: a transport that ignores it leaves a call waiting
- *   for as long as the callee takes, whatever the caller asked for. Work
- *   already begun need not be cancellable (an in-process handler is not); the
- *   obligation is to stop waiting, not to stop the callee.
+ *   Without that, the caller's `timeoutMs` and per-call `signal` mean
+ *   nothing and a call waits as long as the callee takes. Work already begun
+ *   need not be cancellable (an in-process handler is not); the obligation
+ *   is to stop waiting, not to stop the callee.
  * - **Timeouts and retries belong to the caller.** A transport starts no
  *   clock of its own and retries nothing, so one call is one delivery
  *   attempt and an idempotency key means what it says.
+ * - **A transport that keeps the session's cookies itself reports its CSRF
+ *   tokens** on the answer (`csrfTokens`), the one it posted and a read of the
+ *   one it holds, since the caller otherwise judges a sessionExpired by
+ *   document.cookie, which such a transport never writes.
  *
  * Four transports ship: fetch (lambderFetchTransport, the browser default),
  * an in-process Lambder handler (lambderHandlerTransport, for tests), the
@@ -89,16 +89,16 @@ export declare const isLambderTransportFailure: (err: unknown) => err is Lambder
  */
 export type LambderApiTransport = (request: LambderApiTransportRequest) => Promise<LambderApiHttpAnswer>;
 /**
- * The fields of the request envelope, in the order they go on the wire: the
- * one statement of what a call sends, for every sender there is.
+ * The fields of the request envelope, in wire order: the one statement of
+ * what a call sends, for every sender.
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
- * its payload to decide whether to compress it, and splices that JSON onto the
- * end rather than parsing and stringifying it a second time
- * (buildEnvelopeJson, in invoke/LambderLambdaEvent.ts). The splice sits on top
- * of this function precisely so that a new envelope field cannot be added to
- * one sender and missed by the other, which nothing on the wire would catch.
+ * its payload to decide on compression, and splices that JSON onto the end
+ * rather than parsing and stringifying it again (buildEnvelopeJson, in
+ * invoke/LambderLambdaEvent.ts). The splice builds on this function so a new
+ * envelope field cannot reach one sender and miss the other, which nothing on
+ * the wire would catch.
  */
 export declare const buildEnvelopeFields: (fields: {
     apiName: string;

package/dist/shared/transport/LambderApiTransport.js

@@ -15,16 +15,16 @@ export class LambderTransportFailure extends Error {
 /** Brand-based type guard, so a duplicate install of the package still matches. */
 export const isLambderTransportFailure = (err) => err instanceof Error && err.isLambderTransportFailure === true;
 /**
- * The fields of the request envelope, in the order they go on the wire: the
- * one statement of what a call sends, for every sender there is.
+ * The fields of the request envelope, in wire order: the one statement of
+ * what a call sends, for every sender.
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
- * its payload to decide whether to compress it, and splices that JSON onto the
- * end rather than parsing and stringifying it a second time
- * (buildEnvelopeJson, in invoke/LambderLambdaEvent.ts). The splice sits on top
- * of this function precisely so that a new envelope field cannot be added to
- * one sender and missed by the other, which nothing on the wire would catch.
+ * its payload to decide on compression, and splices that JSON onto the end
+ * rather than parsing and stringifying it again (buildEnvelopeJson, in
+ * invoke/LambderLambdaEvent.ts). The splice builds on this function so a new
+ * envelope field cannot reach one sender and miss the other, which nothing on
+ * the wire would catch.
  */
 export const buildEnvelopeFields = (fields) => ({
     apiName: fields.apiName,

package/dist/shared/transport/LambderCookieJar.d.ts

@@ -36,28 +36,23 @@ export declare const parseSetCookie: (header: string, now: number, requestPath?:
  * in-process handler transport in a Node test, and the mock runtime's direct
  * transport. It stores what an answer's Set-Cookie headers set, honours their
  * expiry and deletion, and hands back the Cookie pairs the next request should
- * carry. One jar is one browser; two jars are two.
+ * carry. One jar is one browser.
  *
- * The rules themselves are tough-cookie's, which is the reference
- * implementation of RFC 6265 and carries the public suffix list: domain and
- * path matching, default-path, Max-Age against Expires, Secure, HttpOnly, and
- * the __Host-/__Secure- prefixes. That list is the part worth importing rather
- * than writing. A hand-rolled check can tell that `Domain=com` is a registry
- * suffix by counting labels, and cannot tell that `co.uk` is one, so a
- * hand-rolled jar either trusts `Domain=co.uk` or bans every two-label domain.
+ * The rules (domain and path matching, default-path, Max-Age against Expires,
+ * Secure, HttpOnly, the __Host-/__Secure- prefixes) are tough-cookie's, the
+ * reference RFC 6265 implementation, imported for its public suffix list:
+ * counting labels can tell `Domain=com` is a registry suffix but not `co.uk`,
+ * so a hand-rolled jar either trusts `Domain=co.uk` or bans every two-label
+ * domain.
  *
- * What stays Lambder's is the shape of the questions a transport asks: whole
- * Set-Cookie header lists in (storeSetCookies), `name=value` pairs out
- * (cookiePairs), and a target given as a host and path rather than a URL,
- * since a transport that never speaks HTTP has no URL to give. A field the
- * caller omits is one it could not know, and an unknown field matches
- * anything: a jar pointed at a single host is the ordinary case, and refusing
- * to answer it until it can name that host would make the common setup the
- * awkward one.
+ * What stays Lambder's is the shape of a transport's questions: Set-Cookie
+ * header lists in (storeSetCookies), `name=value` pairs out (cookiePairs),
+ * and a target given as host and path, since a transport that never speaks
+ * HTTP has no URL. An omitted field matches anything, because a jar pointed
+ * at a single host is the ordinary case and should not have to name it.
  *
- * SameSite is stored but never consulted. It answers "did another site
- * initiate this", and a transport call has no initiating site: every call here
- * is same-site by construction.
+ * SameSite is stored but never consulted: it answers "did another site
+ * initiate this", and every transport call is same-site by construction.
  */
 export declare class LambderCookieJar {
     private readonly jar;
@@ -76,25 +71,24 @@ export declare class LambderCookieJar {
      * came from. Its `host` is the sending host, which every Domain is checked
      * against, and its `path` is the default Path of a cookie that names none.
      *
-     * A Domain the sender is not under does not narrow a cookie, it voids it
-     * (RFC 6265 section 5.3 step 6), and so does a Domain that is a public
-     * suffix. Both are how evil.example.com would otherwise plant a cookie
-     * that bank.example.com is handed on the next call.
+     * A Domain the sender is not under voids the cookie rather than narrowing
+     * it (RFC 6265 section 5.3 step 6), and so does a public-suffix Domain.
+     * Otherwise evil.example.com could plant a cookie that bank.example.com
+     * is handed on the next call.
      */
     storeSetCookies(headers: readonly string[], request?: LambderCookieTarget): void;
     /** Every live cookie. */
     list(): LambderStoredCookie[];
     /**
      * The Cookie header pairs the next request carries, as `name=value`, in
-     * the order RFC 6265 section 5.4 puts them in: the longest Path first,
-     * and among equal paths the one set first. Servers that read only the
-     * first value of a repeated name depend on that order, and so does any
-     * test reasoning about which of two same-named cookies wins.
+     * RFC 6265 section 5.4 order: longest Path first, and among equal paths
+     * the one set first. Servers that read only the first value of a repeated
+     * name depend on that order, as does any test about which of two
+     * same-named cookies wins.
      *
-     * Only the cookies whose scope covers the target travel. A field the
-     * target leaves out is one the caller could not know, and matches
-     * anything: a caller that cannot name its own host still gets the cookies
-     * of the one host its jar talks to.
+     * Only cookies whose scope covers the target travel. An omitted target
+     * field matches anything, so a caller that cannot name its host still
+     * gets the cookies of the one host its jar talks to.
      */
     cookiePairs(target?: LambderCookieTarget): string[];
     /**
@@ -107,10 +101,9 @@ export declare class LambderCookieJar {
     } & LambderCookieTarget): string | undefined;
     /**
      * The live cookies whose scope reaches this target, in RFC 6265 send
-     * order. Delegated to tough-cookie whenever the target names a host,
-     * which is the case worth getting exactly right; an unnamed host falls
-     * back to every cookie the jar holds, filtered by the rules that do not
-     * need one and ordered by the same rule.
+     * order. Delegated to tough-cookie whenever a host is known, the case
+     * worth getting exactly right; with no host, every cookie the jar holds
+     * is filtered by the rules that need none and ordered the same way.
      */
     private matchingCookies;
     /** Number of live cookies. */