@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/composition/query-search-and-sort-compose.js

@@ -0,0 +1,79 @@
+import { defineCheck } from "../../core/define.js";
+import { sortTerm } from "../../../../spec/conventions/sort.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, MOVING, pageSize, q } from "../../query/capabilities.js";
+import { orderIgnored, sortedUnder } from "../../query/order.js";
+import { listAgain, listAll, sameSet, setOf, settlePair } from "../../sets/compare.js";
+export const querySearchAndSortCompose = defineCheck({
+    plan: (ctx) => {
+        if (conv(ctx).search === undefined || conv(ctx).order === undefined)
+            return cannot();
+        const searchField = ctx.query?.searchable[0];
+        const sortField = ctx.query?.sortable.find((name) => name !== ctx.identity) ?? ctx.query?.sortable[0];
+        if (searchField === undefined || sortField === undefined)
+            return cannot();
+        const token = ctx.records
+            .map((row) => row[searchField])
+            .find((value) => typeof value === "string" && value.length > 2);
+        if (token === undefined)
+            return cannot(`a cohort value of "${searchField}" long enough to search for`);
+        return ready({ searchField, sortField, token });
+    },
+    dependsOn: ["pagination.page-walk-covers-set", "search.q-narrows-result", "sort.order-is-applied"],
+    id: "query.search-and-sort-compose",
+    lists: true,
+    needs: "searchable and sortable fields",
+    subjects: subjectsOf.list,
+    async run(ctx, { sortField, token }) {
+        const search = q(ctx, { limit: pageSize(ctx), search: token });
+        const sorted = q(ctx, {
+            limit: pageSize(ctx),
+            search: token,
+            order: sortTerm(conv(ctx), { direction: "asc", field: sortField }),
+        });
+        const first = await listAll(ctx, search);
+        const second = await listAll(ctx, sorted);
+        if (first.exchange.status >= 400 || second.exchange.status >= 400) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "search+sort probe was rejected");
+        }
+        if (!first.complete || !second.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the sets are larger than a read covers");
+        }
+        /* A record written between the two reads is the collection moving, not the sort filtering. */
+        const settled = await settlePair(ctx.identity, { first, second }, {
+            first: () => listAgain(ctx, search),
+            second: () => listAgain(ctx, sorted),
+        });
+        if (settled === null)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "search+sort probe was rejected");
+        if (settled === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING);
+        const { first: searched, second: combined } = settled;
+        if (!sameSet(setOf(searched.items, ctx.identity), setOf(combined.items, ctx.identity))) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "adding a sort changes which records a search returns",
+                detail: `q=${JSON.stringify(token)} membership changed when order=${sortField} was added.`,
+                evidence: [searched.exchange, combined.exchange],
+            });
+        }
+        const values = combined.items.map((item) => item[sortField]);
+        if (sortedUnder(ctx, sortField, values) !== null) {
+            const descending = await orderIgnored(ctx, { ascending: values, field: sortField, query: sorted });
+            if (descending === null)
+                return ASSERTED;
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "search results are not ordered",
+                detail: `q + order=${sortField}.asc and .desc returned the same sequence of ${sortField} values.`,
+                evidence: [combined.exchange, descending.exchange],
+            });
+        }
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "search results are not ordered",
+            detail: `q + order=${sortField}.asc did not keep ${sortField} ascending.`,
+            evidence: [combined.exchange],
+        });
+    },
+});
+//# sourceMappingURL=query-search-and-sort-compose.js.map

package/dist/api/runtime/checks/families/composition/query-sort-and-select-compose.d.ts

@@ -0,0 +1,7 @@
+import type { Check } from "../../core/check.ts";
+export declare const querySortAndSelectCompose: Check<{
+    field: string;
+    requested: string[];
+    projection: Record<string, string>;
+}>;
+//# sourceMappingURL=query-sort-and-select-compose.d.ts.map

package/dist/api/runtime/checks/families/composition/query-sort-and-select-compose.js

@@ -0,0 +1,57 @@
+import { defineCheck } from "../../core/define.js";
+import { selectTerm } from "../../../../spec/conventions/select.js";
+import { sortTerm } from "../../../../spec/conventions/sort.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, q } from "../../query/capabilities.js";
+import { orderIgnored, sortedUnder } from "../../query/order.js";
+import { list } from "../../sets/list.js";
+export const querySortAndSelectCompose = defineCheck({
+    plan: (ctx) => {
+        if (conv(ctx).order === undefined || conv(ctx).select === undefined || ctx.records.length <= 1)
+            return cannot();
+        if ((ctx.query?.selectable.length ?? 0) === 0)
+            return cannot();
+        const field = ctx.query?.sortable.find((name) => name !== ctx.identity) ?? ctx.query?.sortable[0];
+        if (field === undefined)
+            return cannot();
+        /* The sort field itself must survive the projection, or the order has nothing to be read off. */
+        const requested = field === ctx.identity ? [ctx.identity] : [ctx.identity, field];
+        const projection = selectTerm(conv(ctx), requested, ctx.entityName);
+        return projection === null ? cannot() : ready({ field, projection, requested });
+    },
+    dependsOn: ["sort.order-is-applied", "select.projection-honored", "select.requested-fields-present"],
+    id: "query.sort-and-select-compose",
+    lists: true,
+    needs: "sortable and selectable fields",
+    subjects: subjectsOf.list,
+    async run(ctx, { field, projection, requested }) {
+        const query = { ...q(ctx, { limit: 20, order: sortTerm(conv(ctx), { direction: "asc", field }) }), ...projection };
+        const result = await list(ctx, query);
+        const [first, second] = result.items;
+        if (result.exchange.status >= 400 || first === undefined || second === undefined) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "sort+select probe was rejected");
+        }
+        const extras = Object.keys(first).filter((key) => !requested.includes(key));
+        const values = result.items.map((item) => item[field]);
+        if (extras.length === 0 && sortedUnder(ctx, field, values) !== null) {
+            const descending = await orderIgnored(ctx, { ascending: values, field, query });
+            if (descending === null)
+                return ASSERTED;
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "sort and select do not compose",
+                detail: `order=${field}.asc and order=${field}.desc returned the same sequence under the projection.`,
+                evidence: [result.exchange, descending.exchange],
+            });
+        }
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "sort and select do not compose",
+            detail: extras.length > 0
+                ? `select leaked ${extras.slice(0, 5).join(", ")}.`
+                : `order=${field}.asc did not hold under the projection.`,
+            evidence: [result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=query-sort-and-select-compose.js.map

package/dist/api/runtime/checks/families/composition/query-unknown-parameter-consistent.d.ts

@@ -0,0 +1,13 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * A query parameter the API does not know is either refused or ignored — consistently.
+ *
+ * Both are defensible policies, and the document rarely says which. What is not defensible is a
+ * name nobody declared changing the result: a caller who misspells `limit` gets a different set
+ * and no error. Two invented names are sent — one plain, one shaped like a real parameter with a
+ * typo — and each answer compared, as a whole set, with the listing asked for without it.
+ */
+export declare const unknownParameterConsistent: Check<{
+    names: string[];
+}>;
+//# sourceMappingURL=query-unknown-parameter-consistent.d.ts.map

package/dist/api/runtime/checks/families/composition/query-unknown-parameter-consistent.js

@@ -0,0 +1,76 @@
+import { defineCheck } from "../../core/define.js";
+import { asserted } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv } from "../../query/capabilities.js";
+import { sameSet, setOf } from "../../sets/compare.js";
+import { readSet } from "../../sets/read.js";
+/**
+ * A query parameter the API does not know is either refused or ignored — consistently.
+ *
+ * Both are defensible policies, and the document rarely says which. What is not defensible is a
+ * name nobody declared changing the result: a caller who misspells `limit` gets a different set
+ * and no error. Two invented names are sent — one plain, one shaped like a real parameter with a
+ * typo — and each answer compared, as a whole set, with the listing asked for without it.
+ */
+export const unknownParameterConsistent = defineCheck({
+    plan: (ctx) => {
+        if (ctx.records.length === 0)
+            return cannot();
+        const real = conv(ctx).limit ?? conv(ctx).page ?? conv(ctx).order ?? "limit";
+        return ready({ names: ["testing_unknown_parameter", `${real}_testing_typo`] });
+    },
+    dependsOn: ["list.read-after-write", "pagination.page-walk-covers-set"],
+    id: "query.unknown-parameter-consistent",
+    lists: true,
+    needs: "a listing and at least one record",
+    subjects: subjectsOf.list,
+    async run(ctx, { names }) {
+        const baseline = await readSet(ctx, {}, { fresh: true });
+        if (baseline.status !== "ok" || !baseline.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, baseline.reason);
+        }
+        const expected = setOf(baseline.items, ctx.identity);
+        const answers = [];
+        for (const name of names) {
+            const probe = await readSet(asProbe(ctx), { [name]: "1" }, { fresh: true });
+            const exchange = probe.last.exchange;
+            if (exchange.status >= 500) {
+                return ctx.findings.backend(this.id, ctx.entityName, {
+                    summary: "an unknown query parameter crashes the listing",
+                    detail: `adding ?${name}=1, a parameter the document does not declare, returned ${exchange.status}.`,
+                    evidence: [exchange],
+                });
+            }
+            if (exchange.status === 400 || exchange.status === 422) {
+                answers.push({ exchange, name, policy: "refused" });
+                continue;
+            }
+            if (probe.status !== "ok" || !probe.complete) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, `?${name}=1 was answered with ${exchange.status}, which says nothing about the parameter`);
+            }
+            if (!sameSet(setOf(probe.items, ctx.identity), expected)) {
+                return ctx.findings.backend(this.id, ctx.entityName, {
+                    summary: "an unknown query parameter silently changes the result",
+                    detail: `adding ?${name}=1, a parameter the document does not declare, returned ${probe.items.length} ` +
+                        `record(s) where the plain listing returns ${expected.size}, with no error. A caller who ` +
+                        "misspells a parameter gets a different answer and no way to know.",
+                    evidence: [baseline.last.exchange, exchange],
+                });
+            }
+            answers.push({ exchange, name, policy: "ignored" });
+        }
+        const policies = new Set(answers.map((answer) => answer.policy));
+        if (policies.size > 1) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "unknown query parameters are handled inconsistently",
+                detail: answers.map((answer) => `?${answer.name}=1 was ${answer.policy} (${answer.exchange.status})`).join("; ") +
+                    ". One unknown name refused and another ignored leaves callers guessing which mistakes are caught.",
+                evidence: answers.map((answer) => answer.exchange),
+            });
+        }
+        return asserted(`unknown query parameters are ${answers[0]?.policy ?? "ignored"} on the listing`);
+    },
+});
+//# sourceMappingURL=query-unknown-parameter-consistent.js.map

package/dist/api/runtime/checks/families/conformance/response-status-is-documented.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from "../../core/check.ts";
+import type { Exchange } from "../../../exchange.ts";
+import type { CheckContext } from "../../core/context.ts";
+/** One line per operation: what it returned, and what the document declares. */
+export declare function describeUndeclared(ctx: CheckContext, byOp: Map<string, Exchange[]>): {
+    lines: string[];
+    evidence: Exchange[];
+};
+export declare const documentedStatusHonored: Check;
+//# sourceMappingURL=response-status-is-documented.d.ts.map

package/dist/api/runtime/checks/families/conformance/response-status-is-documented.js

@@ -0,0 +1,117 @@
+import { defineCheck } from "../../core/define.js";
+import { judges } from "../../../probe-judging.js";
+import { documentsStatus, readStatuses } from "../../../../spec/graph/statuses.js";
+import { isDocumentedFeatureGateDenial } from "../../../feature-gate.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { graded, subjectsOf } from "../../planning/subjects.js";
+/** One line per operation: what it returned, and what the document declares. */
+export function describeUndeclared(ctx, byOp) {
+    const lines = [];
+    const evidence = [];
+    for (const [operationId, exchanges] of byOp) {
+        const raw = ctx.model.rawOperations.get(operationId);
+        const declaredStatuses = Object.keys(raw?.responses ?? {})
+            .filter((key) => key !== "default")
+            .sort()
+            .join(", ");
+        const seen = [...new Set(exchanges.map((item) => item.status))].sort((a, b) => a - b);
+        lines.push(`${operationId} returned ${seen.join(", ")}; the document declares ${declaredStatuses || "no concrete status"}`);
+        const first = exchanges[0];
+        if (first !== undefined && evidence.length < 6)
+            evidence.push(first);
+    }
+    return { evidence, lines };
+}
+function statusIsDeclared(raw, status) {
+    return documentsStatus(readStatuses(raw?.responses), status);
+}
+function declaresConcreteStatuses(raw) {
+    const statuses = readStatuses(raw?.responses);
+    return statuses.exact.length > 0 || statuses.ranges.length > 0;
+}
+/** The operation an exchange judges: this entity's, graded by this run, and not its create. */
+function judgedOperation(ctx, exchange) {
+    const op = exchange.operationId === undefined ? undefined : ctx.model.byOperationId.get(exchange.operationId);
+    if (op === undefined || op.entity !== ctx.entityName)
+        return undefined;
+    if (!graded(ctx, op))
+        return undefined;
+    if (op.operationId === ctx.createOp?.operationId || op.action === "create")
+        return undefined;
+    return op;
+}
+/**
+ * What one exchange says about its operation's statuses: `null` when it says nothing, else the
+ * operation it observed and, when the status is one the document leaves out, how it was sent.
+ */
+async function readExchange(ctx, listed) {
+    /* A documented feature-gate denial is told apart by its body. */
+    const exchange = listed.status === 403 ? await ctx.client.hydrate(listed) : listed;
+    /* A status-0 network failure has no status to judge, and an answer that was asked again
+     * after a refresh or a wait is not the backend's verdict on the request. */
+    if (exchange.status === 0 || exchange.superseded === true)
+        return null;
+    const op = judgedOperation(ctx, exchange);
+    if (op === undefined || exchange.status === 429)
+        return null;
+    const raw = ctx.model.rawOperations.get(op.operationId);
+    if (!declaresConcreteStatuses(raw))
+        return null;
+    const operationId = op.operationId;
+    if (isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody)) {
+        return { exchange, operationId, undeclared: null };
+    }
+    if (statusIsDeclared(raw, exchange.status))
+        return { exchange, operationId, undeclared: null };
+    /* A deliberately invalid request may draw a status the document never needed to name
+     * for real traffic. It is reported, but apart from what ordinary requests got. */
+    return { exchange, operationId, undeclared: exchange.purpose === "probe" ? "probe" : "ordinary" };
+}
+export const documentedStatusHonored = defineCheck({
+    plan: (ctx) => when(ctx.model.operations.some((op) => op.entity === ctx.entityName && op.action !== "create")),
+    id: "response.status-is-documented",
+    judgesTranscript: true,
+    needs: "a modeled non-create operation on this entity",
+    subjects: subjectsOf.nonCreate,
+    async run(ctx) {
+        const byOp = new Map();
+        const probes = new Map();
+        const observed = new Set();
+        for (const listed of ctx.client.exchangesForEntity(ctx.entityName)) {
+            /* A security probe's answer is the security checks' to judge; see probe-judging.ts. */
+            if (!judges(this.id, listed))
+                continue;
+            const reading = await readExchange(ctx, listed);
+            if (reading === null)
+                continue;
+            observed.add(reading.operationId);
+            if (reading.undeclared === null)
+                continue;
+            const bucket = reading.undeclared === "probe" ? probes : byOp;
+            const seen = bucket.get(reading.operationId) ?? [];
+            seen.push(reading.exchange);
+            bucket.set(reading.operationId, seen);
+        }
+        ctx.judged?.([...observed]);
+        if (probes.size > 0) {
+            const { lines, evidence } = describeUndeclared(ctx, probes);
+            ctx.findings.attributed([...probes.keys()]).spec(this.id, ctx.entityName, {
+                summary: "requests the API tester sent to be refused drew statuses the document does not declare",
+                detail: `${lines.join(". ")}. These were deliberately invalid probes, so the refusal is right; ` +
+                    "its status is what the document leaves out.",
+                evidence,
+            });
+        }
+        /* Every operation in the map has a line, so an empty map is the only clean answer. */
+        if (byOp.size === 0)
+            return ASSERTED;
+        const { lines, evidence } = describeUndeclared(ctx, byOp);
+        return ctx.findings.attributed([...byOp.keys()]).spec(this.id, ctx.entityName, {
+            summary: "an operation returned a status the document does not declare",
+            detail: `${lines.join(". ")}. Clients generated from this document will not recognize the response.`,
+            evidence,
+        });
+    },
+});
+//# sourceMappingURL=response-status-is-documented.js.map

package/dist/api/runtime/checks/families/conformance/response-write-only-not-returned.d.ts

@@ -0,0 +1,13 @@
+import type { Check } from "../../core/check.ts";
+import type { JsonSchema } from "../../../../spec/types.ts";
+/**
+ * A property the document marks writeOnly is never sent back — OAS 3 makes it "relevant only for
+ * request messages" — whatever additionalProperties says: an open schema accepts a leaked password,
+ * so schema validation alone misses it. Every 2xx answer of this entity's item read and listing the
+ * run drew is read for one, record by record. A credential-like field is a security
+ * finding; any other is a spec bug. Nothing is sent.
+ */
+export declare const writeOnlyNotReturned: Check<{
+    fields: Map<string, JsonSchema>;
+}>;
+//# sourceMappingURL=response-write-only-not-returned.d.ts.map

package/dist/api/runtime/checks/families/conformance/response-write-only-not-returned.js

@@ -0,0 +1,116 @@
+import { defineCheck } from "../../core/define.js";
+import { isBodyRef } from "../../../exchange.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { recordOf, recordsFromList } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { requestSchemaOf } from "../../payloads/body.js";
+import { itemSchemaOf } from "../../payloads/item-schema.js";
+import { graded, isEventStream, ownOps } from "../../planning/subjects.js";
+const WRITE_ONLY = "response.write-only-not-returned";
+/* A name or format that says the value is a credential: leaking one is a security defect, not drift. */
+const SECRET_NAME = /pass(word)?|secret|token|api[-_]?key|private[-_]?key|credential/i;
+/*
+ * The answers a writeOnly value must never reach: the item read and the listing, read later and by
+ * anyone allowed to. The create's own answer goes to the caller who just sent the value, and handing a
+ * generated key or secret back once there is a common, deliberate pattern; it is not judged.
+ */
+function answers(op) {
+    return op.action === "read" || op.action === "list";
+}
+/**
+ * A property the document marks writeOnly is never sent back — OAS 3 makes it "relevant only for
+ * request messages" — whatever additionalProperties says: an open schema accepts a leaked password,
+ * so schema validation alone misses it. Every 2xx answer of this entity's item read and listing the
+ * run drew is read for one, record by record. A credential-like field is a security
+ * finding; any other is a spec bug. Nothing is sent.
+ */
+export const writeOnlyNotReturned = defineCheck({
+    plan: (ctx) => {
+        if (ctx.readOp === undefined && ctx.listOp === undefined)
+            return cannot();
+        const fields = writeOnlyFields(ctx);
+        return fields.size === 0 ? cannot() : ready({ fields });
+    },
+    id: WRITE_ONLY,
+    judgesTranscript: true,
+    needs: "a property the record's schema or a write's body marks writeOnly, and an item read or a listing",
+    subjects: (entity, model) => ownOps(entity, model, answers),
+    async run(ctx, { fields }) {
+        const judged = new Set();
+        const leaks = new Map();
+        for (const listed of ctx.client.exchangesForEntity(ctx.entityName)) {
+            const op = answeringOf(ctx, listed);
+            if (op === undefined || leaks.has(op.operationId))
+                continue;
+            const exchange = await ctx.client.hydrate(listed);
+            if (isEventStream(exchange, op) || isBodyRef(exchange.responseBody))
+                continue;
+            judged.add(op.operationId);
+            const names = leakedNames(recordsIn(op, exchange.responseBody), fields);
+            if (names.length > 0)
+                leaks.set(op.operationId, { exchange, names });
+        }
+        if (judged.size === 0)
+            return standDown("a 2xx answer of this entity's item read or listing");
+        ctx.judged?.([...judged]);
+        let outcome = ASSERTED;
+        for (const [operationId, { exchange, names }] of leaks) {
+            const claim = {
+                summary: `${operationId} answered a field the document marks writeOnly: ${names.join(", ")}`,
+                detail: `${operationId} returned ${exchange.status} carrying ${names.join(", ")}, which the document marks ` +
+                    "writeOnly: a value a client sends and the server never returns.",
+                evidence: [exchange],
+            };
+            const findings = ctx.findings.attributed([operationId]);
+            const secret = names.some((name) => isSecretLike(name, fields.get(name)));
+            outcome = secret
+                ? findings.security(WRITE_ONLY, ctx.entityName, claim)
+                : findings.spec(WRITE_ONLY, ctx.entityName, claim);
+        }
+        return outcome;
+    },
+});
+/** The writeOnly properties of the record's schema and of each write's request body, by name. */
+function writeOnlyFields(ctx) {
+    const record = itemSchemaOf({ listOp: ctx.listOp, model: ctx.model, readOp: ctx.readOp });
+    const schemas = [
+        record,
+        ...[ctx.createOp, ctx.updateOp].map((op) => (op === undefined ? null : requestSchemaOf(ctx, op))),
+    ];
+    const fields = new Map();
+    for (const schema of schemas) {
+        const properties = (schema?.properties ?? {});
+        for (const [name, property] of Object.entries(properties))
+            if (property.writeOnly === true)
+                fields.set(name, property);
+    }
+    return fields;
+}
+/** The item read or listing an exchange answered with 2xx, when it is this entity's and graded. */
+function answeringOf(ctx, exchange) {
+    if (exchange.status < 200 || exchange.status >= 300 || exchange.superseded === true)
+        return undefined;
+    const op = exchange.operationId === undefined ? undefined : ctx.model.byOperationId.get(exchange.operationId);
+    if (op === undefined || op.entity !== ctx.entityName || !answers(op))
+        return undefined;
+    return graded(ctx, op) ? op : undefined;
+}
+/** The records an answer carries: a listing's rows, else the one record where the operation keeps it. */
+function recordsIn(op, body) {
+    if (op.action === "list")
+        return recordsFromList(body, op.collection);
+    const record = recordOf(op, body);
+    return record === undefined ? [] : [record];
+}
+/** Whether a record holds the field with a value: null, absent and empty say nothing was returned. */
+function holds(record, name) {
+    return Object.hasOwn(record, name) && record[name] !== null && record[name] !== "";
+}
+/** The writeOnly fields any of the records holds with a value. */
+function leakedNames(records, fields) {
+    return [...fields.keys()].filter((name) => records.some((record) => holds(record, name)));
+}
+function isSecretLike(name, schema) {
+    return SECRET_NAME.test(name) || schema?.format === "password";
+}
+//# sourceMappingURL=response-write-only-not-returned.js.map

package/dist/api/runtime/checks/families/conformance/schema-error-response-matches-document.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from "../../core/check.ts";
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import type { OperationObject } from "../../../../spec/types.ts";
+import type { SchemaValidator } from "../../../validate.ts";
+export declare const errorSchemaHonored: Check<{
+    readOp: OperationModel;
+    validator: SchemaValidator;
+    raw: OperationObject;
+}>;
+//# sourceMappingURL=schema-error-response-matches-document.d.ts.map

package/dist/api/runtime/checks/families/conformance/schema-error-response-matches-document.js

@@ -0,0 +1,119 @@
+import { defineCheck } from "../../core/define.js";
+import { isDocumentedFeatureGateDenial } from "../../../feature-gate.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { judges } from "../../../probe-judging.js";
+import { cannot, ready } from "../../core/plan.js";
+import { absentId } from "../../payloads/identity.js";
+import { asProbe } from "../../planning/refusal.js";
+import { graded, itemParamFor, ownOps, subjectsOf } from "../../planning/subjects.js";
+import { verdictOf } from "./schema-verdict.js";
+export const errorSchemaHonored = defineCheck({
+    plan: (ctx) => {
+        const { readOp, validator } = ctx;
+        if (readOp === undefined || validator === undefined)
+            return cannot();
+        const raw = ctx.model.rawOperations.get(readOp.operationId);
+        return raw === undefined ? cannot() : ready({ raw, readOp, validator });
+    },
+    id: "schema.error-response-matches-document",
+    judgesTranscript: true,
+    needs: "a documented error schema on the item route",
+    subjects: (entity, model) => [
+        ...new Set([
+            ...subjectsOf.readAndGated(entity, model),
+            ...ownOps(entity, model, (op) => op.unique !== null && op.unique.length > 0),
+        ]),
+    ],
+    async run(ctx, { raw, readOp, validator }) {
+        /* An empty list has no id to miss. Probing one would grade the get without a row. */
+        if (ctx.createOp === undefined && ctx.records.length === 0)
+            return standDown("the list returned no id");
+        const judge = { check: this.id, ctx, validator };
+        const judged = [];
+        if (graded(ctx, readOp)) {
+            await probeMissingItemError(judge, readOp, raw);
+            judged.push(readOp.operationId);
+        }
+        judged.push(...(await judgeExpectedRefusals(judge)));
+        ctx.judged?.([...new Set(judged)]);
+        return ASSERTED;
+    },
+});
+/**
+ * Expected refusals are coverage for the check that drew them, not for the error schema: a
+ * documented feature-gate 403 or a unique-conflict 409 still has to carry the body the document
+ * declares. Judged here, over everything this entity's run drew; returns the operations judged.
+ */
+async function judgeExpectedRefusals(judge) {
+    const { ctx } = judge;
+    const judged = [];
+    for (const listed of ctx.client.exchangesForEntity(ctx.entityName)) {
+        /* A security probe's answer is the security checks' to judge; see probe-judging.ts. */
+        if (!judges("schema.error-response-matches-document", listed))
+            continue;
+        /* Error bodies are what this judges; one moved out of memory is read back. */
+        const exchange = listed.status >= 400 ? await ctx.client.hydrate(listed) : listed;
+        if (exchange.superseded === true)
+            continue;
+        const op = exchange.operationId === undefined ? undefined : ctx.model.byOperationId.get(exchange.operationId);
+        if (op === undefined || op.entity !== ctx.entityName || !graded(ctx, op))
+            continue;
+        const gated = isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody);
+        const conflict = exchange.status === 409 && op.unique !== null && op.unique.length > 0;
+        if (!gated && !conflict)
+            continue;
+        judged.push(op.operationId);
+        errorBodyDrift(judge, op, exchange);
+    }
+    return judged;
+}
+/** Reports an error body that fails the schema its operation declares for that status. */
+function errorBodyDrift(judge, op, exchange) {
+    const raw = judge.ctx.model.rawOperations.get(op.operationId);
+    if (raw === undefined || !judge.validator.documents(raw, exchange.status))
+        return;
+    const findings = judge.ctx.findings.attributed([op.operationId]);
+    judgeErrorBody(judge, { drift: findings, gaps: findings, operationId: op.operationId, raw }, exchange);
+}
+/** Asks for an id no record holds, and judges the error body that comes back. */
+async function probeMissingItemError(judge, readOp, raw) {
+    const { ctx } = judge;
+    const missing = absentId(ctx);
+    if (missing === null)
+        return;
+    const params = { ...ctx.scope, ...itemParamFor(ctx, missing) };
+    const exchange = await asProbe(ctx).client.get(fillPath(readOp.path, params), { as: { principal: ctx.actor.id } });
+    if (exchange.status < 400 || !judge.validator.documents(raw, exchange.status))
+        return;
+    const subject = {
+        drift: ctx.findings.attributed([readOp.operationId]),
+        gaps: ctx.findings,
+        operationId: readOp.operationId,
+        raw,
+    };
+    judgeErrorBody(judge, subject, exchange);
+}
+/** Validates an error body against its documented schema: a gap when that cannot compile, else drift. */
+function judgeErrorBody(judge, subject, exchange) {
+    const { check, ctx, validator } = judge;
+    const { operationId } = subject;
+    const result = verdictOf(validator, { operationId, raw: subject.raw }, exchange);
+    if (result.unchecked !== undefined) {
+        subject.gaps.gap(check, ctx.entityName, {
+            summary: `${operationId} ${exchange.status} has a schema that cannot be compiled`,
+            detail: `AJV refused the documented schema, so the body was not validated: ${result.unchecked}`,
+        });
+        return;
+    }
+    if (result.ok)
+        return;
+    subject.drift.spec(check, ctx.entityName, {
+        summary: `${exchange.status} error body does not match its documented schema`,
+        detail: `${operationId} returned ${exchange.status} with a body that fails the schema the ` +
+            `document declares for it: ${result.errors.join("; ")}. Clients that parse errors ` +
+            "from the spec will not understand this response.",
+        evidence: [exchange],
+    });
+}
+//# sourceMappingURL=schema-error-response-matches-document.js.map

package/dist/api/runtime/checks/families/conformance/schema-problem-json-shape.d.ts

@@ -0,0 +1,11 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * Every answer served as `application/problem+json` must be shaped as RFC 9457 defines it.
+ *
+ * Clients read a problem detail by its registered members, not by the operation's own document: a
+ * `status` that names another status than the response's, or a member of the wrong type, misleads
+ * every one of them alike. Any answer of this entity's that the API tester drew is judged, a probe's too: a
+ * refusal is right to be one, and still wrong to describe itself falsely.
+ */
+export declare const problemJsonShape: Check;
+//# sourceMappingURL=schema-problem-json-shape.d.ts.map