@crvouga/atlas 0.4.0 → 0.5.0

package/dist/reports/src/attachment-files.js

@@ -0,0 +1,121 @@
+/**
+ * @module Reading the files attachments name
+ *
+ * Turns an attachment that names a file on disk (`path`) into one that carries its bytes (`data`), just before a
+ * layer is published. It owns the safety rules for doing so: a path that came from a test report may only name
+ * files inside the allowed roots, never a hidden file, and never a link that leads out; a path the person running
+ * the command typed is trusted. It does not upload anything. Node-only (reads the file system).
+ *
+ * @see docs/report-contract.md (evidence rule 7: paths inside a report are data from a test run)
+ */
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { contentTypeOf } from './media-types.js';
+/**
+ * Reads the files that attachments name (`path`), at every level (the holder, its `steps` and its `attempts`,
+ * recursively), and hands their bytes over as `data` with a `contentType` guessed from the file name when the
+ * attachment gave none.
+ *
+ * A file that is missing, not allowed or too large is left out with a warning: evidence that could not be
+ * found never stops the results from being published. Attachments without a `path` are kept untouched.
+ *
+ * @param holder A check, step, attempt or any object that may have `attachments`, `steps` and `attempts`.
+ * @param roots Folders a relative path is resolved against (in order), and the only folders an untrusted path may name.
+ * @returns The rewritten copy, counts and warnings; never throws for a bad file.
+ */
+export async function readAttachmentFiles(holder, roots, options = {}) {
+    const warnings = [];
+    const maxBytes = options.maxBytes ?? 512 * 1024 * 1024;
+    let attached = 0, bytes = 0;
+    async function walk(value) {
+        const out = { ...value };
+        if (Array.isArray(out.attachments)) {
+            const kept = [];
+            for (const given of out.attachments) {
+                const file = typeof given.path === 'string' ? given.path : undefined;
+                if (file === undefined) {
+                    kept.push(given);
+                    continue;
+                }
+                const name = String(given.name ?? file);
+                const { path: _path, ...rest } = given;
+                const found = await locate(file, roots, options.trusted === true);
+                if (found.problem) {
+                    warnings.push(`${name}: ${found.problem}`);
+                    continue;
+                }
+                const size = (await stat(found.file)).size;
+                if (size > maxBytes) {
+                    warnings.push(`${name}: ${(size / 1024 / 1024).toFixed(0)} MiB is over the limit of ${Math.round(maxBytes / 1024 / 1024)} MiB`);
+                    continue;
+                }
+                if (options.budget && size > options.budget.remaining) {
+                    warnings.push(`${name}: the total size of attachments would pass the budget (raise --max-total-attachment-mb, or attach a uri)`);
+                    continue;
+                }
+                if (options.budget)
+                    options.budget.remaining -= size;
+                attached += 1;
+                bytes += size;
+                kept.push({ ...rest, data: new Uint8Array(await readFile(found.file)), ...(rest.contentType ? {} : { contentType: contentTypeOf(found.file) }) });
+            }
+            out.attachments = kept;
+        }
+        if (Array.isArray(out.steps)) {
+            const steps = [];
+            for (const step of out.steps)
+                steps.push(await walk(step));
+            out.steps = steps;
+        }
+        if (Array.isArray(out.attempts)) {
+            const attempts = [];
+            for (const attempt of out.attempts)
+                attempts.push(await walk(attempt));
+            out.attempts = attempts;
+        }
+        return out;
+    }
+    return { value: await walk(holder), attached, bytes, warnings };
+}
+/** Is `file` inside `root`, once both are real paths (so a link cannot lead out)? */
+function inside(file, root) {
+    const relative = path.relative(root, file);
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+// Resolves a named file to a real path, or says why not. A trusted path may also be relative to the working
+// directory; an untrusted one must land, after resolving links, inside a root and under no dot-named part.
+async function locate(file, roots, trusted) {
+    const candidates = path.isAbsolute(file) ? [file] : [...roots.map(root => path.resolve(root, file)), ...(trusted ? [path.resolve(file)] : [])];
+    let outside = false;
+    for (const candidate of candidates) {
+        let real;
+        try {
+            real = await realpath(candidate);
+            if (!(await stat(real)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (trusted)
+            return { file: real };
+        const root = await firstRootHolding(real, roots);
+        // A hidden file or folder (.env, .aws, .git, .ssh) is never attached on a report's say-so.
+        if (!root || path.relative(root, real).split(path.sep).some(part => part.startsWith('.'))) {
+            outside = true;
+            continue;
+        }
+        return { file: real };
+    }
+    return { problem: outside ? `${file} is outside the folders reports may attach from (the report's own folder and each --attach-root), or is a hidden file: pass --attach-root <dir> to allow a folder` : `file not found (${file})` };
+}
+async function firstRootHolding(real, roots) {
+    for (const root of roots) {
+        try {
+            if (inside(real, await realpath(root)))
+                return await realpath(root);
+        }
+        catch { /* a root that is not there holds nothing */ }
+    }
+    return null;
+}

package/dist/reports/src/attachment-response.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module Serving attachment bytes safely
+ *
+ * Builds the HTTP response for an attachment's bytes. A producer chose the media type, and the bytes come from a
+ * test run, so they are treated as untrusted: never sniffed, never allowed to run scripts, never embedded by
+ * another site. Videos can be sought (HTTP range requests). Every route that serves attachment bytes must go
+ * through here (or add {@link UNTRUSTED_HEADERS}); it never reads from a store itself.
+ *
+ * @see docs/report-contract.md (evidence rule 8)
+ */
+/**
+ * Headers for bytes that came from a test run: never sniffed (`nosniff`), a sandboxing content-security policy so a
+ * page navigated to at this address runs locked down, and `cross-origin-resource-policy: same-origin` so
+ * another site cannot embed it. Spread these into every response that serves attachment or recorded bytes.
+ */
+export declare const UNTRUSTED_HEADERS: Readonly<Record<string, string>>;
+/**
+ * Answers a request for one attachment's bytes with the untrusted-bytes headers, long-lived immutable caching
+ * and range support.
+ *
+ * The producer's `contentType` is used only when it is a well-formed media type (`type/subtype` with simple
+ * parameters); anything else is served as `application/octet-stream`. A matching `if-none-match` answers 304.
+ * A single `bytes=a-b`, `bytes=a-` or `bytes=-n` range answers 206, an unsatisfiable one 416; multiple ranges are
+ * not understood and get the whole body (200).
+ *
+ * @param etag A strong validator the caller derives from content identity (it is sent as given, so include the quotes).
+ */
+export declare function attachmentResponse(request: Request, entry: {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}, etag: string): Response;

package/dist/reports/src/attachment-response.js

@@ -0,0 +1,55 @@
+/**
+ * @module Serving attachment bytes safely
+ *
+ * Builds the HTTP response for an attachment's bytes. A producer chose the media type, and the bytes come from a
+ * test run, so they are treated as untrusted: never sniffed, never allowed to run scripts, never embedded by
+ * another site. Videos can be sought (HTTP range requests). Every route that serves attachment bytes must go
+ * through here (or add {@link UNTRUSTED_HEADERS}); it never reads from a store itself.
+ *
+ * @see docs/report-contract.md (evidence rule 8)
+ */
+/**
+ * Headers for bytes that came from a test run: never sniffed (`nosniff`), a sandboxing content-security policy so a
+ * page navigated to at this address runs locked down, and `cross-origin-resource-policy: same-origin` so
+ * another site cannot embed it. Spread these into every response that serves attachment or recorded bytes.
+ */
+export const UNTRUSTED_HEADERS = {
+    'x-content-type-options': 'nosniff',
+    // If a page is ever navigated to or framed from this address, it runs as a locked-down document.
+    'content-security-policy': "sandbox; default-src 'none'; img-src data:; media-src 'self'; style-src 'unsafe-inline'",
+    'cross-origin-resource-policy': 'same-origin'
+};
+/**
+ * Answers a request for one attachment's bytes with the untrusted-bytes headers, long-lived immutable caching
+ * and range support.
+ *
+ * The producer's `contentType` is used only when it is a well-formed media type (`type/subtype` with simple
+ * parameters); anything else is served as `application/octet-stream`. A matching `if-none-match` answers 304.
+ * A single `bytes=a-b`, `bytes=a-` or `bytes=-n` range answers 206, an unsatisfiable one 416; multiple ranges are
+ * not understood and get the whole body (200).
+ *
+ * @param etag A strong validator the caller derives from content identity (it is sent as given, so include the quotes).
+ */
+export function attachmentResponse(request, entry, etag) {
+    // A media type is a short token list; anything with line breaks or odd characters is not one.
+    const type = /^[\w.+-]+\/[\w.+-]+(?:\s*;\s*[\w.-]+=[\w.\-"]+)*$/.test(entry.contentType) ? entry.contentType : 'application/octet-stream';
+    const headers = {
+        'content-type': type,
+        ...UNTRUSTED_HEADERS,
+        'cache-control': 'public, max-age=31536000, immutable',
+        'accept-ranges': 'bytes',
+        etag
+    };
+    if (request.headers.get('if-none-match') === etag)
+        return new Response(null, { status: 304, headers });
+    const size = entry.bytes.length;
+    const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '');
+    if (!range || (range[1] === '' && range[2] === ''))
+        return new Response(entry.bytes, { headers: { ...headers, 'content-length': String(size) } });
+    // `bytes=-500` is the last 500 bytes; `bytes=500-` is from 500 on.
+    const start = range[1] === '' ? Math.max(0, size - Number(range[2])) : Number(range[1]);
+    const end = range[1] === '' || range[2] === '' ? size - 1 : Math.min(Number(range[2]), size - 1);
+    if (start >= size || start > end)
+        return new Response(null, { status: 416, headers: { ...headers, 'content-range': `bytes */${size}` } });
+    return new Response(entry.bytes.slice(start, end + 1), { status: 206, headers: { ...headers, 'content-range': `bytes ${start}-${end}/${size}`, 'content-length': String(end - start + 1) } });
+}

package/dist/reports/src/aws-credentials.d.ts

@@ -0,0 +1,48 @@
+import type { Credentials } from './sigv4.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * An async function returning currently valid credentials, with cache control. Concurrent calls share one lookup;
+ * cached credentials are reused until shortly before they expire (never, when they carry no expiry).
+ */
+export type CredentialProvider = (() => Promise<Credentials>) & {
+    /** Drop what is cached, so the next call asks again. Used when a store says the credentials expired. */
+    invalidate(): void;
+    /** Where the credentials came from, once known: "environment", "web identity (IRSA)", "profile prod", … */
+    source(): string | null;
+};
+/** Options of {@link credentialChain}; every one exists so a test can replace a piece of the machine. */
+export type ChainOptions = {
+    /** The environment variables to read. Default `process.env`. */
+    readonly env?: Env;
+    /** The HTTP client for STS, container and instance-metadata calls. Default global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Reads a UTF-8 file. Default `fs.readFile`. */
+    readonly readFile?: (file: string) => Promise<string>;
+    /** Run a command and return its stdout, or null when it is not installed or fails. Default spawns it with a 20 s timeout. */
+    readonly run?: (command: string, args: readonly string[]) => Promise<string | null>;
+    /** The clock, epoch milliseconds. Default `Date.now`. */
+    readonly now?: () => number;
+    /** The home directory that holds `.aws/credentials`. Default `$HOME`, then the OS home. */
+    readonly home?: string;
+    /** Refresh this long before credentials expire, in milliseconds. Default 5 minutes. */
+    readonly skewMs?: number;
+};
+/**
+ * Creates a provider for the credentials an AWS SDK would find, in the same order, with no SDK: environment, web
+ * identity (EKS), container (ECS), shared credentials file, the AWS CLI (which covers SSO and assumed roles),
+ * and EC2 instance metadata. `ATLAS_S3_ACCESS_KEY_ID` / `ATLAS_S3_SECRET_ACCESS_KEY` (and `ATLAS_S3_SESSION_TOKEN`)
+ * come first so one store can use keys that are not the machine's AWS keys, such as Cloudflare R2 tokens.
+ *
+ * Nothing is looked up until the provider is first called. The first source that yields credentials wins and
+ * is cached; a source that throws (for example an STS error) is skipped and reported if no later source works.
+ * When none works the provider rejects with an error that lists every source tried and how to fix it. Set
+ * `ATLAS_NO_AWS_CLI` to skip the `aws` CLI step and `AWS_EC2_METADATA_DISABLED=true` to skip instance metadata.
+ *
+ * @example
+ * const credentials = await credentialChain()();
+ * credentials.accessKeyId;
+ */
+export declare function credentialChain(options?: ChainOptions): CredentialProvider;
+/** Wraps keys that are already known in a {@link CredentialProvider} that never refreshes (its `invalidate` does nothing). */
+export declare function staticCredentials(credentials: Credentials): CredentialProvider;
+export {};

package/dist/reports/src/aws-credentials.js

@@ -0,0 +1,221 @@
+/**
+ * @module AWS credential lookup
+ *
+ * Finds S3 credentials the way an AWS SDK does, without depending on one: environment variables, web identity
+ * (EKS), ECS container credentials, the shared credentials file, the AWS CLI (SSO, assumed roles) and EC2 instance
+ * metadata. It owns the lookup order, the caching and the early refresh before expiry; it does not sign requests
+ * (that is `sigv4.ts`) or know about buckets (`s3-store.ts`). Credentials are never put in a store URL: they
+ * come from here. Node-only (reads files, spawns `aws`). Nothing runs at import time.
+ *
+ * @see docs/report-contract.md (backends)
+ */
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { XMLParser } from 'fast-xml-parser';
+let parser;
+/** Built on first use, so importing this module does no work. */
+const xml = { parse: (text) => (parser ??= new XMLParser({ ignoreAttributes: true, parseTagValue: false })).parse(text) };
+async function runCommand(command, args) {
+    return new Promise(resolve => {
+        try {
+            const child = spawn(command, [...args], { stdio: ['ignore', 'pipe', 'ignore'] });
+            let out = '';
+            const timer = setTimeout(() => { child.kill(); resolve(null); }, 20_000);
+            child.stdout.on('data', chunk => { out += String(chunk); });
+            child.on('error', () => { clearTimeout(timer); resolve(null); });
+            child.on('close', code => { clearTimeout(timer); resolve(code === 0 ? out : null); });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+function parseIni(text) {
+    const sections = {};
+    let current = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#') || line.startsWith(';'))
+            continue;
+        const header = /^\[(?:profile\s+)?([^\]]+)\]$/.exec(line);
+        if (header) {
+            current = sections[header[1].trim()] ??= {};
+            continue;
+        }
+        const at = line.indexOf('=');
+        if (current && at > 0)
+            current[line.slice(0, at).trim().toLowerCase()] = line.slice(at + 1).trim();
+    }
+    return sections;
+}
+function expiry(value) {
+    const time = typeof value === 'string' ? Date.parse(value) : NaN;
+    return Number.isFinite(time) ? time : undefined;
+}
+/**
+ * Creates a provider for the credentials an AWS SDK would find, in the same order, with no SDK: environment, web
+ * identity (EKS), container (ECS), shared credentials file, the AWS CLI (which covers SSO and assumed roles),
+ * and EC2 instance metadata. `ATLAS_S3_ACCESS_KEY_ID` / `ATLAS_S3_SECRET_ACCESS_KEY` (and `ATLAS_S3_SESSION_TOKEN`)
+ * come first so one store can use keys that are not the machine's AWS keys, such as Cloudflare R2 tokens.
+ *
+ * Nothing is looked up until the provider is first called. The first source that yields credentials wins and
+ * is cached; a source that throws (for example an STS error) is skipped and reported if no later source works.
+ * When none works the provider rejects with an error that lists every source tried and how to fix it. Set
+ * `ATLAS_NO_AWS_CLI` to skip the `aws` CLI step and `AWS_EC2_METADATA_DISABLED=true` to skip instance metadata.
+ *
+ * @example
+ * const credentials = await credentialChain()();
+ * credentials.accessKeyId;
+ */
+export function credentialChain(options = {}) {
+    const env = options.env ?? process.env;
+    const doFetch = options.fetch ?? fetch;
+    const read = options.readFile ?? ((file) => readFile(file, 'utf8'));
+    const run = options.run ?? runCommand;
+    const now = options.now ?? Date.now;
+    const skew = options.skewMs ?? 5 * 60_000;
+    const home = options.home ?? env.HOME ?? os.homedir();
+    const profile = env.AWS_PROFILE || env.AWS_DEFAULT_PROFILE || 'default';
+    let cached = null;
+    let pending = null;
+    const sources = [
+        {
+            name: 'environment (ATLAS_S3_*)',
+            load: async () => env.ATLAS_S3_ACCESS_KEY_ID && env.ATLAS_S3_SECRET_ACCESS_KEY
+                ? { accessKeyId: env.ATLAS_S3_ACCESS_KEY_ID, secretAccessKey: env.ATLAS_S3_SECRET_ACCESS_KEY, ...(env.ATLAS_S3_SESSION_TOKEN ? { sessionToken: env.ATLAS_S3_SESSION_TOKEN } : {}) }
+                : null
+        },
+        {
+            name: 'environment (AWS_ACCESS_KEY_ID)',
+            load: async () => env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY
+                ? { accessKeyId: env.AWS_ACCESS_KEY_ID, secretAccessKey: env.AWS_SECRET_ACCESS_KEY, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) }
+                : null
+        },
+        {
+            name: 'web identity (IRSA)',
+            load: async () => {
+                if (!env.AWS_WEB_IDENTITY_TOKEN_FILE || !env.AWS_ROLE_ARN)
+                    return null;
+                const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+                const token = (await read(env.AWS_WEB_IDENTITY_TOKEN_FILE)).trim();
+                const url = new URL(env.AWS_STS_ENDPOINT || `https://sts.${region}.amazonaws.com/`);
+                url.search = new URLSearchParams({ Action: 'AssumeRoleWithWebIdentity', Version: '2011-06-15', RoleArn: env.AWS_ROLE_ARN, RoleSessionName: env.AWS_ROLE_SESSION_NAME || 'atlas', WebIdentityToken: token }).toString();
+                const response = await doFetch(url, { method: 'GET', headers: { accept: 'application/xml' } });
+                const body = await response.text();
+                if (!response.ok)
+                    throw new Error(`STS AssumeRoleWithWebIdentity failed (${response.status}): ${body.slice(0, 300)}`);
+                const found = xml.parse(body)?.AssumeRoleWithWebIdentityResponse?.AssumeRoleWithWebIdentityResult?.Credentials;
+                if (!found?.AccessKeyId)
+                    throw new Error('STS returned no credentials');
+                return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.SessionToken, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+            }
+        },
+        {
+            name: 'container credentials (ECS)',
+            load: async () => {
+                const url = env.AWS_CONTAINER_CREDENTIALS_FULL_URI || (env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI ? `http://169.254.170.2${env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI}` : null);
+                if (!url)
+                    return null;
+                const token = env.AWS_CONTAINER_AUTHORIZATION_TOKEN || (env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE ? (await read(env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE)).trim() : null);
+                const response = await doFetch(url, { headers: token ? { authorization: token } : {} });
+                if (!response.ok)
+                    throw new Error(`The container credentials endpoint answered ${response.status}`);
+                const found = await response.json();
+                return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.Token, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+            }
+        },
+        {
+            name: `shared credentials file (profile ${profile})`,
+            load: async () => {
+                const file = env.AWS_SHARED_CREDENTIALS_FILE || path.join(home, '.aws', 'credentials');
+                const text = await read(file).catch(() => null);
+                const section = text ? parseIni(text)[profile] : undefined;
+                return section?.aws_access_key_id && section.aws_secret_access_key
+                    ? { accessKeyId: section.aws_access_key_id, secretAccessKey: section.aws_secret_access_key, ...(section.aws_session_token ? { sessionToken: section.aws_session_token } : {}) }
+                    : null;
+            }
+        },
+        {
+            name: `AWS CLI (profile ${profile})`,
+            load: async () => {
+                // Covers SSO, assumed roles and credential_process: whatever `aws` itself can sign in with.
+                if (env.ATLAS_NO_AWS_CLI)
+                    return null;
+                const out = await run('aws', ['configure', 'export-credentials', '--format', 'process', ...(env.AWS_PROFILE ? ['--profile', env.AWS_PROFILE] : [])]);
+                if (!out)
+                    return null;
+                try {
+                    const found = JSON.parse(out);
+                    return found.AccessKeyId && found.SecretAccessKey ? { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, ...(found.SessionToken ? { sessionToken: found.SessionToken } : {}), ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) } : null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        },
+        {
+            name: 'EC2 instance metadata',
+            load: async () => {
+                if (env.AWS_EC2_METADATA_DISABLED === 'true')
+                    return null;
+                const base = env.AWS_EC2_METADATA_SERVICE_ENDPOINT || 'http://169.254.169.254';
+                const signal = () => AbortSignal.timeout(1_000);
+                try {
+                    const token = await doFetch(`${base}/latest/api/token`, { method: 'PUT', headers: { 'x-aws-ec2-metadata-token-ttl-seconds': '21600' }, signal: signal() });
+                    if (!token.ok)
+                        return null;
+                    const headers = { 'x-aws-ec2-metadata-token': await token.text() };
+                    const roles = await doFetch(`${base}/latest/meta-data/iam/security-credentials/`, { headers, signal: signal() });
+                    const role = (await roles.text()).split('\n')[0]?.trim();
+                    if (!roles.ok || !role)
+                        return null;
+                    const found = await (await doFetch(`${base}/latest/meta-data/iam/security-credentials/${role}`, { headers, signal: signal() })).json();
+                    return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.Token, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    ];
+    async function resolve() {
+        const failures = [];
+        for (const source of sources) {
+            try {
+                const credentials = await source.load();
+                if (credentials) {
+                    cached = { credentials, source: source.name };
+                    return credentials;
+                }
+            }
+            catch (error) {
+                failures.push(`${source.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error([
+            'No AWS credentials found for the object store.',
+            'Atlas looked, in order, at: ATLAS_S3_ACCESS_KEY_ID / ATLAS_S3_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, EKS web identity, ECS container credentials, ~/.aws/credentials, the AWS CLI (aws sso login), and EC2 instance metadata.',
+            ...failures.map(failure => `  - ${failure}`),
+            'Fix: export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or run `aws sso login` / `aws configure`, or attach a role to the machine.'
+        ].join('\n'));
+    }
+    const provider = (async () => {
+        if (cached && (cached.credentials.expiresAtMs === undefined || cached.credentials.expiresAtMs - skew > now()))
+            return cached.credentials;
+        // One lookup at a time, however many requests are waiting for credentials.
+        pending ??= resolve().finally(() => { pending = null; });
+        return pending;
+    });
+    provider.invalidate = () => { cached = null; };
+    provider.source = () => cached?.source ?? null;
+    return provider;
+}
+/** Wraps keys that are already known in a {@link CredentialProvider} that never refreshes (its `invalidate` does nothing). */
+export function staticCredentials(credentials) {
+    const provider = (async () => credentials);
+    provider.invalidate = () => { };
+    provider.source = () => 'given to the store';
+    return provider;
+}

package/dist/reports/src/browser-navigation.d.ts

@@ -1,2 +1,16 @@
+/**
+ * @module Browser navigation for the reports viewer
+ *
+ * The one implementation of {@link ReportNavigation} that touches `window` and `document`: the explorer's selection
+ * lives in the URL hash, keys come from `keydown`, and the tab title is `document.title`. Browser-only; nothing
+ * here runs until {@link browserReportNavigation} is called, so importing it is safe in Node.
+ */
 import type { ReportNavigation } from './navigation.js';
+/**
+ * Creates a {@link ReportNavigation} backed by `window.location.hash`, `history`, `keydown` and `document.title`.
+ *
+ * `writeHash` does nothing when the hash is already the given one; otherwise it replaces or pushes a history entry
+ * (no `hashchange` is fired by `replaceState`/`pushState`, so the caller owns re-reading). `subscribeHash` listens to both
+ * `hashchange` and `popstate`. Every `subscribe*` returns its unsubscribe function. Must be called in a browser.
+ */
 export declare function browserReportNavigation(): ReportNavigation;

package/dist/reports/src/browser-navigation.js

@@ -1,3 +1,10 @@
+/**
+ * Creates a {@link ReportNavigation} backed by `window.location.hash`, `history`, `keydown` and `document.title`.
+ *
+ * `writeHash` does nothing when the hash is already the given one; otherwise it replaces or pushes a history entry
+ * (no `hashchange` is fired by `replaceState`/`pushState`, so the caller owns re-reading). `subscribeHash` listens to both
+ * `hashchange` and `popstate`. Every `subscribe*` returns its unsubscribe function. Must be called in a browser.
+ */
 export function browserReportNavigation() {
     return {
         readHash: () => window.location.hash,

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

@@ -1,24 +1,56 @@
 import type { ObjectStore } from './object-store.js';
+/** Uncompressed size of one chunk, in bytes (4 MiB). A file larger than this is split across several chunks. */
 export declare const BUNDLE_BYTES: number;
 type Location = {
     blob: string;
     offset: number;
     size: number;
 };
+/**
+ * Where each file of a bundle is, keyed by the file's key (for a layer, `attachments/<sha256>` and the like).
+ * `parts` lists, in order, the byte ranges (`offset`, `size` within the decompressed blob `blob`, a store key) whose
+ * concatenation is the file.
+ */
 export type BundleIndex = Record<string, {
     contentType: string;
     parts: Location[];
 }>;
+/** One file to bundle, or one file read back. */
 export type BundleEntry = {
+    /** The file's name inside the bundle; the key in the {@link BundleIndex}. A repeated key appends more parts to the same file. */
     key: string;
     bytes: Uint8Array;
+    /** The media type to serve the bytes with. The first entry with a key decides it. */
     contentType: string;
 };
+/** The store key of a commit's bundle index for one source: `commits/<sha>/bundles/<source>.json`. This is the older, per-commit layout; layers hold their index in the layer document instead. */
 export declare function bundleIndexKey(sha: string, source: string): string;
-/** Four bounded compressed chunks in flight, with one small index published last. */
+/**
+ * Writes `entries` as blobs next to `key` and then the index at `key`: up to four compressed chunks in flight,
+ * with the one small index published last, so a reader never finds an index whose blobs have not arrived.
+ *
+ * Trap: blobs go to `<key up to "/bundles/">/blobs/`, so `key` must contain `/bundles/` (as {@link bundleIndexKey}
+ * gives); otherwise the prefix is computed from a wrong slice.
+ */
 export declare function publishBundle(store: ObjectStore, key: string, entries: AsyncIterable<BundleEntry>): Promise<void>;
+/**
+ * Packs `entries` into gzip blobs under `prefix` (for layers, `layers/blobs/`) and returns the index that locates
+ * every file; the caller stores the index (a layer keeps it as its `bundle`).
+ *
+ * The entries are consumed lazily with up to four chunks in flight. A blob that already exists in the store is not
+ * written again (one `head` per distinct blob). The gzip header's timestamp is zeroed, and the blob name is the
+ * SHA-256 of the uncompressed chunk, so the same files in the same order always produce the same blobs. Order of
+ * entries matters for that: chunking follows input order. A store error rejects after started writes settle.
+ */
 export declare function writeBundle(store: ObjectStore, entries: AsyncIterable<BundleEntry>, prefix: string): Promise<BundleIndex>;
-/** Cache only immutable blobs; mutable indexes are read for each request. */
+/**
+ * Creates a reader that returns one file of a bundle by key, or `null` when the key is not in `index` or one of
+ * its blobs is missing from the store.
+ *
+ * Only immutable blobs are cached (the last four decompressed blobs, oldest evicted first, including a cached
+ * "missing" answer); mutable indexes are read for each request. Transport errors from the store reject.
+ */
 export declare function createBundleReader(store: ObjectStore, index: BundleIndex): (key: string) => Promise<BundleEntry | null>;
+/** Reads and parses the bundle index at `key`; an index that is not there is an empty bundle (`{}`). Invalid JSON throws. */
 export declare function readBundleIndex(store: ObjectStore, key: string): Promise<BundleIndex>;
 export {};

package/dist/reports/src/bundle.js

@@ -1,6 +1,20 @@
+/**
+ * @module Bundles of captured files
+ *
+ * Packs many small captured files (screenshots, frames, attachments) into a few gzip-compressed, content-addressed
+ * blobs in an {@link ObjectStore}, and reads single files back out. The bytes of every entry are concatenated into
+ * chunks of at most {@link BUNDLE_BYTES} uncompressed bytes; each chunk is gzipped and stored once at
+ * `<prefix><sha256 of the uncompressed chunk>.gz`, so identical chunks and re-publishes write nothing new. A
+ * {@link BundleIndex} says, per file key, which byte ranges of which blobs hold it. A layer document keeps that
+ * index in its `bundle` field. Blobs are immutable; the index is the only mutable-looking part and is written last.
+ *
+ * @see docs/report-contract.md (where bytes go)
+ */
 import { readObjectBytes, readUtf8, writeUtf8, } from './object-io.js';
 import { eachLimitedStream } from './completion-order.js';
+/** Uncompressed size of one chunk, in bytes (4 MiB). A file larger than this is split across several chunks. */
 export const BUNDLE_BYTES = 4 * 1024 * 1024;
+/** The store key of a commit's bundle index for one source: `commits/<sha>/bundles/<source>.json`. This is the older, per-commit layout; layers hold their index in the layer document instead. */
 export function bundleIndexKey(sha, source) {
     return `commits/${sha}/bundles/${source}.json`;
 }
@@ -67,18 +81,39 @@ async function* chunks(entries) {
     if (pending.length > 0)
         yield pending;
 }
-/** Four bounded compressed chunks in flight, with one small index published last. */
+/**
+ * Writes `entries` as blobs next to `key` and then the index at `key`: up to four compressed chunks in flight,
+ * with the one small index published last, so a reader never finds an index whose blobs have not arrived.
+ *
+ * Trap: blobs go to `<key up to "/bundles/">/blobs/`, so `key` must contain `/bundles/` (as {@link bundleIndexKey}
+ * gives); otherwise the prefix is computed from a wrong slice.
+ */
 export async function publishBundle(store, key, entries) {
     const index = await writeBundle(store, entries, `${key.slice(0, key.indexOf('/bundles/'))}/blobs/`);
     await writeUtf8(store, key, JSON.stringify(index), 'application/json');
 }
+/**
+ * Packs `entries` into gzip blobs under `prefix` (for layers, `layers/blobs/`) and returns the index that locates
+ * every file; the caller stores the index (a layer keeps it as its `bundle`).
+ *
+ * The entries are consumed lazily with up to four chunks in flight. A blob that already exists in the store is not
+ * written again (one `head` per distinct blob). The gzip header's timestamp is zeroed, and the blob name is the
+ * SHA-256 of the uncompressed chunk, so the same files in the same order always produce the same blobs. Order of
+ * entries matters for that: chunking follows input order. A store error rejects after started writes settle.
+ */
 export async function writeBundle(store, entries, prefix) {
     const index = {};
     const writes = { prefix, pending: new Map() };
     await eachLimitedStream(chunks(entries), 4, chunk => flush(store, chunk, index, writes));
     return index;
 }
-/** Cache only immutable blobs; mutable indexes are read for each request. */
+/**
+ * Creates a reader that returns one file of a bundle by key, or `null` when the key is not in `index` or one of
+ * its blobs is missing from the store.
+ *
+ * Only immutable blobs are cached (the last four decompressed blobs, oldest evicted first, including a cached
+ * "missing" answer); mutable indexes are read for each request. Transport errors from the store reject.
+ */
 export function createBundleReader(store, index) {
     const cache = new Map();
     return async (key) => {
@@ -108,6 +143,7 @@ export function createBundleReader(store, index) {
         return { key, bytes, contentType: location.contentType };
     };
 }
+/** Reads and parses the bundle index at `key`; an index that is not there is an empty bundle (`{}`). Invalid JSON throws. */
 export async function readBundleIndex(store, key) {
     const text = await readUtf8(store, key);
     return text === null ? {} : JSON.parse(text);