@knowledgefutures/sdk 0.0.0-stage → 0.2.1

package/dist/storage/s3.js

@@ -0,0 +1,254 @@
+import { StorageError } from './errors.js';
+import { attachment, checkExpiresIn, DOWNLOAD_EXPIRES_IN, UPLOAD_EXPIRES_IN, checkKey, checkMetadata, checkPrefix, checkSignUpload, DEFAULT_CONTENT_TYPE, IMMUTABLE, publicDisposition, SHORT_PUBLIC, toBytes, uploadAsPut, } from './shared.js';
+import { encodeKey, EMPTY_SHA256, presign, sha256Hex, signRequest, } from './sigv4.js';
+export function createS3Store(binding, options = {}) {
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const credentials = {
+        accessKeyId: binding.accessKeyId,
+        secretAccessKey: binding.secretAccessKey,
+        region: binding.region,
+        ...(options.sessionToken ? { sessionToken: options.sessionToken } : {}),
+    };
+    const isPublic = binding.publicBase !== undefined;
+    const objectUrl = (key) => new URL(`${binding.endpoint}/${binding.bucket}/${encodeKey(key)}`);
+    async function send(method, url, o = {}) {
+        const headers = await signRequest({
+            method,
+            url,
+            headers: o.headers ?? {},
+            payloadHash: o.payloadHash ?? EMPTY_SHA256,
+            credentials,
+        });
+        try {
+            return await doFetch(url, {
+                method,
+                headers,
+                ...(o.body ? { body: o.body } : {}),
+            });
+        }
+        catch (e) {
+            throw new StorageError('unavailable', `storage is unreachable: ${e.message}`);
+        }
+    }
+    async function put(key, body, opts = {}) {
+        checkKey(key);
+        const metadata = checkMetadata(opts.metadata);
+        const { bytes, contentType } = await toBytes(body, opts.contentType);
+        const cacheControl = opts.cacheControl ?? (isPublic ? SHORT_PUBLIC : undefined);
+        const disposition = isPublic
+            ? publicDisposition(contentType, opts.contentDisposition)
+            : opts.contentDisposition;
+        const headers = { 'content-type': contentType };
+        if (cacheControl)
+            headers['cache-control'] = cacheControl;
+        if (disposition)
+            headers['content-disposition'] = disposition;
+        for (const [name, value] of Object.entries(metadata))
+            headers[`x-amz-meta-${name}`] = value;
+        const res = await send('PUT', objectUrl(key), {
+            headers,
+            body: bytes,
+            payloadHash: await sha256Hex(bytes),
+        });
+        if (!res.ok)
+            throw await failure(res, `put ${key}`);
+        await res.body?.cancel();
+        const stored = {
+            key,
+            size: bytes.byteLength,
+            etag: unquote(res.headers.get('etag') ?? ''),
+            uploaded: new Date(res.headers.get('date') ?? Date.now()),
+            contentType,
+            metadata,
+        };
+        if (cacheControl)
+            stored.cacheControl = cacheControl;
+        if (disposition)
+            stored.contentDisposition = disposition;
+        return stored;
+    }
+    async function head(key) {
+        checkKey(key);
+        const res = await send('HEAD', objectUrl(key));
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw await failure(res, `head ${key}`);
+        return describe(key, res);
+    }
+    async function get(key) {
+        checkKey(key);
+        const res = await send('GET', objectUrl(key));
+        if (res.status === 404) {
+            await res.body?.cancel();
+            return null;
+        }
+        if (!res.ok)
+            throw await failure(res, `get ${key}`);
+        const meta = describe(key, res);
+        const body = res.body ?? new Response('').body;
+        return {
+            ...meta,
+            body,
+            arrayBuffer: () => new Response(body).arrayBuffer(),
+            text: () => new Response(body).text(),
+        };
+    }
+    async function del(key) {
+        checkKey(key);
+        const res = await send('DELETE', objectUrl(key));
+        // 204 for a delete; 404 from some backends for a key that was never there — both are success.
+        if (!res.ok && res.status !== 404)
+            throw await failure(res, `delete ${key}`);
+        await res.body?.cancel();
+    }
+    async function list(opts = {}) {
+        checkPrefix(opts.prefix);
+        const limit = opts.limit ?? 1000;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+            throw new StorageError('invalid', 'limit is 1–1000');
+        }
+        const url = new URL(`${binding.endpoint}/${binding.bucket}`);
+        url.searchParams.set('list-type', '2');
+        url.searchParams.set('max-keys', String(limit));
+        if (opts.prefix)
+            url.searchParams.set('prefix', opts.prefix);
+        if (opts.cursor)
+            url.searchParams.set('continuation-token', opts.cursor);
+        const res = await send('GET', url);
+        if (!res.ok)
+            throw await failure(res, 'list');
+        return parseList(await res.text());
+    }
+    async function signUpload(key, o) {
+        checkKey(key);
+        checkSignUpload(o);
+        const expiresIn = checkExpiresIn(o.expiresIn, UPLOAD_EXPIRES_IN);
+        const cacheControl = o.cacheControl ?? (isPublic ? SHORT_PUBLIC : undefined);
+        // Sent by the browser. content-length is signed too, but the browser sets
+        // it from the body, so it is not in what the caller must send.
+        const sent = { 'content-type': o.contentType };
+        if (cacheControl)
+            sent['cache-control'] = cacheControl;
+        // Signed, so a browser cannot upload HTML to the public store as inline.
+        const disposition = isPublic ? publicDisposition(o.contentType, undefined) : undefined;
+        if (disposition)
+            sent['content-disposition'] = disposition;
+        const url = await presign({
+            method: 'PUT',
+            url: objectUrl(key),
+            headers: { ...sent, 'content-length': String(o.size) },
+            expiresIn,
+            credentials,
+        });
+        return {
+            key,
+            url,
+            method: 'PUT',
+            headers: sent,
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+    }
+    async function signDownload(key, o = {}) {
+        checkKey(key);
+        const expiresIn = checkExpiresIn(o.expiresIn, DOWNLOAD_EXPIRES_IN);
+        const url = objectUrl(key);
+        if (o.filename)
+            url.searchParams.set('response-content-disposition', attachment(o.filename));
+        return presign({ method: 'GET', url, expiresIn, credentials });
+    }
+    const store = {
+        put,
+        get,
+        head,
+        delete: del,
+        list,
+        signUpload,
+        signDownload,
+        upload: async (file, options) => {
+            const p = uploadAsPut(file, options, isPublic ? { cacheControl: IMMUTABLE } : {});
+            return put(p.key, p.body, p.options);
+        },
+    };
+    if (!isPublic)
+        return store;
+    const base = binding.publicBase;
+    return {
+        ...store,
+        url: (key) => {
+            checkKey(key);
+            return `${base}/${encodeKey(key)}`;
+        },
+    };
+}
+/* ------------------------------ responses ------------------------------ */
+function describe(key, res) {
+    const metadata = {};
+    for (const [name, value] of res.headers) {
+        if (name.startsWith('x-amz-meta-'))
+            metadata[name.slice('x-amz-meta-'.length)] = value;
+    }
+    const o = {
+        key,
+        size: Number(res.headers.get('content-length') ?? 0),
+        etag: unquote(res.headers.get('etag') ?? ''),
+        uploaded: new Date(res.headers.get('last-modified') ?? 0),
+        contentType: res.headers.get('content-type') ?? DEFAULT_CONTENT_TYPE,
+        metadata,
+    };
+    const cacheControl = res.headers.get('cache-control');
+    const disposition = res.headers.get('content-disposition');
+    if (cacheControl)
+        o.cacheControl = cacheControl;
+    if (disposition)
+        o.contentDisposition = disposition;
+    return o;
+}
+/** Every backend failure as a StorageError — the vendor's XML never reaches the caller. */
+async function failure(res, what) {
+    const text = res.body ? await res.text().catch(() => '') : '';
+    const code = tag(text, 'Code') ?? '';
+    const message = tag(text, 'Message') ?? res.statusText;
+    const detail = `${what}: ${code || res.status}${message ? ` — ${message}` : ''}`;
+    if (res.status === 413 || code === 'EntityTooLarge') {
+        return new StorageError('too_large', detail, res.status);
+    }
+    if (res.status === 401 || res.status === 403)
+        return new StorageError('forbidden', detail, res.status);
+    if (code === 'NoSuchBucket') {
+        return new StorageError('not_configured', `${detail} (the binding names a bucket that does not exist)`, res.status);
+    }
+    if (res.status === 429 || res.status >= 500)
+        return new StorageError('unavailable', detail, res.status);
+    return new StorageError('invalid', detail, res.status);
+}
+/**
+ * ListObjectsV2 by hand: Workers have no DOMParser, and the response is a
+ * flat, well-known shape.
+ */
+export function parseList(xml) {
+    const objects = [...xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)].map(([, c]) => ({
+        key: tag(c, 'Key') ?? '',
+        size: Number(tag(c, 'Size') ?? 0),
+        etag: unquote(tag(c, 'ETag') ?? ''),
+        uploaded: new Date(tag(c, 'LastModified') ?? 0),
+    }));
+    const truncated = tag(xml, 'IsTruncated') === 'true';
+    const cursor = tag(xml, 'NextContinuationToken');
+    return truncated && cursor ? { objects, cursor } : { objects };
+}
+function tag(xml, name) {
+    const m = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml);
+    return m ? unescapeXml(m[1]) : undefined;
+}
+function unescapeXml(s) {
+    return s.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (_, e) => {
+        if (e[0] === '#') {
+            return String.fromCodePoint(e[1] === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10));
+        }
+        return { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }[e];
+    });
+}
+function unquote(etag) {
+    return etag.replace(/^W\//, '').replace(/^"|"$/g, '');
+}

package/dist/storage/shared.d.ts

@@ -0,0 +1,45 @@
+import type { Body, PutOptions, SignUploadOptions, Upload, UploadOptions } from './types.js';
+export declare const MAX_KEY_BYTES = 1024;
+export declare const MAX_EXPIRES_IN = 604800;
+/** Default lifetimes of a signed upload and a signed download, in seconds. */
+export declare const UPLOAD_EXPIRES_IN = 600;
+export declare const DOWNLOAD_EXPIRES_IN = 300;
+/**
+ * A key is 1–1024 UTF-8 bytes with no leading `/`, no `.` or `..` segment and
+ * no control characters. The segment rule is not S3's: a URL path normalizes
+ * `a/../b` to `b` before it is sent, so such a key would silently name a
+ * different object.
+ */
+export declare function checkKey(key: string): void;
+export declare function checkPrefix(prefix: string | undefined): void;
+export declare function checkMetadata(metadata: Record<string, string> | undefined): Record<string, string>;
+export declare function checkExpiresIn(seconds: number | undefined, fallback: number): number;
+export declare function checkSignUpload(o: SignUploadOptions): void;
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** Bytes and a content type, from anything `put` accepts. */
+export declare function toBytes(body: Body, contentType: string | undefined): Promise<{
+    bytes: Uint8Array;
+    contentType: string;
+}>;
+/** `upload`'s arguments as a `put`: a generated key under the prefix, the file's extension kept. */
+export declare function uploadAsPut(file: Blob | Upload, options: UploadOptions | undefined, defaults: {
+    cacheControl?: string;
+}): {
+    key: string;
+    body: Body;
+    options: PutOptions;
+};
+/** `.jpg` from `Cover Art.JPG`; nothing when there is no sensible extension. */
+export declare function extensionOf(name: string): string;
+/** How the public store caches: generated keys never change, chosen keys might. */
+export declare const IMMUTABLE = "public, max-age=31536000, immutable";
+export declare const SHORT_PUBLIC = "public, max-age=300";
+export declare function rendersInline(contentType: string): boolean;
+/**
+ * The disposition a public object is stored with. A caller's own `attachment;
+ * filename=…` is kept; asking for `inline` on a type outside the list is not
+ * honoured.
+ */
+export declare function publicDisposition(contentType: string, requested: string | undefined): string | undefined;
+/** An attachment disposition, safe for any file name (RFC 6266 + RFC 5987). */
+export declare function attachment(filename: string): string;

package/dist/storage/shared.js

@@ -0,0 +1,167 @@
+import { StorageError } from './errors.js';
+/**
+ * Rules every implementation applies before it talks to a backend. They live
+ * here, once, so "what is invalid" cannot differ between R2, RustFS and the
+ * in-memory store — that difference would be exactly the staging/production
+ * surprise the conformance suite exists to prevent.
+ */
+const utf8 = new TextEncoder();
+export const MAX_KEY_BYTES = 1024;
+export const MAX_EXPIRES_IN = 604_800;
+/** Default lifetimes of a signed upload and a signed download, in seconds. */
+export const UPLOAD_EXPIRES_IN = 600;
+export const DOWNLOAD_EXPIRES_IN = 300;
+const METADATA_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_METADATA_BYTES = 2048;
+/**
+ * A key is 1–1024 UTF-8 bytes with no leading `/`, no `.` or `..` segment and
+ * no control characters. The segment rule is not S3's: a URL path normalizes
+ * `a/../b` to `b` before it is sent, so such a key would silently name a
+ * different object.
+ */
+export function checkKey(key) {
+    if (typeof key !== 'string' || key.length === 0)
+        throw invalid('a key must be a non-empty string');
+    if (utf8.encode(key).length > MAX_KEY_BYTES)
+        throw invalid(`a key is at most ${MAX_KEY_BYTES} bytes`);
+    if (key.startsWith('/'))
+        throw invalid(`"${key}": a key must not start with "/"`);
+    // oxlint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(key))
+        throw invalid(`"${key}": a key must not contain control characters`);
+    for (const segment of key.split('/')) {
+        if (segment === '.' || segment === '..') {
+            throw invalid(`"${key}": a key must not contain a "." or ".." segment`);
+        }
+    }
+}
+export function checkPrefix(prefix) {
+    if (prefix === undefined || prefix === '')
+        return;
+    checkKey(prefix);
+}
+export function checkMetadata(metadata) {
+    const out = {};
+    let bytes = 0;
+    for (const [name, value] of Object.entries(metadata ?? {})) {
+        if (!METADATA_NAME.test(name)) {
+            throw invalid(`metadata name "${name}": lowercase letters, digits and "-", at most 64`);
+        }
+        if (typeof value !== 'string')
+            throw invalid(`metadata "${name}" must be a string`);
+        // Header values: printable ASCII only, which is what every backend round-trips intact.
+        if (!/^[\u0020-\u007e]*$/.test(value)) {
+            throw invalid(`metadata "${name}": printable ASCII only — encode anything else`);
+        }
+        bytes += name.length + value.length;
+        out[name] = value;
+    }
+    if (bytes > MAX_METADATA_BYTES)
+        throw invalid(`metadata is at most ${MAX_METADATA_BYTES} bytes`);
+    return out;
+}
+export function checkExpiresIn(seconds, fallback) {
+    const s = seconds ?? fallback;
+    if (!Number.isInteger(s) || s < 1 || s > MAX_EXPIRES_IN) {
+        throw invalid(`expiresIn is whole seconds, 1–${MAX_EXPIRES_IN}`);
+    }
+    return s;
+}
+export function checkSignUpload(o) {
+    if (!Number.isSafeInteger(o.size) || o.size < 0)
+        throw invalid('size is the exact byte length');
+    if (typeof o.contentType !== 'string' || o.contentType.length === 0) {
+        throw invalid('contentType is required: it is signed into the URL');
+    }
+}
+export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+/** Bytes and a content type, from anything `put` accepts. */
+export async function toBytes(body, contentType) {
+    if (typeof body === 'string') {
+        return { bytes: utf8.encode(body), contentType: contentType ?? 'text/plain; charset=utf-8' };
+    }
+    if (body instanceof Blob) {
+        return {
+            bytes: new Uint8Array(await body.arrayBuffer()),
+            contentType: contentType ?? (body.type || DEFAULT_CONTENT_TYPE),
+        };
+    }
+    if (body instanceof ArrayBuffer) {
+        return {
+            bytes: new Uint8Array(body.slice(0)),
+            contentType: contentType ?? DEFAULT_CONTENT_TYPE,
+        };
+    }
+    if (ArrayBuffer.isView(body)) {
+        const copy = new Uint8Array(body.byteLength);
+        copy.set(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+        return { bytes: copy, contentType: contentType ?? DEFAULT_CONTENT_TYPE };
+    }
+    if (body instanceof ReadableStream) {
+        const bytes = new Uint8Array(await new Response(body).arrayBuffer());
+        return { bytes, contentType: contentType ?? DEFAULT_CONTENT_TYPE };
+    }
+    throw invalid('a body is a string, ArrayBuffer, typed array, Blob or ReadableStream');
+}
+/** `upload`'s arguments as a `put`: a generated key under the prefix, the file's extension kept. */
+export function uploadAsPut(file, options, defaults) {
+    checkPrefix(options?.prefix);
+    const isBlob = file instanceof Blob;
+    const name = isBlob ? file.name : file.name;
+    const ext = typeof name === 'string' ? extensionOf(name) : '';
+    const prefix = options?.prefix ? `${options.prefix.replace(/\/+$/, '')}/` : '';
+    const key = `${prefix}${crypto.randomUUID()}${ext}`;
+    const contentType = isBlob ? file.type || undefined : file.contentType;
+    const cacheControl = options?.cacheControl ?? defaults.cacheControl;
+    return {
+        key,
+        body: isBlob ? file : file.body,
+        options: {
+            ...(contentType ? { contentType } : {}),
+            ...(cacheControl ? { cacheControl } : {}),
+            ...(options?.metadata ? { metadata: options.metadata } : {}),
+        },
+    };
+}
+/** `.jpg` from `Cover Art.JPG`; nothing when there is no sensible extension. */
+export function extensionOf(name) {
+    const m = /\.([A-Za-z0-9]{1,10})$/.exec(name);
+    return m ? `.${m[1].toLowerCase()}` : '';
+}
+/** How the public store caches: generated keys never change, chosen keys might. */
+export const IMMUTABLE = 'public, max-age=31536000, immutable';
+export const SHORT_PUBLIC = 'public, max-age=300';
+/**
+ * Public objects render in a browser tab only if they are media: raster
+ * images, audio, video. Everything else — HTML, SVG, PDF, text — is served as
+ * an attachment, because a static scam page on a KF-held domain needs no
+ * script to do harm (earlier KF projects drew takedown notices for exactly
+ * that). Only direct navigation is affected: <img>, <video>, fonts, CSS and
+ * fetch() ignore the header, so embeds keep working.
+ *
+ * The console's assets zone enforces the same rule on responses, for anyone
+ * writing around the SDK; this makes every backend store it, so local and
+ * staging behave as production does.
+ */
+const INLINE_PUBLIC = /^(image\/(png|jpeg|gif|webp|avif)|audio\/[a-z0-9.+-]+|video\/[a-z0-9.+-]+)$/;
+export function rendersInline(contentType) {
+    return INLINE_PUBLIC.test(contentType.split(';')[0].trim().toLowerCase());
+}
+/**
+ * The disposition a public object is stored with. A caller's own `attachment;
+ * filename=…` is kept; asking for `inline` on a type outside the list is not
+ * honoured.
+ */
+export function publicDisposition(contentType, requested) {
+    if (rendersInline(contentType))
+        return requested;
+    return requested?.trim().toLowerCase().startsWith('attachment') ? requested : 'attachment';
+}
+/** An attachment disposition, safe for any file name (RFC 6266 + RFC 5987). */
+export function attachment(filename) {
+    const ascii = filename.replace(/[^\u0020-\u007e]/g, '_').replace(/["\\]/g, '_');
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+function invalid(message) {
+    return new StorageError('invalid', message);
+}

package/dist/storage/sigv4.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AWS Signature Version 4 on WebCrypto — the dialect R2 and RustFS speak.
+ *
+ * Hand-written rather than aws4fetch because a presigned upload must sign
+ * `content-type` and `content-length`: that is what makes `signUpload` exact
+ * on every backend (R2 has no POST policies, so no `content-length-range`),
+ * and aws4fetch refuses to sign either header. Pure: credentials, time and
+ * request are arguments, so the tests check it against AWS's published
+ * examples byte for byte.
+ */
+export interface Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    /**
+     * Temporary credentials' third part (R2 temporary credentials, STS). Signed
+     * as `x-amz-security-token` on a request and carried as
+     * `X-Amz-Security-Token` in a presigned URL.
+     */
+    sessionToken?: string;
+}
+export interface SignInput {
+    method: string;
+    /** Its path must already be encoded exactly as it will be sent (`encodeKey`). */
+    url: URL;
+    /** Headers to sign and send. `host` is signed from the URL and never sent (fetch sets it). */
+    headers?: Record<string, string>;
+    credentials: Credentials;
+    /** Defaults to now. */
+    date?: Date;
+}
+export declare const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+/** RFC 3986 unreserved characters pass; everything else is %XX of its UTF-8 bytes. */
+export declare function encodeRfc3986(s: string): string;
+/** An object key as a URL path: each segment encoded, the slashes kept. */
+export declare function encodeKey(key: string): string;
+/** The headers to send, `authorization` included, for a request signed in the Authorization header. */
+export declare function signRequest(o: SignInput & {
+    payloadHash: string;
+}): Promise<Record<string, string>>;
+/**
+ * A presigned URL: the signature travels in the query string, and whoever
+ * holds the URL must send exactly the signed headers with exactly these
+ * values, before `expiresIn` runs out.
+ */
+export declare function presign(o: SignInput & {
+    expiresIn: number;
+}): Promise<string>;
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;

package/dist/storage/sigv4.js

@@ -0,0 +1,128 @@
+/**
+ * AWS Signature Version 4 on WebCrypto — the dialect R2 and RustFS speak.
+ *
+ * Hand-written rather than aws4fetch because a presigned upload must sign
+ * `content-type` and `content-length`: that is what makes `signUpload` exact
+ * on every backend (R2 has no POST policies, so no `content-length-range`),
+ * and aws4fetch refuses to sign either header. Pure: credentials, time and
+ * request are arguments, so the tests check it against AWS's published
+ * examples byte for byte.
+ */
+const utf8 = new TextEncoder();
+const SERVICE = 's3';
+export const EMPTY_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+/** RFC 3986 unreserved characters pass; everything else is %XX of its UTF-8 bytes. */
+export function encodeRfc3986(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** An object key as a URL path: each segment encoded, the slashes kept. */
+export function encodeKey(key) {
+    return key.split('/').map(encodeRfc3986).join('/');
+}
+/** The headers to send, `authorization` included, for a request signed in the Authorization header. */
+export async function signRequest(o) {
+    const { amzDate, day } = stamps(o.date ?? new Date());
+    const headers = lowercase({
+        ...o.headers,
+        'x-amz-date': amzDate,
+        'x-amz-content-sha256': o.payloadHash,
+        ...(o.credentials.sessionToken ? { 'x-amz-security-token': o.credentials.sessionToken } : {}),
+    });
+    const { canonical, signed } = canonicalHeaders(o.url, headers);
+    const request = [
+        o.method,
+        o.url.pathname,
+        canonicalQuery(o.url),
+        canonical,
+        signed,
+        o.payloadHash,
+    ].join('\n');
+    const signature = await sign(o.credentials, day, amzDate, request);
+    return {
+        ...headers,
+        authorization: `AWS4-HMAC-SHA256 Credential=${o.credentials.accessKeyId}/${scope(o.credentials, day)}, SignedHeaders=${signed}, Signature=${signature}`,
+    };
+}
+/**
+ * A presigned URL: the signature travels in the query string, and whoever
+ * holds the URL must send exactly the signed headers with exactly these
+ * values, before `expiresIn` runs out.
+ */
+export async function presign(o) {
+    const { amzDate, day } = stamps(o.date ?? new Date());
+    const headers = lowercase(o.headers ?? {});
+    const { canonical, signed } = canonicalHeaders(o.url, headers);
+    const url = new URL(o.url);
+    url.searchParams.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+    if (o.credentials.sessionToken) {
+        url.searchParams.set('X-Amz-Security-Token', o.credentials.sessionToken);
+    }
+    url.searchParams.set('X-Amz-Credential', `${o.credentials.accessKeyId}/${scope(o.credentials, day)}`);
+    url.searchParams.set('X-Amz-Date', amzDate);
+    url.searchParams.set('X-Amz-Expires', String(o.expiresIn));
+    url.searchParams.set('X-Amz-SignedHeaders', signed);
+    const request = [
+        o.method,
+        url.pathname,
+        canonicalQuery(url),
+        canonical,
+        signed,
+        UNSIGNED_PAYLOAD,
+    ].join('\n');
+    const signature = await sign(o.credentials, day, amzDate, request);
+    // Appended by hand: URLSearchParams would re-encode the query we just signed.
+    return `${url.origin}${url.pathname}?${canonicalQuery(url)}&X-Amz-Signature=${signature}`;
+}
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? utf8.encode(data) : data;
+    return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));
+}
+/* ------------------------------ internals ------------------------------ */
+function stamps(date) {
+    const amzDate = date
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}/, '');
+    return { amzDate, day: amzDate.slice(0, 8) };
+}
+function scope(c, day) {
+    return `${day}/${c.region}/${SERVICE}/aws4_request`;
+}
+function lowercase(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+function canonicalHeaders(url, headers) {
+    const all = { ...headers, host: url.host };
+    const names = Object.keys(all).sort();
+    const canonical = names.map((n) => `${n}:${all[n].trim().replace(/\s+/g, ' ')}\n`).join('');
+    return { canonical, signed: names.join(';') };
+}
+/** Every parameter, RFC 3986-encoded, sorted by encoded name then value. */
+function canonicalQuery(url) {
+    return [...url.searchParams]
+        .map(([k, v]) => [encodeRfc3986(k), encodeRfc3986(v)])
+        .sort(([ak, av], [bk, bv]) => (ak < bk ? -1 : ak > bk ? 1 : av < bv ? -1 : av > bv ? 1 : 0))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+}
+async function sign(c, day, amzDate, request) {
+    const toSign = ['AWS4-HMAC-SHA256', amzDate, scope(c, day), await sha256Hex(request)].join('\n');
+    let key = utf8.encode(`AWS4${c.secretAccessKey}`);
+    for (const part of [day, c.region, SERVICE, 'aws4_request'])
+        key = await hmac(key, part);
+    return hex(await hmac(key, toSign));
+}
+async function hmac(key, data) {
+    const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', k, utf8.encode(data)));
+}
+function hex(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}

package/dist/storage/testing.d.ts

@@ -0,0 +1,25 @@
+import type { Storage } from './types.js';
+/**
+ * The storage interface with no network: for a project's unit tests, and
+ * the reference the conformance suite is written against first. It enforces
+ * everything the real backends do — the same key rules (shared.ts), signed
+ * URLs that expire and check their signed headers, a public store that
+ * serves by URL — so a test that passes here is not passing by accident.
+ *
+ * Signed and public URLs are served by `fetch` on the returned object:
+ *
+ *   const storage = memoryStorage()
+ *   const up = await storage.signUpload('a.txt', { contentType: 'text/plain', size: 2 })
+ *   await storage.fetch(up.url, { method: 'PUT', headers: up.headers, body: 'hi' })
+ */
+export interface MemoryStorageOptions {
+    /** The public store: its base URL, or false for an environment that doesn't declare `public`. Default on. */
+    public?: false | {
+        base?: string;
+    };
+}
+export interface MemoryStorage extends Storage {
+    /** Serves the URLs this store hands out: signed uploads, signed downloads, public objects. */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+export declare function memoryStorage(options?: MemoryStorageOptions): MemoryStorage;