@knowledgefutures/sdk 0.0.0-stage → 0.1.0

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;

package/dist/storage/testing.js

@@ -0,0 +1,242 @@
+import { StorageError } from './errors.js';
+import { attachment, checkExpiresIn, DOWNLOAD_EXPIRES_IN, UPLOAD_EXPIRES_IN, checkKey, checkMetadata, checkPrefix, checkSignUpload, IMMUTABLE, publicDisposition, SHORT_PUBLIC, toBytes, uploadAsPut, } from './shared.js';
+import { encodeKey } from './sigv4.js';
+const PRIVATE_ORIGIN = 'https://signed.storage.test';
+const DEFAULT_PUBLIC_BASE = 'https://public.storage.test';
+export function memoryStorage(options = {}) {
+    const grants = new Map();
+    const priv = new MemoryStore(grants, false);
+    const pub = options.public === false
+        ? null
+        : new MemoryStore(grants, true, (options.public?.base ?? DEFAULT_PUBLIC_BASE).replace(/\/+$/, ''));
+    async function serve(input, init) {
+        const req = new Request(input, init);
+        const url = new URL(req.url);
+        if (pub &&
+            req.url.startsWith(`${pub.base}/`) &&
+            (req.method === 'GET' || req.method === 'HEAD')) {
+            const key = decodeKey(url.pathname);
+            const e = pub.objects.get(key);
+            if (!e)
+                return new Response('not found', { status: 404 });
+            return objectResponse(e, req.method === 'HEAD');
+        }
+        if (url.origin !== PRIVATE_ORIGIN)
+            return new Response('not a URL this store handed out', { status: 404 });
+        const grant = grants.get(url.searchParams.get('kf-signature') ?? '');
+        if (!grant || grant.method !== req.method || grant.key !== decodeKey(url.pathname)) {
+            return new Response('SignatureDoesNotMatch', { status: 403 });
+        }
+        if (Date.now() > grant.expires)
+            return new Response('Request has expired', { status: 403 });
+        if (grant.method === 'GET') {
+            const e = grant.store.objects.get(grant.key);
+            if (!e)
+                return new Response('not found', { status: 404 });
+            const res = objectResponse(e, false);
+            if (grant.disposition)
+                res.headers.set('content-disposition', grant.disposition);
+            return res;
+        }
+        // PUT: exactly the signed headers, exactly the signed size.
+        const bytes = new Uint8Array(await req.arrayBuffer());
+        if (req.headers.get('content-type') !== grant.contentType ||
+            (req.headers.get('cache-control') ?? undefined) !== grant.cacheControl ||
+            (req.headers.get('content-disposition') ?? undefined) !== grant.disposition ||
+            bytes.byteLength !== grant.size) {
+            return new Response('SignatureDoesNotMatch', { status: 403 });
+        }
+        await grant.store.put(grant.key, bytes, {
+            contentType: grant.contentType,
+            ...(grant.cacheControl ? { cacheControl: grant.cacheControl } : {}),
+            ...(grant.disposition ? { contentDisposition: grant.disposition } : {}),
+        });
+        return new Response(null, { status: 200 });
+    }
+    return {
+        put: (key, body, o) => priv.put(key, body, o),
+        get: (key) => priv.get(key),
+        head: (key) => priv.head(key),
+        delete: (key) => priv.delete(key),
+        list: (o) => priv.list(o),
+        signUpload: (key, o) => priv.signUpload(key, o),
+        signDownload: (key, o) => priv.signDownload(key, o),
+        upload: (file, o) => priv.upload(file, o),
+        get public() {
+            if (!pub) {
+                throw new StorageError('not_configured', 'this store has no public store (memoryStorage({ public: false }))');
+            }
+            return pub;
+        },
+        fetch: serve,
+    };
+}
+class MemoryStore {
+    grants;
+    isPublic;
+    base;
+    objects = new Map();
+    constructor(grants, isPublic, base) {
+        this.grants = grants;
+        this.isPublic = isPublic;
+        this.base = base;
+    }
+    async put(key, body, opts = {}) {
+        checkKey(key);
+        const metadata = checkMetadata(opts.metadata);
+        const { bytes, contentType } = await toBytes(body, opts.contentType);
+        const cacheControl = opts.cacheControl ?? (this.isPublic ? SHORT_PUBLIC : undefined);
+        const disposition = this.isPublic
+            ? publicDisposition(contentType, opts.contentDisposition)
+            : opts.contentDisposition;
+        const e = {
+            key,
+            size: bytes.byteLength,
+            etag: crypto.randomUUID().replaceAll('-', ''),
+            uploaded: new Date(Math.floor(Date.now() / 1000) * 1000),
+            contentType,
+            metadata,
+            bytes,
+        };
+        if (cacheControl)
+            e.cacheControl = cacheControl;
+        if (disposition)
+            e.contentDisposition = disposition;
+        this.objects.set(key, e);
+        return describe(e);
+    }
+    async get(key) {
+        checkKey(key);
+        const e = this.objects.get(key);
+        if (!e)
+            return null;
+        const copy = e.bytes.slice();
+        return {
+            ...describe(e),
+            body: new Response(copy).body,
+            arrayBuffer: async () => copy.buffer.slice(0),
+            text: async () => new TextDecoder().decode(copy),
+        };
+    }
+    async head(key) {
+        checkKey(key);
+        const e = this.objects.get(key);
+        return e ? describe(e) : null;
+    }
+    async delete(key) {
+        checkKey(key);
+        this.objects.delete(key);
+    }
+    async 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 after = opts.cursor ? decodeCursor(opts.cursor) : undefined;
+        const keys = [...this.objects.keys()]
+            .filter((k) => k.startsWith(opts.prefix ?? '') && (after === undefined || byteCompare(k, after) > 0))
+            .sort(byteCompare);
+        const page = keys.slice(0, limit);
+        const objects = page.map((k) => {
+            const e = this.objects.get(k);
+            return { key: e.key, size: e.size, etag: e.etag, uploaded: e.uploaded };
+        });
+        return keys.length > limit
+            ? { objects, cursor: btoa(encodeURIComponent(page.at(-1))) }
+            : { objects };
+    }
+    async signUpload(key, o) {
+        checkKey(key);
+        checkSignUpload(o);
+        const expiresIn = checkExpiresIn(o.expiresIn, UPLOAD_EXPIRES_IN);
+        const cacheControl = o.cacheControl ?? (this.isPublic ? SHORT_PUBLIC : undefined);
+        const headers = { 'content-type': o.contentType };
+        if (cacheControl)
+            headers['cache-control'] = cacheControl;
+        const disposition = this.isPublic ? publicDisposition(o.contentType, undefined) : undefined;
+        if (disposition)
+            headers['content-disposition'] = disposition;
+        const url = this.grant({
+            method: 'PUT',
+            key,
+            expiresIn,
+            contentType: o.contentType,
+            size: o.size,
+            ...(cacheControl ? { cacheControl } : {}),
+            ...(disposition ? { disposition } : {}),
+        });
+        return {
+            key,
+            url,
+            method: 'PUT',
+            headers,
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+    }
+    async signDownload(key, o = {}) {
+        checkKey(key);
+        const expiresIn = checkExpiresIn(o.expiresIn, DOWNLOAD_EXPIRES_IN);
+        return this.grant({
+            method: 'GET',
+            key,
+            expiresIn,
+            ...(o.filename ? { disposition: attachment(o.filename) } : {}),
+        });
+    }
+    async upload(file, options) {
+        const p = uploadAsPut(file, options, this.isPublic ? { cacheControl: IMMUTABLE } : {});
+        return this.put(p.key, p.body, p.options);
+    }
+    url(key) {
+        checkKey(key);
+        if (!this.base)
+            throw new StorageError('not_configured', 'the private store has no public URLs');
+        return `${this.base}/${encodeKey(key)}`;
+    }
+    grant(g) {
+        const token = crypto.randomUUID();
+        const { expiresIn, ...rest } = g;
+        this.grants.set(token, { ...rest, store: this, expires: Date.now() + expiresIn * 1000 });
+        return `${PRIVATE_ORIGIN}/${encodeKey(g.key)}?kf-signature=${token}`;
+    }
+}
+function describe(e) {
+    const { bytes: _bytes, ...meta } = e;
+    return { ...meta, metadata: { ...meta.metadata } };
+}
+function objectResponse(e, headOnly) {
+    const headers = new Headers({
+        'content-type': e.contentType,
+        'content-length': String(e.size),
+        etag: `"${e.etag}"`,
+        'last-modified': e.uploaded.toUTCString(),
+    });
+    if (e.cacheControl)
+        headers.set('cache-control', e.cacheControl);
+    if (e.contentDisposition)
+        headers.set('content-disposition', e.contentDisposition);
+    return new Response(headOnly ? null : e.bytes.slice(), { status: 200, headers });
+}
+function decodeKey(pathname) {
+    return pathname.slice(1).split('/').map(decodeURIComponent).join('/');
+}
+function decodeCursor(cursor) {
+    try {
+        return decodeURIComponent(atob(cursor));
+    }
+    catch {
+        throw new StorageError('invalid', 'not a cursor this store handed out');
+    }
+}
+const utf8 = new TextEncoder();
+/** S3 lists in UTF-8 byte order, which differs from UTF-16 `<` above the BMP. */
+function byteCompare(a, b) {
+    const x = utf8.encode(a);
+    const y = utf8.encode(b);
+    for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    }
+    return x.length - y.length;
+}