@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/security/issued-secrets.js

@@ -0,0 +1,50 @@
+/**
+ * Secrets a backend issues mid-run: a value it answers under a secret key (a TOTP setup's `secret`,
+ * a fresh API key's `token`) is a credential wherever else it turns up, such as inside an otpauth URI
+ * beside it, in a later request, or quoted in an error. They are found here in every form a record
+ * may show them, so the redactor can scrub them as it scrubs the credentials a run places.
+ */
+import { isSecretJsonKey } from "./credential-names.js";
+/*
+ * A credential, not a word: 16 characters or more whatever they are, since a base32 TOTP secret is
+ * letters alone often enough (26/32 per character) to make a letters rule leak one; 12 to 15 only when
+ * not letters alone, so `Bearer` under `token_type` and a short word under `password_hint` stay.
+ */
+function isCredential(value) {
+    if (value.length >= 16)
+        return true;
+    return value.length >= 12 && !/^[A-Za-z]+$/.test(value);
+}
+/* A base32 secret as an otpauth URI carries it: uppercase, unspaced, unpadded. */
+function base32Form(value) {
+    const compact = value.toUpperCase().replace(/[\s=-]/g, "");
+    return compact !== value && /^[A-Z2-7]+$/.test(compact) ? compact : undefined;
+}
+/** Every value `body` holds under a secret key that reads as a credential, raw and base32-normalized. */
+export function issuedSecrets(body) {
+    const found = new Set();
+    const walk = (value, key) => {
+        if (typeof value === "string") {
+            if (key === undefined || !isSecretJsonKey(key))
+                return;
+            const raw = value.trim();
+            const normal = base32Form(raw);
+            for (const form of [raw, normal])
+                if (form !== undefined && isCredential(form))
+                    found.add(form);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item, key);
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        for (const [child, nested] of Object.entries(value))
+            walk(nested, child);
+    };
+    walk(body, undefined);
+    return [...found];
+}
+//# sourceMappingURL=issued-secrets.js.map

package/dist/api/security/redact.d.ts

@@ -0,0 +1,51 @@
+export declare const REDACTED = "<redacted>";
+/** What one placed credential sends, by name, and the values a redactor must never print. */
+export interface PlacedSecrets {
+    headers: readonly string[];
+    query: readonly string[];
+    cookies: readonly string[];
+    values: readonly string[];
+}
+export declare class Redactor {
+    #private;
+    /** A header a principal injects its credential under: redacted from now on. */
+    registerHeader(name: string): void;
+    /** A query parameter a credential is placed in: its value is redacted from every URL, whatever it is. */
+    registerQuery(name: string): void;
+    /** A cookie a credential is placed in: its value is redacted from every `name=value` pair. */
+    registerCookie(name: string): void;
+    /** Every name and value one placed credential sends. */
+    registerPlacement(secrets: PlacedSecrets): void;
+    /** A credential value the run was issued: scrubbed wherever it appears. Too-short values are ignored. */
+    registerSecret(value: string | undefined): void;
+    /**
+     * Secrets a backend issued in a response `body`, under a secret key: scrubbed from now on wherever
+     * they appear, in this record and every later one, and never sent elsewhere (`holdsSecret`). Only a
+     * response is learned from: a request carries values the run made, such as a generated password.
+     */
+    learn(body: unknown): void;
+    /** Whether `value` carries a registered credential value, whole or inside it: never one to send elsewhere. */
+    holdsSecret(value: string): boolean;
+    isSecretHeader(name: string): boolean;
+    /** `text` with every registered credential value, every registered cookie's value and every otpauth secret replaced. */
+    text(text: string): string;
+    /** A recorded body as it may be written down: text by its media type, anything else as JSON. */
+    body(value: unknown, mediaType: string): unknown;
+    /**
+     * A body that is text, by its media type: a form's fields as `field` redacts them, any other text
+     * scrubbed of registered values. A token endpoint may answer its pair as a form.
+     */
+    textBody(text: string, mediaType: string): string;
+    headers(headers: Record<string, string>): Record<string, string>;
+    /** A form field or urlencoded parameter: redacted when its name is a secret's, scrubbed otherwise. */
+    field(name: string, value: string): string;
+    /**
+     * `value` with secret keys redacted and every registered or issued value scrubbed, wherever it sits.
+     * A body that had anything redacted loses its `data:image/` strings too: a QR code draws the secret
+     * beside it, and no scrub by value reaches the pixels.
+     */
+    json(value: unknown): unknown;
+    /** A URL with registered credentials and secret-named query parameters removed. */
+    url(url: string): string;
+}
+//# sourceMappingURL=redact.d.ts.map

package/dist/api/security/redact.js

@@ -0,0 +1,222 @@
+import { isSecretHeaderName, isSecretJsonKey } from "./credential-names.js";
+import { issuedSecrets } from "./issued-secrets.js";
+/*
+ * One redactor per run, for every place an exchange is written down: the journal, the markdown and
+ * JSON reports, and the repro scripts. Three kinds of secret are caught. Headers by name: the usual
+ * ones, plus whatever header each principal injects its credential under. JSON keys by family:
+ * anything that reads as a token, secret, password, key or session. And credential values the run
+ * was issued, wherever they turn up: echoed in a body, embedded in a URL, quoted in an error.
+ * Every credential a run places registers its header, query and cookie names and its values here,
+ * so whatever the document calls them, they never print. An Authorization header keeps its scheme
+ * word (`Bearer`, `ApiKey`), which says what was sent without saying the secret.
+ */
+export const REDACTED = "<redacted>";
+/* Headers whose value is `<scheme> <credential>`, so the scheme word is no secret. */
+const SCHEMED_HEADERS = /* @__PURE__ */ new Set(["authorization", "proxy-authorization"]);
+/*
+ * An otpauth URI's `secret` parameter, raw and percent-encoded (inside another URL, as a QR service
+ * takes it): a TOTP seed by its scheme alone, whether or not a key beside it named it.
+ */
+const OTPAUTH_SECRET = /(otpauth:\/\/[^\s"'<>?]*\?(?:[^\s"'<>#]*?&)?secret=)[^&#\s"'<>]*/gi;
+const OTPAUTH_SECRET_ENCODED = /(otpauth%3A%2F%2F[^\s"'<>&]*?secret%3D)[^&#%\s"'<>]*/gi;
+/* `application/x-www-form-urlencoded`, with or without parameters. */
+const FORM_MEDIA_TYPE = /^\s*application\/x-www-form-urlencoded\s*(;|$)/i;
+/* A form-encoded name or value as text; a malformed escape is kept as it was sent. */
+function formDecoded(raw) {
+    try {
+        return decodeURIComponent(raw.replaceAll("+", " "));
+    }
+    catch {
+        return raw;
+    }
+}
+/* `value` percent-encoded, RFC 3986 strict and loose, and form-encoded; none for a lone surrogate. */
+function urlForms(value) {
+    let percent;
+    try {
+        percent = encodeURIComponent(value);
+    }
+    catch {
+        return [];
+    }
+    const strict = percent.replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return [percent, strict, new URLSearchParams([["", value]]).toString().slice(1)];
+}
+/* `value` with every `data:image/` string replaced, each key kept. */
+function withoutImages(value) {
+    if (typeof value === "string")
+        return /^data:image\//i.test(value) ? REDACTED : value;
+    if (Array.isArray(value))
+        return value.map(withoutImages);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, withoutImages(child)]));
+}
+export class Redactor {
+    #headers = new Set();
+    #secrets = new Set();
+    #query = new Set();
+    /* A registered cookie's `name=value` pair, by name. */
+    #cookies = new Map();
+    /** A header a principal injects its credential under: redacted from now on. */
+    registerHeader(name) {
+        this.#headers.add(name.toLowerCase());
+    }
+    /** A query parameter a credential is placed in: its value is redacted from every URL, whatever it is. */
+    registerQuery(name) {
+        this.#query.add(name);
+    }
+    /** A cookie a credential is placed in: its value is redacted from every `name=value` pair. */
+    registerCookie(name) {
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        this.#cookies.set(name, new RegExp(`(^|[;,\\s])(${escaped})=[^;,\\s]*`, "g"));
+    }
+    /** Every name and value one placed credential sends. */
+    registerPlacement(secrets) {
+        for (const name of secrets.headers)
+            this.registerHeader(name);
+        for (const name of secrets.query)
+            this.registerQuery(name);
+        for (const name of secrets.cookies)
+            this.registerCookie(name);
+        for (const value of secrets.values)
+            this.registerSecret(value);
+    }
+    /** A credential value the run was issued: scrubbed wherever it appears. Too-short values are ignored. */
+    registerSecret(value) {
+        const trimmed = value?.trim() ?? "";
+        if (trimmed.length < 6)
+            return;
+        this.#addSecret(trimmed);
+        /* A bearer token is also sent bare: register the token itself as well as the header value. */
+        const bare = /^\w+\s+(\S{6,})$/.exec(trimmed)?.[1];
+        if (bare !== undefined)
+            this.#addSecret(bare);
+    }
+    /**
+     * Secrets a backend issued in a response `body`, under a secret key: scrubbed from now on wherever
+     * they appear, in this record and every later one, and never sent elsewhere (`holdsSecret`). Only a
+     * response is learned from: a request carries values the run made, such as a generated password.
+     */
+    learn(body) {
+        for (const value of issuedSecrets(body))
+            this.#addSecret(value);
+    }
+    /* A value as issued and as a URL or a form writes it: a base64 token's `+/=` reach the wire encoded. */
+    #addSecret(value) {
+        for (const written of [value, ...urlForms(value)])
+            this.#secrets.add(written);
+    }
+    /** Whether `value` carries a registered credential value, whole or inside it: never one to send elsewhere. */
+    holdsSecret(value) {
+        for (const secret of this.#secrets)
+            if (value.includes(secret))
+                return true;
+        return false;
+    }
+    isSecretHeader(name) {
+        return isSecretHeaderName(name) || this.#headers.has(name.toLowerCase());
+    }
+    /** `text` with every registered credential value, every registered cookie's value and every otpauth secret replaced. */
+    text(text) {
+        let out = text;
+        for (const secret of this.#secrets) {
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        }
+        for (const pair of this.#cookies.values())
+            out = out.replace(pair, `$1$2=${REDACTED}`);
+        return out.replace(OTPAUTH_SECRET, `$1${REDACTED}`).replace(OTPAUTH_SECRET_ENCODED, `$1${REDACTED}`);
+    }
+    /** A recorded body as it may be written down: text by its media type, anything else as JSON. */
+    body(value, mediaType) {
+        return typeof value === "string" ? this.textBody(value, mediaType) : this.json(value);
+    }
+    /**
+     * A body that is text, by its media type: a form's fields as `field` redacts them, any other text
+     * scrubbed of registered values. A token endpoint may answer its pair as a form.
+     */
+    textBody(text, mediaType) {
+        if (!FORM_MEDIA_TYPE.test(mediaType))
+            return this.text(text);
+        return text
+            .split("&")
+            .map((pair) => this.#formPair(pair))
+            .join("&");
+    }
+    headers(headers) {
+        const out = {};
+        for (const [key, value] of Object.entries(headers))
+            out[key] = this.#headerValue(key, value);
+        return out;
+    }
+    /** A form field or urlencoded parameter: redacted when its name is a secret's, scrubbed otherwise. */
+    field(name, value) {
+        return this.#isSecretParam(name) ? REDACTED : this.text(value);
+    }
+    /**
+     * `value` with secret keys redacted and every registered or issued value scrubbed, wherever it sits.
+     * A body that had anything redacted loses its `data:image/` strings too: a QR code draws the secret
+     * beside it, and no scrub by value reaches the pixels.
+     */
+    json(value) {
+        const seen = { redacted: false };
+        const out = this.#json(value, seen);
+        return seen.redacted ? withoutImages(out) : out;
+    }
+    #json(value, seen) {
+        if (typeof value === "string") {
+            const scrubbed = this.text(value);
+            if (scrubbed !== value)
+                seen.redacted = true;
+            return scrubbed;
+        }
+        if (Array.isArray(value))
+            return value.map((item) => this.#json(item, seen));
+        if (value === null || typeof value !== "object")
+            return value;
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (isSecretJsonKey(key))
+                seen.redacted = true;
+            out[key] = isSecretJsonKey(key) ? REDACTED : this.#json(child, seen);
+        }
+        return out;
+    }
+    /** A URL with registered credentials and secret-named query parameters removed. */
+    url(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return this.text(url);
+        }
+        const entries = Array.from(parsed.searchParams);
+        /* Every occurrence, in place: a repeated parameter stays repeated, so the URL keeps its shape. */
+        if (entries.some(([key]) => this.#isSecretParam(key))) {
+            parsed.search = new URLSearchParams(entries.map(([key, value]) => [key, this.#isSecretParam(key) ? REDACTED : value])).toString();
+        }
+        return this.text(parsed.toString());
+    }
+    #headerValue(name, value) {
+        if (!this.isSecretHeader(name))
+            return this.text(value);
+        const scheme = SCHEMED_HEADERS.has(name.toLowerCase()) ? /^([A-Za-z][\w.-]*)\s+\S/.exec(value)?.[1] : undefined;
+        return scheme === undefined ? REDACTED : `${scheme} ${REDACTED}`;
+    }
+    /* One `name=value` pair, its value redacted as a field; a pair redaction leaves alone keeps its encoding. */
+    #formPair(pair) {
+        const at = pair.indexOf("=");
+        if (at === -1)
+            return this.text(pair);
+        const name = pair.slice(0, at);
+        const value = formDecoded(pair.slice(at + 1));
+        const redacted = this.field(formDecoded(name), value);
+        return redacted === value ? pair : `${name}=${redacted}`;
+    }
+    #isSecretParam(name) {
+        return isSecretJsonKey(name) || this.#query.has(name);
+    }
+}
+//# sourceMappingURL=redact.js.map

package/dist/api/security/strip.d.ts

@@ -0,0 +1,7 @@
+/** The credential header names for a request: the known ones, plus those its principal injects. */
+export declare function credentialHeaderNames(injected?: Iterable<string>): Set<string>;
+/** Removes every credential header, in place, before a request follows a redirect to another origin. */
+export declare function stripCredentials(headers: Record<string, string>, names: ReadonlySet<string>): void;
+/** Removes every placed query parameter, in place, before a request follows a redirect to another origin. */
+export declare function stripQuery(url: URL, names: ReadonlySet<string>): void;
+//# sourceMappingURL=strip.d.ts.map

package/dist/api/security/strip.js

@@ -0,0 +1,18 @@
+import { CREDENTIAL_HEADERS } from "./credential-names.js";
+/** The credential header names for a request: the known ones, plus those its principal injects. */
+export function credentialHeaderNames(injected = []) {
+    return new Set([...CREDENTIAL_HEADERS, ...[...injected].map((name) => name.toLowerCase())]);
+}
+/** Removes every credential header, in place, before a request follows a redirect to another origin. */
+export function stripCredentials(headers, names) {
+    for (const name of Object.keys(headers)) {
+        if (names.has(name.toLowerCase()))
+            delete headers[name];
+    }
+}
+/** Removes every placed query parameter, in place, before a request follows a redirect to another origin. */
+export function stripQuery(url, names) {
+    for (const name of names)
+        url.searchParams.delete(name);
+}
+//# sourceMappingURL=strip.js.map

package/dist/api/spec/allow.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The only operations a run may call.
+ *
+ * Everything else leaves the document before the API tester reads it, so the matrix, the contract floor,
+ * scenarios and teardown cannot reach it: there is nothing to forget to check, because the
+ * operation does not exist as far as the API tester knows. A config that still needs a removed operation —
+ * a recipe's login or refresh step, its mint or revoke, a scenario step — is told so before
+ * anything is sent.
+ */
+import type { PrincipalEntry, Recipe } from "../config/types/security.ts";
+import type { Scenario } from "../config/types/steps.ts";
+import type { OpenApiDocument } from "./types.ts";
+/** The document without the operations `allow` leaves out, what it removed, and the names it kept. */
+export declare function pruneToAllow(doc: OpenApiDocument, allow: readonly string[]): {
+    doc: OpenApiDocument;
+    removed: string[];
+    kept: ReadonlySet<string>;
+};
+/** Recipes by scheme name: the config's `security`, or one principal's overrides of it. */
+type Recipes = Readonly<Record<string, Partial<Recipe>>>;
+/** Every operation the config itself will call by name must survive the allowlist. */
+export declare function assertAllowedReferences(kept: ReadonlySet<string>, config: {
+    security?: Recipes;
+    principals?: Readonly<Record<string, PrincipalEntry>>;
+    scenarios?: readonly Scenario[];
+}): void;
+export {};
+//# sourceMappingURL=allow.d.ts.map

package/dist/api/spec/allow.js

@@ -0,0 +1,83 @@
+/**
+ * The only operations a run may call.
+ *
+ * Everything else leaves the document before the API tester reads it, so the matrix, the contract floor,
+ * scenarios and teardown cannot reach it: there is nothing to forget to check, because the
+ * operation does not exist as far as the API tester knows. A config that still needs a removed operation —
+ * a recipe's login or refresh step, its mint or revoke, a scenario step — is told so before
+ * anything is sent.
+ */
+import { UsageError } from "../errors/usage-error.js";
+import { PATH_ITEM_METHODS as METHODS } from "./methods.js";
+import { operationSlots, resolveOperationName } from "./operation-name.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The document without the operations `allow` leaves out, what it removed, and the names it kept. */
+export function pruneToAllow(doc, allow) {
+    const out = structuredClone(doc);
+    const paths = (out.paths ?? {});
+    const slots = operationSlots(paths);
+    const kept = new Set();
+    const unknown = [];
+    for (const ref of allow) {
+        const name = resolveOperationName(ref, slots);
+        if (name === undefined)
+            unknown.push(ref);
+        else
+            kept.add(name);
+    }
+    if (unknown.length > 0) {
+        throw new UsageError(`allow names ${unknown.map((id) => `"${id}"`).join(", ")}, which the document does not have`);
+    }
+    const removed = [];
+    for (const [name, { item, method }] of slots) {
+        if (kept.has(name))
+            continue;
+        removed.push(name);
+        delete item[method];
+    }
+    for (const [route, item] of Object.entries(paths)) {
+        if (isRecord(item) && !METHODS.some((method) => isRecord(item[method])))
+            delete paths[route];
+    }
+    return { doc: out, kept, removed: removed.sort() };
+}
+/** The operations `steps` call on the document itself that the allowlist removed. */
+function removedCalls(kept, steps) {
+    return steps
+        .filter((step) => "operationId" in step)
+        .filter((step) => step.origin === undefined && !kept.has(step.operationId))
+        .map((step) => step.operationId);
+}
+/* The removed operations one recipe calls by name: its login and refresh steps, its mint and that mint's revoke. */
+function recipeCalls(kept, path, recipe) {
+    const named = (operationId) => operationId === undefined || kept.has(operationId) ? [] : [operationId];
+    return [
+        ...removedCalls(kept, recipe.login?.steps ?? []).map((id) => `${path} login step "${id}"`),
+        ...removedCalls(kept, recipe.refresh?.steps ?? []).map((id) => `${path} refresh step "${id}"`),
+        ...named(recipe.mint?.operationId).map((id) => `${path} mint "${id}"`),
+        ...named(recipe.mint?.revoke).map((id) => `${path} revoke "${id}"`),
+    ];
+}
+function recipesCalls(kept, path, recipes) {
+    return Object.entries(recipes ?? {}).flatMap(([scheme, recipe]) => recipeCalls(kept, `${path}.${scheme}`, recipe));
+}
+function scenarioProblems(kept, scenario) {
+    if (scenario.origin !== undefined)
+        return [];
+    return [
+        ...removedCalls(kept, scenario.steps).map((id) => `scenario "${scenario.id}" step "${id}"`),
+        ...scenario.covers.filter((id) => !kept.has(id)).map((id) => `scenario "${scenario.id}" covers "${id}"`),
+    ];
+}
+/** Every operation the config itself will call by name must survive the allowlist. */
+export function assertAllowedReferences(kept, config) {
+    const problems = [
+        ...recipesCalls(kept, "security", config.security),
+        ...Object.entries(config.principals ?? {}).flatMap(([id, principal]) => recipesCalls(kept, `principals.${id}.security`, principal.security)),
+        ...(config.scenarios ?? []).flatMap((scenario) => scenarioProblems(kept, scenario)),
+    ];
+    if (problems.length > 0) {
+        throw new UsageError(`allow removes operations the config still calls: ${[...new Set(problems)].join("; ")}`);
+    }
+}
+//# sourceMappingURL=allow.js.map

package/dist/api/spec/collection/cursor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The cursor a list response gives for its next page, as the next request sends it. A server may give
+ * it as text or as a number (a `created_at` keyset, a row id); either is sent back as text. Anything
+ * else, an empty string or null included, means no next page.
+ */
+export declare function nextCursorOf(value: unknown): string | undefined;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/api/spec/collection/cursor.js

@@ -0,0 +1,11 @@
+/**
+ * The cursor a list response gives for its next page, as the next request sends it. A server may give
+ * it as text or as a number (a `created_at` keyset, a row id); either is sent back as text. Anything
+ * else, an empty string or null included, means no next page.
+ */
+export function nextCursorOf(value) {
+    if (typeof value === "string")
+        return value === "" ? undefined : value;
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+}
+//# sourceMappingURL=cursor.js.map

package/dist/api/spec/collection/effective.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A schema as the instance sees it: `allOf` members merged into one object, and a nullable union
+ * — `type: ["array", "null"]`, or `anyOf` / `oneOf` with a `null` branch — read as its one
+ * non-null branch. A collection or an identity declared through either is still one.
+ */
+import type { JsonSchema } from "../types.ts";
+export declare function asSchema(value: unknown): JsonSchema | null;
+export declare function effective(schema: JsonSchema | null): JsonSchema | null;
+//# sourceMappingURL=effective.d.ts.map

package/dist/api/spec/collection/effective.js

@@ -0,0 +1,49 @@
+/**
+ * A schema as the instance sees it: `allOf` members merged into one object, and a nullable union
+ * — `type: ["array", "null"]`, or `anyOf` / `oneOf` with a `null` branch — read as its one
+ * non-null branch. A collection or an identity declared through either is still one.
+ */
+export function asSchema(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+/** The non-null branches of the first `anyOf` / `oneOf` the schema has, when it has one. */
+function nonNullBranches(schema) {
+    return ["anyOf", "oneOf"]
+        .map((key) => (Array.isArray(schema[key]) ? schema[key] : null))
+        .find((branches) => branches !== null)
+        ?.filter((branch) => branch?.type !== "null");
+}
+/** `type: [x, "null"]` read as `type: x`. */
+function withoutNullType(schema) {
+    const types = Array.isArray(schema.type) ? schema.type.filter((type) => type !== "null") : null;
+    return types !== null && types.length === 1 ? { ...schema, type: types[0] } : schema;
+}
+function mergeAllOf(typed, parts) {
+    const merged = { ...typed, allOf: undefined };
+    for (const part of parts) {
+        const member = effective(asSchema(part));
+        if (member === null)
+            continue;
+        merged.type ??= member.type;
+        merged.properties = {
+            ...member.properties,
+            ...merged.properties,
+        };
+        merged.required = [...new Set([...(merged.required ?? []), ...(member.required ?? [])])];
+        if (merged.items === undefined && member.items !== undefined)
+            merged.items = member.items;
+    }
+    delete merged.allOf;
+    return merged;
+}
+export function effective(schema) {
+    if (schema === null)
+        return null;
+    const nonNull = nonNullBranches(schema);
+    /* The one branch left is there: it is what the length counts. */
+    if (nonNull !== undefined && nonNull.length === 1)
+        return effective(nonNull[0]);
+    const typed = withoutNullType(schema);
+    return Array.isArray(typed.allOf) ? mergeAllOf(typed, typed.allOf) : typed;
+}
+//# sourceMappingURL=effective.js.map

package/dist/api/spec/collection/identity.d.ts

@@ -0,0 +1,13 @@
+/** The property that identifies an instance of an entity. */
+import type { JsonSchema } from "../types.ts";
+/**
+ * Finds the property that identifies an instance: the one the item route's own parameter names
+ * when the schema has it (`{noteId}` → `id`), then a required identity-like property, then any
+ * identity-like property, then the parameter's implied name. The route comes first because
+ * teardown deletes through it: a `name` that is merely required would put a display value in the
+ * delete path, whose 404 counts as removed while the real record stays behind.
+ */
+export declare function deriveIdentity(raw: JsonSchema | null, pathParamHint?: string, 
+/** The route ends in that parameter, so it names this item rather than a parent. */
+itemRoute?: boolean): string | null;
+//# sourceMappingURL=identity.d.ts.map

package/dist/api/spec/collection/identity.js

@@ -0,0 +1,43 @@
+/** The property that identifies an instance of an entity. */
+import { effective } from "./effective.js";
+const IDENTITY_CANDIDATES = ["id", "uuid", "slug", "key", "name"];
+/** `{table_id}` or `{tableId}` on `/tables/…` implies the item's own key is `id`; `undefined` otherwise. */
+function hintedKey(pathParamHint) {
+    if (pathParamHint === undefined)
+        return undefined;
+    const implied = pathParamHint
+        .replace(/^.*[_.-]/, "")
+        .replace(/^[a-z0-9]+(?=[A-Z])/, "")
+        .toLowerCase();
+    return IDENTITY_CANDIDATES.includes(implied) ? implied : undefined;
+}
+/** A required identity-like property, else any identity-like property the schema has. */
+function identityProperty(itemSchema, names) {
+    const required = Array.isArray(itemSchema.required) ? itemSchema.required : [];
+    return (IDENTITY_CANDIDATES.find((candidate) => required.includes(candidate)) ??
+        IDENTITY_CANDIDATES.find((candidate) => names.includes(candidate)));
+}
+/**
+ * Finds the property that identifies an instance: the one the item route's own parameter names
+ * when the schema has it (`{noteId}` → `id`), then a required identity-like property, then any
+ * identity-like property, then the parameter's implied name. The route comes first because
+ * teardown deletes through it: a `name` that is merely required would put a display value in the
+ * delete path, whose 404 counts as removed while the real record stays behind.
+ */
+export function deriveIdentity(raw, pathParamHint, 
+/** The route ends in that parameter, so it names this item rather than a parent. */
+itemRoute = true) {
+    const hinted = hintedKey(pathParamHint);
+    const itemSchema = effective(raw);
+    const props = itemSchema?.properties;
+    if (itemSchema !== null && props !== null && typeof props === "object") {
+        const names = Object.keys(props);
+        if (itemRoute && hinted !== undefined && names.includes(hinted))
+            return hinted;
+        const found = identityProperty(itemSchema, names);
+        if (found !== undefined)
+            return found;
+    }
+    return hinted ?? null;
+}
+//# sourceMappingURL=identity.js.map

package/dist/api/spec/collection/request.d.ts

@@ -0,0 +1,19 @@
+/** The request body an operation takes: which media type the API tester sends, and its schema. */
+import type { OperationObject, JsonSchema } from "../types.ts";
+export interface RequestContent {
+    mediaType: string;
+    schema: JsonSchema;
+    encoding?: Record<string, {
+        contentType?: string;
+    }>;
+}
+/**
+ * The request body the API tester sends: `preferred` when the operation documents it, else the best-ranked
+ * one. Prefers multipart, then urlencoded, then JSON, then the first listed type: file ops often
+ * document both JSON and a form, and the form is the real contract. A form that cannot carry the
+ * body (`formCarries`) gives way to JSON documented beside it.
+ */
+export declare function requestContent(op: OperationObject, preferred?: string): RequestContent | null;
+export declare function hasRequestBody(op: OperationObject): boolean;
+export declare function requestSchema(op: OperationObject): JsonSchema | null;
+//# sourceMappingURL=request.d.ts.map