@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/http/auth/jwt.js

@@ -0,0 +1,38 @@
+/** HS256 JSON Web Tokens: signed with the server's secret, read back with whether the signature holds. */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/* `{"alg":"HS256","typ":"JWT"}`, base64url-encoded. */
+const HEADER = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
+const mac = (secret, input) => createHmac("sha256", secret).update(input).digest();
+/** The claims, signed with `secret` as an HS256 JWT. */
+export function signJwt(secret, claims) {
+    const input = `${HEADER}.${Buffer.from(JSON.stringify(claims)).toString("base64url")}`;
+    return `${input}.${mac(secret, input).toString("base64url")}`;
+}
+/* A segment's JSON object, or `undefined` when it is not one. */
+function objectOf(segment) {
+    try {
+        const value = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A JWT's claims and whether `secret` signed it; `null` when the text is not a JWT at all. */
+export function decodeJwt(secret, token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const [header, payload, signature] = parts;
+    const head = objectOf(header);
+    const claims = objectOf(payload);
+    if (head === undefined || claims === undefined)
+        return null;
+    const expected = mac(secret, `${header}.${payload}`);
+    const given = Buffer.from(signature, "base64url");
+    const signed = head["alg"] === "HS256" && given.length === expected.length && timingSafeEqual(given, expected);
+    return { claims, signed };
+}
+//# sourceMappingURL=jwt.js.map

package/dist/api/reference/http/auth/sessions.d.ts

@@ -0,0 +1,18 @@
+/** Sign-in sessions: issuing JWT pairs, verifying an access token, rotating a refresh token, revoking. */
+import type { ReferenceOptions, ReferenceState } from "../state.ts";
+import type { AuthState, Principal, Session } from "./types.ts";
+/** A fresh server's sign-in state: the principals as accounts, nothing issued yet. */
+export declare function newAuthState(options: ReferenceOptions): AuthState;
+/** The next id in the auth sequence, as `<prefix>_<n>`. */
+export declare function nextId(auth: AuthState, prefix: string): string;
+/** An access and a refresh token for `principal`, in `family` or a new one. */
+export declare function issueSession(state: ReferenceState, principal: Principal, family?: string): Session;
+/** Who a live access token authenticates: its subject, tenant, role and token id, as it claims them. */
+export declare function accessPrincipal(state: ReferenceState, token: string): Principal;
+/** A new pair for a live refresh token, which is spent. Presenting a spent one revokes its whole family. */
+export declare function rotate(state: ReferenceState, refreshToken: string): Session;
+/** Revokes one of the caller's own tokens, access or refresh. */
+export declare function revokeJwt(state: ReferenceState, caller: Principal, token: string): void;
+/** Refuses every account's tokens from now on, whenever issued: the whole user base is signed out. */
+export declare function killAll(auth: AuthState): void;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/api/reference/http/auth/sessions.js

@@ -0,0 +1,105 @@
+/** Sign-in sessions: issuing JWT pairs, verifying an access token, rotating a refresh token, revoking. */
+import { HttpError } from "../errors.js";
+import { PRINCIPALS } from "../state.js";
+import { decodeJwt, signJwt } from "./jwt.js";
+/* The roles a token carries, at their rank: viewer 0, member 1, admin 2. */
+const ROLES = ["viewer", "member", "admin"];
+const ACCESS_SECONDS = 3600;
+const REFRESH_SECONDS = 30 * 86_400;
+/** A fresh server's sign-in state: the principals as accounts, nothing issued yet. */
+export function newAuthState(options) {
+    return {
+        accounts: new Map(PRINCIPALS.map((account) => [account.key, account])),
+        apiKeys: new Map(),
+        clock: options.clock ?? Date.now,
+        failures: new Map(),
+        killed: new Set(),
+        registered: [],
+        revoked: new Set(),
+        revokedFamilies: new Set(),
+        rotated: new Set(),
+        secret: "testing-reference-secret",
+        sequence: 0,
+        throttle: options.throttleLogins === true,
+    };
+}
+/** The next id in the auth sequence, as `<prefix>_<n>`. */
+export function nextId(auth, prefix) {
+    auth.sequence += 1;
+    return `${prefix}_${auth.sequence}`;
+}
+const unauthorized = (message) => new HttpError(401, "unauthorized", message);
+/** An access and a refresh token for `principal`, in `family` or a new one. */
+export function issueSession(state, principal, family) {
+    const { auth } = state;
+    const fam = family ?? nextId(auth, "fam");
+    const iat = Math.floor(auth.clock() / 1000);
+    const base = { fam, iat, project_id: principal.projectId, role: ROLES[principal.rank], sub: principal.key };
+    const sign = (typ, seconds) => signJwt(auth.secret, { ...base, exp: iat + seconds, jti: nextId(auth, "jti"), typ });
+    const access = sign("access", ACCESS_SECONDS);
+    return {
+        access_token: access,
+        expires_in: state.defects.has("TOKEN_EXPIRY_AS_STRING") ? String(ACCESS_SECONDS) : ACCESS_SECONDS,
+        project_id: principal.projectId,
+        refresh_token: sign("refresh", REFRESH_SECONDS),
+    };
+}
+/* The claims, when every one the server issues is there with its type. */
+function asClaims(raw) {
+    const strings = ["sub", "project_id", "typ", "fam", "jti"].every((name) => typeof raw[name] === "string");
+    const numbers = typeof raw["exp"] === "number" && typeof raw["iat"] === "number";
+    return strings && numbers && ROLES.includes(raw["role"]) ? raw : undefined;
+}
+/* A token's claims, once it holds: signed (unless TOKEN_NOT_VERIFIED), of `typ`, unexpired and unrevoked. */
+function claimsOf(state, token, typ) {
+    const { auth, defects } = state;
+    const decoded = decodeJwt(auth.secret, token);
+    if (decoded === null)
+        throw unauthorized("malformed token");
+    if (!decoded.signed && !defects.has("TOKEN_NOT_VERIFIED"))
+        throw unauthorized("bad token signature");
+    const claims = asClaims(decoded.claims);
+    if (claims === undefined)
+        throw unauthorized("malformed token claims");
+    if (claims.typ !== typ)
+        throw unauthorized(`not ${typ === "access" ? "an access" : "a refresh"} token`);
+    if (claims.exp * 1000 <= auth.clock())
+        throw unauthorized("token expired");
+    const revoked = !defects.has("REVOKED_TOKEN_ACCEPTED") && (auth.revoked.has(claims.jti) || auth.revokedFamilies.has(claims.fam));
+    if (revoked || auth.killed.has(claims.sub))
+        throw unauthorized("token revoked");
+    return claims;
+}
+/** Who a live access token authenticates: its subject, tenant, role and token id, as it claims them. */
+export function accessPrincipal(state, token) {
+    const claims = claimsOf(state, token, "access");
+    return { jti: claims.jti, key: claims.sub, projectId: claims.project_id, rank: ROLES.indexOf(claims.role) };
+}
+/** A new pair for a live refresh token, which is spent. Presenting a spent one revokes its whole family. */
+export function rotate(state, refreshToken) {
+    const claims = claimsOf(state, refreshToken, "refresh");
+    const { auth } = state;
+    if (auth.rotated.has(claims.jti) && !state.defects.has("REFRESH_REUSE_ACCEPTED")) {
+        auth.revokedFamilies.add(claims.fam);
+        throw unauthorized("refresh token reused; its session is revoked");
+    }
+    auth.rotated.add(claims.jti);
+    const principal = { key: claims.sub, projectId: claims.project_id, rank: ROLES.indexOf(claims.role) };
+    return issueSession(state, principal, claims.fam);
+}
+/** Revokes one of the caller's own tokens, access or refresh. */
+export function revokeJwt(state, caller, token) {
+    const decoded = decodeJwt(state.auth.secret, token);
+    if (decoded === null || !decoded.signed) {
+        throw new HttpError(400, "invalid_input", "the token is not one this server issued");
+    }
+    if (decoded.claims["sub"] !== caller.key)
+        throw new HttpError(403, "forbidden", "the token belongs to another principal");
+    state.auth.revoked.add(String(decoded.claims["jti"]));
+}
+/** Refuses every account's tokens from now on, whenever issued: the whole user base is signed out. */
+export function killAll(auth) {
+    for (const key of auth.accounts.keys())
+        auth.killed.add(key);
+}
+//# sourceMappingURL=sessions.js.map

package/dist/api/reference/http/auth/throttle.d.ts

@@ -0,0 +1,8 @@
+/** The login throttle: under `throttleLogins`, an identity that keeps failing to sign in is told to wait. */
+import type { ReferenceState } from "../state.ts";
+import { type ReferenceResponse } from "../wire.ts";
+/** The 429 a login for `identity` gets once it has failed 5 times within a minute; otherwise `undefined`. */
+export declare function throttled(state: ReferenceState, identity: string): ReferenceResponse | undefined;
+/** Records a login for `identity`: a failure counts toward the throttle, a success clears it. */
+export declare function noteLogin(state: ReferenceState, identity: string, succeeded: boolean): void;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/api/reference/http/auth/throttle.js

@@ -0,0 +1,28 @@
+/** The login throttle: under `throttleLogins`, an identity that keeps failing to sign in is told to wait. */
+import { respond } from "../wire.js";
+const WINDOW_MS = 60_000;
+const LIMIT = 5;
+/* Whether failed logins count at all on this server. */
+const throttling = (state) => state.auth.throttle && !state.defects.has("LOGIN_NOT_THROTTLED");
+/** The 429 a login for `identity` gets once it has failed 5 times within a minute; otherwise `undefined`. */
+export function throttled(state, identity) {
+    if (!throttling(state))
+        return undefined;
+    const now = state.auth.clock();
+    const recent = (state.auth.failures.get(identity) ?? []).filter((at) => at > now - WINDOW_MS);
+    state.auth.failures.set(identity, recent);
+    if (recent.length < LIMIT)
+        return undefined;
+    const wait = Math.max(1, Math.ceil((recent[0] + WINDOW_MS - now) / 1000));
+    return respond(429, { error_key: "too_many_requests", message: "too many failed logins; retry later", status: 429, success: false }, { "retry-after": String(wait) });
+}
+/** Records a login for `identity`: a failure counts toward the throttle, a success clears it. */
+export function noteLogin(state, identity, succeeded) {
+    if (!throttling(state))
+        return;
+    if (succeeded)
+        state.auth.failures.delete(identity);
+    else
+        state.auth.failures.set(identity, [...(state.auth.failures.get(identity) ?? []), state.auth.clock()]);
+}
+//# sourceMappingURL=throttle.js.map

package/dist/api/reference/http/auth/types.d.ts

@@ -0,0 +1,80 @@
+/** What the server keeps about sign-ins: accounts, issued and revoked tokens, API keys and failed logins. */
+/** The roles a token carries: viewer, member, admin, at ranks 0, 1 and 2. */
+export type Role = "viewer" | "member" | "admin";
+/** Who a request acts as. Higher rank can do everything a lower rank can. */
+export interface Principal {
+    key: string;
+    projectId: string;
+    rank: number;
+    /** The access token's id, when a JWT authenticated the request. */
+    jti?: string;
+}
+/** Someone who can sign in: by key at `auth.token`, or by email and password at `auth.login`. */
+export interface Account extends Principal {
+    email?: string;
+    password?: string;
+    /** What `account.update` last set as its display name. */
+    displayName?: string;
+    /** What `auth.register` made it with: an account it made has one, a seeded principal none. */
+    signup?: {
+        staff: boolean;
+    };
+}
+/** An API key: bound to its creator's tenant and rank, and to the scopes it was made with. */
+export interface ApiKey {
+    id: string;
+    /** What its creator called it; `null` when unnamed. */
+    name: string | null;
+    value: string;
+    sub: string;
+    projectId: string;
+    rank: number;
+    scopes: readonly string[];
+    revoked: boolean;
+}
+/** The claims every token the server issues carries. */
+export interface Claims {
+    sub: string;
+    project_id: string;
+    role: Role;
+    typ: "access" | "refresh";
+    /** The session family: every token a refresh rotates out of one sign-in shares it. */
+    fam: string;
+    jti: string;
+    iat: number;
+    exp: number;
+}
+/** A sign-in's answer, as `auth.token`, `auth.login` and `auth.refresh` give it. */
+export interface Session {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number | string;
+    project_id: string;
+}
+export interface AuthState {
+    /** Signs every JWT. */
+    secret: string;
+    /** Milliseconds since the epoch: expiry and the login throttle read it. */
+    clock: () => number;
+    /** Under `throttleLogins`: too many failed logins for one identity answer 429. */
+    throttle: boolean;
+    /** Numbers the jti, family and API key ids, apart from the record ids so those stay put. */
+    sequence: number;
+    /** By key: the seeded principals, then whoever registered. */
+    accounts: Map<string, Account>;
+    /** The email of every account `auth.register` made, deleted since or not, in order. */
+    registered: string[];
+    /** Revoked token ids. */
+    revoked: Set<string>;
+    /** Session families revoked whole, on refresh-token reuse. */
+    revokedFamilies: Set<string>;
+    /** Refresh token ids already rotated: presenting one again is reuse. */
+    rotated: Set<string>;
+    /** Subjects whose every token is refused, issued before or after. */
+    killed: Set<string>;
+    /** By value. */
+    apiKeys: Map<string, ApiKey>;
+    /** Failed login instants, per identity, while throttling. */
+    failures: Map<string, number[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/reference/http/auth/types.js

@@ -0,0 +1,3 @@
+/** What the server keeps about sign-ins: accounts, issued and revoked tokens, API keys and failed logins. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/reference/http/body.d.ts

@@ -0,0 +1,11 @@
+/** Reading a request body, refused when its type is not the one the route takes. */
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { ReferenceRequest } from "./wire.ts";
+export declare function readJson(request: ReferenceRequest): Promise<unknown>;
+export declare function requireJson(request: ReferenceRequest, defects: DefectSet): void;
+export declare function requireForm(request: ReferenceRequest, defects: DefectSet): void;
+/** The kind each field of a fixed body takes: a string, an array of strings, or a boolean the body may leave out. */
+export type FieldKinds = Readonly<Record<string, "string" | "string?" | "strings" | "boolean?">>;
+/** A JSON body holding the fields `kinds` names, each of its kind, an optional one or not; anything else is a 400. */
+export declare function readFields(request: ReferenceRequest, defects: DefectSet, kinds: FieldKinds): Promise<Record<string, unknown>>;
+//# sourceMappingURL=body.d.ts.map

package/dist/api/reference/http/body.js

@@ -0,0 +1,55 @@
+/** Reading a request body, refused when its type is not the one the route takes. */
+import { HttpError } from "./errors.js";
+export async function readJson(request) {
+    const text = await request.text();
+    if (text.trim() === "")
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HttpError(400, "invalid_input", "request body is not valid JSON");
+    }
+}
+export function requireJson(request, defects) {
+    requireType(request, defects, "application/json");
+}
+export function requireForm(request, defects) {
+    requireType(request, defects, "application/x-www-form-urlencoded");
+}
+function requireType(request, defects, expected) {
+    if (defects.has("CONTENT_TYPE_NOT_ENFORCED"))
+        return;
+    if (!(request.headers["content-type"] ?? "").includes(expected)) {
+        throw new HttpError(415, "unsupported_media_type", `expected ${expected}`);
+    }
+}
+const ofKind = (value, kind) => {
+    if (kind === "boolean?")
+        return typeof value === "boolean";
+    return kind === "string" || kind === "string?"
+        ? typeof value === "string"
+        : Array.isArray(value) && value.every((item) => typeof item === "string");
+};
+/** A JSON body holding the fields `kinds` names, each of its kind, an optional one or not; anything else is a 400. */
+export async function readFields(request, defects, kinds) {
+    requireJson(request, defects);
+    const body = await readJson(request);
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new HttpError(400, "invalid_input", "request body must be an object");
+    }
+    const fields = body;
+    const unknown = Object.keys(fields).find((name) => !Object.hasOwn(kinds, name));
+    if (unknown !== undefined)
+        throw new HttpError(400, "invalid_input", `field "${unknown}" is not allowed`);
+    for (const [name, kind] of Object.entries(kinds)) {
+        if (kind.endsWith("?") && !(name in fields))
+            continue;
+        if (!(name in fields))
+            throw new HttpError(400, "invalid_input", `field "${name}" is required`);
+        if (!ofKind(fields[name], kind))
+            throw new HttpError(400, "invalid_input", `field "${name}" has the wrong type`);
+    }
+    return fields;
+}
+//# sourceMappingURL=body.js.map

package/dist/api/reference/http/engines.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The reference on each engine: in memory, SQLite (`node:sqlite`), Cloudflare D1 over HTTP, and a
+ * reachable Postgres. Every store is imported lazily — a static import would load one engine's
+ * driver for all of them, and an optional runtime such as `node:sqlite` would take down paths that
+ * never touch it.
+ */
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+import type { Store } from "../store-api.ts";
+import type { PgConnect } from "../stores/postgres.ts";
+import { type Reference, type StoreFactory } from "./reference.ts";
+import { type ReferenceServer } from "./server.ts";
+import type { ReferenceOptions } from "./state.ts";
+/** In memory: no dependencies, no flags, nothing to have running. */
+export declare const memoryStore: StoreFactory;
+/** SQLite, in process via `node:sqlite`. */
+export declare const sqliteStore: StoreFactory;
+/**
+ * Postgres: needs a reachable server, not just the driver. `connect` reaches it; left out, the
+ * store opens postgres.js against the server the environment names.
+ */
+export declare function postgresStore(defects: DefectSet, entities: readonly EntityDef[], connect?: PgConnect): Promise<Store>;
+/** What a Postgres-backed server is made from: the reference's options, and how to reach the server. */
+export interface PostgresServerOptions extends ReferenceOptions {
+    connect?: PgConnect;
+}
+export interface D1Credentials {
+    accountId?: string;
+    databaseId?: string;
+    apiToken?: string;
+}
+/**
+ * Cloudflare D1 — the same SQL over the network, against someone else's build.
+ *
+ * Credentials come from the environment rather than config so a token never reaches a file that
+ * could be committed. Tables are prefixed per run and dropped on close, because D1 persists: two
+ * runs sharing one database would otherwise contaminate each other's results.
+ */
+export declare function d1Store(credentials?: D1Credentials): StoreFactory;
+export declare function createMemoryServer(options?: ReferenceOptions): Promise<ReferenceServer>;
+export declare function createSqliteServer(options?: ReferenceOptions): Promise<ReferenceServer>;
+export declare function createPostgresServer(options?: PostgresServerOptions): Promise<ReferenceServer>;
+export declare function createD1Server(options?: ReferenceOptions & D1Credentials): Promise<ReferenceServer>;
+/** The in-memory reference in process: what a unit test or an in-process conformance task talks to. */
+export declare function createMemoryReference(options?: ReferenceOptions): Promise<Reference>;
+//# sourceMappingURL=engines.d.ts.map

package/dist/api/reference/http/engines.js

@@ -0,0 +1,75 @@
+/**
+ * The reference on each engine: in memory, SQLite (`node:sqlite`), Cloudflare D1 over HTTP, and a
+ * reachable Postgres. Every store is imported lazily — a static import would load one engine's
+ * driver for all of them, and an optional runtime such as `node:sqlite` would take down paths that
+ * never touch it.
+ */
+import { loadPostgres } from "../stores/postgres-driver.js";
+import { createReference } from "./reference.js";
+import { createReferenceServer } from "./server.js";
+/** In memory: no dependencies, no flags, nothing to have running. */
+export const memoryStore = async () => {
+    const { MemoryStore } = await import("../stores/memory.js");
+    return new MemoryStore();
+};
+/** SQLite, in process via `node:sqlite`. */
+export const sqliteStore = async (defects, entities) => {
+    const { SqlStore } = await import("../stores/sqlite.js");
+    const { nodeSqliteDriver } = await import("../stores/sqlite-driver.js");
+    return SqlStore.create(defects, await nodeSqliteDriver(), { entities });
+};
+/**
+ * Postgres: needs a reachable server, not just the driver. `connect` reaches it; left out, the
+ * store opens postgres.js against the server the environment names.
+ */
+export async function postgresStore(defects, entities, connect) {
+    const { PgStore } = await loadPostgres(() => import("../stores/postgres.js"));
+    return PgStore.create(defects, entities, connect);
+}
+/**
+ * Cloudflare D1 — the same SQL over the network, against someone else's build.
+ *
+ * Credentials come from the environment rather than config so a token never reaches a file that
+ * could be committed. Tables are prefixed per run and dropped on close, because D1 persists: two
+ * runs sharing one database would otherwise contaminate each other's results.
+ */
+export function d1Store(credentials = {}) {
+    const accountId = credentials.accountId ?? process.env["CLOUDFLARE_ACCOUNT_ID"];
+    const databaseId = credentials.databaseId ?? process.env["CLOUDFLARE_D1_DATABASE_ID"];
+    const apiToken = credentials.apiToken ?? process.env["CLOUDFLARE_API_TOKEN"];
+    const missing = [
+        accountId === undefined ? "CLOUDFLARE_ACCOUNT_ID" : null,
+        databaseId === undefined ? "CLOUDFLARE_D1_DATABASE_ID" : null,
+        apiToken === undefined ? "CLOUDFLARE_API_TOKEN" : null,
+    ].filter((name) => name !== null);
+    if (missing.length > 0)
+        throw new Error(`D1 backend needs ${missing.join(", ")} in the environment`);
+    const prefix = `testing_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}_`;
+    return async (defects, entities) => {
+        const { SqlStore } = await import("../stores/sqlite.js");
+        const { d1Driver } = await import("../stores/sqlite-driver.js");
+        const driver = d1Driver({
+            accountId: accountId,
+            apiToken: apiToken,
+            databaseId: databaseId,
+        });
+        return SqlStore.create(defects, driver, { entities, prefix });
+    };
+}
+export function createMemoryServer(options = {}) {
+    return createReferenceServer(options, memoryStore);
+}
+export function createSqliteServer(options = {}) {
+    return createReferenceServer(options, sqliteStore);
+}
+export function createPostgresServer(options = {}) {
+    return createReferenceServer(options, (defects, entities) => postgresStore(defects, entities, options.connect));
+}
+export async function createD1Server(options = {}) {
+    return createReferenceServer(options, d1Store(options));
+}
+/** The in-memory reference in process: what a unit test or an in-process conformance task talks to. */
+export function createMemoryReference(options = {}) {
+    return createReference(options, memoryStore);
+}
+//# sourceMappingURL=engines.js.map

package/dist/api/reference/http/errors.d.ts

@@ -0,0 +1,16 @@
+/** How the reference refuses a request, and the answer every failure becomes. */
+import type { DefectSet } from "../defects/defect-set.ts";
+import { type ReferenceResponse } from "./wire.ts";
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly errorKey: string;
+    constructor(status: number, errorKey: string, message: string);
+}
+/** The answer a failed request gets: a refusal as itself, a bad filter as a 400, anything else as a 500. */
+export declare function errorResponse(error: unknown, defects: DefectSet): ReferenceResponse;
+/**
+ * A precondition the request names does not hold: an RFC 9457 problem detail. It is answered here,
+ * not as an `HttpError`, so what reshapes every other refusal leaves it as it is.
+ */
+export declare function preconditionFailed(defects: DefectSet, detail: string): ReferenceResponse;
+//# sourceMappingURL=errors.d.ts.map

package/dist/api/reference/http/errors.js

@@ -0,0 +1,47 @@
+/** How the reference refuses a request, and the answer every failure becomes. */
+import { messageOf } from "../../errors/message.js";
+import { SqlError } from "../store-api.js";
+import { respond } from "./wire.js";
+export class HttpError extends Error {
+    status;
+    errorKey;
+    constructor(status, errorKey, message) {
+        super(message);
+        this.status = status;
+        this.errorKey = errorKey;
+    }
+}
+/** The answer a failed request gets: a refusal as itself, a bad filter as a 400, anything else as a 500. */
+export function errorResponse(error, defects) {
+    if (error instanceof HttpError) {
+        if (defects.has("ERROR_SCHEMA_DRIFT"))
+            return respond(error.status, { detail: error.message, error: error.errorKey });
+        return failure(error.status, error.errorKey, error.message);
+    }
+    if (error instanceof SqlError) {
+        /* Correct behavior is a 400. The defect lets the filter parser's own exception escape, which
+         * the transport surfaces as a 500 — validation confused with crashing. */
+        if (defects.has("ERROR_500_ON_BAD_FILTER") && error.code === "invalid_filter") {
+            return failure(500, "internal_error", error.message);
+        }
+        return failure(400, "invalid_input", error.message);
+    }
+    return failure(500, "internal_error", messageOf(error));
+}
+/**
+ * A precondition the request names does not hold: an RFC 9457 problem detail. It is answered here,
+ * not as an `HttpError`, so what reshapes every other refusal leaves it as it is.
+ */
+export function preconditionFailed(defects, detail) {
+    const problem = {
+        detail,
+        status: defects.has("PROBLEM_JSON_MALFORMED") ? 400 : 412,
+        title: "Precondition Failed",
+        type: "about:blank",
+    };
+    return respond(412, problem, { "content-type": "application/problem+json" });
+}
+function failure(status, errorKey, message) {
+    return respond(status, { error_key: errorKey, message, status, success: false });
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/reference/http/fetch.d.ts

@@ -0,0 +1,4 @@
+/** A handler as a transport: the client hands it each request, and no socket stands between them. */
+import type { Handle } from "./node.ts";
+export declare function asFetch(handle: Handle): typeof fetch;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/api/reference/http/fetch.js

@@ -0,0 +1,12 @@
+/** A handler as a transport: the client hands it each request, and no socket stands between them. */
+import { referenceRequest } from "./wire.js";
+export function asFetch(handle) {
+    return async (input, init) => {
+        /* A streamed body must say it is sent half-duplex; any other body is unaffected. */
+        const request = new Request(input, { ...init, duplex: "half" });
+        const read = () => request.text();
+        const answer = await handle(referenceRequest(request.method, new URL(request.url), { headers: Object.fromEntries(request.headers), read }));
+        return new Response(answer.status === 204 ? null : answer.body, { headers: answer.headers, status: answer.status });
+    };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/api/reference/http/handlers/actions.d.ts

@@ -0,0 +1,6 @@
+/** Actions whose effect lands later or elsewhere: an async job, and a notification and its inbox. */
+import { type Route } from "./fixed.ts";
+export declare const startJob: Route;
+export declare const notify: Route;
+export declare const inbox: Route;
+//# sourceMappingURL=actions.d.ts.map

package/dist/api/reference/http/handlers/actions.js

@@ -0,0 +1,59 @@
+/** Actions whose effect lands later or elsewhere: an async job, and a notification and its inbox. */
+import { assertWrite } from "../access.js";
+import { readJson, requireJson } from "../body.js";
+import { HttpError } from "../errors.js";
+import { withDefaults } from "../records.js";
+import { respond } from "../wire.js";
+import { ownProject } from "./fixed.js";
+export const startJob = async (state, request) => {
+    if (!request.url.pathname.endsWith("/jobs/start") || request.method !== "POST")
+        return undefined;
+    const projectId = request.url.pathname.split("/")[3] ?? "";
+    ownProject(state, request, projectId);
+    requireJson(request, state.defects);
+    const name = (await readJson(request)).name;
+    if (typeof name !== "string" || name === "")
+        throw new HttpError(400, "invalid_input", 'field "name" is required');
+    if (state.defects.has("ACTION_CRASHES"))
+        throw new HttpError(500, "internal_error", "job runner unavailable");
+    const job = withDefaults(state, { entity: state.job, scope: { project_id: projectId } }, { name });
+    job["status"] = "pending";
+    job["progress"] = 0;
+    if (!state.defects.has("EFFECT_NOT_APPLIED")) {
+        await state.store.insert(state.job, job);
+        state.jobStartedAt.set(String(job["id"]), Date.now());
+    }
+    return respond(202, state.defects.has("ASYNC_RECEIPT_MISSING_ID") ? { accepted: true } : { accepted: true, job_id: job["id"] });
+};
+/* A write whose effect lands elsewhere, later: the message reaches the inbox after a short delay,
+ * the way a queue consumer or a webhook delivery would. x-wait documents it. */
+export const notify = async (state, request) => {
+    const match = /^\/v1\/projects\/([^/]+)\/notifications$/.exec(request.url.pathname);
+    if (match === null || request.method !== "POST")
+        return undefined;
+    const projectId = match[1];
+    assertWrite(state, ownProject(state, request, projectId), "create");
+    requireJson(request, state.defects);
+    const message = (await readJson(request)).message;
+    if (typeof message !== "string" || message === "" || message.length > 200) {
+        throw new HttpError(400, "invalid_input", 'field "message" is required');
+    }
+    const id = `ntf_${String(state.ids.tick()).padStart(6, "0")}`;
+    if (!state.defects.has("SIDE_EFFECT_NEVER_ARRIVES")) {
+        setTimeout(() => {
+            const inbox = state.inboxes.get(projectId) ?? [];
+            inbox.push({ id, message });
+            state.inboxes.set(projectId, inbox);
+        }, 40);
+    }
+    return respond(202, { accepted: true, notification_id: id });
+};
+export const inbox = async (state, request) => {
+    const match = /^\/v1\/projects\/([^/]+)\/inbox$/.exec(request.url.pathname);
+    if (match === null || request.method !== "GET")
+        return undefined;
+    const projectId = match[1];
+    ownProject(state, request, projectId);
+    return respond(200, { messages: state.inboxes.get(projectId) ?? [] });
+};
+//# sourceMappingURL=actions.js.map

package/dist/api/reference/http/handlers/api-keys.d.ts

@@ -0,0 +1,16 @@
+/** Minting, reading and revoking API keys: a signed-in caller's, bound to its tenant, rank and the scopes it names. */
+import type { ReferenceState } from "../state.ts";
+import type { Route } from "./fixed.ts";
+/** Every scope a key may hold: reading or writing each entity. */
+export declare function knownScopes(state: ReferenceState): string[];
+/** `apiKey.create { scopes }`: a new key, answered once with its value. */
+export declare const createKey: Route;
+/** `apiKey.get`: GET `/v1/api-keys/{id}`, a live key without its value, which only its create shows. */
+export declare const readKey: Route;
+/** `apiKey.list` behind key-lifecycle: GET `/v1/api-keys`, the caller's tenant's live keys. */
+export declare const listKeys: Route;
+/** `apiKey.update` behind key-lifecycle: PATCH `/v1/api-keys/{id}` `{ name }`, a key of the caller's tenant. */
+export declare const renameKey: Route;
+/** `apiKey.revoke`: DELETE `/v1/api-keys/{id}`. */
+export declare const revokeKey: Route;
+//# sourceMappingURL=api-keys.d.ts.map