@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/security/privileged-signup.js

@@ -0,0 +1,227 @@
+/*
+ * The sign-up side of auth.privileged-field-ignored. Anyone may sign up, so a sign-up must not make
+ * an account holding a property only the highest rank may set. The API tester signs one account up through the
+ * document's sign-up (the operation marked x-fresh-principal, or one it leaves unmarked): a body
+ * generated from its schema, each marked property set to the value that grants the privilege. Then
+ * it reads back whether that took, by the first read that shows it: the account's own read, the
+ * listing of the entity the sign-up makes, or the property in the sign-up's own answer. With none
+ * that could show it, nothing is sent. The sign-up goes through the client, so the run's ledger names
+ * the account before it goes, and teardown removes it as it removes any account the run made, or
+ * names it a leftover.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { messageOf } from "../../../../errors/message.js";
+import { requestSchema } from "../../../../spec/collection/request.js";
+import { successSchema } from "../../../../spec/collection/responses.js";
+import { propertySchema } from "../../../../spec/extensions/privileged.js";
+import { accountIdentity } from "../../../accounts/identity.js";
+import { makesAccount, SELF_IDENTITY } from "../../../../spec/sign-up.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { buildCohort } from "../../../fixture.js";
+import { selfReadIds } from "../../../self/operations.js";
+import { recordOf, recordsFromList } from "../../../world/records.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+const CHECK = "auth.privileged-field-ignored";
+/** Whether the operation signs an account up: marked x-fresh-principal, or a sign-up the document leaves unmarked. */
+export function isSignUp(ctx) {
+    return makesAccount(ctx.operation, ctx.model);
+}
+/** What the sign-up probe sends and reads; a stand-down naming what is missing, before anything is sent. */
+export function signUpPlan(ctx) {
+    /* The model holds every operation it lists; a marked property implies a request body. */
+    const raw = ctx.model.rawOperations.get(ctx.operation.operationId);
+    const schema = requestSchema(raw);
+    return andThen(valuesOf(ctx, schema), (values) => andThen(bodyOf(ctx, { schema, values }), (body) => {
+        const reads = readBacks(ctx, { body, paths: values.map(([path]) => path), raw });
+        if (reads.length > 0)
+            return ready({ body, kind: "signup", reads, values });
+        return cannot(`a read that shows ${values.map(([path]) => path).join(", ")} of the account ${ctx.operation.operationId} ` +
+            "makes: the account's own read (x-entity identity self), a listing of the entity it makes, or its own answer");
+    }));
+}
+/*
+ * The value each marked property is set to: its `const`, its enum's one member, or `true` for a
+ * boolean. Any other property says nothing of which value is privileged, and the API tester never guesses one.
+ */
+function valuesOf(ctx, schema) {
+    const values = [];
+    for (const path of ctx.operation.privileged) {
+        const property = propertySchema(schema, path);
+        if (property !== undefined && Object.hasOwn(property, "const"))
+            values.push([path, property.const]);
+        else if (Array.isArray(property?.enum) && property.enum.length === 1)
+            values.push([path, property.enum[0]]);
+        else if (property?.type === "boolean")
+            values.push([path, true]);
+        else
+            return cannot(`${path}: no value the API tester can tell is privileged (no const, no one-member enum, not a boolean)`);
+    }
+    return ready(values);
+}
+/* One baseline member of the sign-up's schema, under the run's seed and a nonce of its own, with each value set. */
+function bodyOf(ctx, { schema, values }) {
+    const { operationId } = ctx.operation;
+    let body;
+    try {
+        /* One variant asked for, one member back, and its body is always an object. */
+        const [member] = buildCohort(schema, ctx.seed, {
+            defs: ctx.model.defs,
+            nonce: `${ctx.nonce}privileged`,
+            operationId,
+            variants: ["baseline"],
+        });
+        body = member.body;
+    }
+    catch (error) {
+        /* A schema no body satisfies: buildCohort throws a FixtureOverflow naming why. */
+        return cannot(`a valid sign-up body for ${operationId}: ${messageOf(error)}`);
+    }
+    for (const [path, value] of values) {
+        const keys = path.split(".");
+        const parent = keys.length === 1 ? body : valueAt(body, keys.slice(0, -1).join("."));
+        if (!isFields(parent))
+            return cannot(`a sign-up body that holds the object ${path} sits in`);
+        parent[keys.at(-1)] = value;
+    }
+    return ready(body);
+}
+/* Each read whose answer declares every marked path, in the order they are tried. */
+function readBacks(ctx, { body, paths, raw }) {
+    const reads = [];
+    const self = selfReadOf(ctx.model, paths);
+    if (self !== undefined)
+        reads.push({ kind: "self", op: self });
+    const listing = listingOf(ctx, { body, paths });
+    if (listing !== undefined)
+        reads.push(listing);
+    if (declares(successSchema(raw), ctx.operation.recordPath, paths))
+        reads.push({ kind: "answer" });
+    return reads;
+}
+/* The caller's own read, a GET of the self-identity entity naming no record, whose answer declares every path. */
+function selfReadOf(model, paths) {
+    const reads = [...model.entities.values()]
+        .filter((entity) => entity.identity === SELF_IDENTITY)
+        /* An entity's reads name operations of the model. */
+        .flatMap((entity) => selfReadIds(entity).map((id) => model.byOperationId.get(id)));
+    return reads.find((op) => op.method.toUpperCase() === "GET" &&
+        op.pathParams.length === 0 &&
+        declares(successSchema(model.rawOperations.get(op.operationId)), op.recordPath, paths));
+}
+/*
+ * The listing of the entity the sign-up makes, when its rows declare every path and the body names
+ * the account to find its row by; sent as the highest-ranked principal, its scope filling the path.
+ */
+function listingOf(ctx, { body, paths }) {
+    const list = ctx.model.entities.get(ctx.operation.entity ?? "")?.list;
+    /* An entity's list names an operation of the model. */
+    const op = list === undefined ? undefined : ctx.model.byOperationId.get(list);
+    const rows = op?.collection?.itemSchema ?? null;
+    if (op === undefined || !paths.every((path) => propertySchema(rows, path) !== undefined))
+        return undefined;
+    const identity = accountIdentity(body);
+    if (Object.keys(identity).length === 0)
+        return undefined;
+    const as = ctx.principals.toSorted((a, b) => b.rank - a.rank)[0];
+    if (!op.pathParams.every((param) => Object.hasOwn(as.scope, param)))
+        return undefined;
+    return { as, identity, kind: "listing", op, path: fillPath(op.path, as.scope) };
+}
+/* Where `x-entity.recordPath` keeps the record, as a dotted prefix: `$.data` is `data.`; a path through rows is none. */
+const RECORD_PATH = /^\$((?:\.[^.[\]\s]+)*)$/;
+/* Whether the answer's schema declares every path in the record. */
+function declares(schema, recordPath, paths) {
+    const match = RECORD_PATH.exec(recordPath ?? "$");
+    if (match === null)
+        return false;
+    const prefix = match[1].split(".").filter(Boolean);
+    return paths.every((path) => propertySchema(schema, [...prefix, path].join(".")) !== undefined);
+}
+/**
+ * Signs the account up, anonymously as any sign-up is sent, and judges by the first read that shows
+ * it: a marked property holding the value it was set to is the finding. A sign-up refused made no
+ * account with it, which passes; a server error leaves it unresolved.
+ */
+export async function signUpAndJudge(ctx, probe) {
+    const { method, operationId, path, requiredQuery: query } = ctx.operation;
+    const names = probe.values.map(([field]) => field).join(", ");
+    const signUp = await ctx.client.request(method, path, {
+        as: { anonymous: true },
+        body: probe.body,
+        operationId,
+        query,
+    });
+    if (signUp.status >= 500) {
+        return ctx.findings.unresolved(CHECK, ctx.subject, `a sign-up that set ${names} drew ${signUp.status}, a server error`);
+    }
+    if (signUp.status >= 300)
+        return ASSERTED;
+    const reasons = [];
+    for (const read of probe.reads) {
+        const shown = await readBack(ctx, { probe, read, signUp });
+        if ("untested" in shown)
+            reasons.push(shown.untested);
+        else
+            return judged(ctx, { probe, shown, signUp });
+    }
+    return standDown(`no read showed ${names} of the account ${operationId} made: ${reasons.join("; ")}`);
+}
+async function readBack(ctx, { probe, read, signUp }) {
+    const { operationId } = ctx.operation;
+    if (read.kind === "answer") {
+        return showing(probe, {
+            evidence: [],
+            from: `${operationId}'s answer`,
+            record: recordOf(ctx.operation, signUp.responseBody),
+        });
+    }
+    const { op } = read;
+    const as = read.kind === "self" ? await ctx.accounts.signIn(signUp, op) : { principal: read.as.id };
+    if ("untested" in as)
+        return { untested: `${op.operationId}: ${as.untested}` };
+    const path = read.kind === "self" ? op.path : read.path;
+    const exchange = await ctx.client.get(path, { as, operationId: op.operationId, query: op.requiredQuery });
+    if (exchange.status >= 300)
+        return { untested: `${op.operationId} answered ${exchange.status}` };
+    if (read.kind === "self") {
+        return showing(probe, {
+            evidence: [exchange],
+            from: `the account's own ${op.operationId}`,
+            record: recordOf(op, exchange.responseBody),
+        });
+    }
+    const row = recordsFromList(exchange.responseBody, op.collection).find((one) => Object.entries(read.identity).every(([key, value]) => one[key] === value));
+    if (row === undefined)
+        return { untested: `${op.operationId} as ${read.as.id} did not list the account` };
+    return showing(probe, { evidence: [exchange], from: `${op.operationId} as ${read.as.id}`, record: row });
+}
+/* The read, when its record holds every marked path; else why it shows nothing. */
+function showing(probe, shown) {
+    const { record } = shown;
+    const missing = probe.values.map(([path]) => path).filter((path) => valueAt(record, path) === undefined);
+    if (record === undefined || missing.length > 0)
+        return { untested: `${shown.from} did not show ${missing.join(", ")}` };
+    return { ...shown, record };
+}
+function judged(ctx, { probe, shown, signUp }) {
+    const { operationId } = ctx.operation;
+    const took = probe.values.filter(([path, value]) => isDeepStrictEqual(valueAt(shown.record, path), value));
+    if (took.length === 0)
+        return ASSERTED;
+    const set = took.map(([path, value]) => `${path} to ${JSON.stringify(value)}`).join(", ");
+    return ctx.findings.security(CHECK, ctx.subject, {
+        detail: `An anonymous sign-up by ${operationId} set ${set}, marked x-privileged; ${operationId} answered ` +
+            `${signUp.status} and ${shown.from} shows the account holding it. Anyone who signs up gets a ` +
+            "privilege only the highest rank may grant.",
+        evidence: [signUp, ...shown.evidence],
+        summary: `${operationId} grants ${took.map(([path]) => path).join(", ")}, marked x-privileged, to whoever signs up`,
+    });
+}
+function isFields(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function valueAt(value, path) {
+    return path.split(".").reduce((at, key) => (isFields(at) ? at[key] : undefined), value);
+}
+//# sourceMappingURL=privileged-signup.js.map

package/dist/api/runtime/checks/families/security/probing.d.ts

@@ -0,0 +1,77 @@
+import type { Actor } from "../../../../client/credential-source.ts";
+import type { RequestOptions } from "../../../../client/types.ts";
+import type { Exchange } from "../../../exchange.ts";
+import { type Outcome } from "../../../finding.ts";
+import type { SpecModel } from "../../../../spec/graph/types.ts";
+import type { Requirement, ResolvedSecurity } from "../../../../spec/security/requirements.ts";
+import type { CheckId } from "../../../check-ids.ts";
+import type { Actor as Principal } from "../../core/context.ts";
+import type { OperationContext } from "../../core/operation-context.ts";
+import { type Plan } from "../../core/plan.ts";
+/** Where a probe of the operation goes, and the body it carries. */
+export interface Address {
+    path: string;
+    body?: unknown;
+    contentType?: string;
+}
+/** A client either stage hands a check: a read-only one sends reads alone. */
+interface Sender {
+    request(method: string, path: string, options: RequestOptions): Promise<Exchange>;
+}
+/** What `send` needs of a context. */
+export type Sending = Pick<OperationContext, "operation"> & {
+    client: Sender;
+};
+/** Stands down where the document declares no security: a refusal is due only where one is declared. */
+export declare function declaredPlan(ctx: Pick<OperationContext, "operation">): Plan<undefined>;
+/** Stands down unless the security is declared and requires a credential: only then is a refusal due. */
+export declare function securedPlan(ctx: Pick<OperationContext, "operation" | "security" | "subject">): Plan<undefined>;
+/**
+ * Who an acceptance probe acts as, and the control it is compared with: the target record's creator,
+ * so the outcome it expects is acceptance. A record another principal made is no proof the actor may
+ * read it. With no target, or one whose creator is no principal of the run, the actor. A refusal
+ * probe keeps its own sender: nobody, a forged credential, another scheme, or a deliberate peer.
+ */
+export declare function acceptorOf(ctx: Pick<OperationContext, "actor" | "principals" | "target">): Principal;
+/**
+ * Where the probe goes, by its placement: a collection read under the actor's scope; a read of one
+ * record, or a write, to the run-created target alone, never anywhere else.
+ */
+export declare function addressOf(ctx: OperationContext): Plan<Address>;
+/** The operation's path under the actor's scope, or a stand-down naming the parameters it lacks. */
+export declare function scopedAddress(ctx: Pick<OperationContext, "actor" | "operation">): Plan<Address>;
+/**
+ * Sends one probe of the operation as `as`. A probe that expects a refusal (the default) is marked
+ * one, so the client never refreshes or retries its 401; an `answer` is sent as any request is.
+ */
+export declare function send(ctx: Sending, address: Address, as: Actor, expects?: "refusal" | "answer"): Promise<Exchange>;
+/** Whether a status refuses the request's credential. */
+export declare function refused(status: number): boolean;
+/** Why a refusal probe answered 400 or 422 proves nothing: see `byValidation`. */
+export declare const BY_VALIDATION = "refused by validation before authorization could be observed";
+/**
+ * Whether the answer came from validation: 400 or 422. Never a pass, since an API that validates
+ * before it authenticates would hide an unguarded route behind it; the probe is inconclusive.
+ */
+export declare function byValidation(status: number): boolean;
+/** Whether the security lets an anonymous caller in: `[]`, or an empty alternative. */
+export declare function allowsAnonymous(security: ResolvedSecurity): boolean;
+/** The alternatives of exactly one scheme, the first of each scheme: what one credential satisfies alone. */
+export declare function singleSchemes(security: Pick<ResolvedSecurity, "alternatives">): Requirement[];
+/** Every declared scheme an operation of the document names, with the scopes it is first named with. */
+export declare function documentSchemes(model: SpecModel): Requirement[];
+/** The security in words: `jwt, or apiKey with notes:read`. */
+export declare function describeSecurity(security: Pick<ResolvedSecurity, "alternatives">): string;
+/** One probe that must be refused: its answer, what it sent in the reader's terms, and the finding's line. */
+export interface Refusal {
+    exchange: Exchange;
+    sent: string;
+    summary: string;
+}
+/**
+ * The verdict on probes that must each be refused: SECURITY for every one answered with a success,
+ * unresolved when one drew neither a refusal nor a success, else asserted.
+ */
+export declare function judgeRefusals(ctx: Pick<OperationContext, "findings" | "security" | "subject">, check: CheckId, probes: readonly Refusal[]): Outcome;
+export {};
+//# sourceMappingURL=probing.d.ts.map

package/dist/api/runtime/checks/families/security/probing.js

@@ -0,0 +1,148 @@
+/*
+ * What the security checks share: where a probe of an operation goes, how it is sent, and how a probe
+ * that must be refused is judged. A collection read is probed under the actor's own scope; a read of
+ * one record, or a write, only on the record the run created (`ctx.target`). A write's body is that
+ * record's current state cut to what the request accepts (`writableBody`): harmless if a broken API
+ * applies it, and never a readOnly property a strict one refuses before it judges the caller.
+ */
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED } from "../../../finding.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { targetPlan } from "../../core/operation.js";
+import { andThen, cannot, ready, when } from "../../core/plan.js";
+import { currentOf, writableBody } from "./writable.js";
+/** Stands down where the document declares no security: a refusal is due only where one is declared. */
+export function declaredPlan(ctx) {
+    const undeclared = noSecurityReason(ctx.operation);
+    return undeclared === undefined ? ready(undefined) : cannot(undeclared);
+}
+/** Stands down unless the security is declared and requires a credential: only then is a refusal due. */
+export function securedPlan(ctx) {
+    return andThen(declaredPlan(ctx), () => when(!allowsAnonymous(ctx.security), `an operation that requires a credential; ${ctx.subject} lets anonymous callers in`));
+}
+/**
+ * Who an acceptance probe acts as, and the control it is compared with: the target record's creator,
+ * so the outcome it expects is acceptance. A record another principal made is no proof the actor may
+ * read it. With no target, or one whose creator is no principal of the run, the actor. A refusal
+ * probe keeps its own sender: nobody, a forged credential, another scheme, or a deliberate peer.
+ */
+export function acceptorOf(ctx) {
+    const owner = ctx.target?.owner;
+    return ctx.principals.find((principal) => principal.id === owner) ?? ctx.actor;
+}
+/**
+ * Where the probe goes, by its placement: a collection read under the actor's scope; a read of one
+ * record, or a write, to the run-created target alone, never anywhere else.
+ */
+export function addressOf(ctx) {
+    if (ctx.placement === "read")
+        return scopedAddress(ctx);
+    return andThen(targetPlan(ctx), (target) => targetAddress(ctx, target));
+}
+/** The operation's path under the actor's scope, or a stand-down naming the parameters it lacks. */
+export function scopedAddress(ctx) {
+    const { actor, operation } = ctx;
+    const missing = operation.pathParams.filter((name) => !Object.hasOwn(actor.scope, name));
+    return andThen(when(missing.length === 0, `a value for ${missing.join(" and ")} in ${operation.operationId}'s path`), () => ready({ path: fillPath(operation.path, actor.scope) }));
+}
+/* The target's path, and for a write that takes a body, the target's current state as that body. */
+function targetAddress(ctx, target) {
+    if (ctx.placement !== "write" || !ctx.operation.hasRequestBody)
+        return ready({ path: target.path });
+    const record = currentOf(target);
+    if (record === undefined)
+        return cannot("the target record's current state, for a harmless body");
+    return ready({ body: writableBody(ctx, record), path: target.path });
+}
+/**
+ * Sends one probe of the operation as `as`. A probe that expects a refusal (the default) is marked
+ * one, so the client never refreshes or retries its 401; an `answer` is sent as any request is.
+ */
+export function send(ctx, address, as, expects = "refusal") {
+    const { operation } = ctx;
+    const options = { as, operationId: operation.operationId };
+    if (expects === "refusal")
+        options.probe = true;
+    if (Object.keys(operation.requiredQuery).length > 0)
+        options.query = { ...operation.requiredQuery };
+    if (address.body !== undefined)
+        options.body = address.body;
+    if (address.contentType !== undefined)
+        options.contentType = address.contentType;
+    return ctx.client.request(operation.method.toUpperCase(), address.path, options);
+}
+/** Whether a status refuses the request's credential. */
+export function refused(status) {
+    return status === 401 || status === 403;
+}
+/** Why a refusal probe answered 400 or 422 proves nothing: see `byValidation`. */
+export const BY_VALIDATION = "refused by validation before authorization could be observed";
+/**
+ * Whether the answer came from validation: 400 or 422. Never a pass, since an API that validates
+ * before it authenticates would hide an unguarded route behind it; the probe is inconclusive.
+ */
+export function byValidation(status) {
+    return status === 400 || status === 422;
+}
+/** Whether the security lets an anonymous caller in: `[]`, or an empty alternative. */
+export function allowsAnonymous(security) {
+    return security.alternatives.some((alternative) => alternative.length === 0);
+}
+/** The alternatives of exactly one scheme, the first of each scheme: what one credential satisfies alone. */
+export function singleSchemes(security) {
+    const seen = new Set();
+    const single = [];
+    for (const [requirement, ...rest] of security.alternatives) {
+        if (requirement === undefined || rest.length > 0 || seen.has(requirement.scheme))
+            continue;
+        seen.add(requirement.scheme);
+        single.push(requirement);
+    }
+    return single;
+}
+/** Every declared scheme an operation of the document names, with the scopes it is first named with. */
+export function documentSchemes(model) {
+    const first = new Map();
+    for (const { security } of model.operations) {
+        for (const requirement of security.alternatives.flat()) {
+            if (security.undeclared.includes(requirement.scheme) || first.has(requirement.scheme))
+                continue;
+            first.set(requirement.scheme, requirement);
+        }
+    }
+    return [...first.values()];
+}
+/** The security in words: `jwt, or apiKey with notes:read`. */
+export function describeSecurity(security) {
+    return security.alternatives
+        .map((alternative) => (alternative.length === 0 ? "no credential" : alternative.map(described).join(" and ")))
+        .join(", or ");
+}
+/* One scheme in words, with the scopes it must carry. */
+function described({ scheme, scopes }) {
+    return scopes.length === 0 ? scheme : `${scheme} with ${scopes.join(" ")}`;
+}
+/**
+ * The verdict on probes that must each be refused: SECURITY for every one answered with a success,
+ * unresolved when one drew neither a refusal nor a success, else asserted.
+ */
+export function judgeRefusals(ctx, check, probes) {
+    const accepted = probes.filter(({ exchange }) => exchange.status >= 200 && exchange.status < 300);
+    let outcome = ASSERTED;
+    for (const { exchange, sent, summary } of accepted) {
+        outcome = ctx.findings.security(check, ctx.subject, {
+            detail: `${ctx.subject} answered ${exchange.status} to ${sent}. The document requires ${describeSecurity(ctx.security)}.`,
+            evidence: [exchange],
+            summary,
+        });
+    }
+    if (accepted.length > 0)
+        return outcome;
+    const other = probes.find(({ exchange }) => !refused(exchange.status));
+    if (other === undefined)
+        return ASSERTED;
+    const why = byValidation(other.exchange.status) ? BY_VALIDATION : "neither a refusal nor a success";
+    const reason = `${ctx.subject} answered ${other.exchange.status} to ${other.sent}: ${why}`;
+    return ctx.findings.unresolved(check, ctx.subject, reason);
+}
+//# sourceMappingURL=probing.js.map

package/dist/api/runtime/checks/families/security/writable.d.ts

@@ -0,0 +1,19 @@
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import { type Record_ } from "../../../world/records.ts";
+import type { OperationContext, WriteTarget } from "../../core/operation-context.ts";
+/** The GET that shares the operation's path: how the record it writes is read back. */
+export declare function readOf(ctx: OperationContext): OperationModel | undefined;
+/**
+ * The target's record as the stage read it back: already out of any envelope its read declares, so
+ * never unwrapped again. Undefined when the read showed no record.
+ */
+export declare function currentOf(target: WriteTarget): Record_ | undefined;
+/** The record an answer of the record's read holds (`x-entity.recordPath`), or undefined. */
+export declare function recordAt(ctx: OperationContext, body: unknown): Record_ | undefined;
+/**
+ * `record`'s properties that any writer may send by the operation's request schema: declared, not
+ * `readOnly`, and not an optional property marked x-privileged, which only the highest rank may set.
+ * A schema that names no properties says nothing to cut by, so the record goes as it is.
+ */
+export declare function writableBody(ctx: OperationContext, record: Record_): Record_;
+//# sourceMappingURL=writable.d.ts.map

package/dist/api/runtime/checks/families/security/writable.js

@@ -0,0 +1,40 @@
+/*
+ * A write probe's harmless body: the record as it is now, cut to what the operation's request body
+ * accepts from any writer. Sending the whole record would carry `readOnly` fields (an id, a
+ * timestamp) that a strict API rightly refuses with a 400, and x-privileged ones it refuses with a
+ * 403, before it ever judges who is writing.
+ */
+import { requestContent } from "../../../../spec/collection/request.js";
+import { ordinaryRequestSchema } from "../../../fixture.js";
+import { recordOf } from "../../../world/records.js";
+/** The GET that shares the operation's path: how the record it writes is read back. */
+export function readOf(ctx) {
+    return ctx.model.operations.find((op) => op.method.toUpperCase() === "GET" && op.path === ctx.operation.path);
+}
+/**
+ * The target's record as the stage read it back: already out of any envelope its read declares, so
+ * never unwrapped again. Undefined when the read showed no record.
+ */
+export function currentOf(target) {
+    const { current } = target;
+    return typeof current === "object" && current !== null && !Array.isArray(current) ? current : undefined;
+}
+/** The record an answer of the record's read holds (`x-entity.recordPath`), or undefined. */
+export function recordAt(ctx, body) {
+    return recordOf(readOf(ctx) ?? ctx.operation, body);
+}
+/**
+ * `record`'s properties that any writer may send by the operation's request schema: declared, not
+ * `readOnly`, and not an optional property marked x-privileged, which only the highest rank may set.
+ * A schema that names no properties says nothing to cut by, so the record goes as it is.
+ */
+export function writableBody(ctx, record) {
+    /* The model holds every operation it lists. */
+    const raw = ctx.model.rawOperations.get(ctx.operation.operationId);
+    const content = requestContent(raw);
+    if (content?.schema.properties === undefined)
+        return { ...record };
+    const properties = ordinaryRequestSchema(content.schema).properties;
+    return Object.fromEntries(Object.entries(record).filter(([name]) => Object.hasOwn(properties, name)));
+}
+//# sourceMappingURL=writable.js.map

package/dist/api/runtime/checks/families/sort/sort-default-order-applied.d.ts

@@ -0,0 +1,5 @@
+import type { Check } from "../../core/check.ts";
+export declare const sortDefaultOrderApplied: Check<{
+    defaultOrder: string;
+}>;
+//# sourceMappingURL=sort-default-order-applied.d.ts.map

package/dist/api/runtime/checks/families/sort/sort-default-order-applied.js

@@ -0,0 +1,47 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { MOVING, pageSize, resolvedCaps } from "../../query/capabilities.js";
+import { collectSet, settlePair } from "../../sets/compare.js";
+import { ids } from "../../sets/list.js";
+export const sortDefaultOrderApplied = defineCheck({
+    plan: (ctx) => {
+        const defaultOrder = resolvedCaps(ctx).sort?.defaultOrder ?? ctx.query?.defaultOrder;
+        return defaultOrder === undefined || ctx.records.length <= 1 ? cannot() : ready({ defaultOrder });
+    },
+    dependsOn: ["sort.order-is-applied", "pagination.page-walk-covers-set"],
+    id: "sort.default-order-applied",
+    lists: true,
+    needs: "a declared defaultOrder and a complete walk",
+    subjects: subjectsOf.list,
+    async run(ctx, { defaultOrder }) {
+        const limit = pageSize(ctx);
+        let implicit = await collectSet(ctx, limit);
+        let explicit = await collectSet(ctx, limit, {}, { order: defaultOrder });
+        if (implicit === null || explicit === null) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "default-order walk was rejected");
+        }
+        const settled = await settlePair(ctx.identity, { first: implicit, second: explicit }, {
+            first: () => collectSet(ctx, limit, {}, { fresh: true }),
+            second: () => collectSet(ctx, limit, {}, { order: defaultOrder, fresh: true }),
+        });
+        if (settled === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING);
+        if (settled === null)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "default-order walk was rejected");
+        implicit = settled.first;
+        explicit = settled.second;
+        if (!implicit.complete || !explicit.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the walk is incomplete, so default order cannot be compared");
+        }
+        if (ids(implicit.items, ctx.identity).join(",") === ids(explicit.items, ctx.identity).join(","))
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "omitting order does not match defaultOrder",
+            detail: `defaultOrder=${defaultOrder} produced a different sequence than the implicit listing.`,
+            evidence: [implicit.last.exchange, explicit.last.exchange],
+        });
+    },
+});
+//# sourceMappingURL=sort-default-order-applied.js.map

package/dist/api/runtime/checks/families/sort/sort-invalid-direction-rejected.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * A sort direction the declared grammar does not have must be refused. Read as ascending instead,
+ * a caller asking for an order the backend cannot give gets a different one and is never told.
+ */
+export declare const sortInvalidDirectionRejected: Check<{
+    control: string;
+    order: string;
+}>;
+//# sourceMappingURL=sort-invalid-direction-rejected.d.ts.map

package/dist/api/runtime/checks/families/sort/sort-invalid-direction-rejected.js

@@ -0,0 +1,56 @@
+import { defineCheck } from "../../core/define.js";
+import { sortSpec, sortTerm } from "../../../../spec/conventions/sort.js";
+import { renderUnknownDirection } from "../../../../spec/render/sort.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe, judgeRefusal } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, pageSize, q } from "../../query/capabilities.js";
+import { ids, list } from "../../sets/list.js";
+/** A direction token no sort grammar has. */
+const UNKNOWN_DIRECTION = "testingsideways";
+/**
+ * A sort direction the declared grammar does not have must be refused. Read as ascending instead,
+ * a caller asking for an order the backend cannot give gets a different one and is never told.
+ */
+export const sortInvalidDirectionRejected = defineCheck({
+    plan: (ctx) => {
+        const conventions = conv(ctx);
+        if (conventions.order === undefined || conventions.sortDeclared !== true)
+            return cannot();
+        const field = ctx.query?.sortable.find((name) => name !== ctx.identity) ?? ctx.query?.sortable[0];
+        if (field === undefined)
+            return cannot("a sortable field");
+        const order = renderUnknownDirection(sortSpec(conventions), field, UNKNOWN_DIRECTION);
+        if (order === null)
+            return cannot("a sort grammar with a token for each direction");
+        return ready({ control: sortTerm(conventions, { direction: "asc", field }), order });
+    },
+    dependsOn: ["sort.order-is-applied"],
+    id: "sort.invalid-direction-rejected",
+    lists: true,
+    needs: "a declared sort grammar with a token for each direction",
+    subjects: subjectsOf.list,
+    async run(ctx, { control, order }) {
+        const result = await list(asProbe(ctx), q(ctx, { limit: pageSize(ctx), order }));
+        if (result.exchange.status >= 500) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "an unknown sort direction produces a server error",
+                detail: `order=${order} returned ${result.exchange.status}; a rejected input should be 4xx.`,
+                evidence: [result.exchange],
+            });
+        }
+        const refused = judgeRefusal(ctx, this.id, ["validation"], result.exchange);
+        if (refused !== null)
+            return refused;
+        const ascending = await list(ctx, q(ctx, { limit: pageSize(ctx), order: control }));
+        const same = ids(result.items, ctx.identity).join(",") === ids(ascending.items, ctx.identity).join(",");
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "an unknown sort direction is accepted",
+            detail: `order=${order} returned ${result.exchange.status}` +
+                (same ? " in ascending order, so the direction was read as ascending" : "") +
+                ". A direction the declared grammar does not have must be refused, not guessed.",
+            evidence: [ascending.exchange, result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=sort-invalid-direction-rejected.js.map

package/dist/api/runtime/checks/families/sort/sort-multi-key-tiebreak.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+import type { Record_ } from "../../../world/records.ts";
+export declare const sortMultiKeyTiebreak: Check<{
+    primary: string;
+    secondary: string;
+    tied: Record_[];
+}>;
+//# sourceMappingURL=sort-multi-key-tiebreak.d.ts.map