@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/dialect/presets.js

@@ -0,0 +1,193 @@
+/**
+ * The conventions a reference backend speaks.
+ *
+ * Everything the API tester had quietly hardcoded — what the page-size parameter is called, where the total
+ * lives in the envelope, how a filter expression is spelled — varies wildly between real APIs
+ * and not at all between two instances of the same fixture. A single-dialect fixture therefore
+ * proves that the checks work on *one* shape, which is a much weaker claim than it appears.
+ *
+ * Two dialects, differing in every name and in the filter grammar, turn that into a real test:
+ * the defects and the checks are identical, so anything that passes on one and fails on the
+ * other was reading a convention rather than the contract.
+ */
+/** `field.op.value` with cursor pagination and entity-named collections. */
+export const POSTGREST = {
+    envelope: {
+        collection: null,
+        hasMore: "hasMore",
+        limit: "limit",
+        nextCursor: "nextCursor",
+        page: "page",
+        total: "count",
+    },
+    grammar: "postgrest",
+    name: "postgrest",
+    params: {
+        cursor: "cursor",
+        filter: "filter",
+        limit: "limit",
+        order: "order",
+        page: "page",
+        search: "q",
+        searchMode: "search_mode",
+        select: "select",
+    },
+};
+/**
+ * A deliberately unrelated spelling: `per_page`, `sort`, `fields`, `search`, a `data` envelope
+ * with `total_count`/`has_more`, no cursor at all, and `field=op:value` filters.
+ *
+ * Nothing here shares a name with the other dialect, so a check that still works is working from
+ * the document rather than from familiarity.
+ */
+export const CLASSIC = {
+    envelope: {
+        collection: "data",
+        hasMore: "has_more",
+        limit: "per_page",
+        page: "page",
+        total: "total_count",
+    },
+    grammar: "colon",
+    name: "classic",
+    params: {
+        filter: "filter",
+        limit: "per_page",
+        order: "sort",
+        page: "page",
+        search: "search",
+        select: "fields",
+    },
+};
+/**
+ * Root array, `Link` header pagination, `offset`/`limit`.
+ *
+ * No envelope at all: the body is the array, there is no total, no `hasMore`, and no page number.
+ * Whether more pages exist is answered by `rel="next"` in a header. Nothing about a check should
+ * have to change for this, and where something does, the check was reading the fixture's habits.
+ */
+export const LINKED = {
+    envelope: null,
+    grammar: "postgrest",
+    name: "linked",
+    params: {
+        filter: "filter",
+        limit: "limit",
+        offset: "offset",
+        order: "order",
+        search: "q",
+        select: "fields",
+    },
+};
+/**
+ * JSON:API-flavored: `sort=-name` for descending, `fields[table]=id,name` for projection.
+ *
+ * The parameter *names* here are unremarkable — `sort`, `fields`, `page`, `filter` — which is the
+ * point. Everything the API tester had generalized was the name; the value grammars stayed hardcoded to one
+ * spelling. A shape that renames nothing but writes its values differently is the sharpest test
+ * of whether that generalization was real.
+ */
+export const JSONAPI = {
+    envelope: {
+        collection: "data",
+        hasMore: "has_more",
+        limit: "size",
+        page: "number",
+        total: "total",
+    },
+    grammar: "postgrest",
+    name: "jsonapi",
+    params: {
+        filter: "filter",
+        limit: "size",
+        order: "sort",
+        page: "page",
+        search: "q",
+        select: "fields",
+    },
+    selectGrammar: "bracketed",
+    sortGrammar: "prefixed",
+};
+/**
+ * The plainest shape there is: `?status=active&page=2`, no filter expression language at all.
+ *
+ * Half of the API tester's query checks cannot be expressed here — there is no way to write a negation, a
+ * range, or a pattern — and that is precisely the point. Every one of them must report what it
+ * could not test and why, because a run that goes quiet against the most common API shape in the
+ * world is the single most damaging way this tool could fail.
+ */
+export const PLAIN = {
+    envelope: {
+        collection: "items",
+        hasMore: "has_more",
+        limit: "limit",
+        page: "page",
+        total: "total",
+    },
+    grammar: "equality",
+    name: "plain",
+    params: {
+        /* Declared for completeness; the equality grammar never sends it, and the fixture never
+         * reads it. A parameter a backend accepts and ignores is itself a defect the API tester reports. */
+        filter: "filter",
+        limit: "limit",
+        order: "sort",
+        page: "page",
+        search: "q",
+        select: "fields",
+    },
+    sortGrammar: "colon",
+};
+/**
+ * A grammar the API tester has no name for, declared as a template: one term per filter parameter,
+ * `and_status_eq_active`, repeated for every term. `ne` spells not-equal, null tests are terms of
+ * their own, `in` values are comma-joined, an underscore in a value is written `~`, and `like`
+ * matches a bare substring. Sort keys are `name_ascending` / `name_descending`, comma-joined.
+ *
+ * Nothing in the API tester may know this grammar except through the declaration, so every filter check that
+ * still runs here is reading the template rather than a preset. Its names are the same: no alias
+ * finds `filter_by` or `take`, so every check that sends one read it off `x-query.params`, and none
+ * finds `tally` or `more_ahead`, so every walk that reads one read it off `x-query.envelope`.
+ */
+export const TEMPLATE = {
+    envelope: {
+        collection: "results",
+        hasMore: "more_ahead",
+        limit: "limit",
+        page: "page",
+        total: "tally",
+    },
+    filterTemplate: {
+        combine: "repeat",
+        conj: { and: "and", or: "or" },
+        escape: { _: "~" },
+        likeMatches: "contains",
+        list: ",",
+        null: { is: "{conj}_{field}_is_null", not: "{conj}_{field}_isn_null" },
+        ops: { eq: "eq", gt: "gt", gte: "gte", in: "in", like: "like", lt: "lt", lte: "lte", neq: "ne" },
+        or: "terms",
+        term: "{conj}_{field}_{op}_{value}",
+    },
+    grammar: "template",
+    name: "template",
+    sortGrammar: "template",
+    sortTemplate: { asc: "ascending", desc: "descending", join: ",", term: "{field}_{direction}" },
+    declaresNames: true,
+    params: {
+        filter: "filter_by",
+        limit: "take",
+        order: "arrange",
+        page: "leaf",
+        search: "needle",
+        select: "pick",
+    },
+};
+export const DIALECTS = {
+    jsonapi: JSONAPI,
+    plain: PLAIN,
+    classic: CLASSIC,
+    linked: LINKED,
+    postgrest: POSTGREST,
+    template: TEMPLATE,
+};
+//# sourceMappingURL=presets.js.map

package/dist/api/reference/dialect/template.d.ts

@@ -0,0 +1,3 @@
+/** Repeated `and_…` terms must all hold; `or_…` terms, at least one of them. */
+export declare function fromTemplateTerms(terms: readonly string[]): string | null;
+//# sourceMappingURL=template.d.ts.map

package/dist/api/reference/dialect/template.js

@@ -0,0 +1,63 @@
+/*
+ * The template dialect's terms, parsed on their own terms rather than through the API tester's renderer: a
+ * reference that reused the renderer would agree with it by construction and prove nothing.
+ * A value never holds an underscore (it is written `~`), so the last `_op_` in a term is its operator.
+ */
+const TEMPLATE_TERM = /^(and|or)_(.+)_(eq|ne|gt|gte|lt|lte|like|in)_([^_]*)$/s;
+const TEMPLATE_NULL = /^(and|or)_(.+)_(is|isn)_null$/s;
+/* An operator this grammar lacks reaches the canonical layer as one, which refuses it. */
+const TEMPLATE_UNKNOWN_OP = /^(and|or)_(.+)_([a-z]+)_([^_]*)$/s;
+const TEMPLATE_OPS = {
+    eq: "eq",
+    gt: "gt",
+    gte: "gte",
+    in: "in",
+    like: "like",
+    lt: "lt",
+    lte: "lte",
+    ne: "neq",
+};
+const unescapeTemplate = (value) => value.replaceAll("~", "_");
+/** Repeated `and_…` terms must all hold; `or_…` terms, at least one of them. */
+export function fromTemplateTerms(terms) {
+    const all = [];
+    const any = [];
+    for (const term of terms) {
+        const read = templateTerm(term);
+        if (read === null)
+            return null;
+        (read.conj === "and" ? all : any).push(read.canonical);
+    }
+    if (any.length > 0)
+        all.push(any.length === 1 ? any[0] : `or(${any.join(",")})`);
+    if (all.length === 0)
+        return null;
+    return all.length === 1 ? all[0] : `and(${all.join(",")})`;
+}
+/* One term as its combinator and its canonical `field.op.value`; null when it is no term at all. */
+function templateTerm(term) {
+    const nullTest = TEMPLATE_NULL.exec(term);
+    if (nullTest !== null) {
+        const [, conj, field, test] = nullTest;
+        return { canonical: `${field}.is.${test === "is" ? "null" : "notnull"}`, conj };
+    }
+    const match = TEMPLATE_TERM.exec(term);
+    if (match !== null) {
+        const [, conj, field, op, value] = match;
+        return { canonical: knownTerm(field, op, value), conj };
+    }
+    const unknown = TEMPLATE_UNKNOWN_OP.exec(term);
+    if (unknown === null)
+        return null;
+    const [, conj, field, op, value] = unknown;
+    return { canonical: `${field}.${op}.${unescapeTemplate(value)}`, conj };
+}
+/* `in` values are comma-joined, and `like` matches a bare substring. */
+function knownTerm(field, op, value) {
+    if (op === "in")
+        return `${field}.in.(${value.split(",").map(unescapeTemplate).join(",")})`;
+    if (op === "like")
+        return `${field}.like.*${unescapeTemplate(value)}*`;
+    return `${field}.${TEMPLATE_OPS[op]}.${unescapeTemplate(value)}`;
+}
+//# sourceMappingURL=template.js.map

package/dist/api/reference/dialect/types.d.ts

@@ -0,0 +1,61 @@
+import type { RawOf } from "../../config/types/raw.ts";
+import type { SortGrammarSpec } from "../../spec/render/sort.ts";
+/** The names, envelope and grammars one API speaks; see `presets.ts` for why there are several. */
+export interface Dialect {
+    name: string;
+    /**
+     * The dialect names its parameters on `x-query.params` and its paging fields on `x-query.envelope`,
+     * because no alias the API tester knows would find them.
+     */
+    declaresNames?: boolean;
+    /** Query parameter names, by role. */
+    params: {
+        filter: string;
+        order: string;
+        select: string;
+        search: string;
+        limit: string;
+        /** Page number, where the API counts pages. Absent when it counts rows skipped. */
+        page?: string;
+        /** Rows to skip, where the API pages by offset rather than page number. */
+        offset?: string;
+        cursor?: string;
+        /** How the search term matches, where the API lets the caller choose. */
+        searchMode?: string;
+    };
+    /**
+     * Envelope property names, by role.
+     *
+     * `null` for the whole object means the response *is* the array and pagination facts travel in
+     * a `Link` header instead — the GitHub shape. That is a different pagination model, not a
+     * different spelling of one, which is precisely why it belongs in the fixture: a tool that
+     * only ever saw facts in a body may be reading conventions rather than the contract.
+     */
+    envelope: {
+        /** Property holding the array. `null` means "named after the entity" — `tables`, `rows`. */
+        collection: string | null;
+        total?: string;
+        hasMore?: string;
+        nextCursor?: string;
+        page?: string;
+        limit?: string;
+    } | null;
+    /**
+     * How filter expressions are written.
+     *
+     * `equality` has no filter parameter at all: each filterable field is its own query parameter,
+     * and only equality is expressible. It is the most common shape in the wild and the one where
+     * The API tester can say the least — which makes it the real test of whether "I cannot express this" is
+     * reported honestly rather than silently skipped.
+     */
+    grammar: "postgrest" | "colon" | "equality" | "template";
+    /** The template a `template` grammar declares on `x-query.grammar`. */
+    filterTemplate?: Record<string, unknown>;
+    /** How sort directions are written. Defaults to the dotted form when unset. */
+    sortGrammar?: "dotted" | "prefixed" | "colon" | "spaced" | "template";
+    /** The template a `template` sort grammar declares on `x-query.sortGrammar`. */
+    sortTemplate?: RawOf<SortGrammarSpec>;
+    /** How a sparse fieldset is written. Defaults to comma-separated names. */
+    selectGrammar?: "csv" | "bracketed";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/reference/dialect/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,27 @@
+/** Who is asking, and what they may reach: credentials, roles, tenancy and the path's parents. */
+import type { Row } from "../store-api.ts";
+import type { EntityCall, ItemCall } from "./handlers/entity.ts";
+import { type EntityRecord, type Principal, type ReferenceState, type Scope } from "./state.ts";
+import type { ReferenceRequest } from "./wire.ts";
+/** The bearer value a request carries, or `undefined`: what the conformance's own small backends read. */
+export declare function bearer(request: ReferenceRequest): string | undefined;
+/** Viewer cannot write; member cannot delete; admin can do everything. Under ROLE_NOT_CHECKED anyone can. */
+export declare function assertWrite(state: ReferenceState, principal: Principal, kind: "create" | "update" | "delete"): void;
+/** A path under another tenant's project is not the caller's. */
+export declare function assertTenant(principal: Principal, projectId: string | number | undefined): void;
+/** Walks a record up its parent chain to the owning tenant, driven by the descriptors. */
+export declare function ownedByTenant(state: ReferenceState, { entity, record }: EntityRecord, principal: Principal): Promise<boolean>;
+/**
+ * Every ancestor named in the path must exist, be live, and belong to the caller — and its own
+ * ancestors must be the ones the path names. Without this, a caller could list or write rows of
+ * another tenant's table by placing that table's id under their own project.
+ */
+export declare function assertParents(state: ReferenceState, call: EntityCall): Promise<void>;
+/**
+ * A record is served under the path that names its own parents, and no other — all the way up: a
+ * row's table must itself sit under the project the path names.
+ */
+export declare function underPath(state: ReferenceState, { entity, record }: EntityRecord, scope: Scope): Promise<boolean>;
+/** The record a caller may read or write under this path, or the refusal a correct backend gives. */
+export declare function findItem(state: ReferenceState, call: ItemCall, purpose?: "read" | "write"): Promise<Row>;
+//# sourceMappingURL=access.d.ts.map

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

@@ -0,0 +1,131 @@
+/** Who is asking, and what they may reach: credentials, roles, tenancy and the path's parents. */
+import { HttpError } from "./errors.js";
+import { hiddenFromCreator, tombstoned } from "./records.js";
+import { TENANT_FIELD, } from "./state.js";
+const notFound = (entity, id, why = "does not exist") => new HttpError(404, "not_found", `${entity.name} ${String(id)} ${why}`);
+/** The bearer value a request carries, or `undefined`: what the conformance's own small backends read. */
+export function bearer(request) {
+    const header = request.headers["authorization"];
+    return header?.startsWith("Bearer ") === true ? header.slice(7).trim() : undefined;
+}
+/** Viewer cannot write; member cannot delete; admin can do everything. Under ROLE_NOT_CHECKED anyone can. */
+export function assertWrite(state, principal, kind) {
+    if (state.defects.has("ROLE_NOT_CHECKED"))
+        return;
+    if (kind === "update" && state.defects.has("ROLE_WRITE_INVERTED")) {
+        /* The lattice turned over for updates: the viewer may, the member may not. */
+        if (principal.rank === 1)
+            throw new HttpError(403, "forbidden", "role cannot write");
+        if (principal.rank === 0)
+            return;
+    }
+    if (kind === "delete" && principal.rank < 2)
+        throw new HttpError(403, "forbidden", "role cannot delete");
+    if (kind !== "delete" && principal.rank < 1)
+        throw new HttpError(403, "forbidden", "role cannot write");
+}
+/** A path under another tenant's project is not the caller's. */
+export function assertTenant(principal, projectId) {
+    if (projectId !== undefined && projectId !== principal.projectId) {
+        throw new HttpError(403, "forbidden", "resource belongs to another tenant");
+    }
+}
+function parentOf(state, param) {
+    return state.entities.find((candidate) => candidate.itemParam === param);
+}
+/** Walks a record up its parent chain to the owning tenant, driven by the descriptors. */
+export async function ownedByTenant(state, { entity, record }, principal) {
+    if (entity.fields.some((f) => f.name === TENANT_FIELD))
+        return record[TENANT_FIELD] === principal.projectId;
+    for (const param of entity.parents) {
+        const parentEntity = parentOf(state, param);
+        const link = record[param];
+        if (parentEntity === undefined || (typeof link !== "string" && typeof link !== "number"))
+            continue;
+        const parent = await state.store.byId(parentEntity, link);
+        return parent !== null && ownedByTenant(state, { entity: parentEntity, record: parent }, principal);
+    }
+    return false;
+}
+/**
+ * Every ancestor named in the path must exist, be live, and belong to the caller — and its own
+ * ancestors must be the ones the path names. Without this, a caller could list or write rows of
+ * another tenant's table by placing that table's id under their own project.
+ */
+export async function assertParents(state, call) {
+    const { entity, scope } = call;
+    for (const param of entity.parents) {
+        const parentEntity = parentOf(state, param);
+        if (parentEntity === undefined)
+            continue;
+        const id = scope[param] ?? "";
+        const parent = await state.store.byId(parentEntity, id);
+        /* Under the defect a parent only has to exist: whose it is, and whose path names it, go
+         * unchecked — another tenant's parent id under the caller's own root is let through. */
+        if (parent !== null && state.defects.has("FOREIGN_PARENT_ACCEPTED"))
+            continue;
+        if (parent === null || !(await liveAndOwned(state, { entity: parentEntity, record: parent }, call))) {
+            throw notFound(parentEntity, id);
+        }
+    }
+}
+/* A parent the call's path may name: linked to the path's own ancestors, live, and the caller's. */
+async function liveAndOwned(state, parent, call) {
+    const { entity, record } = parent;
+    const { scope } = call;
+    const linked = entity.parents.every((ancestor) => !entity.fields.some((f) => f.name === ancestor) || record[ancestor] === scope[ancestor]);
+    return linked && !tombstoned(entity, record) && ownedByTenant(state, parent, call.principal);
+}
+/**
+ * A record is served under the path that names its own parents, and no other — all the way up: a
+ * row's table must itself sit under the project the path names.
+ */
+export async function underPath(state, { entity, record }, scope) {
+    const stored = (param) => entity.fields.some((f) => f.name === param);
+    if (entity.parents.some((param) => stored(param) && scope[param] !== undefined && record[param] !== scope[param])) {
+        return false;
+    }
+    const parentParam = entity.parents.toReversed().find((param) => parentOf(state, param) !== undefined);
+    if (parentParam === undefined || !stored(parentParam))
+        return true;
+    const parentEntity = parentOf(state, parentParam);
+    const parent = await state.store.byId(parentEntity, record[parentParam]);
+    return parent !== null && underPath(state, { entity: parentEntity, record: parent }, scope);
+}
+function canReadViaGrant(state, { entity, resourceId }, principal) {
+    if (state.defects.has("INVITE_NEVER_GRANTS"))
+        return false;
+    return [...state.grants.values()].some((grant) => grant.entity === entity &&
+        grant.resourceId === resourceId &&
+        grant.granteeKey === principal.key &&
+        grant.accepted);
+}
+/** The record a caller may read or write under this path, or the refusal a correct backend gives. */
+export async function findItem(state, call, purpose = "read") {
+    const { entity, itemId: id, principal, scope } = call;
+    const { defects } = state;
+    const record = await state.store.byId(entity, id);
+    if (record === null || hiddenFromCreator(defects, entity, record))
+        throw notFound(entity, id);
+    /* Writes looked up by id alone: reads stay scoped, so only a write probe can tell. */
+    if (purpose === "write" && defects.has("CROSS_TENANT_WRITE"))
+        return record;
+    /* A record named under somebody else's parents is not this caller's to read, whoever owns it. */
+    const held = { entity, record };
+    const inPath = await underPath(state, held, scope);
+    const owned = inPath && (await ownedByTenant(state, held, principal));
+    const granted = inPath && canReadViaGrant(state, { entity: entity.name, resourceId: String(id) }, principal);
+    /* The leak is a lookup by id alone: no tenant check, and no check of the path either. */
+    if (!defects.has("CROSS_TENANT_READ") && !owned && !granted) {
+        /* Correct is 404: the same answer an id that never existed would get. Answering 403 here is
+         * the defect — the denial is right, but the *status* confirms the record is real, which is
+         * all an attacker enumerating identifiers needs. */
+        throw defects.has("EXISTENCE_LEAK_VIA_STATUS")
+            ? new HttpError(403, "forbidden", `${entity.name} ${id} belongs to another tenant`)
+            : notFound(entity, id);
+    }
+    if (tombstoned(entity, record))
+        throw notFound(entity, id, "has been deleted");
+    return record;
+}
+//# sourceMappingURL=access.js.map

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

@@ -0,0 +1,27 @@
+/** API keys: minted by a signed-in caller, bound to its tenant, rank and scopes, and revocable. */
+import type { ReferenceState } from "../state.ts";
+import type { ApiKey, Principal } from "./types.ts";
+/** What an operation asks of an API key: the scope it needs, and the tenant its path names, if any. */
+export interface ApiKeyNeed {
+    scope: string;
+    projectId?: string | number | undefined;
+}
+/** A new key for `creator`, holding `scopes`, unnamed until its creator names it. */
+export declare function createApiKey(state: ReferenceState, creator: Principal, scopes: readonly string[]): ApiKey;
+/**
+ * A live key of the caller's tenant by its id. A revoked key is gone, and another tenant's is as absent
+ * as an unknown one: each is a 404.
+ */
+export declare function findApiKey(state: ReferenceState, caller: Principal, id: string): ApiKey;
+/** Revokes a key of the caller's tenant; under KEY_DELETE_CROSS_TENANT, also a live key of another tenant. */
+export declare function revokeApiKey(state: ReferenceState, caller: Principal, id: string): void;
+/** A live key of the caller's tenant that the caller may change: its own, or any when it is the tenant's admin. */
+export declare function ownedApiKey(state: ReferenceState, caller: Principal, id: string): ApiKey;
+/** The caller's tenant's live keys, in the order they were made. */
+export declare function listApiKeys(state: ReferenceState, caller: Principal): ApiKey[];
+/**
+ * Who a live key authenticates as: its creator's rank, in its own tenant, for an operation it holds
+ * the scope of. `need` is `undefined` where a jwt-only route lets keys in anyway.
+ */
+export declare function apiKeyPrincipal(state: ReferenceState, value: string, need: ApiKeyNeed | undefined): Principal;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/api/reference/http/auth/api-keys.js

@@ -0,0 +1,83 @@
+/** API keys: minted by a signed-in caller, bound to its tenant, rank and scopes, and revocable. */
+import { createHmac } from "node:crypto";
+import { HttpError } from "../errors.js";
+/** A new key for `creator`, holding `scopes`, unnamed until its creator names it. */
+export function createApiKey(state, creator, scopes) {
+    const { auth } = state;
+    auth.sequence += 1;
+    const id = `apikey_${String(auth.sequence).padStart(6, "0")}`;
+    const value = `ak_${createHmac("sha256", auth.secret).update(id).digest("hex").slice(0, 32)}`;
+    const key = {
+        id,
+        name: null,
+        projectId: creator.projectId,
+        rank: creator.rank,
+        revoked: false,
+        scopes: [...scopes],
+        sub: creator.key,
+        value,
+    };
+    auth.apiKeys.set(value, key);
+    /* Every key the server issues is one it created, whoever asked for it. */
+    state.ids.noteNamed("api-key", id);
+    return key;
+}
+/**
+ * A live key of the caller's tenant by its id. A revoked key is gone, and another tenant's is as absent
+ * as an unknown one: each is a 404.
+ */
+export function findApiKey(state, caller, id) {
+    const key = [...state.auth.apiKeys.values()].find((item) => item.id === id && item.projectId === caller.projectId && !item.revoked);
+    if (key === undefined)
+        throw new HttpError(404, "not_found", `API key ${id} does not exist`);
+    return key;
+}
+/** Revokes a key of the caller's tenant; under KEY_DELETE_CROSS_TENANT, also a live key of another tenant. */
+export function revokeApiKey(state, caller, id) {
+    const anyTenant = [...state.auth.apiKeys.values()].find((item) => item.id === id && !item.revoked);
+    const foreign = anyTenant !== undefined && anyTenant.projectId !== caller.projectId;
+    if (state.defects.has("KEY_DELETE_CROSS_TENANT") && foreign)
+        anyTenant.revoked = true;
+    else
+        ownedApiKey(state, caller, id).revoked = true;
+}
+/* The tenant's admins rank 2: they manage every key of their tenant, as each creator manages its own. */
+const ADMIN_RANK = 2;
+/** A live key of the caller's tenant that the caller may change: its own, or any when it is the tenant's admin. */
+export function ownedApiKey(state, caller, id) {
+    const key = findApiKey(state, caller, id);
+    if (key.sub !== caller.key && caller.rank < ADMIN_RANK) {
+        throw new HttpError(403, "forbidden", `API key ${id} is not the caller's to change`);
+    }
+    return key;
+}
+/** The caller's tenant's live keys, in the order they were made. */
+export function listApiKeys(state, caller) {
+    return [...state.auth.apiKeys.values()].filter((item) => item.projectId === caller.projectId && !item.revoked);
+}
+/**
+ * Who a live key authenticates as: its creator's rank, in its own tenant, for an operation it holds
+ * the scope of. `need` is `undefined` where a jwt-only route lets keys in anyway.
+ */
+export function apiKeyPrincipal(state, value, need) {
+    const { auth, defects } = state;
+    const key = auth.apiKeys.get(value);
+    if (key === undefined)
+        throw new HttpError(401, "unauthorized", "unknown API key");
+    if ((key.revoked && !defects.has("REVOKED_TOKEN_ACCEPTED")) || auth.killed.has(key.sub)) {
+        throw new HttpError(401, "unauthorized", "API key revoked");
+    }
+    let projectId = key.projectId;
+    const named = need?.projectId;
+    if (named !== undefined && named !== key.projectId) {
+        if (!defects.has("CROSS_TENANT_KEY_ACCEPTED")) {
+            throw new HttpError(403, "forbidden", "the API key belongs to another tenant");
+        }
+        projectId = String(named);
+    }
+    if (need !== undefined && !key.scopes.includes(need.scope) && !defects.has("SCOPE_NOT_CHECKED")) {
+        throw new HttpError(403, "forbidden", `the API key lacks the scope "${need.scope}"`);
+    }
+    return { key: key.sub, projectId, rank: key.rank };
+}
+//# sourceMappingURL=api-keys.js.map

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

@@ -0,0 +1,12 @@
+/** Who a request acts as, by the credential its Authorization header carries: a bearer JWT or an API key. */
+import type { ReferenceState } from "../state.ts";
+import type { ReferenceRequest } from "../wire.ts";
+import { type ApiKeyNeed } from "./api-keys.ts";
+import type { Principal } from "./types.ts";
+export type { ApiKeyNeed } from "./api-keys.ts";
+/**
+ * The caller. Every secured route takes a bearer JWT; a route that also takes an API key passes what
+ * it asks of one as `need`, and any other route refuses keys.
+ */
+export declare function authenticate(state: ReferenceState, request: ReferenceRequest, need?: ApiKeyNeed): Principal;
+//# sourceMappingURL=credentials.d.ts.map

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

@@ -0,0 +1,33 @@
+/** Who a request acts as, by the credential its Authorization header carries: a bearer JWT or an API key. */
+import { HttpError } from "../errors.js";
+import { apiKeyPrincipal } from "./api-keys.js";
+import { accessPrincipal } from "./sessions.js";
+/**
+ * The caller. Every secured route takes a bearer JWT; a route that also takes an API key passes what
+ * it asks of one as `need`, and any other route refuses keys.
+ */
+export function authenticate(state, request, need) {
+    const [scheme = "", value = ""] = (request.headers["authorization"] ?? "").trim().split(/\s+/, 2);
+    if (value === "")
+        throw new HttpError(401, "unauthorized", "missing credential");
+    switch (scheme.toLowerCase()) {
+        case "bearer":
+            return accessPrincipal(state, value);
+        case "apikey":
+            return keyHolder(state, value, need);
+        default:
+            throw new HttpError(401, "unauthorized", "unsupported credential scheme");
+    }
+}
+/* An API key's holder, where this route lets one in. */
+function keyHolder(state, value, need) {
+    const { defects } = state;
+    if (need === undefined && !defects.has("ANY_SCHEME_ACCEPTED")) {
+        throw new HttpError(401, "unauthorized", "this operation does not accept an API key");
+    }
+    if (need !== undefined && defects.has("APIKEY_ALTERNATIVE_BROKEN")) {
+        throw new HttpError(401, "unauthorized", "API keys are not accepted here");
+    }
+    return apiKeyPrincipal(state, value, need);
+}
+//# sourceMappingURL=credentials.js.map

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

@@ -0,0 +1,11 @@
+/** HS256 JSON Web Tokens: signed with the server's secret, read back with whether the signature holds. */
+/** A token's claims, and whether its signature is the server's own over an HS256 header. */
+export interface DecodedJwt {
+    claims: Record<string, unknown>;
+    signed: boolean;
+}
+/** The claims, signed with `secret` as an HS256 JWT. */
+export declare function signJwt(secret: string, claims: Record<string, unknown>): string;
+/** A JWT's claims and whether `secret` signed it; `null` when the text is not a JWT at all. */
+export declare function decodeJwt(secret: string, token: string): DecodedJwt | null;
+//# sourceMappingURL=jwt.d.ts.map