@rikalabs/akter 0.1.0-alpha.0

package/dist/serve/api.js

@@ -0,0 +1,403 @@
+import { Schema, SchemaAST } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/http-api";
+import { declaredStatus, } from "../actor/served.js";
+import { Credential } from "./auth.js";
+import { ASSERTION_HEADER } from "./assertion/binding.js";
+import { SUBPROTOCOL } from "../protocol/frames.js";
+import { ContentRef } from "../identity/content.js";
+import { Defect, envelope } from "../protocol/wire.js";
+const COMMAND_ERRORS = {
+    400: ["InvalidCommandId", "InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    404: ["NotCreated", "InvalidInput"],
+    409: ["CommandConflict"],
+    410: ["CommandExpired"],
+    413: ["InvalidInput"],
+    415: ["InvalidInput"],
+    429: ["MailboxFull"],
+    503: ["ActorUnavailable", "RunnerAtCapacity"],
+    504: ["Timeout"],
+};
+const QUERY_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    404: ["InvalidInput"],
+    413: ["InvalidInput"],
+    415: ["InvalidInput"],
+    503: ["ActorUnavailable"],
+    504: ["Timeout"],
+};
+const errorSchemas = (errors, prefix) => Object.entries(errors).map(([status, tags]) => envelope({ tags, identifier: `${prefix}ActorError${status}` }).annotate({
+    httpApiStatus: Number(status),
+}));
+/** A refused upgrade; once upgraded, a session ends with an `end` message instead. */
+const UPGRADE_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["InvalidInput"],
+    404: ["InvalidInput"],
+    413: ["InvalidInput"],
+    503: ["RunnerAtCapacity"],
+};
+/** A refused feed; a feed that ends later sends an `end` message instead. */
+const FEED_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    404: ["NotCreated", "InvalidInput"],
+    503: ["ActorUnavailable", "RunnerAtCapacity"],
+};
+/** A refused content operation; a download a sweep cut short ends its body early instead. */
+const CONTENT_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    404: ["InvalidInput"],
+    413: ["InvalidInput"],
+    503: ["ActorUnavailable"],
+};
+const contentErrors = errorSchemas(CONTENT_ERRORS, "Content");
+const commandErrors = errorSchemas(COMMAND_ERRORS, "Command");
+const feedErrors = errorSchemas(FEED_ERRORS, "Feed");
+const upgradeErrors = errorSchemas(UPGRADE_ERRORS, "Upgrade");
+const queryErrors = errorSchemas(QUERY_ERRORS, "Query");
+const defect = Defect.annotate({ httpApiStatus: 500 });
+const ProtocolInfo = Schema.Struct({
+    protocol: Schema.Literal(1),
+    retryWindowMs: Schema.Int,
+    now: Schema.Int,
+}).annotate({ identifier: "Protocol" });
+const ReadinessReason = Schema.Literals([
+    "draining",
+    "drained",
+    "storage",
+    "routing",
+    "peering",
+    "unregistered",
+]);
+const Ready = Schema.Struct({ ready: Schema.Literal(true) }).annotate({ identifier: "Ready" });
+const NotReady = Schema.Struct({ ready: Schema.Literal(false), reason: ReadinessReason }).annotate({
+    identifier: "NotReady",
+    httpApiStatus: 503,
+});
+/** The body of `POST /command-ids`. */
+const MintedCommandId = Schema.Struct({ commandId: Schema.String }).annotate({
+    identifier: "MintedCommandId",
+});
+const IdempotencyKey = Schema.String.annotate({
+    description: "The command id, v1.<issuedAtMs>.<expiresAtMs>.<uuidv4>; retries send the same one.",
+});
+/** The path of a served member below the base path, as the router and the OpenAPI document both spell it. */
+export const memberPath = ({ definition, member }) => definition.key === "singleton"
+    ? `/actors/${definition.name}/${member.tag}`
+    : `/actors/${definition.name}/:id/${member.tag}`;
+const endpoint = (basePath, definition, member) => {
+    const isQuery = member.kind === "query";
+    const path = `${basePath}${memberPath({ definition, member })}`;
+    const declared = member.errors.map((error) => SchemaAST.resolveAt("httpApiStatus")(error.ast) === undefined
+        ? error.annotate({ httpApiStatus: declaredStatus(error) })
+        : error);
+    return HttpApiEndpoint.post(member.tag, path, {
+        params: definition.key === "singleton" ? undefined : { id: Schema.String },
+        headers: isQuery ? undefined : { "idempotency-key": IdempotencyKey },
+        payload: SchemaAST.isVoid(member.input.ast) ? undefined : member.input,
+        success: SchemaAST.isVoid(member.output.ast) ? HttpApiSchema.NoContent : member.output,
+        error: [...declared, ...(isQuery ? queryErrors : commandErrors), defect],
+    });
+};
+const frameSchemaName = (definition, connection, part) => `${definition.name}.${connection.tag}.${part}`;
+/** The schemas a connection's messages carry: `hello` params, and frames each way. */
+const frameParts = (connection) => ({
+    params: connection.params,
+    server: connection.server,
+    client: connection.client,
+});
+/**
+ * OpenAPI can't describe a socket's message flow, so a connection is an upgrade
+ * operation that names its frame schemas; the envelope is the served protocol's.
+ */
+const connectionEndpoint = (basePath, definition, connection) => HttpApiEndpoint.get(connection.tag, `${basePath}${memberPath({ definition, member: connection })}`, {
+    params: definition.key === "singleton" ? undefined : { id: Schema.String },
+    error: [...upgradeErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => {
+    const { 204: _, ...refusals } = operation.responses ?? {};
+    return {
+        ...operation,
+        responses: {
+            101: { description: `WebSocket upgrade with subprotocol ${SUBPROTOCOL}` },
+            ...refusals,
+        },
+        "x-durable-transport": "websocket",
+        "x-durable-subprotocol": SUBPROTOCOL,
+        "x-durable-frames": Object.fromEntries(Object.keys(frameParts(connection)).map((part) => [
+            part,
+            { $ref: `#/components/schemas/${frameSchemaName(definition, connection, part)}` },
+        ])),
+    };
+});
+/** An event feed is served over SSE: one message per event, its cursor as the `id`. */
+const feedEndpoint = (basePath, definition) => HttpApiEndpoint.get("events", `${basePath}${memberPath({ definition, member: { tag: "events" } })}`, {
+    params: definition.key === "singleton" ? undefined : { id: Schema.String },
+    query: {
+        event: Schema.Array(Schema.Literals(definition.feeds)),
+        after: Schema.optionalKey(Schema.String),
+    },
+    error: [...feedErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => {
+    const { 204: _, ...refusals } = operation.responses ?? {};
+    return {
+        ...operation,
+        responses: {
+            200: {
+                description: "Server-sent events: `id` is the event cursor, `event` its tag; `Last-Event-ID` resumes after it",
+                content: { "text/event-stream": { schema: { type: "string" } } },
+            },
+            ...refusals,
+            410: { description: "RetentionGap: events after the cursor were pruned" },
+        },
+        "x-durable-transport": "sse",
+    };
+});
+/** A refused subscription; one that ends later sends an `end` message instead. */
+const STREAM_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["InvalidInput"],
+    404: ["InvalidInput"],
+    413: ["InvalidInput"],
+    415: ["InvalidInput"],
+};
+const streamErrors = errorSchemas(STREAM_ERRORS, "Stream");
+/** A stream is served over SSE: `element` messages, then one `end`; OpenAPI names its element schema. */
+const streamEndpoint = (basePath, definition, member) => HttpApiEndpoint.post(member.tag, `${basePath}${memberPath({ definition, member })}`, {
+    params: definition.key === "singleton" ? undefined : { id: Schema.String },
+    payload: SchemaAST.isVoid(member.input.ast) ? undefined : member.input,
+    error: [...streamErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => {
+    const { 204: _, ...refusals } = operation.responses ?? {};
+    return {
+        ...operation,
+        responses: {
+            200: {
+                description: "Server-sent events: `element` with each encoded output, then `end` with null or the error that ended the stream",
+                content: { "text/event-stream": { schema: { type: "string" } } },
+            },
+            ...refusals,
+        },
+        "x-durable-transport": "sse",
+        "x-durable-element": {
+            $ref: `#/components/schemas/${definition.name}.${member.tag}.element`,
+        },
+    };
+});
+/** A refused watch; one that ends later sends an `end` message instead. */
+const WATCH_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    404: ["NotCreated", "InvalidInput"],
+    413: ["InvalidInput"],
+    415: ["InvalidInput"],
+    503: ["ActorUnavailable", "RunnerAtCapacity"],
+};
+const watchErrors = errorSchemas(WATCH_ERRORS, "Watch");
+const watchEndpoint = (basePath, definition, member) => HttpApiEndpoint.post(`${member.tag}.watch`, `${basePath}${memberPath({ definition, member })}/watch`, {
+    params: definition.key === "singleton" ? undefined : { id: Schema.String },
+    payload: SchemaAST.isVoid(member.input.ast) ? undefined : member.input,
+    error: [...watchErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => {
+    const { 204: _, ...refusals } = operation.responses ?? {};
+    return {
+        ...operation,
+        responses: {
+            200: {
+                description: "Server-sent events: `result` with each encoded output, whose `id` is the commit version the rerun waited for when there was one, then `end` with the error that ended the watch. A watch is state, not history: intermediate results are skipped, and a reconnect sends the current result first",
+                content: { "text/event-stream": { schema: { type: "string" } } },
+            },
+            ...refusals,
+        },
+        "x-durable-transport": "sse",
+        "x-durable-element": {
+            $ref: `#/components/schemas/${definition.name}.${member.tag}.element`,
+        },
+    };
+});
+/** A refused fleet subscription; one that ends later sends an `end` message instead. */
+const FLEET_ERRORS = {
+    400: ["InvalidInput"],
+    401: ["Unauthorized"],
+    403: ["Unauthorized", "InvalidInput"],
+    503: ["ActorUnavailable", "RunnerAtCapacity"],
+};
+const fleetErrors = errorSchemas(FLEET_ERRORS, "Fleet");
+/**
+ * A fleet view is served over SSE for the caller's tenant: equality filters on
+ * its group keys and `limit` in the query, then `result` pages of
+ * `{ asOf, stale, rows }`.
+ */
+const fleetEndpoint = (basePath, view) => HttpApiEndpoint.get(`fleet.${view.name}`, `${basePath}/fleet/${view.name}`, {
+    query: {
+        ...Object.fromEntries(view.groupBy.map((key) => [key, Schema.optionalKey(Schema.String)])),
+        limit: Schema.optionalKey(Schema.String),
+    },
+    error: [...fleetErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => {
+    const { 204: _, ...refusals } = operation.responses ?? {};
+    return {
+        ...operation,
+        responses: {
+            200: {
+                description: "Server-sent events: `result` with `{ asOf, stale, rows }`, the caller's tenant's groups in group-key order, first at once and again whenever the view changed; an identical page is not sent. `end` carries the error that ended the subscription. A fleet subscription is state, not history, so there is no resume",
+                content: { "text/event-stream": { schema: { type: "string" } } },
+            },
+            ...refusals,
+        },
+        "x-durable-transport": "sse",
+    };
+});
+const frameSchemas = (definition, connection) => Object.entries(frameParts(connection)).map(([part, schema]) => schema.annotate({ identifier: frameSchemaName(definition, connection, part) }));
+const ContentRefSchema = ContentRef.annotate({ identifier: "ContentRef" });
+const OCTETS = { "application/octet-stream": { schema: { type: "string", format: "binary" } } };
+/** The path segment an actor's content routes are served under, so no member may take it. */
+export const CONTENT_ROUTE = "content";
+const contentPath = (basePath, definition) => `${basePath}${memberPath({ definition, member: { tag: CONTENT_ROUTE } })}/:blob/:name`;
+const contentParams = (definition) => {
+    const entry = { blob: Schema.Literals(definition.contents), name: Schema.String };
+    return definition.key === "singleton" ? entry : { id: Schema.String, ...entry };
+};
+/** Downloads stream the entry's bytes; grants answer a fresh `ContentRef`. */
+const contentEndpoints = (basePath, definition) => [
+    HttpApiEndpoint.get(CONTENT_ROUTE, contentPath(basePath, definition), {
+        params: contentParams(definition),
+        error: [...contentErrors, defect],
+    }).annotate(OpenApi.Transform, (operation) => {
+        const { 204: _, ...refusals } = operation.responses ?? {};
+        return {
+            ...operation,
+            responses: {
+                200: { description: "The referenced content's bytes", content: OCTETS },
+                ...refusals,
+            },
+        };
+    }),
+    HttpApiEndpoint.post(`${CONTENT_ROUTE}.grant`, `${contentPath(basePath, definition)}/grant`, {
+        params: contentParams(definition),
+        success: ContentRefSchema,
+        error: [...contentErrors, defect],
+    }),
+];
+const uploadEndpoint = (basePath) => HttpApiEndpoint.post("uploadContent", `${basePath}/content`, {
+    success: ContentRefSchema,
+    error: [...contentErrors, defect],
+}).annotate(OpenApi.Transform, (operation) => ({
+    ...operation,
+    requestBody: { required: true, content: OCTETS },
+}));
+/** Protocol routes live in their own group. */
+const PROTOCOL_GROUP = "durable";
+/** The operation id of the route that mints command ids. */
+export const MINT_OPERATION = `${PROTOCOL_GROUP}.commandIds`;
+/** Operation ids of the protocol routes; no served member may reuse one. */
+export const PROTOCOL_OPERATIONS = new Set([
+    `${PROTOCOL_GROUP}.protocol`,
+    MINT_OPERATION,
+    `${PROTOCOL_GROUP}.uploadContent`,
+    `${PROTOCOL_GROUP}.ready`,
+]);
+/** Paths of the protocol routes under the base path; `openapi.path` may not take one. */
+export const PROTOCOL_PATHS = new Set([
+    "/protocol",
+    "/command-ids",
+    "/ready",
+    "/content",
+]);
+/** Protocol operations that take no credentials. */
+const UNAUTHENTICATED = new Set([
+    `${PROTOCOL_GROUP}.protocol`,
+    `${PROTOCOL_GROUP}.ready`,
+]);
+/** The `HttpApi` of the served actors: the protocol group, then one group per actor with members, connections, feed, content, and streams. */
+export const buildServedApi = ({ definitions, fleet, basePath, content }) => {
+    const groups = [
+        HttpApiGroup.make(PROTOCOL_GROUP).add(HttpApiEndpoint.get("protocol", `${basePath}/protocol`, {
+            success: ProtocolInfo,
+        }), HttpApiEndpoint.get("ready", `${basePath}/ready`, {
+            success: Ready,
+            error: NotReady,
+        }), HttpApiEndpoint.post("commandIds", `${basePath}/command-ids`, {
+            success: MintedCommandId,
+            error: [
+                ...errorSchemas({ 401: ["Unauthorized"], 503: ["ActorUnavailable"] }, "Mint"),
+                defect,
+            ],
+        }), ...(content ? [uploadEndpoint(basePath)] : []), ...fleet.map((view) => fleetEndpoint(basePath, view))),
+    ];
+    for (const definition of definitions) {
+        const endpoints = [
+            ...definition.members.map((member) => endpoint(basePath, definition, member)),
+            ...definition.connections.map((connection) => connectionEndpoint(basePath, definition, connection)),
+            ...(definition.feeds.length > 0 ? [feedEndpoint(basePath, definition)] : []),
+            ...(content && definition.contents.length > 0 ? contentEndpoints(basePath, definition) : []),
+            ...definition.streams.map((member) => streamEndpoint(basePath, definition, member)),
+            ...definition.members
+                .filter((member) => member.watch)
+                .map((member) => watchEndpoint(basePath, definition, member)),
+        ];
+        if (endpoints.length > 0)
+            groups.push(HttpApiGroup.make(definition.name).add(endpoints[0], ...endpoints.slice(1)));
+    }
+    const api = HttpApi.make("akter")
+        .add(groups[0], ...groups.slice(1))
+        .annotate(HttpApi.AdditionalSchemas, definitions.flatMap((definition) => [
+        ...definition.connections.flatMap((connection) => frameSchemas(definition, connection)),
+        ...[...definition.streams, ...definition.members.filter((member) => member.watch)].map((member) => member.output.annotate({ identifier: `${definition.name}.${member.tag}.element` })),
+    ]));
+    return api;
+};
+/** The OpenAPI security scheme a credential is documented as; a provider has at most one per scheme. */
+export const schemeName = Credential.$match({
+    Bearer: () => "bearer",
+    Jwt: () => "bearer",
+    Cookie: () => "cookie",
+    Assertion: () => "assertion",
+});
+const securityScheme = Credential.$match({
+    Bearer: () => ({ type: "http", scheme: "bearer" }),
+    Jwt: () => ({ type: "http", scheme: "bearer", bearerFormat: "JWT" }),
+    Cookie: ({ name }) => ({ type: "apiKey", in: "cookie", name }),
+    Assertion: () => ({ type: "apiKey", in: "header", name: ASSERTION_HEADER }),
+});
+/**
+ * The OpenAPI 3.1 document of `api`. Every authenticated operation lists the
+ * provider's credentials as alternatives, since any one of them authenticates.
+ */
+export const openApiDocument = ({ api, auth, title, version }) => {
+    const spec = OpenApi.fromApi(api);
+    const security = auth.credentials.map((credential) => ({
+        [schemeName(credential)]: [],
+    }));
+    const paths = Object.fromEntries(Object.entries(spec.paths).map(([path, item]) => [
+        path,
+        Object.fromEntries(Object.entries(item).map(([method, operation]) => [
+            method,
+            Array.isArray(operation)
+                ? operation
+                : Object.assign({}, operation, {
+                    security: "operationId" in operation && UNAUTHENTICATED.has(operation.operationId)
+                        ? []
+                        : security,
+                }),
+        ])),
+    ]));
+    return {
+        ...spec,
+        info: { ...spec.info, title, version },
+        paths,
+        components: {
+            ...spec.components,
+            securitySchemes: Object.fromEntries(auth.credentials.map((credential) => [schemeName(credential), securityScheme(credential)])),
+        },
+    };
+};

package/dist/serve/assertion/binding.d.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+/**
+ * The canonical request binding of a hosted edge assertion. The edge signs
+ * the SHA-256 of the canonical string of the request it forwards; the runner
+ * rebuilds the string from the request it received and compares, so an
+ * assertion can't be moved to another actor, member, command id, or body.
+ */
+/** The header that carries an assertion from the edge to a runner. */
+export declare const ASSERTION_HEADER = "durable-assertion";
+/** The JWS `typ` of an assertion. */
+export declare const ASSERTION_TYPE = "durable-assertion+jwt";
+/** The JWS `typ` of the edge's push asking a runner to reread its key set. */
+export declare const KEY_REFRESH_TYPE = "durable-key-refresh+jwt";
+/** The route, under a served layer's base path, that takes the edge's key-set refresh push. */
+export declare const KEY_REFRESH_PATH = "/assertion-keys/refresh";
+/** What the canonical string binds, as the edge forwards and the runner receives it. */
+export interface BoundRequest {
+    readonly method: string;
+    /** The request target: a path with an optional `?query`, as it arrives. */
+    readonly target: string;
+    /** The raw `Idempotency-Key` header value, if the request has one. */
+    readonly idempotencyKey: string | undefined;
+    /** The body bytes exactly as forwarded; empty when there is none. */
+    readonly body: Uint8Array;
+}
+/** A path with percent-encoding normalized to uppercase hex and no dot segments. */
+export declare const canonicalPath: (path: string) => string;
+/** Query parameters sorted by name then value, each percent-encoded, joined by `&`. */
+export declare const canonicalQuery: (query: string) => string;
+/** The canonical string of a request, before hashing. */
+export declare const canonicalRequest: (request: BoundRequest) => Effect.Effect<string, never, never>;
+/** The `req` claim of an assertion for `request`: the SHA-256 of its canonical string. */
+export declare const requestDigest: (request: BoundRequest) => Effect.Effect<string, never, never>;
+/**
+ * The `req` claim of a streaming session's reauthentication assertion: it
+ * binds the session's upgrade path and its session id, not a request.
+ */
+export declare const reauthenticationDigest: (options: {
+    readonly path: string;
+    readonly session: string;
+}) => Effect.Effect<string, never, never>;

package/dist/serve/assertion/binding.js

@@ -0,0 +1,92 @@
+import { Effect } from "effect";
+/**
+ * The canonical request binding of a hosted edge assertion. The edge signs
+ * the SHA-256 of the canonical string of the request it forwards; the runner
+ * rebuilds the string from the request it received and compares, so an
+ * assertion can't be moved to another actor, member, command id, or body.
+ */
+/** The header that carries an assertion from the edge to a runner. */
+export const ASSERTION_HEADER = "durable-assertion";
+/** The JWS `typ` of an assertion. */
+export const ASSERTION_TYPE = "durable-assertion+jwt";
+/** The JWS `typ` of the edge's push asking a runner to reread its key set. */
+export const KEY_REFRESH_TYPE = "durable-key-refresh+jwt";
+/** The route, under a served layer's base path, that takes the edge's key-set refresh push. */
+export const KEY_REFRESH_PATH = "/assertion-keys/refresh";
+const VERSION = "durable-assertion/v1";
+const utf8 = new TextEncoder();
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+const sha256 = (bytes) => Effect.promise(() => crypto.subtle.digest("SHA-256", new Uint8Array(bytes))).pipe(Effect.map(hex));
+/** RFC 3986 unreserved characters, which percent-encoding never changes the meaning of. */
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+/** Uppercases percent-encoding hex, and decodes it where it encodes an unreserved character. */
+const normalizeEscapes = (segment) => segment.replace(/%([0-9A-Fa-f]{2})/g, (_, digits) => {
+    const character = String.fromCharCode(Number.parseInt(digits, 16));
+    return UNRESERVED.test(character) ? character : `%${digits.toUpperCase()}`;
+});
+/** RFC 3986 section 5.2.4: removes `.` and `..` segments. `..` never climbs above the root, the path's leading empty segment. */
+const removeDotSegments = (path) => {
+    const output = [];
+    const segments = path.split("/");
+    for (const [index, segment] of segments.entries()) {
+        const last = index === segments.length - 1;
+        if (segment === ".") {
+            if (last)
+                output.push("");
+            continue;
+        }
+        if (segment === "..") {
+            if (output.length > 1)
+                output.pop();
+            if (last)
+                output.push("");
+            continue;
+        }
+        output.push(segment);
+    }
+    return output.join("/");
+};
+/** A path with percent-encoding normalized to uppercase hex and no dot segments. */
+export const canonicalPath = (path) => {
+    const normalized = removeDotSegments(path.split("/").map(normalizeEscapes).join("/"));
+    return normalized.startsWith("/") ? normalized : `/${normalized}`;
+};
+/** Encodes everything but unreserved characters, so both sides agree whatever the client escaped. */
+const strictEncode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/** Query parameters sorted by name then value, each percent-encoded, joined by `&`. */
+export const canonicalQuery = (query) => [...new URLSearchParams(query)]
+    .map(([name, value]) => [strictEncode(name), strictEncode(value)])
+    .sort(([leftName, leftValue], [rightName, rightValue]) => leftName === rightName ? compare(leftValue, rightValue) : compare(leftName, rightName))
+    .map(([name, value]) => `${name}=${value}`)
+    .join("&");
+const splitTarget = (target) => {
+    const mark = target.indexOf("?");
+    return mark === -1
+        ? { path: target, query: "" }
+        : { path: target.slice(0, mark), query: target.slice(mark + 1) };
+};
+/** The canonical string of a request, before hashing. */
+export const canonicalRequest = Effect.fnUntraced(function* (request) {
+    const { path, query } = splitTarget(request.target);
+    return [
+        VERSION,
+        request.method.toUpperCase(),
+        canonicalPath(path),
+        canonicalQuery(query),
+        request.idempotencyKey ?? "",
+        yield* sha256(request.body),
+    ].join("\n");
+});
+/** The `req` claim of an assertion for `request`: the SHA-256 of its canonical string. */
+export const requestDigest = (request) => canonicalRequest(request).pipe(Effect.flatMap((text) => sha256(utf8.encode(text))));
+/**
+ * The `req` claim of a streaming session's reauthentication assertion: it
+ * binds the session's upgrade path and its session id, not a request.
+ */
+export const reauthenticationDigest = (options) => sha256(utf8.encode([
+    VERSION,
+    "REAUTHENTICATE",
+    canonicalPath(splitTarget(options.path).path),
+    options.session,
+].join("\n")));

package/dist/serve/assertion/verify.d.ts

@@ -0,0 +1,93 @@
+import { Duration, Schema } from "effect";
+import { HttpClient } from "effect/http";
+import { type AuthProvider } from "../auth.ts";
+/** An edge verification key: an Ed25519 public JWK, valid from `nbf` until `exp` (epoch seconds). */
+export declare const AssertionKey: Schema.Struct<{
+    readonly kid: Schema.NonEmptyString;
+    readonly kty: Schema.Literal<"OKP">;
+    readonly crv: Schema.Literal<"Ed25519">;
+    readonly x: Schema.NonEmptyString;
+    readonly nbf: Schema.optionalKey<Schema.Finite>;
+    readonly exp: Schema.optionalKey<Schema.Finite>;
+}>;
+/** An edge verification key. */
+export type AssertionKey = typeof AssertionKey.Type;
+/** The key set the control plane publishes for runners. */
+export declare const AssertionKeySet: Schema.Struct<{
+    readonly keys: Schema.$Array<Schema.Struct<{
+        readonly kid: Schema.NonEmptyString;
+        readonly kty: Schema.Literal<"OKP">;
+        readonly crv: Schema.Literal<"Ed25519">;
+        readonly x: Schema.NonEmptyString;
+        readonly nbf: Schema.optionalKey<Schema.Finite>;
+        readonly exp: Schema.optionalKey<Schema.Finite>;
+    }>>;
+}>;
+/** The key set the control plane publishes for runners. */
+export type AssertionKeySet = typeof AssertionKeySet.Type;
+/** Options of `Actor.auth.assertion`. */
+export interface AssertionOptions<Keys extends URL | AssertionKeySet> {
+    /** The edge's issuer; `iss` must equal it. */
+    readonly issuer: string;
+    /** The deployment id; `aud` must equal it. */
+    readonly audience: string;
+    /** The runner's region; an assertion routed to another region is refused. */
+    readonly region: string;
+    /** The published key-set URL, reread every `refreshEvery`, or static keys. */
+    readonly keys: Keys;
+    /**
+     * How often a key-set URL is reread, which bounds how long a removed key is
+     * still accepted. Default 5 minutes.
+     */
+    readonly refreshEvery?: Duration.Input;
+}
+/** The most an assertion may live, from `iat` to `exp`. */
+export declare const MAX_ASSERTION_SECONDS = 60;
+/** Clock skew allowed on `iat` and `exp`; edge and runners run synchronized clocks. */
+export declare const ASSERTION_SKEW_MS = 5000;
+/** The claims of an edge's key-set refresh push. */
+export declare const KeyRefreshClaims: Schema.Struct<{
+    readonly iss: Schema.String;
+    readonly aud: Schema.String;
+    readonly iat: Schema.Finite;
+    readonly exp: Schema.Finite;
+}>;
+/** The claims of an edge's key-set refresh push. */
+export type KeyRefreshClaims = typeof KeyRefreshClaims.Type;
+/** The claims an edge signs; `actor`, `id`, `member`, and `cid` are there for logs. */
+export declare const AssertionClaims: Schema.Struct<{
+    readonly iss: Schema.String;
+    readonly aud: Schema.String;
+    readonly region: Schema.String;
+    readonly iat: Schema.Finite;
+    readonly exp: Schema.Finite;
+    readonly tenant: Schema.String;
+    readonly caller: Schema.Union<readonly [Schema.TaggedStruct<"User", {
+        readonly subject: Schema.NonEmptyString;
+    }>, Schema.TaggedStruct<"Anonymous", {}>]>;
+    readonly req: Schema.String;
+    /** The streaming session id, on assertions for a WebSocket open or renewal. */
+    readonly sid: Schema.optionalKey<Schema.NonEmptyString>;
+    /** The external credential's own expiry in epoch seconds, which caps a live session. */
+    readonly cexp: Schema.optionalKey<Schema.Finite>;
+    readonly actor: Schema.optionalKey<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.String>;
+    readonly member: Schema.optionalKey<Schema.String>;
+    readonly cid: Schema.optionalKey<Schema.String>;
+}>;
+/** The claims an edge signs. */
+export type AssertionClaims = typeof AssertionClaims.Type;
+/**
+ * Verifies the hosted edge's signed assertion, the only provider a hosted
+ * runner uses. It checks the signature, key, issuer, deployment, region, and
+ * lifetime here; the server then checks the request binding against the
+ * request it received before any turn.
+ *
+ * A key set older than `refreshEvery` is reread before use, and a runner that
+ * can't reread it refuses with `ActorUnavailable` rather than keep trusting
+ * keys the control plane may have removed. The provider's `refreshKeys` takes
+ * the edge's signed push and rereads the key set at once, however recently it
+ * was read, so a revoked key stops verifying without waiting for
+ * `refreshEvery`; repeating a push is harmless.
+ */
+export declare const assertion: <Keys extends URL | AssertionKeySet>(options: AssertionOptions<Keys>) => AuthProvider<Keys extends URL ? HttpClient.HttpClient : never>;