ankka 0.11.0 → 0.13.0

package/dist/server/server.d.ts

@@ -1,5 +1,6 @@
-import type { Registry } from "../service.ts";
+import { Registry } from "../service.ts";
 import type { ComponentClient } from "../client.ts";
+import { type Buckets } from "../storage.ts";
 export interface ServerOptions {
     /** `127.0.0.1` by default; `0.0.0.0` for the testkit; anything else is refused. */
     readonly host?: string;
@@ -8,12 +9,21 @@ export interface ServerOptions {
     /** The largest message accepted from the sidecar; 64 MiB by default. */
     readonly readMaxBytes?: number;
     readonly log?: (message: string) => void;
+    /**
+     * The service's buckets, in place of the store `ANKKA_STORAGE_BACKEND` and the `ANKKA_S3_*` variables
+     * choose: the integration testkit's in-memory store.
+     */
+    readonly storage?: Buckets;
+    /** Where `service.json` is read from for the buckets it declares; the working directory by default. */
+    readonly serviceDirectory?: string;
 }
 /** What every servicer needs. */
 export interface ServerContext {
     readonly registry: Registry;
     readonly client: ComponentClient;
     readonly log: (message: string) => void;
+    /** The buckets every endpoint instance is given; the process's store when absent. */
+    readonly storage?: Buckets;
 }
 export declare class Server {
     #private;

package/dist/server/server.js

@@ -4,6 +4,9 @@
 // the integration testkit, whose sidecar reaches this process from a container.
 import { createServer } from "node:http2";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { Registry } from "../service.js";
+import { _setProcessStorage, chooseStorage, DirectoryBuckets } from "../storage.js";
+import { DirectoryStorageEndpoint } from "./storageEndpoint.js";
 import { renderSpec } from "../spec.js";
 import { discoveryRoutes } from "./discovery.js";
 import { eventSourcedRoutes } from "./eventSourced.js";
@@ -12,6 +15,13 @@ import { workflowRoutes } from "./workflow.js";
 import { statelessRoutes } from "./stateless.js";
 import { agentRoutes } from "./agent.js";
 import { httpRoutes } from "./http.js";
+import { mcpRoutes } from "./mcp.js";
+/** The registry with the directory store's endpoint, which serves the URLs that store signs. */
+function withStorageEndpoint(registry) {
+    const cls = DirectoryStorageEndpoint;
+    const endpoint = Object.freeze({ id: cls.name, cls, prefix: cls.prefix, acl: cls.acl, routes: new Map(Object.entries(cls.routes)) });
+    return new Registry(registry.components, new Map([...registry.endpoints, [endpoint.id, endpoint]]));
+}
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0", "::"]);
 export class Server {
     #context;
@@ -39,6 +49,14 @@ export class Server {
         const port = this.#options.port ?? Number(process.env.ANKKA_PROCESS_PORT ?? 9010);
         if (!Number.isInteger(port) || port < 0 || port > 65535)
             throw new Error(`not a port: ${String(port)}`);
+        // The service's buckets: the store given, or the one the environment chooses. A directory store's
+        // URLs are answered by an endpoint this process declares at /_ankka/storage.
+        const given = this.#options.storage;
+        const chosen = given ? { backend: "given", buckets: given } : chooseStorage(process.env, { ...(this.#options.serviceDirectory ? { serviceDirectory: this.#options.serviceDirectory } : {}) });
+        _setProcessStorage(chosen.buckets);
+        const registry = chosen.buckets instanceof DirectoryBuckets ? withStorageEndpoint(this.#context.registry) : this.#context.registry;
+        this.#context = { ...this.#context, registry, storage: chosen.buckets };
+        this.#context.log(`ankka: object storage is ${chosen.backend}${chosen.buckets instanceof DirectoryBuckets ? ` at ${chosen.buckets.root}` : ""}`);
         const handler = connectNodeAdapter({
             routes: (router) => {
                 discoveryRoutes(router, () => renderSpec(this.#context.registry), this.#context.log);
@@ -48,6 +66,7 @@ export class Server {
                 statelessRoutes(router, this.#context);
                 agentRoutes(router, this.#context);
                 httpRoutes(router, this.#context);
+                mcpRoutes(router, this.#context);
             },
             shutdownSignal: this.#shutdown.signal,
             readMaxBytes: this.#options.readMaxBytes ?? 64 * 1024 * 1024,

package/dist/server/stateless.js

@@ -15,6 +15,7 @@ import { JSON_CONTENT } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { decodePayload, encodePayload } from "./payloads.js";
 import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+import { standingFromProto } from "../standing.js";
 function messageOf(e) {
     return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
 }
@@ -33,7 +34,7 @@ async function handleKeyedView(req, sourceId, ctx) {
     const view = new registered.cls();
     try {
         const client = ctx.client.withMetadata(metadata);
-        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec));
+        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec), standingFromProto(req.standing));
         const effect = (req.deleted
             ? source.deleted
                 ? await source.deleted(view)
@@ -63,7 +64,7 @@ export async function handleView(req, ctx) {
     const view = new registered.cls();
     try {
         const row = req.row ? decodePayload(registered.rowCodec, req.row) : null;
-        view._bind(row, metadata, ctx.client.withMetadata(metadata));
+        view._bind(row, metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
         const effect = req.deleted ? await view.onDelete() : await view.onChange(decodePayload(registered.eventCodec, req.event));
         switch (effect.kind) {
             case "update-row":
@@ -102,7 +103,7 @@ function produceAll(request, messages) {
 }
 async function graphEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     switch (effect.kind) {
         case "publish":
@@ -121,7 +122,7 @@ async function graphEffect(registered, req, metadata, ctx) {
 }
 async function consumerEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     const outCodec = () => {
         if (!registered.outCodec)

package/dist/server/storageEndpoint.d.ts

@@ -0,0 +1,14 @@
+import { Endpoint } from "../endpoint.ts";
+import { Acl, RawReply, type RouteRef } from "../routes.ts";
+type Params = Readonly<Record<string, string>>;
+export declare class DirectoryStorageEndpoint extends Endpoint {
+    #private;
+    static readonly prefix = "/_ankka/storage";
+    static readonly acl: Acl;
+    /** @internal The SDK's own endpoint under `/_ankka`, which registration admits. */
+    static readonly _sdkReserved = true;
+    static readonly routes: Readonly<Record<string, RouteRef<DirectoryStorageEndpoint, any, any, any>>>;
+    read(params: Params, depth: number): Promise<RawReply>;
+    keep(params: Params, depth: number, body: Uint8Array): Promise<RawReply>;
+}
+export {};

package/dist/server/storageEndpoint.js

@@ -0,0 +1,82 @@
+// What a TypeScript service on a developer's machine serves at `/_ankka/storage/<bucket>/<name>` while its
+// store is a directory (feature 055, research R12): the signed URLs and public addresses that store
+// makes, answered through the sidecar like any route, so a browser reads and keeps through them as it
+// would through an object store's. The runtime's `DirectoryStorageEndpoint` says the same in Scala.
+//
+// The token is the whole of the authority, as a signature is on an object store: a `GET` reads with a
+// token for `read`, or with none on a public bucket; a `PUT` keeps with a token for `keep`. Anything
+// else is `403`, and an object not there `404`. The sidecar matches a route by whole segments and an
+// object's name holds slashes, so one route is declared per depth, up to `MAX_ADDRESS_SEGMENTS`; a
+// deeper name travels as one segment with its slashes encoded.
+import { binaryCodecs } from "../codec.js";
+import { Endpoint } from "../endpoint.js";
+import { Acl, get, HttpProblem, put, RawReply } from "../routes.js";
+import { DirectoryBuckets, MAX_ADDRESS_SEGMENTS, STORAGE_PATH } from "../storage.js";
+/** A segment as the sidecar forwards it, encoded; one that is not valid encoding is taken as it is. */
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/** The bucket's segment and the object's name a request's path parameters spell. */
+function addressed(params, depth) {
+    const parts = [];
+    for (let i = 1; i <= depth; i++)
+        parts.push(decoded(params[`n${i}`] ?? ""));
+    return { segment: decoded(params.bucket ?? ""), objectName: parts.join("/") };
+}
+const NOWHERE = "no object at this address";
+const UNSIGNED = "this address is not signed for that, or its signature has expired";
+export class DirectoryStorageEndpoint extends Endpoint {
+    static prefix = STORAGE_PATH;
+    static acl = Acl.allowAll;
+    /** @internal The SDK's own endpoint under `/_ankka`, which registration admits. */
+    static _sdkReserved = true;
+    static routes = (() => {
+        const table = {};
+        for (let depth = 1; depth <= MAX_ADDRESS_SEGMENTS; depth++) {
+            const template = "/{bucket}" + Array.from({ length: depth }, (_, i) => `/{n${i + 1}}`).join("");
+            table[`read${depth}`] = get(template, binaryCodecs.bytes, (ep, req) => ep.read(req.params, depth));
+            table[`keep${depth}`] = put(template, binaryCodecs.bytes, binaryCodecs.bytes, (ep, req, body) => ep.keep(req.params, depth, body));
+        }
+        return Object.freeze(table);
+    })();
+    #store(segment) {
+        const store = this.storage;
+        if (!(store instanceof DirectoryBuckets))
+            throw new HttpProblem(404, NOWHERE);
+        const found = store.bySegment(segment);
+        if (!found)
+            throw new HttpProblem(404, NOWHERE);
+        return { store, bucket: found.bucket, segment: found.segment };
+    }
+    #signedFor(store, segment, objectName, access) {
+        const q = this.request.query;
+        const expires = Number(q.get("expires") ?? "");
+        const token = q.get("token");
+        return q.get("access") === access && token !== null && Number.isInteger(expires) && store.admits(segment, objectName, access, expires, token);
+    }
+    async read(params, depth) {
+        const { segment, objectName } = addressed(params, depth);
+        const { store, bucket } = this.#store(segment);
+        const open = bucket.exposure === "public" && bucket.name !== undefined;
+        if (!open && !this.#signedFor(store, segment, objectName, "read"))
+            throw new HttpProblem(403, UNSIGNED);
+        const object = await bucket.get(objectName);
+        if (!object)
+            throw new HttpProblem(404, `no object '${objectName}'`);
+        return new RawReply(200, object.contentType, await object.bytes());
+    }
+    async keep(params, depth, body) {
+        const { segment, objectName } = addressed(params, depth);
+        const { store, bucket } = this.#store(segment);
+        if (!this.#signedFor(store, segment, objectName, "keep"))
+            throw new HttpProblem(403, UNSIGNED);
+        const contentType = this.request.headers.get("content-type") ?? "application/octet-stream";
+        await bucket.put(objectName, body, { contentType });
+        return new RawReply(200, "text/plain; charset=utf-8", new Uint8Array());
+    }
+}

package/dist/service.d.ts

@@ -13,6 +13,7 @@ import { Agent, type AgentClass } from "./agent.ts";
 import { type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
 import { Endpoint, type EndpointClass } from "./endpoint.ts";
+import { McpEndpoint, type McpEndpointClass, type RegisteredMcpEndpoint } from "./mcp-endpoint.ts";
 import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
 import type { RouteRef, Acl } from "./routes.ts";
 import { ComponentClient } from "./client.ts";
@@ -28,6 +29,8 @@ export interface RegisteredEventSourced {
     readonly eventCodec: Codec<any>;
     readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
     readonly snapshotEvery: number;
+    /** Declared replicated (1.19). */
+    readonly replicated: boolean;
 }
 export interface RegisteredKeyValue {
     readonly kind: "key-value";
@@ -58,6 +61,8 @@ export type Source = {
     readonly contract?: Contract;
     /** The declared broker the topic is on; absent is the installation's. */
     readonly broker?: string;
+    /** Another project's topic: the project whose topic it is (1.15). */
+    readonly project?: string;
     /** Partitions handled at once, each in order. */
     readonly parallel?: boolean;
 };
@@ -102,6 +107,8 @@ export interface RegisteredConsumer {
     /** A graph consumer: its handlers return elements, each published as a delta under its element key. */
     readonly graph: boolean;
     readonly version: number | undefined;
+    /** Given a replicated entity's mirrored changes too (1.19). */
+    readonly mirroredChanges: boolean;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";
@@ -144,7 +151,10 @@ export interface RegisteredEndpoint {
 export declare class Registry {
     readonly components: ReadonlyMap<string, RegisteredComponent>;
     readonly endpoints: ReadonlyMap<string, RegisteredEndpoint>;
-    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>);
+    /** The MCP endpoints (1.20), by id, their references resolved. */
+    readonly mcpEndpoints: ReadonlyMap<string, RegisteredMcpEndpoint>;
+    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>, mcpEndpoints?: ReadonlyMap<string, RegisteredMcpEndpoint>);
+    mcpEndpoint(id: string): RegisteredMcpEndpoint | undefined;
     component(id: string): RegisteredComponent | undefined;
     /** The component `id` when it is of `kind`. */
     of<K extends RegisteredComponent["kind"]>(kind: K, id: string): Extract<RegisteredComponent, {
@@ -179,6 +189,7 @@ export declare class ServiceBuilder {
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;
     register<C extends Agent>(cls: AgentClass<C>): this;
     register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;
+    register<C extends McpEndpoint>(cls: McpEndpointClass<C>): this;
     register<C extends Endpoint>(cls: EndpointClass<C>): this;
     /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
     validate(): Registry;

package/dist/service.js

@@ -18,7 +18,8 @@ import { Agent } from "./agent.js";
 import { serverProblems, TOOL_PREFIX } from "./mcp.js";
 import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
 import { Endpoint } from "./endpoint.js";
-import { isAcl } from "./routes.js";
+import { McpEndpoint, registerMcpEndpoint } from "./mcp-endpoint.js";
+import { isAcl, isEndpointAcl } from "./routes.js";
 import { ComponentClient } from "./client.js";
 import { Server } from "./server/server.js";
 import { renderSpec } from "./spec.js";
@@ -26,11 +27,17 @@ import { renderSpec } from "./spec.js";
 export class Registry {
     components;
     endpoints;
-    constructor(components, endpoints) {
+    /** The MCP endpoints (1.20), by id, their references resolved. */
+    mcpEndpoints;
+    constructor(components, endpoints, mcpEndpoints = new Map()) {
         this.components = components;
         this.endpoints = endpoints;
+        this.mcpEndpoints = mcpEndpoints;
         Object.freeze(this);
     }
+    mcpEndpoint(id) {
+        return this.mcpEndpoints.get(id);
+    }
     component(id) {
         return this.components.get(id);
     }
@@ -83,6 +90,7 @@ export class ServiceBuilder {
         const components = new Map();
         const endpoints = new Map();
         const prefixes = new Map();
+        const mcpClasses = [];
         const add = (r, cls) => {
             if (!r)
                 return;
@@ -112,6 +120,9 @@ export class ServiceBuilder {
                 add(registerAgent(cls, problems), cls);
             else if (extendsBase(cls, AutonomousAgent))
                 add(registerAutonomousAgent(cls, problems), cls);
+            // Before Endpoint: an MCP endpoint is one, served by the platform rather than by routes.
+            else if (extendsBase(cls, McpEndpoint))
+                mcpClasses.push(cls);
             else if (extendsBase(cls, Endpoint)) {
                 const ep = cls;
                 if (typeof ep.prefix === "string") {
@@ -129,12 +140,35 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent, Endpoint or McpEndpoint`);
+            }
+        }
+        // MCP endpoints last: their references name the components and endpoints registered above.
+        const mcpEndpoints = new Map();
+        const mcpPaths = new Map();
+        for (const cls of mcpClasses) {
+            const r = registerMcpEndpoint(cls, components, endpoints, problems);
+            if (!r)
+                continue;
+            const other = mcpPaths.get(r.path);
+            if (other)
+                problems.push(`MCP endpoints ${other} and ${r.id} share the path ${r.path}`);
+            mcpPaths.set(r.path, r.id);
+            for (const e of endpoints.values()) {
+                for (const route of e.routes.values()) {
+                    const full = route.template === "/" ? e.prefix : e.prefix === "/" ? route.template : `${e.prefix}${route.template}`;
+                    if (full === r.path)
+                        problems.push(`${r.id}: its path ${r.path} is also the route ${route.method} ${full} of ${e.id}`);
+                }
             }
+            if (mcpEndpoints.has(r.id))
+                problems.push(`two MCP endpoints are named ${r.id}`);
+            else
+                mcpEndpoints.set(r.id, r);
         }
         if (problems.length > 0)
             throw new RegistrationError(problems);
-        return new Registry(components, endpoints);
+        return new Registry(components, endpoints, mcpEndpoints);
     }
     /** The discovery `Spec` for what is registered, without listening. */
     spec() {
@@ -191,7 +225,18 @@ function registerEventSourced(cls, problems) {
     const handlers = collectHandlers(cls.handlers, "handlers", ["command", "query"], fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "event-sourced", id: cls.componentId, cls, stateCodec: codecFor(cls.state), eventCodec: codecFor(cls.events), handlers, snapshotEvery });
+    if (cls.replicated !== undefined && typeof cls.replicated !== "boolean")
+        fail(`replicated must be true or false, not ${String(cls.replicated)}`);
+    return Object.freeze({
+        kind: "event-sourced",
+        id: cls.componentId,
+        cls,
+        stateCodec: codecFor(cls.state),
+        eventCodec: codecFor(cls.events),
+        handlers,
+        snapshotEvery,
+        replicated: cls.replicated === true,
+    });
 }
 function registerKeyValue(cls, problems) {
     const { fail, ok } = checker(cls, problems);
@@ -261,6 +306,12 @@ function topicProblems(cls, consumer, fail) {
     if ((cls.contract !== undefined || cls.broker !== undefined || cls.parallel !== undefined) && !readsTopic) {
         fail("declares a contract, a broker or parallel, which apply to a topic; it reads a component");
     }
+    if (cls.project !== undefined && (typeof cls.project !== "string" || cls.project.trim() === ""))
+        fail("project must be the id of the project whose topic this is");
+    if (cls.project !== undefined && !readsTopic)
+        fail("names a project, which applies to a topic; it reads a component");
+    if (cls.project !== undefined && cls.broker !== undefined)
+        fail("names a project and a broker; another project's topic is on the installation's broker");
 }
 function sourceOf(cls, fail, consumer) {
     const hasSource = cls.source !== undefined;
@@ -281,6 +332,7 @@ function sourceOf(cls, fail, consumer) {
             ...(cls.contract instanceof Contract ? { contract: cls.contract } : {}),
             ...(typeof cls.broker === "string" ? { broker: cls.broker } : {}),
             ...(cls.parallel === true ? { parallel: true } : {}),
+            ...(typeof cls.project === "string" ? { project: cls.project } : {}),
         };
     }
     const src = cls.source;
@@ -413,6 +465,7 @@ function registerConsumer(cls, problems) {
         produces,
         graph: false,
         version: cls.version,
+        mirroredChanges: cls.mirroredChanges === true,
     });
 }
 /**
@@ -436,10 +489,15 @@ function publicationOf(declared, fail) {
         fail("producesTo.contract must be a Contract: Contract.fromFile(path, name)");
     if (p.broker !== undefined && (typeof p.broker !== "string" || p.broker.trim() === ""))
         fail("producesTo.broker must be the name of a broker the project declares");
+    if (p.project !== undefined && (typeof p.project !== "string" || p.project.trim() === ""))
+        fail("producesTo.project must be the id of the project whose topic this is");
+    if (p.project !== undefined && p.broker !== undefined)
+        fail("producesTo names a project and a broker; another project's topic is on the installation's broker");
     return {
         topic: p.topic,
         ...(p.contract instanceof Contract ? { contract: p.contract } : {}),
         ...(typeof p.broker === "string" ? { broker: p.broker } : {}),
+        ...(typeof p.project === "string" ? { project: p.project } : {}),
     };
 }
 /** A graph consumer is a consumer to discovery and to the runtime: one that produces deltas to its topic. */
@@ -465,6 +523,7 @@ function registerGraphConsumer(cls, problems) {
         produces: undefined,
         graph: true,
         version: cls.version,
+        mirroredChanges: cls.mirroredChanges === true,
     });
 }
 function registerTimedAction(cls, problems) {
@@ -610,9 +669,16 @@ function registerEndpoint(cls, problems) {
     if (typeof cls.prefix !== "string" || !cls.prefix.startsWith("/") || (cls.prefix.length > 1 && cls.prefix.endsWith("/"))) {
         fail(`needs a static prefix starting with "/" and not ending with one, not ${JSON.stringify(cls.prefix)}`);
     }
+    else if ((cls.prefix === "/_ankka" || cls.prefix.startsWith("/_ankka/")) && cls._sdkReserved !== true) {
+        // The SDK's own directory-store endpoint is the one exception, as the sidecar admits it alone.
+        fail(`prefix '${cls.prefix}' is under /_ankka, which is the runtime's`);
+    }
     if (!isAcl(cls.acl)) {
         fail(`needs a static acl — Acl.allowAll, Acl.denyAll, Acl.authenticated or Acl.allowCallers(...). An unstated access rule is a decision nobody made`);
     }
+    else if (!isEndpointAcl(cls.acl)) {
+        fail("admits client keys or states Acl.anyOf, which only an MCP endpoint can: extend McpEndpoint");
+    }
     const routes = new Map();
     const seen = new Map();
     if (typeof cls.routes !== "object" || cls.routes === null) {
@@ -632,6 +698,8 @@ function registerEndpoint(cls, problems) {
             seen.set(key, id);
             if (r.acl !== undefined && !isAcl(r.acl))
                 fail(`routes.${id}: unknown acl ${JSON.stringify(r.acl)}`);
+            else if (r.acl !== undefined && !isEndpointAcl(r.acl))
+                fail(`routes.${id} admits client keys or states Acl.anyOf, which only an MCP endpoint can`);
             routes.set(id, r);
         }
     }

package/dist/sigv4.d.ts

@@ -0,0 +1,47 @@
+/** A key pair. Never printed whole: `toString` hides the secret. */
+export declare class Credentials {
+    #private;
+    readonly accessKey: string;
+    constructor(accessKey: string, secretKey: string);
+    /** @internal */
+    get _secretKey(): string;
+    toString(): string;
+    toJSON(): string;
+}
+export declare const ALGORITHM = "AWS4-HMAC-SHA256";
+/** The payload hash a put sends so its body is streamed once and never hashed. */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+export declare function sha256Hex(data: Uint8Array | string): string;
+export declare function hmac(key: Uint8Array | string, data: string): Buffer;
+/** The hash of an empty payload. */
+export declare const EMPTY_PAYLOAD: string;
+/** RFC 3986 encoding as SigV4 states it: unreserved characters kept, everything else `%XX` of its UTF-8 bytes. */
+export declare function encode(text: string, encodeSlash: boolean): string;
+/** One request: the endpoint's scheme and authority, a decoded path and decoded query pairs. */
+export declare class SignedRequest {
+    readonly method: string;
+    readonly endpoint: URL;
+    readonly path: string;
+    readonly query: readonly (readonly [string, string])[];
+    constructor(method: string, endpoint: URL | string, path: string, query?: readonly (readonly [string, string])[]);
+    /** The `host` header's value: the host, with the port when the endpoint names one. */
+    get host(): string;
+    get canonicalPath(): string;
+    get canonicalQuery(): string;
+    /** The URL the request is sent to: the same encoding as the one signed. */
+    get url(): string;
+    withQuery(more: readonly (readonly [string, string])[]): SignedRequest;
+}
+/** `20150830T123600Z`. */
+export declare function amzDate(now: Date): string;
+/**
+ * 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 declare function sign(request: SignedRequest, headers: Readonly<Record<string, string>>, payloadHash: string, credentials: Credentials, region: string, service: string, now: Date): {
+    "x-amz-date": string;
+    Authorization: string;
+};
+/** A URL anyone may use, until it expires, for `request`'s method on its path. Signs `host` alone. */
+export declare function presign(request: SignedRequest, credentials: Credentials, region: string, service: string, expiresSeconds: number, now: Date): string;

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;
+}