ankka 0.12.0 → 0.13.0

package/dist/sigv4.js

@@ -0,0 +1,149 @@
+// AWS Signature Version 4, as S3 and every store that speaks it reads it: a request signed in its
+// headers, and a URL signed in its query string (feature 055). The runtime's `SigV4.scala` made the
+// same choices, and the same vectors hold both: paths are encoded once, segment by segment, as S3
+// expects; a put's payload is `UNSIGNED-PAYLOAD`, so a stream is sent once and never hashed.
+//
+// The signer works on a request's parts — its method, its endpoint, its path and query *before*
+// encoding, the headers it signs and the hash of its payload — so the header form and the query form
+// share one canonical request, and AWS's published examples test it with no client at all.
+import { createHash, createHmac } from "node:crypto";
+/** A key pair. Never printed whole: `toString` hides the secret. */
+export class Credentials {
+    accessKey;
+    #secretKey;
+    constructor(accessKey, secretKey) {
+        this.accessKey = accessKey;
+        this.#secretKey = secretKey;
+        Object.freeze(this);
+    }
+    /** @internal */
+    get _secretKey() {
+        return this.#secretKey;
+    }
+    toString() {
+        return `Credentials(${this.accessKey}, ***)`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+export const ALGORITHM = "AWS4-HMAC-SHA256";
+/** The payload hash a put sends so its body is streamed once and never hashed. */
+export const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+const utf8 = new TextEncoder();
+export function sha256Hex(data) {
+    return createHash("sha256").update(typeof data === "string" ? utf8.encode(data) : data).digest("hex");
+}
+export function hmac(key, data) {
+    return createHmac("sha256", key).update(data, "utf8").digest();
+}
+/** The hash of an empty payload. */
+export const EMPTY_PAYLOAD = sha256Hex(new Uint8Array());
+/** RFC 3986 encoding as SigV4 states it: unreserved characters kept, everything else `%XX` of its UTF-8 bytes. */
+export function encode(text, encodeSlash) {
+    let out = "";
+    for (const b of utf8.encode(text)) {
+        const c = String.fromCharCode(b);
+        if ((b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || (b >= 0x30 && b <= 0x39) || c === "-" || c === "_" || c === "." || c === "~" || (c === "/" && !encodeSlash)) {
+            out += c;
+        }
+        else {
+            out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+        }
+    }
+    return out;
+}
+/** One request: the endpoint's scheme and authority, a decoded path and decoded query pairs. */
+export class SignedRequest {
+    method;
+    endpoint;
+    path;
+    query;
+    constructor(method, endpoint, path, query = []) {
+        this.method = method;
+        this.endpoint = typeof endpoint === "string" ? new URL(endpoint) : endpoint;
+        this.path = path;
+        this.query = query;
+        Object.freeze(this);
+    }
+    /** The `host` header's value: the host, with the port when the endpoint names one. */
+    get host() {
+        return this.endpoint.port === "" ? this.endpoint.hostname : `${this.endpoint.hostname}:${this.endpoint.port}`;
+    }
+    get canonicalPath() {
+        const raw = this.endpoint.pathname === "/" ? "" : this.endpoint.pathname;
+        const base = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+        const p = this.path.startsWith("/") ? this.path : "/" + this.path;
+        return base + encode(p, false);
+    }
+    get canonicalQuery() {
+        return this.query
+            .map(([k, v]) => [encode(k, true), encode(v, true)])
+            .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
+            .map(([k, v]) => `${k}=${v}`)
+            .join("&");
+    }
+    /** The URL the request is sent to: the same encoding as the one signed. */
+    get url() {
+        const q = this.canonicalQuery;
+        return `${this.endpoint.protocol}//${this.host}${this.canonicalPath}${q === "" ? "" : "?" + q}`;
+    }
+    withQuery(more) {
+        return new SignedRequest(this.method, this.endpoint, this.path, [...this.query, ...more]);
+    }
+}
+function pad(n, width = 2) {
+    return String(n).padStart(width, "0");
+}
+/** `20150830T123600Z`. */
+export function amzDate(now) {
+    return `${shortDate(now)}T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}Z`;
+}
+function shortDate(now) {
+    return `${pad(now.getUTCFullYear(), 4)}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}`;
+}
+function signingKey(secret, now, region, service) {
+    const date = hmac(utf8.encode("AWS4" + secret), shortDate(now));
+    return hmac(hmac(hmac(date, region), service), "aws4_request");
+}
+function stringToSign(stamp, scope, canonicalRequest) {
+    return `${ALGORITHM}\n${stamp}\n${scope}\n${sha256Hex(canonicalRequest)}`;
+}
+/**
+ * The headers to send with `request` so the store believes it: `x-amz-date` and `Authorization`.
+ * `headers` are the ones to sign beside `host` and `x-amz-date` — an S3 request includes
+ * `x-amz-content-sha256` among them — and are sent as given.
+ */
+export function sign(request, headers, payloadHash, credentials, region, service, now) {
+    const stamp = amzDate(now);
+    const signed = new Map();
+    for (const [k, v] of Object.entries(headers))
+        signed.set(k.toLowerCase(), v);
+    signed.set("host", request.host);
+    signed.set("x-amz-date", stamp);
+    const sorted = [...signed.entries()].map(([k, v]) => [k, v.trim().replace(/ +/g, " ")]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const names = sorted.map(([k]) => k).join(";");
+    const canonical = sorted.map(([k, v]) => `${k}:${v}\n`).join("");
+    const scope = `${shortDate(now)}/${region}/${service}/aws4_request`;
+    const creq = [request.method, request.canonicalPath, request.canonicalQuery, canonical, names, payloadHash].join("\n");
+    const signature = hmac(signingKey(credentials._secretKey, now, region, service), stringToSign(stamp, scope, creq)).toString("hex");
+    return {
+        "x-amz-date": stamp,
+        Authorization: `${ALGORITHM} Credential=${credentials.accessKey}/${scope}, SignedHeaders=${names}, Signature=${signature}`,
+    };
+}
+/** A URL anyone may use, until it expires, for `request`'s method on its path. Signs `host` alone. */
+export function presign(request, credentials, region, service, expiresSeconds, now) {
+    const stamp = amzDate(now);
+    const scope = `${shortDate(now)}/${region}/${service}/aws4_request`;
+    const withAuth = request.withQuery([
+        ["X-Amz-Algorithm", ALGORITHM],
+        ["X-Amz-Credential", `${credentials.accessKey}/${scope}`],
+        ["X-Amz-Date", stamp],
+        ["X-Amz-Expires", String(expiresSeconds)],
+        ["X-Amz-SignedHeaders", "host"],
+    ]);
+    const creq = [request.method, withAuth.canonicalPath, withAuth.canonicalQuery, `host:${request.host}\n`, "host", UNSIGNED_PAYLOAD].join("\n");
+    const signature = hmac(signingKey(credentials._secretKey, now, region, service), stringToSign(stamp, scope, creq)).toString("hex");
+    return withAuth.withQuery([["X-Amz-Signature", signature]]).url;
+}

package/dist/spec.d.ts

@@ -1,10 +1,16 @@
 import { type MessageInitShape } from "@bufbuild/protobuf";
-import { Endpoint_Acl, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
+import { Endpoint_Acl, type McpAclSchema, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import type { Registry } from "./service.ts";
 import type { Acl } from "./routes.ts";
-export declare const PROTOCOL_VERSION = "1.19";
+export declare const PROTOCOL_VERSION = "1.21";
 export declare const SDK_NAME = "ankka-typescript";
+/** An HTTP endpoint's rule; client keys and `anyOf` are refused for one at registration, so they deny here. */
 export declare function aclToProto(acl: Acl): Endpoint_Acl;
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */
 export declare function callersToProto(acl: Acl): MessageInitShape<typeof CallerMatcherSchema>[];
+/**
+ * An MCP endpoint's or tool's rule as discovery carries it (1.20): each member of an `anyOf` sets its
+ * own field, so `anyOf(clientKeys, authenticated)` is `client_keys` and `tokens`.
+ */
+export declare function mcpAclToProto(acl: Acl): MessageInitShape<typeof McpAclSchema>;
 export declare function renderSpec(registry: Registry): Spec;

package/dist/spec.js

@@ -17,11 +17,12 @@ function toolInit(t) {
         ...(approval !== undefined ? { approval } : {}),
     };
 }
-export const PROTOCOL_VERSION = "1.19";
+export const PROTOCOL_VERSION = "1.21";
 export const SDK_NAME = "ankka-typescript";
+/** An HTTP endpoint's rule; client keys and `anyOf` are refused for one at registration, so they deny here. */
 export function aclToProto(acl) {
     if (typeof acl === "object")
-        return Endpoint_Acl.CALLERS;
+        return acl.kind === "callers" ? Endpoint_Acl.CALLERS : Endpoint_Acl.DENY_ALL;
     switch (acl) {
         case "allow-all":
             return Endpoint_Acl.ALLOW_ALL;
@@ -29,11 +30,13 @@ export function aclToProto(acl) {
             return Endpoint_Acl.DENY_ALL;
         case "authenticated":
             return Endpoint_Acl.AUTHENTICATED;
+        case "client-keys":
+            return Endpoint_Acl.DENY_ALL;
     }
 }
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */
 export function callersToProto(acl) {
-    if (typeof acl !== "object")
+    if (typeof acl !== "object" || acl.kind !== "callers")
         return [];
     return acl.callers.map((m) => {
         switch (m.kind) {
@@ -50,6 +53,38 @@ export function callersToProto(acl) {
         }
     });
 }
+/**
+ * An MCP endpoint's or tool's rule as discovery carries it (1.20): each member of an `anyOf` sets its
+ * own field, so `anyOf(clientKeys, authenticated)` is `client_keys` and `tokens`.
+ */
+export function mcpAclToProto(acl) {
+    const out = { allowAll: false, denyAll: false, tokens: false, clientKeys: false, callers: [] };
+    const add = (rule) => {
+        if (typeof rule === "object") {
+            if (rule.kind === "anyOf")
+                rule.acls.forEach(add);
+            else
+                out.callers.push(...callersToProto(rule));
+            return;
+        }
+        switch (rule) {
+            case "allow-all":
+                out.allowAll = true;
+                break;
+            case "deny-all":
+                out.denyAll = true;
+                break;
+            case "authenticated":
+                out.tokens = true;
+                break;
+            case "client-keys":
+                out.clientKeys = true;
+                break;
+        }
+    };
+    add(acl);
+    return out;
+}
 function handlerInits(handlers) {
     return [...handlers.values()]
         .map((h) => ({ name: h.name, readOnly: h.readOnly, streaming: h.streaming }))
@@ -232,10 +267,25 @@ export function renderSpec(registry) {
             ...(r.acl !== undefined ? { acl: aclToProto(r.acl), allowCallers: callersToProto(r.acl) } : {}),
         })),
     }));
+    const mcpEndpoints = [...registry.mcpEndpoints.values()].map((e) => ({
+        id: e.id,
+        path: e.path,
+        ...(e.serverName !== undefined ? { name: e.serverName } : {}),
+        ...(e.serverVersion !== undefined ? { version: e.serverVersion } : {}),
+        acl: mcpAclToProto(e.acl),
+        tools: e.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchemaJson: JSON.stringify(t.inputSchema),
+            ...(t.acl !== undefined ? { acl: mcpAclToProto(t.acl) } : {}),
+        })),
+        brokered: e.brokered,
+    }));
     return create(SpecSchema, {
         protocolVersion: PROTOCOL_VERSION,
         sdk: { name: SDK_NAME, version: VERSION },
         components,
         endpoints,
+        mcpEndpoints,
     });
 }

package/dist/storage.d.ts

@@ -0,0 +1,288 @@
+import { CommandError } from "./effects/common.ts";
+import { Credentials } from "./sigv4.ts";
+import { Instant } from "./time.ts";
+/** How a bucket is reached from outside the installation. */
+export type BucketExposure = "private" | "signed" | "public" | "supplied";
+/** What a signed URL lets its holder do with one object. */
+export type SignedAccess = "read" | "keep";
+/** An object read from a bucket. Read its `body` once, or call `bytes()`. */
+export interface StoredObject {
+    readonly contentType: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+    readonly body: ReadableStream<Uint8Array>;
+    /** The whole body, read from `body`. */
+    bytes(): Promise<Uint8Array>;
+}
+/** What a bucket keeps under a name, without the bytes. */
+export interface ObjectInfo {
+    readonly name: string;
+    readonly contentType: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+}
+/** One object in a listing. */
+export interface ObjectEntry {
+    readonly name: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+}
+/** How a put keeps its body: its content type, and its length, which a stream must declare. */
+export interface PutOptions {
+    readonly contentType: string;
+    readonly length?: number;
+}
+/**
+ * One bucket. Its objects are named with `/` between segments, so a listing by prefix reads like a
+ * directory; it is not one. A put replaces the whole object or leaves the old one.
+ */
+export interface Bucket {
+    /** The descriptor's name for it; `undefined` for the unnamed bucket. */
+    readonly name: string | undefined;
+    readonly exposure: BucketExposure;
+    /**
+     * Keeps `body` under `name`, replacing what was there. A stream declares its `length`; one that ends
+     * before it fails and keeps nothing, and the old object, if any, stays.
+     */
+    put(name: string, body: ReadableStream<Uint8Array> | Uint8Array, options: PutOptions): Promise<void>;
+    /** The object kept under `name`, or `undefined` when there is none. */
+    get(name: string): Promise<StoredObject | undefined>;
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    delete(name: string): Promise<void>;
+    /** Every object whose name begins with `prefix`, in name order; pages are read as it is walked. */
+    list(prefix: string): AsyncIterable<ObjectEntry>;
+    /** What is kept under `name`, without its bytes, or `undefined`. */
+    stat(name: string): Promise<ObjectInfo | undefined>;
+    /**
+     * A URL a browser may use, until `spanSeconds` (15 minutes by default, at most seven days) have
+     * passed, to read or keep the object under `name`. Computed: no request reaches the store. A signed
+     * bucket's, or the unnamed bucket's when the service sets `exposeObjectStorage`.
+     */
+    signedUrl(name: string, access: SignedAccess, spanSeconds?: number): string;
+    /** The address a browser reads the object under `name` at, with no signature: a public bucket's only. */
+    url(name: string): string;
+}
+/** A service's buckets: `default`, the unnamed one, and the named ones by name. */
+export interface Buckets {
+    /** The unnamed bucket. Refuses, naming `provisionObjectStorage`, when the service has none. */
+    readonly default: Bucket;
+    /** A bucket the descriptor's `buckets` list names; refused, naming the ones it does name, otherwise. */
+    bucket(name: string): Bucket;
+    /** Every named bucket, in no particular order. */
+    readonly buckets: Bucket[];
+}
+/**
+ * What an object's name, a prefix, a bucket's name and a signed URL's span may be. Every store and every
+ * test double applies these, and `protocol/fixtures/storage/rules.json` holds them to the other SDKs.
+ */
+export declare const ObjectRules: Readonly<{
+    MAX_NAME_BYTES: 1024;
+    MAX_BUCKET_NAME: 32;
+    /** Seven days. */
+    MAX_SIGNED_URL_SECONDS: 604800;
+    /** Fifteen minutes. */
+    DEFAULT_SIGNED_URL_SECONDS: 900;
+    BUCKET_NAME_RULE: "lower-case letters, digits and '-', 1 to 32 characters";
+    /** What is wrong with an object's `name`, if anything. */
+    nameProblem(name: string): string | undefined;
+    /** What is wrong with a listing's `prefix`, if anything. Empty is everything. */
+    prefixProblem(prefix: string): string | undefined;
+    /** What is wrong with a bucket's name, if anything, in the descriptor's words. */
+    bucketNameProblem(name: string): string | undefined;
+    /** What is wrong with a signed URL's span, in seconds, if anything. */
+    spanProblem(spanSeconds: number): string | undefined;
+    checkName(name: string): void;
+    checkPrefix(prefix: string): void;
+    checkSpan(spanSeconds: number): void;
+}>;
+/** What the storage client says when it refuses: the runtime's words (`StorageRefusals` in the Scala SDK). */
+export declare const StorageRefusals: Readonly<{
+    noBucket(): CommandError;
+    unknown(name: string, known: Iterable<string>): CommandError;
+    noCredential(): CommandError;
+    notExposed(): CommandError;
+    notSigned(bucket: string, exposure: BucketExposure): CommandError;
+    notPublic(bucket: string | undefined, exposure: BucketExposure): CommandError;
+    unreachable(endpoint: string, cause: string): CommandError;
+    refusedByStore(endpoint: string, status: number, detail: string): CommandError;
+    unreadable(endpoint: string, cause: string): CommandError;
+    shortBody(declared: number, read: number): CommandError;
+    negativeLength(length: number): CommandError;
+    /** TypeScript's own: a stream's length cannot be known before it is read, and S3 is told it first. */
+    undeclaredLength(): CommandError;
+    stepsOnly(): CommandError;
+}>;
+/** Buckets that refuse every call, naming `provisionObjectStorage`: a deployed service with no bucket. */
+export declare const noStorage: Buckets;
+export interface InMemoryBucketsOptions {
+    /** The named buckets and their exposure; more may be declared later with `declare`. */
+    readonly buckets?: Readonly<Record<string, BucketExposure>>;
+    /** Whether the service has the unnamed bucket; `true` by default. */
+    readonly unnamed?: boolean;
+    /** The unnamed bucket's exposure: `signed` by default, so a test may sign a URL for it. */
+    readonly unnamedExposure?: BucketExposure;
+    /** Where a public bucket's objects are read: `http://memory/public/<bucket>` by default, reaching nothing. */
+    readonly publicBase?: (bucket: string) => string;
+}
+/**
+ * A service's buckets in memory: the test kits' store, so a test of a handler that keeps or reads an
+ * object needs no object store and no Docker. It applies every rule the other stores apply, in the
+ * same words. A signed URL is computed (`http://memory/...`) and reaches nothing.
+ */
+export declare class InMemoryBuckets implements Buckets {
+    #private;
+    constructor(options?: InMemoryBucketsOptions);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+    /** Declares a named bucket, before or after the service starts. */
+    declare(name: string, exposure: BucketExposure): void;
+    /** Forgets every object; the declared buckets stay. */
+    clear(): void;
+}
+/** What a descriptor declares: whether the unnamed bucket is asked for, and each named one. */
+export interface DeclaredBuckets {
+    readonly unnamed: boolean;
+    readonly buckets: Readonly<Record<string, BucketExposure>>;
+}
+/**
+ * The buckets `service.json` in `directory` declares, read where a service runs on a developer's machine
+ * and in a test, so the directory and memory stores refuse the names a deployed service would; `undefined`
+ * when there is no such file. Only the two fields that say which buckets there are.
+ */
+export declare function declaredBuckets(directory?: string): DeclaredBuckets | undefined;
+/** Where a service serves its directory store's objects. */
+export declare const STORAGE_PATH = "/_ankka/storage";
+/** The unnamed bucket's directory and URL segment: no bucket name begins with `_`. */
+export declare const DEFAULT_SEGMENT = "_default";
+export interface DirectoryBucketsOptions {
+    /** The buckets `service.json` declares; with none, the unnamed bucket and any name asked for, as private. */
+    readonly declared?: DeclaredBuckets;
+    /** The service's own address, where its URLs point: `http://<ANKKA_HTTP_INTERFACE or 127.0.0.1>:<ANKKA_HTTP_PORT or 9000>`. */
+    readonly addressBase?: () => string;
+}
+/** The address a local service's HTTP port answers at, as the sidecar beside it binds it. */
+export declare function localAddress(env?: Readonly<Record<string, string | undefined>>): string;
+/**
+ * A service's buckets in a directory on a developer's machine: what a service keeps when it runs with no
+ * variable of an object store. The runtime's layout exactly, so a Scala service and a TypeScript one read
+ * each other's: one directory per bucket under `root` (`_default` for the unnamed one), an object's name
+ * encoded into one file name under `objects/` (its hash when too long), and beside it under `meta/` its
+ * name, content type, length and when it was kept. A put writes a temporary file and moves it into place,
+ * so a stream that ends short leaves the old object.
+ *
+ * A signed URL and a public address point at the service's own HTTP port, under `/_ankka/storage`, which
+ * the SDK serves through the sidecar while this is the service's store.
+ */
+export declare class DirectoryBuckets implements Buckets {
+    #private;
+    readonly root: string;
+    constructor(root: string, options?: DirectoryBucketsOptions);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+    /** The bucket a URL's segment names, `_default` or a bucket's name, as this store would answer it. */
+    bySegment(segment: string): {
+        readonly bucket: Bucket;
+        readonly segment: string;
+    } | undefined;
+    /** `HMAC-SHA256(key, "<segment>/<name>|<access>|<expires>")` in hex, over the key kept in the root. */
+    token(segment: string, objectName: string, access: string, expires: number): string;
+    /** Whether `token` signs this access until `expires`, and `expires` is still to come. */
+    admits(segment: string, objectName: string, access: string, expires: number, token: string): boolean;
+}
+/**
+ * The deepest object name whose address keeps its slashes. The sidecar matches a process's route by
+ * whole segments, so the storage endpoint declares one route per depth up to this; a deeper name's
+ * slashes are encoded and it travels as one segment.
+ */
+export declare const MAX_ADDRESS_SEGMENTS = 16;
+/** An object's name in a directory store's address: as the runtime writes it, while the sidecar can route it. */
+export declare function addressOf(objectName: string): string;
+/** One S3 bucket and how to reach it. */
+export interface S3Target {
+    readonly endpoint: URL;
+    readonly region: string;
+    readonly bucket: string;
+    readonly credentials: Credentials | undefined;
+    readonly publicEndpoint: URL | undefined;
+}
+/** A bucket the descriptor names: its exposure, where it is, and for a public one the base it is read at. */
+export interface NamedTarget {
+    readonly name: string;
+    readonly exposure: BucketExposure;
+    readonly target: S3Target;
+    readonly publicUrl: string | undefined;
+}
+/** The S3 store's settings, read from the `ANKKA_S3_*` variables as the runtime's `StorageSettings` reads them. */
+export interface S3Settings {
+    readonly unnamed: S3Target | undefined;
+    readonly named: readonly NamedTarget[];
+    /** How long one request waits for an answer: 30 seconds. */
+    readonly timeoutMs: number;
+}
+type Env = Readonly<Record<string, string | undefined>>;
+/** The bucket a variable's `<NAME>` names: lower case, `_` as `-`. */
+export declare function bucketNameOf(suffix: string): string;
+/** The `<NAME>` of a bucket's variables: upper case, `-` as `_`. */
+export declare function bucketVariableSuffix(bucket: string): string;
+/**
+ * The S3 settings in `env`: the unnamed family `ANKKA_S3_{ENDPOINT,REGION,BUCKET,ACCESS_KEY,SECRET_KEY,PUBLIC_ENDPOINT}`;
+ * a named bucket the platform made, `ANKKA_S3_BUCKET_<NAME>`, `ANKKA_S3_EXPOSURE_<NAME>` and, for a public
+ * one, `ANKKA_S3_PUBLIC_URL_<NAME>`, sharing the unnamed family's endpoint, region and key; a supplied
+ * bucket, the five `ANKKA_S3_{ENDPOINT,REGION,BUCKET,ACCESS_KEY,SECRET_KEY}_<NAME>` of its own. Throws,
+ * naming the variable, on a family that cannot be read.
+ */
+export declare function s3Settings(env?: Env, timeoutMs?: number): S3Settings;
+/** A `ListObjectsV2` answer: its entries, and the token for the next page while it is truncated. */
+export declare function parseListing(xml: string): {
+    readonly entries: ObjectEntry[];
+    readonly next: string | undefined;
+};
+/** One bucket in an S3 store: path-style requests, a put streamed once with an unsigned payload, a listing paged as it is walked. */
+export declare class S3Bucket implements Bucket {
+    #private;
+    readonly name: string | undefined;
+    readonly exposure: BucketExposure;
+    constructor(target: S3Target, name: string | undefined, exposure: BucketExposure, publicUrl: string | undefined, timeoutMs?: number);
+    put(objectName: string, body: ReadableStream<Uint8Array> | Uint8Array, options: PutOptions): Promise<void>;
+    get(objectName: string): Promise<StoredObject | undefined>;
+    stat(objectName: string): Promise<ObjectInfo | undefined>;
+    delete(objectName: string): Promise<void>;
+    list(prefix: string): AsyncIterable<ObjectEntry>;
+    signedUrl(objectName: string, access: SignedAccess, spanSeconds?: number): string;
+    url(objectName: string): string;
+}
+/** The S3 store's buckets, by name, from `s3Settings`. */
+export declare class S3Buckets implements Buckets {
+    #private;
+    constructor(settings?: S3Settings);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+}
+/** What stands behind every bucket of a service. */
+export type StorageBackend = "s3" | "directory" | "memory" | "unavailable";
+export interface ChosenStorage {
+    readonly backend: StorageBackend;
+    readonly buckets: Buckets;
+}
+export interface StorageChoiceOptions {
+    /** Where `service.json` is read from, for the buckets it declares: the working directory by default. */
+    readonly serviceDirectory?: string;
+    /** The service's own address, for the directory store's URLs. */
+    readonly addressBase?: () => string;
+}
+/**
+ * The one place a process's store is chosen, as the runtime chooses its own: `ANKKA_STORAGE_BACKEND` when
+ * set (`s3`, `directory` or `memory`); otherwise S3 when any `ANKKA_S3_*` bucket is given, the directory
+ * store (`ANKKA_STORAGE_DIR`, default `.ankka/storage`) on a developer's machine — anywhere Kubernetes did
+ * not start the process — and no store at all on the platform. Throws, naming the variable, when the
+ * settings cannot be read: a service that cannot reach its buckets does not start.
+ */
+export declare function chooseStorage(env?: Env, options?: StorageChoiceOptions): ChosenStorage;
+/** The store the server chose for this process, which every component's `storage` answers unless a test gave it one. */
+export declare function processStorage(): Buckets;
+/** @internal The server's: the store this process was given. */
+export declare function _setProcessStorage(buckets: Buckets): void;
+export {};