@knowledgefutures/sdk 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knowledge Futures, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @knowledgefutures/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Clients for the services a [Knowledge Futures Console](https://console.knowledgefutures.org)
+project declares, with nothing to configure: the console writes each service's
+binding into every environment that declares it, and `kf dev` writes the same
+variables pointing at local stand-ins.
+
+```sh
+npm i @knowledgefutures/sdk
+```
+
+```ts
+import { storage } from '@knowledgefutures/sdk/storage' // kf/storage@1
+await storage.put('covers/1.jpg', bytes, { contentType: 'image/jpeg' })
+
+// In tests, an in-memory store with the same interface:
+import { memoryStorage } from '@knowledgefutures/sdk/storage/testing'
+```
+
+`createStorage(env)` builds a client from an explicit environment, such as a
+Worker's `env` when `nodejs_compat` is off.
+
+## Whistle (`kf/whistle@1`)
+
+On a Worker the console hosts, declaring `kf/whistle@1` is enough for errors:
+Whistle tails every run, so uncaught exceptions, `console.error(err)` and cron
+runs reach it with no code. Log `console.error(err)`, not `err.message`, to keep
+the stack. This entry point is for what a run can't say by itself.
+
+On Hono, one line, registered before the routes:
+
+```ts
+import { whistle } from '@knowledgefutures/sdk/whistle'
+
+app.use(whistle())
+```
+
+It records a 403, or a 401 to a request that sent an `Authorization` header,
+as `access.denied` (Whistle alerts on bursts per client and per user), and a
+successful write under `/admin` or `/api/admin` as `admin.action`, with the
+route pattern and the user. The user is `c.var.user.id` unless
+`user: (c) => …` says otherwise; `admin` sets the prefixes. On a Worker it
+also logs an error a custom `onError` turned into a 5xx, which the tail would
+otherwise never see.
+
+The rest by hand:
+
+```ts
+import { checkIn, requestFields, telemetryFromEnv } from '@knowledgefutures/sdk/whistle'
+
+const t = telemetryFromEnv(env, { waitUntil })
+t.securityEvent('auth.failed', {
+  actor: `user:${id}`,
+  outcome: 'failure',
+  ...requestFields(request),
+})
+
+// A job that isn't a Worker cron: Whistle says when it fails or stops running.
+await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+```
+
+`captureError(err)` is for an error the app handles and doesn't log; on a
+tailed Worker, one it also logs or throws would count twice. `sentryDsn(url)`
+turns `KF_WHISTLE_URL` into a Sentry DSN, for apps that keep a Sentry SDK.
+`actor` is an id (`user:<id>`), never an email or a name, and `detail` is
+scrubbed of anything named like a credential. Events go under
+`KF_WHISTLE_PROJECT` and `KF_WHISTLE_ENVIRONMENT`, which the console and
+`kf dev` set; pass `project` and `environment` elsewhere.
+
+What a project declares and what the services give it:
+[console.knowledgefutures.org/llms.txt](https://console.knowledgefutures.org/llms.txt).
+Source: `packages/sdk/` in [knowledgefutures/kf-console](https://github.com/knowledgefutures/kf-console).

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/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The only error project code sees from storage. Every implementation maps
+ * its failures onto these codes — vendor XML, status codes and server quirks
+ * never escape — so a `catch` written against the in-memory store handles
+ * R2 the same way.
+ */
+export type StorageErrorCode = 
+/** No binding: the environment doesn't declare the service (or `public`). */
+'not_configured'
+/** The request itself is wrong: a bad key, metadata name, size or expiry. Fix the call. */
+ | 'invalid'
+/** The credentials were refused, or a signed URL was used past its expiry or not as signed. */
+ | 'forbidden'
+/** Bigger than the backend accepts. */
+ | 'too_large'
+/** The backend is down or unreachable. Safe to retry. */
+ | 'unavailable';
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    readonly status?: number | undefined;
+    readonly name = "StorageError";
+    constructor(code: StorageErrorCode, message: string, 
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    status?: number | undefined);
+}
+export declare function isStorageError(e: unknown, code?: StorageErrorCode): e is StorageError;

package/dist/storage/errors.js

@@ -0,0 +1,21 @@
+/**
+ * The only error project code sees from storage. Every implementation maps
+ * its failures onto these codes — vendor XML, status codes and server quirks
+ * never escape — so a `catch` written against the in-memory store handles
+ * R2 the same way.
+ */
+export class StorageError extends Error {
+    code;
+    status;
+    name = 'StorageError';
+    constructor(code, message, 
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isStorageError(e, code) {
+    return e instanceof StorageError && (code === undefined || e.code === code);
+}

package/dist/storage/index.d.ts

@@ -0,0 +1,34 @@
+import { PUBLIC_STORAGE_ENV, STORAGE_ENV } from './binding.js';
+import { type S3StoreOptions } from './s3.js';
+import type { Storage } from './types.js';
+/**
+ * `@knowledgefutures/sdk/storage` — files for a project that declares
+ * `kf/storage@1`, with nothing to configure:
+ *
+ *   import { storage } from '@knowledgefutures/sdk/storage'
+ *   await storage.put('covers/1.jpg', bytes, { contentType: 'image/jpeg' })
+ *   const { key } = await storage.public.upload(file, { prefix: 'covers' })
+ *   storage.public.url(key)
+ *
+ * The console writes `KF_STORAGE_URL` (and `KF_STORAGE_PUBLIC_URL` with
+ * `"public": true`) into every environment that declares the service; `kf
+ * dev` writes the same variables pointing at a local RustFS. Code never sees
+ * which backend it has.
+ */
+export type * from './types.js';
+export { StorageError, isStorageError, type StorageErrorCode } from './errors.js';
+export type { S3StoreOptions } from './s3.js';
+type Env = Partial<Record<typeof STORAGE_ENV | typeof PUBLIC_STORAGE_ENV, string | undefined>>;
+/**
+ * A client from an explicit environment: a Worker's `env` (when
+ * `nodejs_compat` is off, `process.env` is empty), a script's, a test's. A
+ * string is the private store's binding alone.
+ */
+export declare function createStorage(env: Env | string, options?: S3StoreOptions): Storage;
+/**
+ * The zero-config client. It reads `process.env` on first use, never at
+ * import, so importing it costs nothing where storage isn't declared and a
+ * missing binding fails at the call that needed it, with the fix in the
+ * message.
+ */
+export declare const storage: Storage;

package/dist/storage/index.js

@@ -0,0 +1,77 @@
+import { parseBinding, PUBLIC_STORAGE_ENV, STORAGE_ENV } from './binding.js';
+import { createBrokeredStore } from './brokered.js';
+import { StorageError } from './errors.js';
+import { createS3Store } from './s3.js';
+export { StorageError, isStorageError } from './errors.js';
+/**
+ * A client from an explicit environment: a Worker's `env` (when
+ * `nodejs_compat` is off, `process.env` is empty), a script's, a test's. A
+ * string is the private store's binding alone.
+ */
+export function createStorage(env, options) {
+    const vars = typeof env === 'string' ? { [STORAGE_ENV]: env } : env;
+    const priv = vars[STORAGE_ENV];
+    if (!priv)
+        throw unconfigured(STORAGE_ENV, 'kf/storage@1');
+    // Either form (binding.ts): `s3+https://…` with fixed credentials (kf dev, tests), or
+    // `https://<instance>:<secret>@<storage service>/`, which exchanges for short-lived ones.
+    const parsed = parseBinding(priv, STORAGE_ENV);
+    const store = parsed.kind === 'static'
+        ? createS3Store(parsed.binding, options)
+        : createBrokeredStore({ ...parsed.binding, store: 'private' }, options);
+    let pub;
+    return {
+        ...store,
+        get public() {
+            if (pub)
+                return pub;
+            const value = vars[PUBLIC_STORAGE_ENV];
+            if (!value)
+                throw unconfigured(PUBLIC_STORAGE_ENV, '"public": true under kf/storage@1');
+            const p = parseBinding(value, PUBLIC_STORAGE_ENV);
+            if (!p.binding.publicBase) {
+                throw new StorageError('not_configured', `${PUBLIC_STORAGE_ENV} has no base URL`);
+            }
+            const publicBase = p.binding.publicBase;
+            pub =
+                p.kind === 'static'
+                    ? createS3Store({ ...p.binding, publicBase }, options)
+                    : createBrokeredStore({ ...p.binding, store: 'public', publicBase }, options);
+            return pub;
+        },
+    };
+}
+/**
+ * The zero-config client. It reads `process.env` on first use, never at
+ * import, so importing it costs nothing where storage isn't declared and a
+ * missing binding fails at the call that needed it, with the fix in the
+ * message.
+ */
+export const storage = (() => {
+    let resolved;
+    const current = () => {
+        if (resolved)
+            return resolved;
+        const env = globalThis.process?.env;
+        if (!env?.[STORAGE_ENV])
+            throw unconfigured(STORAGE_ENV, 'kf/storage@1');
+        resolved = createStorage(env);
+        return resolved;
+    };
+    // async, so a missing binding is a rejected promise like every other failure, not a throw.
+    const methods = {
+        put: async (...a) => current().put(...a),
+        get: async (...a) => current().get(...a),
+        head: async (...a) => current().head(...a),
+        delete: async (...a) => current().delete(...a),
+        list: async (...a) => current().list(...a),
+        signUpload: async (...a) => current().signUpload(...a),
+        signDownload: async (...a) => current().signDownload(...a),
+        upload: async (...a) => current().upload(...a),
+    };
+    return Object.defineProperty(methods, 'public', { get: () => current().public });
+})();
+function unconfigured(name, declare) {
+    return new StorageError('not_configured', `${name} is not set: declare ${declare} in kf.project.jsonc for this environment, ` +
+        `run under \`kf dev\`, or pass the environment to createStorage(env)`);
+}

package/dist/storage/s3.d.ts

@@ -0,0 +1,22 @@
+import type { StorageBinding } from './binding.js';
+import type { ListResult, PublicStore, Store } from './types.js';
+/**
+ * A store over the S3 API — R2 behind the console, RustFS under `kf dev`.
+ * Path-style URLs (`<endpoint>/<bucket>/<key>`), which both accept, so there
+ * is one code path. Nothing here knows which backend it is talking to.
+ */
+export interface S3StoreOptions {
+    /** For tests. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** With temporary credentials (brokered.ts): signed into every request and presigned URL. */
+    sessionToken?: string;
+}
+export declare function createS3Store(binding: StorageBinding & {
+    publicBase: string;
+}, options?: S3StoreOptions): PublicStore;
+export declare function createS3Store(binding: StorageBinding, options?: S3StoreOptions): Store;
+/**
+ * ListObjectsV2 by hand: Workers have no DOMParser, and the response is a
+ * flat, well-known shape.
+ */
+export declare function parseList(xml: string): ListResult;