@crvouga/atlas 0.3.0 → 0.5.0

package/dist/reports/src/s3-store.js

@@ -0,0 +1,295 @@
+/**
+ * @module S3 object store
+ *
+ * An `ObjectStore` on AWS S3 or anything that speaks its protocol (Cloudflare R2, MinIO, SeaweedFS, GCS interoperability,
+ * Backblaze B2, Wasabi), written without an SDK: requests are signed with Signature Version 4 and sent with `fetch`, so
+ * it runs on Bun and Node. Built for many writers and a long-lived reader: connections are reused, requests in flight
+ * are capped, throttling and server errors are retried with jittered backoff, a bucket in another region is followed,
+ * and expired credentials are refreshed once. Credentials never come from a URL; they come from options or the
+ * environment the way an AWS SDK finds them. Importing the module does no work. Change it only with the S3 integration
+ * tests passing against a real server: a fake `fetch` cannot tell you S3 accepts your signature.
+ *
+ * @see docs/report-contract.md#backends
+ * @see docs/deploying.md
+ */
+import { XMLParser } from 'fast-xml-parser';
+import { credentialChain, staticCredentials } from './aws-credentials.js';
+import { amzDate, presignUrl, sha256Hex, signRequest, uriEncode } from './sigv4.js';
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+/**
+ * An error from the store. The message names the bucket and what to do about it (for example the missing IAM
+ * permission); `status` and `code` are what the service answered, `null` when it was never reached.
+ * `retryable` says whether trying again can help; the store already retried before throwing.
+ */
+export class S3Error extends Error {
+    status;
+    code;
+    retryable;
+    constructor(message, status, code, retryable = false) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'S3Error';
+    }
+}
+let parser;
+/** Built on first use, so importing this module does no work. */
+const xml = { parse: (text) => (parser ??= new XMLParser({ ignoreAttributes: true, parseTagValue: false, isArray: name => name === 'Contents' || name === 'CommonPrefixes' })).parse(text) };
+const RETRYABLE_CODES = new Set(['SlowDown', 'RequestTimeout', 'InternalError', 'ServiceUnavailable', 'RequestTimeTooSkewedRetry', 'Throttling', 'ThrottlingException', 'RequestLimitExceeded']);
+function hint(code, status, where, method = 'GET') {
+    switch (code) {
+        case 'AccessDenied':
+        case 'Forbidden':
+            return `${where}: access denied. The credentials need s3:GetObject, s3:PutObject and s3:ListBucket on this bucket and prefix (\`atlas report policy\` prints a least-privilege policy), and the bucket must not forbid them.${method === 'GET' || method === 'HEAD' ? ' Note that S3 also answers 403 for an object that does not exist when s3:ListBucket is not granted.' : ''}`;
+        case 'InvalidAccessKeyId':
+            return `${where}: the access key id is not known to this service. Check AWS_ACCESS_KEY_ID, and that the endpoint and region belong to the same account.`;
+        case 'SignatureDoesNotMatch':
+            return `${where}: the signature was rejected. The secret key is wrong, or the region/endpoint is not the one the keys belong to, or the clock is far off.`;
+        case 'RequestTimeTooSkewed':
+            return `${where}: this machine's clock differs from the service's by more than 15 minutes. Fix the clock.`;
+        case 'NoSuchBucket':
+            return `${where}: the bucket does not exist (or is in another account or endpoint).`;
+        case 'ExpiredToken':
+        case 'InvalidToken':
+            return `${where}: the session token expired. Sign in again (\`aws sso login\`) or refresh the role.`;
+        default:
+            return `${where}: ${code ?? 'HTTP ' + status}`;
+    }
+}
+function parseError(text) {
+    try {
+        const found = xml.parse(text)?.Error;
+        return { code: found?.Code ?? null, message: found?.Message ?? null };
+    }
+    catch {
+        return { code: null, message: null };
+    }
+}
+class Gate {
+    limit;
+    #active = 0;
+    #waiting = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async run(task) {
+        // A finished request hands its place straight to the next in line, so no newcomer can slip in between.
+        if (this.#active >= this.limit)
+            await new Promise(resolve => this.#waiting.push(resolve));
+        else
+            this.#active += 1;
+        try {
+            return await task();
+        }
+        finally {
+            const next = this.#waiting.shift();
+            if (next)
+                next();
+            else
+                this.#active -= 1;
+        }
+    }
+}
+/**
+ * An {@link ObjectStore} on S3, or anything that speaks its protocol: Cloudflare R2, MinIO, Google
+ * Cloud Storage (interoperability), Backblaze B2, Wasabi, SeaweedFS. No SDK: requests are signed with
+ * Signature Version 4 and sent with `fetch`, so it runs on Bun and Node and adds nothing
+ * to the install.
+ *
+ * Made for many writers and a long-lived reader: connections are reused, requests in flight are
+ * capped, throttling and server errors are retried with jittered backoff, a bucket in another region
+ * is followed, and expired credentials are refreshed once.
+ *
+ * Behaviour to know: a missing key reads as `null`/`false` only when S3 answers 404. For an account without
+ * `s3:ListBucket`, S3 answers 403 for a missing key, which throws `S3Error` with a hint: the publishing credentials
+ * need `s3:GetObject`, `s3:PutObject` and `s3:ListBucket` (`atlas report policy` prints a least-privilege policy).
+ * `getUri` returns a presigned URL valid for one hour. `deleteMany` sends one request per key, 16 at a time.
+ * `listKeys` pages through the whole listing and sorts it; use `listPage` to read part of a large catalog. Nothing is
+ * checked or created at construction: the first request is the first contact.
+ *
+ * @example
+ * const store = s3Store({ bucket: 'my-evidence', prefix: 'atlas/my-project', region: 'eu-west-1' });
+ * await store.put('layers/manifests/x.json', bytes, 'application/json');
+ * const { ok, error } = await store.ping();
+ */
+export function s3Store(options) {
+    const env = options.env ?? process.env;
+    const doFetch = options.fetch ?? fetch;
+    const now = options.now ?? (() => new Date());
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const retries = options.retries ?? 4;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const gate = new Gate(options.concurrency ?? 64);
+    const provider = !options.credentials ? credentialChain({ env, fetch: doFetch })
+        : typeof options.credentials === 'function' ? options.credentials : staticCredentials(options.credentials);
+    const prefix = (options.prefix ?? '').replace(/^\/+/, '');
+    const base = prefix && !prefix.endsWith('/') ? `${prefix}/` : prefix;
+    let region = options.region || env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+    const customEndpoint = options.endpoint || env.AWS_ENDPOINT_URL_S3 || env.AWS_ENDPOINT_URL;
+    const pathStyle = options.forcePathStyle ?? (Boolean(customEndpoint) || options.bucket.includes('.'));
+    const where = `s3://${options.bucket}/${base}`;
+    function urlFor(key, query = []) {
+        const encodedKey = key.split('/').map(segment => uriEncode(segment)).join('/');
+        let url;
+        if (customEndpoint) {
+            url = new URL(customEndpoint);
+            url.pathname = `${url.pathname.replace(/\/$/, '')}/${pathStyle ? `${options.bucket}/` : ''}${encodedKey}`;
+            if (!pathStyle)
+                url.hostname = `${options.bucket}.${url.hostname}`;
+        }
+        else if (pathStyle) {
+            url = new URL(`https://s3.${region}.amazonaws.com/${options.bucket}/${encodedKey}`);
+        }
+        else {
+            url = new URL(`https://${options.bucket}.s3.${region}.amazonaws.com/${encodedKey}`);
+        }
+        for (const [name, value] of query)
+            url.searchParams.append(name, value);
+        return url;
+    }
+    async function request(method, key, init = {}) {
+        let refreshed = false;
+        let redirected = false;
+        for (let attempt = 0;; attempt++) {
+            const credentials = await provider();
+            const url = urlFor(key, init.query);
+            const payloadHash = init.body ? await sha256Hex(init.body) : await sha256Hex('');
+            // One instant for the date header and the signature, or a request that straddles a second is rejected.
+            const at = now();
+            const { datetime } = amzDate(at);
+            const headers = await signRequest({
+                method, url, payloadHash, credentials, region, service: 's3', at,
+                headers: { 'x-amz-content-sha256': payloadHash, 'x-amz-date': datetime, ...(credentials.sessionToken ? { 'x-amz-security-token': credentials.sessionToken } : {}) }
+            });
+            if (init.contentType)
+                headers['content-type'] = init.contentType;
+            let response = null;
+            let failure = null;
+            // The timeout is for the service to answer, not for a large body to arrive: it stops at the headers.
+            let timedOut = false;
+            try {
+                // The clock starts when the request does, not while it waits its turn behind the others.
+                response = await gate.run(async () => {
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+                    try {
+                        return await doFetch(url, { method, headers, ...(init.body ? { body: init.body } : {}), signal: controller.signal });
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                });
+            }
+            catch (error) {
+                const reason = timedOut ? `timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error);
+                failure = new S3Error(`${where}: cannot reach ${url.host} (${reason})`, null, null, true);
+            }
+            if (response) {
+                if (response.ok)
+                    return response;
+                const text = method === 'HEAD' ? '' : await response.text().catch(() => '');
+                const { code, message } = parseError(text);
+                // A missing key is an answer. A missing bucket is a mistake, and says so.
+                if (response.status === 404 && init.allow404 && code !== 'NoSuchBucket')
+                    return null;
+                const bucketRegion = response.headers.get('x-amz-bucket-region');
+                if (bucketRegion && bucketRegion !== region && !redirected && [301, 307, 400, 403].includes(response.status)) {
+                    region = bucketRegion;
+                    redirected = true;
+                    continue;
+                }
+                if ((code === 'ExpiredToken' || code === 'InvalidToken' || code === 'ExpiredTokenException') && !refreshed) {
+                    provider.invalidate();
+                    refreshed = true;
+                    continue;
+                }
+                const retryable = response.status >= 500 || response.status === 429 || response.status === 408 || RETRYABLE_CODES.has(code ?? '');
+                failure = new S3Error(`${hint(code, response.status, `${where}${key.slice(base.length)}`, method)}${message && code !== 'AccessDenied' ? ` (${message})` : ''}`, response.status, code, retryable);
+            }
+            if (!failure || !failure.retryable || attempt >= retries)
+                throw failure;
+            // Exponential backoff with full jitter, capped.
+            await sleep(Math.random() * Math.min(8_000, 100 * 2 ** attempt));
+        }
+    }
+    const store = {
+        label: `s3://${options.bucket}/${base}${customEndpoint ? ` (${new URL(customEndpoint).host})` : ` (${region})`}`,
+        credentialSource: () => provider.source(),
+        async get(key) {
+            const response = await request('GET', base + key, { allow404: true });
+            if (!response)
+                return null;
+            return { body: response.body ?? new Blob([]).stream(), contentType: response.headers.get('content-type') ?? 'application/octet-stream', size: Number(response.headers.get('content-length') ?? 0) };
+        },
+        async put(key, bytes, contentType) {
+            const response = await request('PUT', base + key, { body: bytes, contentType });
+            await response?.arrayBuffer();
+        },
+        async head(key) {
+            const response = await request('HEAD', base + key, { allow404: true });
+            return response !== null;
+        },
+        async delete(key) {
+            const response = await request('DELETE', base + key, { allow404: true });
+            await response?.arrayBuffer();
+        },
+        async deleteMany(keys) {
+            // One request per key, a few at a time: DeleteObjects needs a checksum Web Crypto cannot make (MD5).
+            const queue = [...keys];
+            await Promise.all(Array.from({ length: Math.min(16, queue.length) }, async () => {
+                for (let key = queue.shift(); key !== undefined; key = queue.shift())
+                    await store.delete(key);
+            }));
+        },
+        async getUri(key) {
+            if (!(await store.head(key)))
+                return null;
+            return presignUrl({ url: urlFor(base + key), credentials: await provider(), region, service: 's3', at: now(), expiresSeconds: 3600 });
+        },
+        async listKeys(listPrefix = '') {
+            const keys = [];
+            let token;
+            do {
+                const query = [['list-type', '2'], ['encoding-type', 'url'], ['prefix', base + listPrefix]];
+                if (token)
+                    query.push(['continuation-token', token]);
+                const response = (await request('GET', '', { query }));
+                const result = xml.parse(await response.text())?.ListBucketResult;
+                if (!result)
+                    throw new S3Error(`${where}: the listing was not a ListBucketResult`, response.status, null);
+                for (const entry of result.Contents ?? [])
+                    keys.push(decodeURIComponent(String(entry.Key).replace(/\+/g, ' ')).slice(base.length));
+                token = result.IsTruncated === 'true' ? result.NextContinuationToken : undefined;
+            } while (token);
+            // The contract is code-unit order.
+            return keys.sort();
+        },
+        async listPage(listPrefix = '', options = {}) {
+            const limit = Math.max(1, Math.min(options.limit ?? 1000, 1000));
+            const query = [['list-type', '2'], ['encoding-type', 'url'], ['prefix', base + listPrefix], ['max-keys', String(limit)]];
+            if (options.after !== undefined)
+                query.push(['start-after', base + options.after]);
+            const response = (await request('GET', '', { query }));
+            const result = xml.parse(await response.text())?.ListBucketResult;
+            if (!result)
+                throw new S3Error(`${where}: the listing was not a ListBucketResult`, response.status, null);
+            const keys = (result.Contents ?? []).map((entry) => decodeURIComponent(String(entry.Key).replace(/\+/g, ' ')).slice(base.length));
+            return { keys, next: result.IsTruncated === 'true' && keys.length ? keys.at(-1) : null };
+        },
+        withPrefix(extra) {
+            return new ObjectStoreWithPrefix(store, extra);
+        },
+        async ping() {
+            const started = performance.now();
+            try {
+                await request('GET', '', { query: [['list-type', '2'], ['max-keys', '1'], ['prefix', base]] });
+                return { ok: true, ms: Math.round(performance.now() - started) };
+            }
+            catch (error) {
+                return { ok: false, ms: Math.round(performance.now() - started), error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+    };
+    return store;
+}

package/dist/reports/src/scenario.d.ts

@@ -1,15 +1,25 @@
+/**
+ * @module Gherkin scenario view of a recorded run
+ *
+ * Recognises the Gherkin-keyword steps (`Given`, `When`, `Then`, `And`, `But`, `*`) at the top of a recorded step tree
+ * and groups the harness actions nested under each, so the viewer can show a run as a readable script. Pure functions
+ * over `ReportStep`.
+ */
 import type { ReportStep } from './report-types.js';
+/** One Gherkin line of a scenario and what the harness did while it ran. */
 export type ScenarioLine = {
+    /** The Gherkin step itself. */
     readonly step: ReportStep;
     /** Nested harness steps: the actions taken while this line ran. */
     readonly actions: readonly ReportStep[];
 };
+/** Whether a step's `kind` (trimmed, any case) is a Gherkin keyword: `given`, `when`, `then`, `and`, `but` or `*`. */
 export declare function isGherkinStep(step: ReportStep): boolean;
-/** Title with the keyword removed, so the script can show the keyword once. */
+/** The step's title with a leading copy of its `kind` removed (case-insensitively, not word-aware), so the script can show the keyword once. Returns the trimmed title unchanged when it does not start with the kind. */
 export declare function gherkinText(step: ReportStep): string;
 /**
- * Top-level Gherkin lines and the actions nested under each. Null when the
- * run is not a scenario (a model check, a property), so the step tree is
- * the action log instead.
+ * Groups a run's top-level Gherkin steps with the actions nested under each, every descendant step flattened in
+ * depth-first order. Returns `null` when no top-level step is a Gherkin step (a model check, a property), so the step
+ * tree is the action log instead. Gherkin steps nested deeper than the top level are only listed as actions.
  */
 export declare function scenarioScript(steps: readonly ReportStep[]): readonly ScenarioLine[] | null;

package/dist/reports/src/scenario.js

@@ -1,8 +1,9 @@
 const GHERKIN = new Set(['given', 'when', 'then', 'and', 'but', '*']);
+/** Whether a step's `kind` (trimmed, any case) is a Gherkin keyword: `given`, `when`, `then`, `and`, `but` or `*`. */
 export function isGherkinStep(step) {
     return GHERKIN.has(step.kind.trim().toLowerCase());
 }
-/** Title with the keyword removed, so the script can show the keyword once. */
+/** The step's title with a leading copy of its `kind` removed (case-insensitively, not word-aware), so the script can show the keyword once. Returns the trimmed title unchanged when it does not start with the kind. */
 export function gherkinText(step) {
     const kind = step.kind.trim();
     const title = step.title.trim();
@@ -19,9 +20,9 @@ function walkActions(steps, out) {
     }
 }
 /**
- * Top-level Gherkin lines and the actions nested under each. Null when the
- * run is not a scenario (a model check, a property), so the step tree is
- * the action log instead.
+ * Groups a run's top-level Gherkin steps with the actions nested under each, every descendant step flattened in
+ * depth-first order. Returns `null` when no top-level step is a Gherkin step (a model check, a property), so the step
+ * tree is the action log instead. Gherkin steps nested deeper than the top level are only listed as actions.
  */
 export function scenarioScript(steps) {
     const lines = steps.filter(isGherkinStep);

package/dist/reports/src/sigv4.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @module AWS Signature Version 4
+ *
+ * AWS Signature Version 4 request signing and URL presigning, with Web Crypto only, so it runs unchanged on Bun, Node
+ * and in a Worker. S3 and every store that speaks its protocol (R2, MinIO, GCS interoperability, B2, Wasabi) sign this
+ * way. Pure apart from Web Crypto: the time is passed in, nothing is sent. It is tested against AWS's published signing
+ * vectors; change it only with the S3 integration tests passing against a real server.
+ *
+ * @see docs/report-contract.md#backends
+ */
+/** An AWS-style credential. */
+export type Credentials = {
+    /** The public key id; sent in the `Authorization` header. */
+    readonly accessKeyId: string;
+    /** The secret used to derive the signing key. Never sent. */
+    readonly secretAccessKey: string;
+    /** Temporary-credential token, sent as `x-amz-security-token` by the caller; absent for long-lived keys. */
+    readonly sessionToken?: string;
+    /** Epoch milliseconds after which these stop working. Absent for long-lived keys. */
+    readonly expiresAtMs?: number;
+};
+/** The SHA-256 digest of a string (UTF-8) or bytes, as 64 lowercase hex digits. */
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;
+/**
+ * RFC 3986 percent-encoding of the UTF-8 bytes of `value`, which is what SigV4 asks for: letters, digits and `-_.~`
+ * stay, everything else (including `/`, unless `keepSlash`) becomes uppercase `%XX`.
+ */
+export declare function uriEncode(value: string, keepSlash?: boolean): string;
+/** Formats a time for signing: `date` is `YYYYMMDD` and `datetime` is `YYYYMMDDTHHMMSSZ`, both UTC. */
+export declare function amzDate(at: Date): {
+    readonly date: string;
+    readonly datetime: string;
+};
+/** What `signRequest` signs. */
+export type SignInput = {
+    /** The HTTP method, uppercase (`GET`, `PUT`). */
+    readonly method: string;
+    /** The full request URL; its path and query are signed. */
+    readonly url: URL;
+    /** Every header to sign, lowercase names. `host` is added when missing. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** SHA-256 hex of the body, or `UNSIGNED-PAYLOAD`. */
+    readonly payloadHash: string;
+    /** The key to sign with. */
+    readonly credentials: Credentials;
+    /** The region in the credential scope, such as `us-east-1`. */
+    readonly region: string;
+    /** The service in the credential scope, `s3` for S3. */
+    readonly service: string;
+    /** The signing instant. Use the same instant for the `x-amz-date` header, or a request that straddles a second is rejected. */
+    readonly at: Date;
+    /** S3 keeps the path exactly as given; other services encode it twice. */
+    readonly doubleEncodePath?: boolean;
+};
+/**
+ * Signs a request and returns the headers to send: those given, plus `host` (when missing) and `authorization`. The
+ * caller must send exactly these headers (and any it did not sign must not matter to the service). Does not send
+ * anything and does not read the body; `payloadHash` is trusted.
+ */
+export declare function signRequest(input: SignInput): Promise<Record<string, string>>;
+/**
+ * A query-signed URL anyone can GET until it expires, without credentials: for handing a file to a browser. Valid for
+ * `expiresSeconds` from `at`; signs only the `host` header and an unsigned payload, so it works for `GET` only.
+ */
+export declare function presignUrl(input: {
+    readonly url: URL;
+    readonly credentials: Credentials;
+    readonly region: string;
+    readonly service: string;
+    readonly at: Date;
+    readonly expiresSeconds: number;
+}): Promise<string>;

package/dist/reports/src/sigv4.js

@@ -0,0 +1,96 @@
+/**
+ * @module AWS Signature Version 4
+ *
+ * AWS Signature Version 4 request signing and URL presigning, with Web Crypto only, so it runs unchanged on Bun, Node
+ * and in a Worker. S3 and every store that speaks its protocol (R2, MinIO, GCS interoperability, B2, Wasabi) sign this
+ * way. Pure apart from Web Crypto: the time is passed in, nothing is sent. It is tested against AWS's published signing
+ * vectors; change it only with the S3 integration tests passing against a real server.
+ *
+ * @see docs/report-contract.md#backends
+ */
+const encoder = new TextEncoder();
+function hex(bytes) {
+    return Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/** The SHA-256 digest of a string (UTF-8) or bytes, as 64 lowercase hex digits. */
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+    return hex(await crypto.subtle.digest('SHA-256', bytes));
+}
+async function hmac(key, data) {
+    const raw = typeof key === 'string' ? encoder.encode(key) : key;
+    const imported = await crypto.subtle.importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return crypto.subtle.sign('HMAC', imported, encoder.encode(data));
+}
+/**
+ * RFC 3986 percent-encoding of the UTF-8 bytes of `value`, which is what SigV4 asks for: letters, digits and `-_.~`
+ * stay, everything else (including `/`, unless `keepSlash`) becomes uppercase `%XX`.
+ */
+export function uriEncode(value, keepSlash = false) {
+    let out = '';
+    for (const byte of encoder.encode(value)) {
+        const char = String.fromCharCode(byte);
+        if ((byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a) || (byte >= 0x30 && byte <= 0x39) || char === '-' || char === '_' || char === '.' || char === '~' || (keepSlash && char === '/'))
+            out += char;
+        else
+            out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return out;
+}
+/** Formats a time for signing: `date` is `YYYYMMDD` and `datetime` is `YYYYMMDDTHHMMSSZ`, both UTC. */
+export function amzDate(at) {
+    const iso = at.toISOString().replace(/[:-]|\.\d{3}/g, '');
+    return { date: iso.slice(0, 8), datetime: iso };
+}
+function canonicalQuery(params) {
+    return [...params]
+        .map(([key, value]) => [uriEncode(key), uriEncode(value)])
+        .sort(([a, av], [b, bv]) => (a < b ? -1 : a > b ? 1 : av < bv ? -1 : av > bv ? 1 : 0))
+        .map(([key, value]) => `${key}=${value}`)
+        .join('&');
+}
+async function signingKey(secret, date, region, service) {
+    return hmac(await hmac(await hmac(await hmac(`AWS4${secret}`, date), region), service), 'aws4_request');
+}
+/**
+ * Signs a request and returns the headers to send: those given, plus `host` (when missing) and `authorization`. The
+ * caller must send exactly these headers (and any it did not sign must not matter to the service). Does not send
+ * anything and does not read the body; `payloadHash` is trusted.
+ */
+export async function signRequest(input) {
+    const { date, datetime } = amzDate(input.at);
+    const headers = { ...input.headers };
+    headers.host ??= input.url.host;
+    const names = Object.keys(headers).map(name => name.toLowerCase()).sort();
+    const canonicalHeaders = names.map(name => `${name}:${(headers[name] ?? '').trim().replace(/\s+/g, ' ')}\n`).join('');
+    const path = input.url.pathname.split('/').map(segment => uriEncode(decodeURIComponent(segment))).join('/') || '/';
+    const canonicalPath = input.doubleEncodePath ? path.split('/').map(segment => uriEncode(segment)).join('/') : path;
+    const signedHeaders = names.join(';');
+    const canonical = [input.method, canonicalPath, canonicalQuery(input.url.searchParams), canonicalHeaders, signedHeaders, input.payloadHash].join('\n');
+    const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+    const toSign = ['AWS4-HMAC-SHA256', datetime, scope, await sha256Hex(canonical)].join('\n');
+    const signature = hex(await hmac(await signingKey(input.credentials.secretAccessKey, date, input.region, input.service), toSign));
+    headers.authorization = `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return headers;
+}
+/**
+ * A query-signed URL anyone can GET until it expires, without credentials: for handing a file to a browser. Valid for
+ * `expiresSeconds` from `at`; signs only the `host` header and an unsigned payload, so it works for `GET` only.
+ */
+export async function presignUrl(input) {
+    const { date, datetime } = amzDate(input.at);
+    const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+    const url = new URL(input.url);
+    url.searchParams.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+    url.searchParams.set('X-Amz-Credential', `${input.credentials.accessKeyId}/${scope}`);
+    url.searchParams.set('X-Amz-Date', datetime);
+    url.searchParams.set('X-Amz-Expires', String(input.expiresSeconds));
+    url.searchParams.set('X-Amz-SignedHeaders', 'host');
+    if (input.credentials.sessionToken)
+        url.searchParams.set('X-Amz-Security-Token', input.credentials.sessionToken);
+    const path = url.pathname.split('/').map(segment => uriEncode(decodeURIComponent(segment))).join('/') || '/';
+    const canonical = ['GET', path, canonicalQuery(url.searchParams), `host:${url.host}\n`, 'host', 'UNSIGNED-PAYLOAD'].join('\n');
+    const toSign = ['AWS4-HMAC-SHA256', datetime, scope, await sha256Hex(canonical)].join('\n');
+    url.searchParams.set('X-Amz-Signature', hex(await hmac(await signingKey(input.credentials.secretAccessKey, date, input.region, input.service), toSign)));
+    return url.toString();
+}

package/dist/reports/src/snapshot-bundle.d.ts

@@ -1,16 +1,39 @@
 import type { ObjectStore } from './object-store.js';
+/**
+ * Copies `files` from `local` into gzip chunks on `remote`, then writes the index last, so a reader that finds the
+ * index can read every chunk it names.
+ *
+ * Each file is read from `local` at `localPrefix + file` and stored under the name `file` in the index. Chunks are
+ * packed up to about 1 MiB of encoded text (a larger single file gets a chunk of its own) and uploaded four at a time
+ * to `remotePrefix`. Throws `Missing report snapshot: <key>` when a listed file is absent in `local`, before anything
+ * is written to `remote`.
+ */
 export declare function publishSnapshotBundle(args: {
+    /** Where the recorded files are now. */
     readonly local: ObjectStore;
+    /** Where the bundle is written. */
     readonly remote: ObjectStore;
+    /** The key prefix of the files in `local`. */
     readonly localPrefix: string;
+    /** The key prefix to write the bundle under; end it with `/`. */
     readonly remotePrefix: string;
+    /** The file names, relative to `localPrefix`. */
     readonly files: readonly string[];
 }): Promise<void>;
+/**
+ * Reads one file from a bundle written by `publishSnapshotBundle`, decompressing the chunk that holds it. Returns `null`
+ * when the bundle has no index, the file is not in the index, or its chunk is missing. Throws `Invalid snapshot chunk`
+ * for a chunk name that is not `snapshots-<n>.json.gz`, and a `SyntaxError` for a corrupt index or chunk.
+ */
 export declare function readBundledSnapshot(store: ObjectStore, prefix: string, file: string): Promise<{
     readonly bytes: Uint8Array;
     readonly contentType: string;
 } | null>;
-/** A streamed test reads each compressed chunk once even when it contains many frames. */
+/**
+ * Streams the requested `files` of a bundle as `{ file, bytes, contentType }`, in the order chunks finish reading (not
+ * the order of `files`). A streamed test reads each compressed chunk once even when it contains many frames. Files not
+ * in the index and chunks that are missing are skipped silently; a bundle with no index yields nothing.
+ */
 export declare function readBundledSnapshots(store: ObjectStore, prefix: string, files: ReadonlySet<string>): AsyncGenerator<{
     bytes: Uint8Array;
     contentType: string;

package/dist/reports/src/snapshot-bundle.js

@@ -1,4 +1,11 @@
-/** Indexed gzip chunks keep snapshot uploads small in count and reads bounded. */
+/**
+ * @module Snapshot bundles
+ *
+ * Packs the frame files of one recorded test into a few gzip chunks of roughly 1 MiB (JSON of base64 snapshots), with a
+ * small index from file to chunk, so a test with hundreds of frames uploads as a handful of objects and a reader
+ * fetches only the chunks it needs. Keys are `<prefix>snapshots.json` (the index, written last) and
+ * `<prefix>snapshots-<n>.json.gz`. Reads reject a chunk name that does not look like `snapshots-<n>.json.gz`.
+ */
 import { readBytes, readObjectBytes, readUtf8, writeUtf8, } from './object-io.js';
 import { eachLimited, inCompletionOrder } from './completion-order.js';
 const CHUNK_BYTES = 1024 * 1024;
@@ -12,6 +19,15 @@ async function gzip(text) {
     const input = new Blob([text]).stream();
     return readBytes(input.pipeThrough(new CompressionStream('gzip')));
 }
+/**
+ * Copies `files` from `local` into gzip chunks on `remote`, then writes the index last, so a reader that finds the
+ * index can read every chunk it names.
+ *
+ * Each file is read from `local` at `localPrefix + file` and stored under the name `file` in the index. Chunks are
+ * packed up to about 1 MiB of encoded text (a larger single file gets a chunk of its own) and uploaded four at a time
+ * to `remotePrefix`. Throws `Missing report snapshot: <key>` when a listed file is absent in `local`, before anything
+ * is written to `remote`.
+ */
 export async function publishSnapshotBundle(args) {
     const index = {};
     const chunks = [];
@@ -45,6 +61,11 @@ export async function publishSnapshotBundle(args) {
     });
     await writeUtf8(args.remote, `${args.remotePrefix}snapshots.json`, JSON.stringify(index), 'application/json');
 }
+/**
+ * Reads one file from a bundle written by `publishSnapshotBundle`, decompressing the chunk that holds it. Returns `null`
+ * when the bundle has no index, the file is not in the index, or its chunk is missing. Throws `Invalid snapshot chunk`
+ * for a chunk name that is not `snapshots-<n>.json.gz`, and a `SyntaxError` for a corrupt index or chunk.
+ */
 export async function readBundledSnapshot(store, prefix, file) {
     const text = await readUtf8(store, `${prefix}snapshots.json`);
     if (text === null)
@@ -74,7 +95,11 @@ function snapshotBody(snapshot) {
     const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
     return { bytes, contentType: snapshot.contentType };
 }
-/** A streamed test reads each compressed chunk once even when it contains many frames. */
+/**
+ * Streams the requested `files` of a bundle as `{ file, bytes, contentType }`, in the order chunks finish reading (not
+ * the order of `files`). A streamed test reads each compressed chunk once even when it contains many frames. Files not
+ * in the index and chunks that are missing are skipped silently; a bundle with no index yields nothing.
+ */
 export async function* readBundledSnapshots(store, prefix, files) {
     const text = await readUtf8(store, `${prefix}snapshots.json`);
     if (text === null)