@knowledgefutures/sdk 0.0.0-stage → 0.1.0

package/dist/analytics/types.d.ts

@@ -0,0 +1,22 @@
+import type { Cube, Query, QueryResult } from './cubes.js';
+import type { ServerHint } from './envelope.js';
+/** What project code holds. Every implementation — the collector, the memory double, `kf dev`'s log — is this. */
+export interface Analytics {
+    /**
+     * A server event, signed with the project's secret, so it counts as
+     * `source = 'server'`. For what matters: a download the project's Worker
+     * served, a sign-up. Pass the reader's `country` and `userAgent` when the
+     * server knows them.
+     */
+    track(event: ServerHint): Promise<void>;
+    /** The project's own numbers. Server-side only: the secret signs it. */
+    query<C extends Cube>(q: Query<C>): Promise<QueryResult>;
+    /**
+     * The `<script>` tag for the project's pages. `keyed` adds the public site
+     * id, for a project whose domains the console can't list. Empty under
+     * `kf dev` and in the memory double: nothing collects there.
+     */
+    beaconTag(options?: {
+        keyed?: boolean;
+    }): string;
+}

package/dist/analytics/types.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/binding.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `KF_STORAGE_URL` and `KF_STORAGE_PUBLIC_URL` — the whole contract between
+ * the console, which provisions a bucket and writes the binding into a
+ * project's environment, and the SDK, which reads it. Both import this file,
+ * so the format has exactly one definition.
+ *
+ *   s3+https://<accessKeyId>:<secretAccessKey>@<host>[:port]/<bucket>?region=<r>[&base=<public origin>]
+ *
+ * `s3+http` only for a local server. Credentials are percent-encoded (secrets
+ * contain `/` and `+`). `base` is present on the public store only: where
+ * `url(key)` points. One variable per store, so a store can never be half
+ * configured.
+ *
+ * Not for project code, and not published: projects call `createStorage` /
+ * `storage`, which read these variables. Only what WRITES them imports this
+ * entry point — the console's adapter and `kf dev`, both from the workspace.
+ */
+export interface StorageBinding {
+    /** `https://<account>.r2.cloudflarestorage.com`, or `http://localhost:9000` for a local server. */
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** `auto` for R2; a local server accepts any, conventionally `us-east-1`. */
+    region: string;
+    /** The public store's origin, e.g. `https://my-project.kfassets.example`. */
+    publicBase?: string;
+}
+export declare const STORAGE_ENV = "KF_STORAGE_URL";
+export declare const PUBLIC_STORAGE_ENV = "KF_STORAGE_PUBLIC_URL";
+export declare function encodeStorageBinding(b: StorageBinding): string;
+export declare function decodeStorageBinding(value: string, name?: string): StorageBinding;
+/**
+ * The deployed form (storage plan §8): no vendor credential at all, only the
+ * instance's id and secret at the storage service, which signs short-lived
+ * R2 credentials for its bucket on request.
+ *
+ *   https://<instance>:<secret>@<storage service host>/[?store=public&base=<public origin>]
+ *
+ * The static `s3+…` form above stays for `kf dev` (RustFS) and tests.
+ */
+export interface BrokeredBinding {
+    /** The storage service's origin, e.g. `https://console-storage-service.kfutures.org`. */
+    service: string;
+    instance: string;
+    secret: string;
+    store: 'private' | 'public';
+    /** The public store's origin, where `url(key)` points. */
+    publicBase?: string;
+}
+/**
+ * What the storage service's `POST /v1/credentials` answers: R2 temporary
+ * credentials for one bucket. The service (its own repo) defines the response
+ * and this is what the SDK reads; `brokered.test.ts` and the service's tests
+ * hold the same example response, so a change to either side fails a test.
+ */
+export interface IssuedCredentials {
+    endpoint: string;
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    /** ISO time. */
+    expiresAt: string;
+}
+export type ParsedBinding = {
+    kind: 'static';
+    binding: StorageBinding;
+} | {
+    kind: 'brokered';
+    binding: BrokeredBinding;
+};
+export declare function encodeBrokeredBinding(b: BrokeredBinding): string;
+/** Either form; the scheme says which. */
+export declare function parseBinding(value: string, name?: string): ParsedBinding;

package/dist/storage/binding.js

@@ -0,0 +1,97 @@
+import { StorageError } from './errors.js';
+export const STORAGE_ENV = 'KF_STORAGE_URL';
+export const PUBLIC_STORAGE_ENV = 'KF_STORAGE_PUBLIC_URL';
+const BUCKET = /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/;
+export function encodeStorageBinding(b) {
+    const endpoint = new URL(b.endpoint);
+    if (endpoint.protocol !== 'https:' && endpoint.protocol !== 'http:') {
+        throw new StorageError('invalid', `endpoint must be http(s): ${b.endpoint}`);
+    }
+    if (!BUCKET.test(b.bucket))
+        throw new StorageError('invalid', `not a bucket name: ${b.bucket}`);
+    const query = new URLSearchParams({ region: b.region });
+    if (b.publicBase)
+        query.set('base', trimSlash(b.publicBase));
+    return (`s3+${endpoint.protocol}//` +
+        `${encodeURIComponent(b.accessKeyId)}:${encodeURIComponent(b.secretAccessKey)}@` +
+        `${endpoint.host}/${b.bucket}?${query}`);
+}
+export function decodeStorageBinding(value, name = STORAGE_ENV) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw bad(name, 'not a URL');
+    }
+    const scheme = /^s3\+(https?):$/.exec(url.protocol)?.[1];
+    if (!scheme)
+        throw bad(name, 'the scheme is s3+https (or s3+http for a local server)');
+    const bucket = url.pathname.replace(/^\/+|\/+$/g, '');
+    if (!BUCKET.test(bucket))
+        throw bad(name, 'the path is the bucket name');
+    if (!url.username || !url.password)
+        throw bad(name, 'credentials are missing');
+    const region = url.searchParams.get('region');
+    if (!region)
+        throw bad(name, 'region is missing');
+    const base = url.searchParams.get('base');
+    return {
+        endpoint: `${scheme}://${url.host}`,
+        bucket,
+        accessKeyId: decodeURIComponent(url.username),
+        secretAccessKey: decodeURIComponent(url.password),
+        region,
+        ...(base ? { publicBase: trimSlash(base) } : {}),
+    };
+}
+function trimSlash(s) {
+    return s.replace(/\/+$/, '');
+}
+function bad(name, why) {
+    // Never echo the value: it carries the secret.
+    return new StorageError('not_configured', `${name} is malformed: ${why}`);
+}
+export function encodeBrokeredBinding(b) {
+    const service = new URL(b.service);
+    if (service.protocol !== 'https:' && service.protocol !== 'http:') {
+        throw new StorageError('invalid', `service must be http(s): ${b.service}`);
+    }
+    const query = new URLSearchParams();
+    if (b.store === 'public')
+        query.set('store', 'public');
+    if (b.publicBase)
+        query.set('base', trimSlash(b.publicBase));
+    const q = query.toString();
+    return (`${service.protocol}//${encodeURIComponent(b.instance)}:${encodeURIComponent(b.secret)}@` +
+        `${service.host}/${q ? `?${q}` : ''}`);
+}
+/** Either form; the scheme says which. */
+export function parseBinding(value, name = STORAGE_ENV) {
+    const v = value.trim();
+    if (/^s3\+https?:/.test(v))
+        return { kind: 'static', binding: decodeStorageBinding(v, name) };
+    let url;
+    try {
+        url = new URL(v);
+    }
+    catch {
+        throw bad(name, 'not a URL');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw bad(name, 'the scheme is s3+https (static) or https (the storage service)');
+    }
+    if (!url.username || !url.password)
+        throw bad(name, 'the instance id and secret are missing');
+    const base = url.searchParams.get('base');
+    return {
+        kind: 'brokered',
+        binding: {
+            service: `${url.protocol}//${url.host}`,
+            instance: decodeURIComponent(url.username),
+            secret: decodeURIComponent(url.password),
+            store: url.searchParams.get('store') === 'public' ? 'public' : 'private',
+            ...(base ? { publicBase: trimSlash(base) } : {}),
+        },
+    };
+}

package/dist/storage/brokered.d.ts

@@ -0,0 +1,21 @@
+import type { BrokeredBinding, IssuedCredentials } from './binding.js';
+import { type S3StoreOptions } from './s3.js';
+import type { PublicStore, Store } from './types.js';
+/**
+ * A store whose credentials come from the storage service (storage plan §8):
+ * the binding holds only the instance's id and secret, and the service signs
+ * an hour of R2 temporary credentials for this instance's bucket on request.
+ * They are cached and refreshed five minutes before they expire, one exchange
+ * at a time, so a busy process asks about once an hour and every call after
+ * that goes straight to R2.
+ *
+ * A signed URL carries the session token, so it stops working when the
+ * credentials that signed it expire. Signing therefore uses credentials that
+ * outlive the URL, exchanging early if the cached ones don't, and refuses a
+ * lifetime no credentials from the service can cover.
+ */
+export type { IssuedCredentials };
+export declare function createBrokeredStore(b: BrokeredBinding & {
+    store: 'public';
+}, options?: S3StoreOptions): PublicStore;
+export declare function createBrokeredStore(b: BrokeredBinding, options?: S3StoreOptions): Store;

package/dist/storage/brokered.js

@@ -0,0 +1,94 @@
+import { StorageError } from './errors.js';
+import { createS3Store } from './s3.js';
+import { checkExpiresIn, checkKey, DOWNLOAD_EXPIRES_IN, UPLOAD_EXPIRES_IN } from './shared.js';
+import { encodeKey } from './sigv4.js';
+const REFRESH_EARLY_MS = 5 * 60_000;
+export function createBrokeredStore(b, options = {}) {
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    let cached;
+    let inflight;
+    async function exchange() {
+        let res;
+        try {
+            res = await doFetch(`${b.service}/v1/credentials`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Basic ${btoa(`${b.instance}:${b.secret}`)}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ store: b.store }),
+            });
+        }
+        catch (e) {
+            throw new StorageError('unavailable', `the storage service is unreachable: ${e.message}`);
+        }
+        if (!res.ok) {
+            const why = (await res.text().catch(() => '')).slice(0, 200);
+            if (res.status === 401 || res.status === 403) {
+                throw new StorageError('forbidden', `the storage service refused this instance: ${why}`, res.status);
+            }
+            if (res.status === 404 || res.status === 410) {
+                throw new StorageError('not_configured', `the storage service has no such store: ${why}`, res.status);
+            }
+            throw new StorageError('unavailable', `the storage service answered ${res.status}: ${why}`, res.status);
+        }
+        const c = (await res.json());
+        const store = createS3Store({
+            endpoint: c.endpoint,
+            bucket: c.bucket,
+            region: c.region,
+            accessKeyId: c.accessKeyId,
+            secretAccessKey: c.secretAccessKey,
+            ...(b.publicBase ? { publicBase: b.publicBase } : {}),
+        }, { ...options, sessionToken: c.sessionToken });
+        const expiresAt = Date.parse(c.expiresAt);
+        cached = { store, refreshAt: expiresAt - REFRESH_EARLY_MS, expiresAt };
+        return store;
+    }
+    async function current() {
+        if (cached && Date.now() < cached.refreshAt)
+            return cached.store;
+        inflight ??= exchange().finally(() => {
+            inflight = undefined;
+        });
+        return inflight;
+    }
+    /** A store whose credentials last at least `seconds` more. */
+    async function lasting(seconds) {
+        // A function, not a narrowed read: `cached` changes across the awaits.
+        const leftMs = () => (cached ? cached.expiresAt - Date.now() : 0);
+        let s = await current();
+        if (leftMs() >= seconds * 1000)
+            return s;
+        cached = undefined;
+        s = await current();
+        if (leftMs() >= seconds * 1000)
+            return s;
+        throw new StorageError('invalid', `expiresIn is at most ${Math.max(0, Math.floor(leftMs() / 1000))} seconds here: a ` +
+            'signed URL stops working when the storage service’s short-lived credentials that ' +
+            'signed it expire');
+    }
+    const store = {
+        put: async (...a) => (await current()).put(...a),
+        get: async (...a) => (await current()).get(...a),
+        head: async (...a) => (await current()).head(...a),
+        delete: async (...a) => (await current()).delete(...a),
+        list: async (...a) => (await current()).list(...a),
+        signUpload: async (key, o) => (await lasting(checkExpiresIn(o.expiresIn, UPLOAD_EXPIRES_IN))).signUpload(key, o),
+        signDownload: async (key, o = {}) => (await lasting(checkExpiresIn(o.expiresIn, DOWNLOAD_EXPIRES_IN))).signDownload(key, o),
+        upload: async (...a) => (await current()).upload(...a),
+    };
+    if (b.store !== 'public')
+        return store;
+    if (!b.publicBase)
+        throw new StorageError('not_configured', 'a public store binding has no base URL');
+    const base = b.publicBase;
+    // url() needs no credentials: the public origin plus the encoded key, as the static store builds it.
+    return {
+        ...store,
+        url: (key) => {
+            checkKey(key);
+            return `${base}/${encodeKey(key)}`;
+        },
+    };
+}

package/dist/storage/conformance.d.ts

@@ -0,0 +1,24 @@
+import type { Storage } from './types.js';
+/**
+ * The storage conformance suite: what "same interface" means, as tests.
+ * Every implementation — `memoryStorage`, RustFS under `kf dev`, R2 behind the
+ * console — must pass all of it, or it is not offered. Project code written
+ * against one therefore runs the same against the others.
+ *
+ *   describeStorageConformance('rustfs', async () => ({ storage, fetch }))
+ *
+ * Everything is written under a fresh `conformance/<uuid>/` prefix and
+ * deleted afterwards, so the suite is safe against a real, shared bucket.
+ */
+export interface ConformanceTarget {
+    storage: Storage;
+    /**
+     * How a browser would reach the URLs the store hands out (signed uploads,
+     * signed downloads, public objects). The global fetch for a real backend;
+     * `memoryStorage().fetch` for the in-memory store.
+     */
+    fetch: (input: string, init?: RequestInit) => Promise<Response>;
+    /** false when the environment doesn't declare `public`: the public tests then check it refuses. */
+    hasPublic?: boolean;
+}
+export declare function describeStorageConformance(name: string, setup: () => Promise<ConformanceTarget>): void;

package/dist/storage/conformance.js

@@ -0,0 +1,311 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { isStorageError } from './errors.js';
+export function describeStorageConformance(name, setup) {
+    describe(`storage conformance: ${name}`, () => {
+        let t;
+        const run = `conformance/${crypto.randomUUID()}/`;
+        const k = (key) => `${run}${key}`;
+        beforeAll(async () => {
+            t = await setup();
+        });
+        afterAll(async () => {
+            if (!t)
+                return;
+            const stores = [t.storage];
+            if (t.hasPublic !== false)
+                stores.push(t.storage.public);
+            for (const store of stores) {
+                let cursor;
+                do {
+                    const page = await store.list({ prefix: run, ...(cursor ? { cursor } : {}) });
+                    for (const o of page.objects)
+                        await store.delete(o.key);
+                    cursor = page.cursor;
+                } while (cursor);
+            }
+        });
+        describe('objects', () => {
+            it('put then get returns the bytes, type and metadata', async () => {
+                const put = await t.storage.put(k('a.bin'), new Uint8Array([0, 1, 2, 255]), {
+                    contentType: 'application/x-test',
+                    metadata: { owner: 'atlas', 'page-count': '3' },
+                    cacheControl: 'private, max-age=60',
+                });
+                expect(put).toMatchObject({ key: k('a.bin'), size: 4, contentType: 'application/x-test' });
+                expect(put.etag).not.toBe('');
+                const got = await t.storage.get(k('a.bin'));
+                expect(got).not.toBeNull();
+                expect([...new Uint8Array(await got.arrayBuffer())]).toEqual([0, 1, 2, 255]);
+                expect(got).toMatchObject({
+                    size: 4,
+                    contentType: 'application/x-test',
+                    cacheControl: 'private, max-age=60',
+                    metadata: { owner: 'atlas', 'page-count': '3' },
+                    etag: put.etag,
+                });
+            });
+            it('head agrees with put', async () => {
+                const put = await t.storage.put(k('head.txt'), 'hello');
+                const head = await t.storage.head(k('head.txt'));
+                expect(head).toMatchObject({
+                    key: k('head.txt'),
+                    size: 5,
+                    etag: put.etag,
+                    contentType: 'text/plain; charset=utf-8',
+                });
+                expect(Math.abs(head.uploaded.getTime() - put.uploaded.getTime())).toBeLessThan(5000);
+            });
+            it('accepts a Blob, taking its type, and a stream', async () => {
+                await t.storage.put(k('blob.json'), new Blob(['{"a":1}'], { type: 'application/json' }));
+                expect((await t.storage.head(k('blob.json')))?.contentType).toBe('application/json');
+                const stream = new Blob(['streamed']).stream();
+                await t.storage.put(k('stream.txt'), stream, { contentType: 'text/plain' });
+                expect(await (await t.storage.get(k('stream.txt'))).text()).toBe('streamed');
+            });
+            it('get and head of a missing key are null; deleting it is success', async () => {
+                expect(await t.storage.get(k('missing'))).toBeNull();
+                expect(await t.storage.head(k('missing'))).toBeNull();
+                await t.storage.delete(k('missing'));
+            });
+            it('delete removes; overwrite changes the etag', async () => {
+                const first = await t.storage.put(k('over.txt'), 'one');
+                const second = await t.storage.put(k('over.txt'), 'two!');
+                expect(second.etag).not.toBe(first.etag);
+                expect(await (await t.storage.get(k('over.txt'))).text()).toBe('two!');
+                await t.storage.delete(k('over.txt'));
+                expect(await t.storage.head(k('over.txt'))).toBeNull();
+            });
+            it('keys that need encoding round-trip exactly', async () => {
+                const keys = [
+                    'sp ace.txt',
+                    'plus+sign',
+                    'pct%20lit',
+                    'q?mark#hash',
+                    'ünï/cødé/文字',
+                    "quote'(paren)*",
+                ];
+                for (const key of keys)
+                    await t.storage.put(k(`enc/${key}`), key);
+                for (const key of keys)
+                    expect(await (await t.storage.get(k(`enc/${key}`))).text()).toBe(key);
+                const listed = (await t.storage.list({ prefix: k('enc/') })).objects.map((o) => o.key);
+                expect(listed.sort()).toEqual(keys.map((key) => k(`enc/${key}`)).sort());
+            });
+        });
+        describe('list', () => {
+            it('lists a prefix in key order, paged by cursor', async () => {
+                const names = ['e', 'a', 'c', 'b', 'd'];
+                for (const n of names)
+                    await t.storage.put(k(`list/${n}`), n);
+                await t.storage.put(k('listing-not-this'), 'x');
+                const seen = [];
+                let cursor;
+                let pages = 0;
+                do {
+                    const page = await t.storage.list({
+                        prefix: k('list/'),
+                        limit: 2,
+                        ...(cursor ? { cursor } : {}),
+                    });
+                    expect(page.objects.length).toBeLessThanOrEqual(2);
+                    seen.push(...page.objects.map((o) => o.key));
+                    cursor = page.cursor;
+                    pages++;
+                } while (cursor && pages < 10);
+                expect(seen).toEqual(['a', 'b', 'c', 'd', 'e'].map((n) => k(`list/${n}`)));
+                expect(pages).toBe(3);
+            });
+            it('reports size and etag', async () => {
+                const put = await t.storage.put(k('sized/one'), '12345');
+                const [o] = (await t.storage.list({ prefix: k('sized/') })).objects;
+                expect(o).toMatchObject({ key: k('sized/one'), size: 5, etag: put.etag });
+                expect(o.uploaded).toBeInstanceOf(Date);
+            });
+        });
+        describe('refusals are the same everywhere', () => {
+            it.each([
+                ['empty', ''],
+                ['a leading slash', '/abs'],
+                ['a .. segment', 'a/../b'],
+                ['a . segment', 'a/./b'],
+                ['a control character', 'a\u0001b'],
+                ['more than 1024 bytes', 'x'.repeat(1025)],
+            ])('a key with %s is invalid', async (_why, key) => {
+                await expect(t.storage.put(key, 'x')).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
+                await expect(t.storage.get(key)).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
+            });
+            it('every failure is a rejected promise, never a synchronous throw', async () => {
+                const calls = [
+                    () => t.storage.put('', 'x'),
+                    () => t.storage.upload(new Blob(['x']), { prefix: '/abs' }),
+                    () => t.storage.signUpload('', { contentType: 'text/plain', size: 1 }),
+                    () => t.storage.list({ limit: 0 }),
+                ];
+                for (const call of calls) {
+                    let promise;
+                    expect(() => {
+                        promise = call();
+                    }).not.toThrow();
+                    await expect(promise).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
+                }
+            });
+            it('a metadata name outside [a-z0-9-] is invalid', async () => {
+                await expect(t.storage.put(k('meta'), 'x', { metadata: { Bad_Name: 'x' } })).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
+            });
+        });
+        describe('upload', () => {
+            it('generates a key under the prefix, keeping the extension and type', async () => {
+                const file = new File(['cover'], 'Cover Art.JPG', { type: 'image/jpeg' });
+                const o = await t.storage.upload(file, { prefix: k('covers') });
+                expect(o.key).toMatch(new RegExp(`^${k('covers/')}[0-9a-f-]{36}\\.jpg$`));
+                expect(o.contentType).toBe('image/jpeg');
+                expect(await (await t.storage.get(o.key)).text()).toBe('cover');
+            });
+        });
+        describe('signed URLs', () => {
+            it('signUpload: a PUT with the signed headers and exact size lands', async () => {
+                const body = 'uploaded from a browser';
+                const up = await t.storage.signUpload(k('signed/ok.txt'), {
+                    contentType: 'text/plain',
+                    size: new TextEncoder().encode(body).length,
+                });
+                expect(up.method).toBe('PUT');
+                const res = await t.fetch(up.url, { method: 'PUT', headers: up.headers, body });
+                expect(res.status).toBeLessThan(300);
+                const got = await t.storage.get(k('signed/ok.txt'));
+                expect(await got.text()).toBe(body);
+                expect(got.contentType).toBe('text/plain');
+            });
+            it('signUpload: a different size or type is refused', async () => {
+                const up = await t.storage.signUpload(k('signed/strict.txt'), {
+                    contentType: 'text/plain',
+                    size: 5,
+                });
+                const tooBig = await t.fetch(up.url, { method: 'PUT', headers: up.headers, body: '123456' });
+                expect(tooBig.ok).toBe(false);
+                const wrongType = await t.fetch(up.url, {
+                    method: 'PUT',
+                    headers: { ...up.headers, 'content-type': 'text/html' },
+                    body: '12345',
+                });
+                expect(wrongType.ok).toBe(false);
+                expect(await t.storage.head(k('signed/strict.txt'))).toBeNull();
+            });
+            it('signDownload: GET returns the object, as an attachment when named', async () => {
+                await t.storage.put(k('signed/dl.txt'), 'download me');
+                const res = await t.fetch(await t.storage.signDownload(k('signed/dl.txt')));
+                expect(res.status).toBe(200);
+                expect(await res.text()).toBe('download me');
+                const named = await t.fetch(await t.storage.signDownload(k('signed/dl.txt'), { filename: 'Réport.txt' }));
+                expect(named.headers.get('content-disposition')).toContain('attachment');
+                expect(named.headers.get('content-disposition')).toContain('R%C3%A9port.txt');
+            });
+            it('an expired signed URL is refused', async () => {
+                await t.storage.put(k('signed/expiring.txt'), 'soon gone');
+                const url = await t.storage.signDownload(k('signed/expiring.txt'), { expiresIn: 2 });
+                expect((await t.fetch(url)).ok).toBe(true);
+                // The server judges expiry by its own clock, which can drift from
+                // ours (a container's VM, say): poll for the refusal rather than
+                // assume exactly when it comes.
+                let refused = false;
+                for (let waited = 0; !refused && waited < 10_000; waited += 500) {
+                    await new Promise((r) => setTimeout(r, 500));
+                    refused = !(await t.fetch(url)).ok;
+                }
+                expect(refused).toBe(true);
+            }, 15_000);
+            it('expiresIn outside 1–604800 seconds is invalid', async () => {
+                await expect(t.storage.signDownload(k('x'), { expiresIn: 604_801 })).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
+            });
+        });
+        describe('public store', () => {
+            it('is refused with not_configured when the environment has none', async () => {
+                if (t.hasPublic !== false)
+                    return;
+                expect(() => t.storage.public).toThrow(expect.objectContaining({ code: 'not_configured' }));
+            });
+            it('url(key) serves the object to anyone', async () => {
+                if (t.hasPublic === false)
+                    return;
+                await t.storage.public.put(k('pub/hello.txt'), 'public bytes', {
+                    contentType: 'text/plain',
+                });
+                const res = await t.fetch(t.storage.public.url(k('pub/hello.txt')));
+                expect(res.status).toBe(200);
+                expect(await res.text()).toBe('public bytes');
+                expect(res.headers.get('cache-control')).toBe('public, max-age=300');
+            });
+            it('upload() writes an immutable object at a fresh key', async () => {
+                if (t.hasPublic === false)
+                    return;
+                const o = await t.storage.public.upload(new Blob(['img'], { type: 'image/png' }), {
+                    prefix: k('pub/covers'),
+                });
+                expect(o.cacheControl).toBe('public, max-age=31536000, immutable');
+                const res = await t.fetch(t.storage.public.url(o.key));
+                expect(await res.text()).toBe('img');
+                expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable');
+            });
+            it('serves anything but raster images, audio and video as an attachment', async () => {
+                if (t.hasPublic === false)
+                    return;
+                const page = '<html><body>not a scam</body></html>';
+                const html = await t.storage.public.put(k('pub/page.html'), page, {
+                    contentType: 'text/html',
+                });
+                expect(html.contentDisposition).toMatch(/^attachment/);
+                const res = await t.fetch(t.storage.public.url(k('pub/page.html')));
+                expect(res.headers.get('content-disposition')).toMatch(/^attachment/);
+                expect(await res.text()).toBe(page);
+                // Asking for inline is not honoured for a type outside the list.
+                const svg = await t.storage.public.put(k('pub/logo.svg'), '<svg/>', {
+                    contentType: 'image/svg+xml',
+                    contentDisposition: 'inline',
+                });
+                expect(svg.contentDisposition).toMatch(/^attachment/);
+                // A caller's own attachment, with a file name, is kept.
+                const named = await t.storage.public.put(k('pub/r.pdf'), '%PDF', {
+                    contentType: 'application/pdf',
+                    contentDisposition: 'attachment; filename="report.pdf"',
+                });
+                expect(named.contentDisposition).toBe('attachment; filename="report.pdf"');
+                const png = await t.storage.public.put(k('pub/cover.png'), new Uint8Array([137, 80]), {
+                    contentType: 'image/png',
+                });
+                expect(png.contentDisposition).toBeUndefined();
+                const img = await t.fetch(t.storage.public.url(k('pub/cover.png')));
+                expect(img.headers.get('content-disposition')).toBeNull();
+            });
+            it('signs the attachment into a public upload, so a browser cannot drop it', async () => {
+                if (t.hasPublic === false)
+                    return;
+                const body = '<html></html>';
+                const up = await t.storage.public.signUpload(k('pub/up.html'), {
+                    contentType: 'text/html',
+                    size: body.length,
+                });
+                expect(up.headers['content-disposition']).toBe('attachment');
+                const { 'content-disposition': _dropped, ...without } = up.headers;
+                expect((await t.fetch(up.url, { method: 'PUT', headers: without, body })).ok).toBe(false);
+                expect((await t.fetch(up.url, { method: 'PUT', headers: up.headers, body })).ok).toBe(true);
+                expect((await t.storage.public.head(k('pub/up.html')))?.contentDisposition).toBe('attachment');
+                const img = await t.storage.public.signUpload(k('pub/up.webp'), {
+                    contentType: 'image/webp',
+                    size: 3,
+                });
+                expect(img.headers['content-disposition']).toBeUndefined();
+            });
+            it('leaves the private store alone', async () => {
+                const o = await t.storage.put(k('priv.html'), '<p>', { contentType: 'text/html' });
+                expect(o.contentDisposition).toBeUndefined();
+            });
+            it('the private and public stores are separate', async () => {
+                if (t.hasPublic === false)
+                    return;
+                await t.storage.put(k('pub/secret.txt'), 'private');
+                expect(await t.storage.public.head(k('pub/secret.txt'))).toBeNull();
+                expect((await t.fetch(t.storage.public.url(k('pub/secret.txt')))).ok).toBe(false);
+            });
+        });
+    });
+}