@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/security/auth-cross-tenant-key-refused.js

@@ -0,0 +1,89 @@
+import { defineCheck } from "../../core/define.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { ASSERTED } from "../../../finding.js";
+import { fillPath } from "../../../fill-path.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { isRefused, settle, unlessUnsatisfied } from "./lifecycle.js";
+import { BY_VALIDATION, byValidation } from "./probing.js";
+/**
+ * An API key belongs to one tenant. On a GET under the actor's tenant that takes an API key alone,
+ * the peer tenant's key (minted through the run's store like any credential, so teardown revokes it)
+ * must be refused with 401, 403 or 404. Its acceptance in the peer's own tenant proves the refusal
+ * was about the tenant, not a broken key.
+ */
+export const crossTenantKeyRefused = defineCheck({
+    id: "auth.cross-tenant-key-refused",
+    needs: "a peer tenant, and a tenant-scoped GET that takes an API key",
+    plan: (ctx) => {
+        const undeclared = noSecurityReason(ctx.operation);
+        if (undeclared !== undefined)
+            return cannot(undeclared);
+        const { peer } = ctx;
+        if (peer === undefined)
+            return cannot("a principal of another tenant");
+        if (ctx.operation.method.toUpperCase() !== "GET") {
+            return cannot(`a GET; ${ctx.operation.operationId} is probed by the write stage's checks`);
+        }
+        return andThen(keySchemes(ctx), (schemes) => andThen(paths(ctx, peer), ({ foreign, own }) => ready({ foreign, own, peer, schemes })));
+    },
+    subject: "operation",
+    async run(ctx, planned) {
+        const outcomes = [];
+        for (const scheme of planned.schemes) {
+            const label = `${planned.peer.id}'s ${scheme} key`;
+            outcomes.push(await unlessUnsatisfied(label, () => crossWith(ctx, { planned, scheme })));
+        }
+        return settle(outcomes);
+    },
+});
+const CHECK = "auth.cross-tenant-key-refused";
+/* The API-key schemes an alternative of the operation takes alone. */
+function keySchemes(ctx) {
+    const schemes = ctx.operation.security.alternatives.flatMap((set) => {
+        const scheme = set.length === 1 ? set[0]?.scheme : undefined;
+        return scheme !== undefined && ctx.model.schemes.get(scheme)?.kind === "apiKey" ? [scheme] : [];
+    });
+    return schemes.length > 0 ? ready([...new Set(schemes)]) : cannot("an alternative that takes an API key alone");
+}
+/* The operation's path under each tenant: both scopes fill every parameter, and differently. */
+function paths(ctx, peer) {
+    const { pathParams, path } = ctx.operation;
+    const fills = (actor) => pathParams.every((name) => name in actor.scope);
+    if (pathParams.length > 0 && fills(ctx.actor) && fills(peer)) {
+        const foreign = fillPath(path, ctx.actor.scope);
+        const own = fillPath(path, peer.scope);
+        if (foreign !== own)
+            return ready({ foreign, own });
+    }
+    return cannot("a path the actor's and the peer's scopes each fill, differently");
+}
+async function crossWith(ctx, { planned, scheme }) {
+    const { foreign, own, peer } = planned;
+    const { operationId, requiredQuery: query } = ctx.operation;
+    const as = { principal: peer.id, scheme };
+    const key = `${peer.id}'s ${scheme} key`;
+    const tenant = String(ctx.actor.tenant);
+    const crossed = await ctx.client.get(foreign, { as, operationId, probe: true, query });
+    if (crossed.status < 300) {
+        return ctx.findings.security(CHECK, ctx.subject, {
+            detail: `${key} (tenant ${String(peer.tenant)}) was sent to ${operationId} under ${tenant}, ` +
+                `${ctx.actor.id}'s tenant: ${operationId} answered ${crossed.status}. A key must work only ` +
+                "in the tenant it was issued for.",
+            evidence: [crossed],
+            summary: `an ${scheme} key of one tenant is accepted in another`,
+        });
+    }
+    if (byValidation(crossed.status)) {
+        return ctx.findings.unresolved(CHECK, ctx.subject, `${key} drew ${crossed.status} under ${tenant}: ${BY_VALIDATION}`);
+    }
+    if (!isRefused(crossed.status) && crossed.status !== 404) {
+        const reason = `${key} drew ${crossed.status} under ${tenant}, neither a refusal nor a success`;
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    const home = await ctx.client.get(own, { as, operationId, query });
+    if (home.status < 300)
+        return ASSERTED;
+    const reason = `${key} was refused (${home.status}) in its own tenant too, so the refusal proves nothing`;
+    return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+}
+//# sourceMappingURL=auth-cross-tenant-key-refused.js.map

package/dist/api/runtime/checks/families/security/auth-invalid-credential-refused.d.ts

@@ -0,0 +1,16 @@
+import type { OperationCheck } from "../../core/check.ts";
+import type { Requirement } from "../../../../spec/security/requirements.ts";
+import { type Address } from "./probing.ts";
+/** A value no scheme issues: garbage, so it stays visible in the journal. */
+export declare const GARBAGE = "testing-invalid-credential";
+/** Whether `value` is a JWT: three base64url segments, the first a JSON header naming its `alg`. */
+export declare function isJwt(value: string): boolean;
+/** The JWT with its signature's first character changed: every bit of it counts, unlike the last's. */
+export declare function flipSignature(jwt: string): string;
+interface Planned {
+    address: Address;
+    schemes: Requirement[];
+}
+export declare const invalidCredentialRefused: OperationCheck<Planned>;
+export {};
+//# sourceMappingURL=auth-invalid-credential-refused.d.ts.map

package/dist/api/runtime/checks/families/security/auth-invalid-credential-refused.js

@@ -0,0 +1,67 @@
+import { defineCheck } from "../../core/define.js";
+import { isUntested } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { addressOf, judgeRefusals, securedPlan, send, singleSchemes } from "./probing.js";
+const ID = "auth.invalid-credential-refused";
+/** A value no scheme issues: garbage, so it stays visible in the journal. */
+export const GARBAGE = "testing-invalid-credential";
+/** Whether `value` is a JWT: three base64url segments, the first a JSON header naming its `alg`. */
+export function isJwt(value) {
+    const [header, payload, signature, ...rest] = value.split(".");
+    if (rest.length > 0 || !header || !payload || !signature)
+        return false;
+    try {
+        const decoded = JSON.parse(Buffer.from(header, "base64url").toString("utf8"));
+        return typeof decoded === "object" && decoded !== null && typeof decoded.alg === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/** The JWT with its signature's first character changed: every bit of it counts, unlike the last's. */
+export function flipSignature(jwt) {
+    const at = jwt.lastIndexOf(".") + 1;
+    return `${jwt.slice(0, at)}${jwt[at] === "A" ? "B" : "A"}${jwt.slice(at + 1)}`;
+}
+export const invalidCredentialRefused = defineCheck({
+    id: ID,
+    mutates: true,
+    needs: "an operation whose security requires a credential",
+    plan: (ctx) => andThen(securedPlan(ctx), () => {
+        const schemes = singleSchemes(ctx.security);
+        if (schemes.length === 0)
+            return cannot("an alternative of one scheme, for a credential to stand in for");
+        return andThen(addressOf(ctx), (address) => ready({ address, schemes }));
+    }),
+    async run(ctx, { address, schemes }) {
+        const probes = [];
+        for (const requirement of schemes)
+            probes.push(...(await probesOf(ctx, { address, requirement })));
+        return judgeRefusals(ctx, ID, probes);
+    },
+    subject: "operation",
+});
+/* Garbage for the scheme, then the actor's own JWT for it with its signature altered, where it holds one. */
+async function probesOf(ctx, at) {
+    const { address, requirement } = at;
+    const { scheme } = requirement;
+    const garbage = await send(ctx, address, { forged: { scheme, value: GARBAGE } });
+    const probes = [
+        {
+            exchange: garbage,
+            sent: `an invalid ${scheme} credential`,
+            summary: "a secured operation accepted an invalid credential",
+        },
+    ];
+    const held = await ctx.probe.held({ principal: ctx.actor.id, scheme, scopes: requirement.scopes });
+    if (isUntested(held) || !isJwt(held.value))
+        return probes;
+    const altered = await send(ctx, address, { forged: { derived: true, scheme, value: flipSignature(held.value) } });
+    probes.push({
+        exchange: altered,
+        sent: `${ctx.actor.id}'s ${scheme} JWT with its signature altered`,
+        summary: "a secured operation accepted a JWT whose signature was altered",
+    });
+    return probes;
+}
+//# sourceMappingURL=auth-invalid-credential-refused.js.map

package/dist/api/runtime/checks/families/security/auth-login-throttled.d.ts

@@ -0,0 +1,16 @@
+import type { OperationCheck } from "../../core/check.ts";
+/**
+ * The most failed logins the check sends: the reference's threshold (5 failures within a minute)
+ * plus 3, so a throttle that counts a little late still answers in time, and one that never does is
+ * not hammered.
+ */
+export declare const LOGIN_ATTEMPTS = 8;
+/**
+ * Repeated failed logins are throttled. Opt-in (`optIn`, which the security stage enforces), since a
+ * throttle that counts by address can slow every login from the machine running the API tester for a while.
+ * Anchored on the login step of a login recipe, it sends failed logins anonymously for one identity
+ * no account can hold (`testing-nonexistent-<nonce>`, at `example.invalid` where the field is an email),
+ * never a principal's, until the login answers 429 or the cap.
+ */
+export declare const loginThrottled: OperationCheck<Record<string, unknown>>;
+//# sourceMappingURL=auth-login-throttled.d.ts.map

package/dist/api/runtime/checks/families/security/auth-login-throttled.js

@@ -0,0 +1,91 @@
+import { defineCheck } from "../../core/define.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { asserted } from "../../../finding.js";
+import { fillPath } from "../../../fill-path.js";
+import { buildCohort } from "../../../fixture.js";
+import { nonexistentIdentity } from "../../../nonexistent-identity.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { requestContent } from "../../../../spec/collection/request.js";
+import { anchoredSchemes } from "./lifecycle.js";
+/**
+ * The most failed logins the check sends: the reference's threshold (5 failures within a minute)
+ * plus 3, so a throttle that counts a little late still answers in time, and one that never does is
+ * not hammered.
+ */
+export const LOGIN_ATTEMPTS = 8;
+/**
+ * The failed login's body: valid by the schema, every string field naming an identity no account can
+ * hold. An email-shaped one is at RFC 2606's reserved `.invalid` domain, which never resolves.
+ */
+function nobodyOf(body, { nonce, schema }) {
+    /* A body drawn from a schema with no properties has no field to map. */
+    const properties = schema.properties;
+    return Object.fromEntries(Object.entries(body).map(([name, value]) => [
+        name,
+        typeof value === "string" ? nonexistentIdentity({ name, schema: properties[name] }, nonce) : value,
+    ]));
+}
+/**
+ * Repeated failed logins are throttled. Opt-in (`optIn`, which the security stage enforces), since a
+ * throttle that counts by address can slow every login from the machine running the API tester for a while.
+ * Anchored on the login step of a login recipe, it sends failed logins anonymously for one identity
+ * no account can hold (`testing-nonexistent-<nonce>`, at `example.invalid` where the field is an email),
+ * never a principal's, until the login answers 429 or the cap.
+ */
+export const loginThrottled = defineCheck({
+    id: "auth.login-throttled",
+    mutates: true,
+    mutatesCredentials: true,
+    needs: "a login recipe whose login step the document declares, with a request body schema",
+    optIn: true,
+    plan: (ctx) => {
+        const undeclared = noSecurityReason(ctx.operation);
+        if (undeclared !== undefined)
+            return cannot(undeclared);
+        const { operationId } = ctx.operation;
+        return andThen(anchoredSchemes(ctx, { kind: "issue", login: true }), () => {
+            /* The model holds every operation it lists. */
+            const raw = ctx.model.rawOperations.get(operationId);
+            const schema = requestContent(raw)?.schema ?? null;
+            return schema === null
+                ? cannot(`a request body schema for ${operationId}, to build a failed login from`)
+                : ready(schema);
+        });
+    },
+    subject: "operation",
+    async run(ctx, schema) {
+        const { method, operationId, path } = ctx.operation;
+        const [drawn] = buildCohort(schema, 0, {
+            defs: ctx.model.defs,
+            nonce: ctx.nonce,
+            operationId,
+            variants: ["baseline"],
+        });
+        const body = nobodyOf(drawn.body, { nonce: ctx.nonce, schema });
+        const target = fillPath(path, ctx.actor.scope);
+        const sent = [];
+        while (sent.length < LOGIN_ATTEMPTS) {
+            const attempt = await ctx.client.request(method, target, {
+                as: { anonymous: true },
+                body,
+                operationId,
+                probe: true,
+            });
+            sent.push(attempt);
+            if (attempt.status === 429) {
+                return asserted(`a login for one identity was throttled (429) after ${sent.length - 1} failures`);
+            }
+            if (attempt.status < 300) {
+                const reason = `a login for an identity that does not exist answered ${attempt.status}, so its failures cannot be counted`;
+                return ctx.findings.unresolved(this.id, ctx.subject, reason);
+            }
+        }
+        return ctx.findings.security(this.id, ctx.subject, {
+            detail: `${LOGIN_ATTEMPTS} failed logins for one identity that does not exist, sent to ${operationId} ` +
+                "back to back, drew no 429. Without a throttle a password can be guessed at the server's full speed.",
+            evidence: sent,
+            summary: "repeated failed logins are never throttled",
+        });
+    },
+});
+//# sourceMappingURL=auth-login-throttled.js.map

package/dist/api/runtime/checks/families/security/auth-missing-credential-refused.d.ts

@@ -0,0 +1,4 @@
+import type { OperationCheck } from "../../core/check.ts";
+import { type Address } from "./probing.ts";
+export declare const missingCredentialRefused: OperationCheck<Address>;
+//# sourceMappingURL=auth-missing-credential-refused.d.ts.map

package/dist/api/runtime/checks/families/security/auth-missing-credential-refused.js

@@ -0,0 +1,29 @@
+/*
+ * A secured operation must refuse a request that carries no credential. Planned only where the
+ * security requires one: an operation that lets anonymous callers in owes no refusal, and a document
+ * that declares no security says nothing either way. Probes go where `addressOf` puts them, by their
+ * placement; a write only to the run-created record, with its current state, so a broken API that
+ * applies it changes nothing. Mutating, since some of its probes write.
+ */
+import { defineCheck } from "../../core/define.js";
+import { andThen } from "../../core/plan.js";
+import { addressOf, judgeRefusals, securedPlan, send } from "./probing.js";
+const ID = "auth.missing-credential-refused";
+export const missingCredentialRefused = defineCheck({
+    id: ID,
+    mutates: true,
+    needs: "an operation whose security requires a credential",
+    plan: (ctx) => andThen(securedPlan(ctx), () => addressOf(ctx)),
+    async run(ctx, address) {
+        const exchange = await send(ctx, address, { anonymous: true });
+        return judgeRefusals(ctx, ID, [
+            {
+                exchange,
+                sent: "a request with no credential",
+                summary: "a secured operation answered a request with no credential",
+            },
+        ]);
+    },
+    subject: "operation",
+});
+//# sourceMappingURL=auth-missing-credential-refused.js.map

package/dist/api/runtime/checks/families/security/auth-privileged-field-ignored.d.ts

@@ -0,0 +1,34 @@
+import type { OperationCheck } from "../../core/check.ts";
+import type { Actor } from "../../core/context.ts";
+import type { WriteTarget } from "../../core/operation-context.ts";
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import { type SignUpProbe } from "./privileged-signup.ts";
+type Fields = Record<string, unknown>;
+/** The record written to, how it is re-read, who writes, who outranks it, and the body it sends. */
+interface RecordProbe {
+    kind: "record";
+    target: WriteTarget;
+    read: OperationModel;
+    /** What any writer may send of the record as it is now; the marked properties are set on it. */
+    body: Fields;
+    /** Every rank below the top of the owner's tenant, highest first: the next writes when one cannot. */
+    writers: Actor[];
+    top: Actor;
+    changes: ReadonlyArray<[path: string, value: unknown]>;
+}
+/** A write to a record the run created, or a sign-up of an account of its own. */
+type PrivilegedProbe = RecordProbe | SignUpProbe;
+/**
+ * Only the highest rank may set a property the document marks `x-privileged: true`. A principal
+ * ranked below it writes a record this run created, through a dedicated credential (never its own
+ * session): the record's current state cut to what the request body accepts, each marked property
+ * changed. The verdict is the record as its owner re-reads it, not the status: a marked property
+ * left as it was passes, whether the write drew a 403, a 400 naming it, or a 200; one that changed is
+ * the finding. A refusal passes only once the same writer's harmless write is accepted: a writer whose
+ * role cannot update the record proves nothing, and the next rank below the top writes instead. A
+ * server error, a record that cannot be re-read, or no rank able to write leaves it unresolved. A sign-up,
+ * which anyone may send, must not grant one either: see `privileged-signup.ts`.
+ */
+export declare const privilegedFieldIgnored: OperationCheck<PrivilegedProbe>;
+export {};
+//# sourceMappingURL=auth-privileged-field-ignored.d.ts.map

package/dist/api/runtime/checks/families/security/auth-privileged-field-ignored.js

@@ -0,0 +1,210 @@
+import { defineCheck } from "../../core/define.js";
+import { isUntested, targetPlan } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { requestContent } from "../../../../spec/collection/request.js";
+import { unlessUnsatisfied } from "./lifecycle.js";
+import { isSignUp, signUpAndJudge, signUpPlan } from "./privileged-signup.js";
+import { currentOf, readOf, recordAt, writableBody } from "./writable.js";
+/**
+ * Only the highest rank may set a property the document marks `x-privileged: true`. A principal
+ * ranked below it writes a record this run created, through a dedicated credential (never its own
+ * session): the record's current state cut to what the request body accepts, each marked property
+ * changed. The verdict is the record as its owner re-reads it, not the status: a marked property
+ * left as it was passes, whether the write drew a 403, a 400 naming it, or a 200; one that changed is
+ * the finding. A refusal passes only once the same writer's harmless write is accepted: a writer whose
+ * role cannot update the record proves nothing, and the next rank below the top writes instead. A
+ * server error, a record that cannot be re-read, or no rank able to write leaves it unresolved. A sign-up,
+ * which anyone may send, must not grant one either: see `privileged-signup.ts`.
+ */
+export const privilegedFieldIgnored = defineCheck({
+    id: "auth.privileged-field-ignored",
+    mutates: true,
+    needs: "a property marked x-privileged, and a sign-up or a run-created record with a principal ranked below the highest",
+    plan: (ctx) => {
+        if (ctx.operation.privileged.length > 0 && isSignUp(ctx))
+            return signUpPlan(ctx);
+        const undeclared = noSecurityReason(ctx.operation);
+        if (undeclared !== undefined)
+            return cannot(undeclared);
+        if (ctx.operation.privileged.length === 0) {
+            const marked = ctx.model.operations.some((op) => op.privileged.length > 0);
+            return cannot(marked
+                ? `a request body property marked x-privileged; ${ctx.operation.operationId} marks none`
+                : "no property is marked x-privileged");
+        }
+        return andThen(targetPlan(ctx), (target) => {
+            const read = readOf(ctx);
+            if (read === undefined)
+                return cannot("a GET on the write's path, to re-read the record");
+            const record = currentOf(target);
+            if (record === undefined)
+                return cannot("the target record's current state, for a harmless body");
+            const body = writableBody(ctx, record);
+            return andThen(changesOf(ctx, { body, record }), (changes) => andThen(writersOf(ctx, target), (pair) => ready({ ...pair, body, changes, kind: "record", read, target })));
+        });
+    },
+    subject: "operation",
+    async run(ctx, probe) {
+        if (probe.kind === "signup")
+            return signUpAndJudge(ctx, probe);
+        const reasons = [];
+        for (const set of ctx.operation.security.alternatives) {
+            const scheme = set.length === 1 ? set[0] : undefined;
+            if (scheme === undefined)
+                continue;
+            const outcome = await acrossWriters(ctx, { probe, scheme });
+            if (!("untested" in outcome))
+                return outcome;
+            reasons.push(outcome.untested);
+        }
+        return standDown(reasons.join("; "));
+    },
+});
+const CHECK = "auth.privileged-field-ignored";
+/**
+ * Each writer in turn, until one can update the record at all. A writer refused even the harmless
+ * write proves nothing about the marked properties (its role may not update this record), so the next
+ * rank below the top writes. Unresolved when every such rank was refused; untested when none could be
+ * sent as.
+ */
+async function acrossWriters(ctx, { probe, scheme }) {
+    const refused = [];
+    const untested = [];
+    for (const writer of probe.writers) {
+        /* The write spends nothing of the credential, so one of the writer's serves every such probe. */
+        const dedicated = await ctx.probe.dedicated({
+            principal: writer.id,
+            reusable: true,
+            scheme: scheme.scheme,
+            scopes: scheme.scopes,
+        });
+        if (isUntested(dedicated)) {
+            untested.push(`${scheme.scheme}: ${dedicated.untested}`);
+            continue;
+        }
+        const as = { principal: dedicated.actor.principal, scheme: scheme.scheme };
+        const outcome = await unlessUnsatisfied(scheme.scheme, () => writeAndJudge(ctx, { as, probe, writer }));
+        if ("untested" in outcome)
+            untested.push(outcome.untested);
+        else if ("refused" in outcome)
+            refused.push(outcome.refused);
+        else
+            return outcome;
+    }
+    /* One reason per scheme, however many writers it stopped. */
+    if (refused.length === 0)
+        return { untested: [...new Set(untested)].join("; ") };
+    const names = probe.changes.map(([path]) => path).join(", ");
+    const reason = `no rank below ${probe.top.id} can update the record (${refused.join(", ")}), so whether one may set ${names} is untested`;
+    return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+}
+async function writeAndJudge(ctx, { as, probe, writer }) {
+    const { changes, read, target, top } = probe;
+    const { method, operationId, requiredQuery: query } = ctx.operation;
+    const names = changes.map(([path]) => path).join(", ");
+    const body = structuredClone(probe.body);
+    for (const [path, value] of changes)
+        setAt(body, path, value);
+    const wrote = await ctx.client.request(method, target.path, { as, body, operationId, probe: true, query });
+    if (wrote.status >= 500) {
+        return ctx.findings.unresolved(CHECK, ctx.subject, `${writer.id}'s write of ${names} drew ${wrote.status}, a server error`);
+    }
+    const reread = await ctx.client.get(target.path, {
+        as: { principal: target.owner },
+        operationId: read.operationId,
+        query: read.requiredQuery,
+    });
+    const state = reread.status < 300 ? recordAt(ctx, reread.responseBody) : undefined;
+    if (state === undefined) {
+        const reason = `the record could not be re-read after the write (${reread.status}), so whether ${names} changed is unknown`;
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    const applied = changes.filter(([path, value]) => Object.is(valueAt(state, path), value)).map(([path]) => path);
+    if (applied.length === 0)
+        return wrote.status < 400 ? ASSERTED : controlled(ctx, { as, probe, writer });
+    return ctx.findings.security(CHECK, ctx.subject, {
+        detail: `${writer.id} (rank ${writer.rank}) wrote ${applied.join(", ")}, marked x-privileged, on a record ` +
+            `this run created; ${operationId} answered ${wrote.status} and the re-read shows it applied. Only ` +
+            `${top.id} (rank ${top.rank}), the highest rank, may set it.`,
+        evidence: [wrote, reread],
+        summary: "a write below the highest rank sets an x-privileged property",
+    });
+}
+/*
+ * A refused probe, told apart: the same writer sends the harmless body alone. Accepted, the refusal
+ * was the marked properties' (a pass); refused too, this writer cannot update the record at all. A
+ * server error is unresolved, as on the probe.
+ */
+async function controlled(ctx, { as, probe, writer }) {
+    const { method, operationId, requiredQuery: query } = ctx.operation;
+    const control = await ctx.client.request(method, probe.target.path, {
+        as,
+        body: structuredClone(probe.body),
+        operationId,
+        probe: true,
+        query,
+    });
+    if (control.status >= 500) {
+        return ctx.findings.unresolved(CHECK, ctx.subject, `${writer.id}'s harmless write drew ${control.status}, a server error`);
+    }
+    return control.status < 300 ? ASSERTED : { refused: `${writer.id} ${control.status}` };
+}
+/* The writers: every principal of the target owner's tenant ranked below its highest, highest first. */
+function writersOf(ctx, target) {
+    const owner = ctx.principals.find((actor) => actor.id === target.owner) ?? ctx.actor;
+    const home = ctx.principals.filter((actor) => actor.tenant === owner.tenant).toSorted((a, b) => b.rank - a.rank);
+    const top = home[0];
+    const writers = home.filter((actor) => actor.rank < top.rank);
+    return writers.length === 0
+        ? cannot("a principal ranked below the highest of the target owner's tenant")
+        : ready({ top, writers });
+}
+/*
+ * Each marked property with the value the probe sets it to, changed from the record's own; any one the API tester
+ * cannot change, or whose parent the body (which never carries a marked property) lacks, stands it down.
+ */
+function changesOf(ctx, { body, record }) {
+    const changes = [];
+    for (const path of ctx.operation.privileged) {
+        const value = changed(valueAt(record, path), typeOf(ctx, path));
+        if (value === undefined || !isFields(parentOf(body, path)))
+            return cannot(`a value of ${path} the API tester can change`);
+        changes.push([path, value]);
+    }
+    return ready(changes);
+}
+/* A different value of the same type: a boolean flipped (a missing boolean set), a number one up, a string suffixed. */
+function changed(current, type) {
+    if (typeof current === "boolean")
+        return !current;
+    if (typeof current === "number")
+        return current + 1;
+    if (typeof current === "string")
+        return `${current}-testing`;
+    return current === undefined && type === "boolean" ? true : undefined;
+}
+/* The declared type of the request body property at the dotted `path`. */
+function typeOf(ctx, path) {
+    /* The model holds every operation it lists; a marked property implies a request body. */
+    const raw = ctx.model.rawOperations.get(ctx.operation.operationId);
+    return valueAt(requestContent(raw), `schema.properties.${path.split(".").join(".properties.")}.type`);
+}
+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);
+}
+/* The object holding the last segment of `path`. */
+function parentOf(value, path) {
+    const keys = path.split(".");
+    return keys.length === 1 ? value : valueAt(value, keys.slice(0, -1).join("."));
+}
+function setAt(value, path, next) {
+    const keys = path.split(".");
+    const last = keys.at(-1);
+    parentOf(value, path)[last] = next;
+}
+//# sourceMappingURL=auth-privileged-field-ignored.js.map

package/dist/api/runtime/checks/families/security/auth-refresh-reuse-refused.d.ts

@@ -0,0 +1,10 @@
+import type { OperationCheck } from "../../core/check.ts";
+import { type Lifecycle } from "./lifecycle.ts";
+/**
+ * A refresh token works once. For each scheme whose recipe declares a refresh, anchored on that
+ * refresh operation, the check acquires a dedicated session (never the principal's own), rotates it,
+ * proves the rotated session on one read, then replays the refresh token the rotation spent. The
+ * replay must fail: a stolen refresh token that keeps refreshing is a session that never ends.
+ */
+export declare const refreshReuseRefused: OperationCheck<Lifecycle[]>;
+//# sourceMappingURL=auth-refresh-reuse-refused.d.ts.map

package/dist/api/runtime/checks/families/security/auth-refresh-reuse-refused.js

@@ -0,0 +1,52 @@
+import { defineCheck } from "../../core/define.js";
+import { isUntested } from "../../core/operation.js";
+import { lifecyclePlan, settle } from "./lifecycle.js";
+/**
+ * A refresh token works once. For each scheme whose recipe declares a refresh, anchored on that
+ * refresh operation, the check acquires a dedicated session (never the principal's own), rotates it,
+ * proves the rotated session on one read, then replays the refresh token the rotation spent. The
+ * replay must fail: a stolen refresh token that keeps refreshing is a session that never ends.
+ */
+export const refreshReuseRefused = defineCheck({
+    id: "auth.refresh-reuse-refused",
+    mutates: true,
+    mutatesCredentials: true,
+    needs: "a recipe that declares a refresh, and a GET the credential authenticates",
+    plan: (ctx) => lifecyclePlan(ctx, "refresh"),
+    subject: "operation",
+    async run(ctx, planned) {
+        const outcomes = [];
+        for (const lifecycle of planned)
+            outcomes.push(await rotateAndReplay(ctx, lifecycle));
+        return settle(outcomes);
+    },
+});
+const CHECK = "auth.refresh-reuse-refused";
+async function rotateAndReplay(ctx, { actor, route, scheme }) {
+    const { method, operation, path, scopes } = route;
+    const reads = operation.operationId;
+    const dedicated = await ctx.probe.dedicated({ principal: actor, scheme, scopes });
+    if (isUntested(dedicated))
+        return { untested: `${scheme}: ${dedicated.untested}` };
+    if (dedicated.rotate === undefined)
+        return { untested: `${scheme}: the dedicated credential has no declared refresh` };
+    const rotation = await dedicated.rotate();
+    const as = { principal: dedicated.actor.principal, scheme };
+    const proven = await ctx.client.request(method, path, { as, operationId: reads, query: operation.requiredQuery });
+    if (proven.status >= 300) {
+        const reason = `the rotated ${scheme} session was refused (${proven.status}) on ${reads}, ` +
+            "so a refused reuse would prove nothing";
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    const replayed = await rotation.replay();
+    if (!replayed.accepted)
+        return { kind: "asserted" };
+    return ctx.findings.security(CHECK, ctx.subject, {
+        detail: `${actor}'s ${scheme} session, issued for this probe alone, was rotated through ` +
+            `${ctx.subject} and proven on ${reads}; the refresh token that rotation spent then refreshed ` +
+            "again. Reuse of a rotated refresh token must fail, and should revoke the whole session.",
+        evidence: [proven, ...ctx.client.exchangesFor(ctx.subject).slice(-1)],
+        summary: `a rotated ${scheme} refresh token refreshes again`,
+    });
+}
+//# sourceMappingURL=auth-refresh-reuse-refused.js.map

package/dist/api/runtime/checks/families/security/auth-revoked-credential-refused.d.ts

@@ -0,0 +1,10 @@
+import type { OperationCheck } from "../../core/check.ts";
+import { type Lifecycle } from "./lifecycle.ts";
+/**
+ * A revoked credential stops working. For each scheme whose recipe declares a revoke, anchored on
+ * that revoke operation, the check acquires a dedicated credential (never the principal's own),
+ * proves it on one read it can send whole (`readRoute`), revokes it through the declared path, and sends it to the same read again,
+ * which must now refuse it with 401 or 403.
+ */
+export declare const revokedCredentialRefused: OperationCheck<Lifecycle[]>;
+//# sourceMappingURL=auth-revoked-credential-refused.d.ts.map