@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,57 @@
+import { defineCheck } from "../../core/define.js";
+import { isUntested } from "../../core/operation.js";
+import { isRefused, lifecyclePlan, settle } from "./lifecycle.js";
+/**
+ * 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 const revokedCredentialRefused = defineCheck({
+    id: "auth.revoked-credential-refused",
+    mutates: true,
+    mutatesCredentials: true,
+    needs: "a recipe that declares a revoke, and a GET the credential authenticates",
+    plan: (ctx) => lifecyclePlan(ctx, "revoke"),
+    subject: "operation",
+    async run(ctx, planned) {
+        const outcomes = [];
+        for (const lifecycle of planned)
+            outcomes.push(await revokeAndProbe(ctx, lifecycle));
+        return settle(outcomes);
+    },
+});
+const CHECK = "auth.revoked-credential-refused";
+async function revokeAndProbe(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}` };
+    const { revoke } = dedicated;
+    if (revoke === undefined)
+        return { untested: `${scheme}: the dedicated credential has no declared revoke` };
+    const as = { principal: dedicated.actor.principal, scheme };
+    const query = operation.requiredQuery;
+    const before = await ctx.client.request(method, path, { as, operationId: reads, query });
+    if (before.status >= 300) {
+        const reason = `a fresh ${scheme} credential was refused (${before.status}) on ${reads} before its revoke`;
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    await revoke();
+    const after = await ctx.client.request(method, path, { as, operationId: reads, probe: true, query });
+    if (isRefused(after.status))
+        return { kind: "asserted" };
+    if (after.status >= 300) {
+        const reason = `after its revoke, a ${scheme} credential drew ${after.status} on ${reads}, neither a refusal nor a success`;
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    return ctx.findings.security(CHECK, ctx.subject, {
+        detail: `${actor}'s ${scheme} credential, issued for this probe alone and revoked through ` +
+            `${ctx.subject}, was still accepted: ${reads} answered ${after.status}. A credential that ` +
+            "survives its revoke cannot be taken back from whoever holds it.",
+        evidence: [before, after],
+        summary: `a revoked ${scheme} credential still authenticates`,
+    });
+}
+//# sourceMappingURL=auth-revoked-credential-refused.js.map

package/dist/api/runtime/checks/families/security/auth-role-enforced.d.ts

@@ -0,0 +1,21 @@
+import type { OperationCheck } from "../../core/check.ts";
+import type { Actor } from "../../core/context.ts";
+import type { WriteTarget } from "../../core/operation-context.ts";
+/** The record written to, what is sent (a delete sends nothing), and the readOnly principal that writes. */
+interface RoleProbe {
+    target: WriteTarget;
+    send: {
+        body?: Record<string, unknown>;
+    };
+    readOnly: Actor;
+}
+/**
+ * A read-only role cannot write. Only the config says which principal is read-only (`readOnly: true`);
+ * rank alone never does. That principal's write to a record this run created, in its own tenant, with
+ * the record's current state cut to what the request body accepts (a delete sends none), must be
+ * refused with 401 or 403. Unlike
+ * auth.rank-is-monotonic-on-writes this fires when every rank may write, which is still monotonic.
+ */
+export declare const roleEnforced: OperationCheck<RoleProbe>;
+export {};
+//# sourceMappingURL=auth-role-enforced.d.ts.map

package/dist/api/runtime/checks/families/security/auth-role-enforced.js

@@ -0,0 +1,74 @@
+import { defineCheck } from "../../core/define.js";
+import { isReadMethod, targetPlan } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { ASSERTED } from "../../../finding.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { isRefused, settle, unlessUnsatisfied } from "./lifecycle.js";
+import { BY_VALIDATION, byValidation } from "./probing.js";
+import { currentOf, writableBody } from "./writable.js";
+/**
+ * A read-only role cannot write. Only the config says which principal is read-only (`readOnly: true`);
+ * rank alone never does. That principal's write to a record this run created, in its own tenant, with
+ * the record's current state cut to what the request body accepts (a delete sends none), must be
+ * refused with 401 or 403. Unlike
+ * auth.rank-is-monotonic-on-writes this fires when every rank may write, which is still monotonic.
+ */
+export const roleEnforced = defineCheck({
+    id: "auth.role-enforced",
+    mutates: true,
+    needs: "a principal marked readOnly, and a run-created record in its tenant to write to",
+    plan: (ctx) => {
+        const undeclared = noSecurityReason(ctx.operation);
+        if (undeclared !== undefined)
+            return cannot(undeclared);
+        if (isReadMethod(ctx.operation))
+            return cannot("a write method");
+        if (ctx.operation.security.alternatives.some((set) => set.length === 0)) {
+            return cannot("a write the document secures");
+        }
+        return andThen(targetPlan(ctx), (target) => {
+            const record = currentOf(target);
+            const deletes = ctx.operation.method.toUpperCase() === "DELETE";
+            if (!deletes && record === undefined)
+                return cannot("the target record's current state, for a harmless body");
+            const send = deletes || record === undefined ? {} : { body: writableBody(ctx, record) };
+            return andThen(readOnlyOf(ctx, target), (readOnly) => ready({ readOnly, send, target }));
+        });
+    },
+    subject: "operation",
+    async run(ctx, planned) {
+        return settle([await unlessUnsatisfied(`${planned.readOnly.id}'s write`, () => writeAs(ctx, planned))]);
+    },
+});
+const CHECK = "auth.role-enforced";
+/* The read-only principal's harmless write to the run's record: refused passes, applied is the finding. */
+async function writeAs(ctx, { readOnly, send, target }) {
+    const { method, operationId, requiredQuery: query } = ctx.operation;
+    const as = { principal: readOnly.id };
+    const wrote = await ctx.client.request(method, target.path, { ...send, as, operationId, probe: true, query });
+    if (isRefused(wrote.status))
+        return ASSERTED;
+    if (byValidation(wrote.status)) {
+        return ctx.findings.unresolved(CHECK, ctx.subject, `${readOnly.id}'s write drew ${wrote.status}: ${BY_VALIDATION}`);
+    }
+    if (wrote.status >= 300) {
+        const reason = `${readOnly.id}'s write drew ${wrote.status}, neither a refusal nor a success`;
+        return ctx.findings.unresolved(CHECK, ctx.subject, reason);
+    }
+    return ctx.findings.security(CHECK, ctx.subject, {
+        detail: `${readOnly.id}, marked readOnly in tenant ${String(readOnly.tenant)}, wrote to a record this ` +
+            `run created, and ${operationId} answered ${wrote.status}. Roles must be enforced on writes.`,
+        evidence: [wrote],
+        summary: "a read-only principal's write is accepted",
+    });
+}
+/* The first principal marked readOnly in the target owner's tenant. */
+function readOnlyOf(ctx, target) {
+    const marked = ctx.principals.filter((actor) => actor.readOnly === true);
+    if (marked.length === 0)
+        return cannot("no principal is marked readOnly");
+    const owner = ctx.principals.find((actor) => actor.id === target.owner) ?? ctx.actor;
+    const readOnly = marked.find((actor) => actor.tenant === owner.tenant);
+    return readOnly === undefined ? cannot("a readOnly principal sharing the target owner's tenant") : ready(readOnly);
+}
+//# sourceMappingURL=auth-role-enforced.js.map

package/dist/api/runtime/checks/families/security/auth-scope-enforced.d.ts

@@ -0,0 +1,10 @@
+import type { OperationCheck } from "../../core/check.ts";
+import type { Requirement } from "../../../../spec/security/requirements.ts";
+import { type Address } from "./probing.ts";
+interface Planned {
+    address: Address;
+    scoped: Requirement[];
+}
+export declare const scopeEnforced: OperationCheck<Planned>;
+export {};
+//# sourceMappingURL=auth-scope-enforced.d.ts.map

package/dist/api/runtime/checks/families/security/auth-scope-enforced.js

@@ -0,0 +1,89 @@
+/*
+ * A credential without the scope an operation requires must be refused. For each alternative of one
+ * scheme that names scopes, the actor's credential for that scheme issued with no scope at all is
+ * sent in its place. Only a mint recipe issues a credential for the scopes asked: a login holds
+ * whatever the server grants, and a grant asked for no scope gets the server's default, so either
+ * would send a fully scoped credential and report a refusal that is not due. The key is acquired
+ * through the store, once per run for the empty scope set, so teardown revokes it with the rest; it
+ * is a real value, sent as a derived forged one and redacted. A refusal counts only once the same
+ * actor's credential issued with the scopes is let in: a server that refuses the scheme outright, as
+ * one whose API keys are broken does, refuses the bare credential too, and that is no scope check. The
+ * control goes second, so a write it lets through never takes the record from the probe. Probes go
+ * where `addressOf` puts them; mutating, since some write.
+ */
+import { ASSERTED, standDown } from "../../../finding.js";
+import { defineCheck } from "../../core/define.js";
+import { isUntested } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { addressOf, judgeRefusals, refused, securedPlan, send, singleSchemes, } from "./probing.js";
+const ID = "auth.scope-enforced";
+export const scopeEnforced = defineCheck({
+    id: ID,
+    mutates: true,
+    needs: "an operation that requires a scope, of a scheme a mint recipe issues",
+    plan: (ctx) => andThen(securedPlan(ctx), () => andThen(mintedPlan(ctx), (scoped) => andThen(addressOf(ctx), (address) => ready({ address, scoped })))),
+    async run(ctx, { address, scoped }) {
+        const probes = [];
+        const untested = [];
+        for (const requirement of scoped) {
+            const probe = await probeWithout(ctx, address, requirement);
+            if (typeof probe === "string")
+                untested.push(probe);
+            else
+                probes.push(probe);
+        }
+        if (probes.length === 0)
+            return standDown(untested.join("; "));
+        const judged = judgeRefusals(ctx, ID, probes);
+        return judged.kind === "asserted" ? controlled(ctx, address, scoped) : judged;
+    },
+    subject: "operation",
+});
+/* The actor's credential for `requirement`'s scheme issued without its scopes, sent; or why it cannot be had. */
+async function probeWithout(ctx, address, { scheme, scopes }) {
+    const bare = await ctx.probe.held({ principal: ctx.actor.id, scheme, scopes: [] });
+    if (isUntested(bare))
+        return bare.untested;
+    return {
+        exchange: await send(ctx, address, { forged: { derived: true, scheme, value: bare.value } }),
+        sent: `${ctx.actor.id}'s ${scheme} credential issued without ${scopes.join(" ")}`,
+        summary: "an operation accepted a credential without the scope it requires",
+    };
+}
+/*
+ * Every bare credential was refused: asserted once the actor's credential issued with the scopes is
+ * let in, for each scheme, and unresolved where it is refused too.
+ */
+async function controlled(ctx, address, scoped) {
+    for (const { scheme, scopes } of scoped) {
+        const full = await ctx.probe.held({ principal: ctx.actor.id, scheme, scopes });
+        if (isUntested(full))
+            return standDown(full.untested);
+        const control = await send(ctx, address, { forged: { derived: true, scheme, value: full.value } });
+        if (refused(control.status)) {
+            return ctx.findings.unresolved(ID, ctx.subject, `${ctx.subject} refused ${ctx.actor.id}'s ${scheme} credential issued with ${scopes.join(" ")} too ` +
+                `(${control.status}), so the refusal without the scope proves nothing`);
+        }
+    }
+    return ASSERTED;
+}
+/* The scoped alternatives of one scheme whose recipe is a mint, or why there are none. */
+function mintedPlan(ctx) {
+    const scoped = singleSchemes(ctx.security).filter((requirement) => requirement.scopes.length > 0);
+    if (scoped.length === 0)
+        return cannot("an alternative that requires a scope");
+    const minted = [];
+    const reasons = [];
+    for (const requirement of scoped) {
+        const recipe = ctx.probe.recipe({ principal: ctx.actor.id, scheme: requirement.scheme });
+        if (isUntested(recipe))
+            reasons.push(recipe.untested);
+        else if (recipe.kind === "mint")
+            minted.push(requirement);
+        else {
+            reasons.push(`a mint recipe, which issues a credential for the scopes asked; ${ctx.actor.id}'s ${requirement.scheme} recipe is a ${recipe.kind} recipe`);
+        }
+    }
+    return minted.length === 0 ? cannot(reasons.join("; ")) : ready(minted);
+}
+//# sourceMappingURL=auth-scope-enforced.js.map

package/dist/api/runtime/checks/families/security/auth-wrong-scheme-refused.d.ts

@@ -0,0 +1,10 @@
+import type { OperationCheck } from "../../core/check.ts";
+import type { Requirement } from "../../../../spec/security/requirements.ts";
+import { type Address } from "./probing.ts";
+interface Planned {
+    address: Address;
+    others: Requirement[];
+}
+export declare const wrongSchemeRefused: OperationCheck<Planned>;
+export {};
+//# sourceMappingURL=auth-wrong-scheme-refused.d.ts.map

package/dist/api/runtime/checks/families/security/auth-wrong-scheme-refused.js

@@ -0,0 +1,45 @@
+/*
+ * A secured operation must refuse a valid credential of a scheme it does not list: a route the
+ * document secures with jwt alone takes no API key, however real. For each declared scheme another
+ * operation of the document names and this one does not, the actor's own credential for it (with the
+ * scopes it is first named with) is sent in its place. It is a real value, so it is sent as a derived
+ * forged one, redacted like the credential. Probes go where `addressOf` puts them; mutating, since
+ * some write.
+ */
+import { standDown } from "../../../finding.js";
+import { defineCheck } from "../../core/define.js";
+import { isUntested } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { addressOf, documentSchemes, judgeRefusals, securedPlan, send } from "./probing.js";
+const ID = "auth.wrong-scheme-refused";
+export const wrongSchemeRefused = defineCheck({
+    id: ID,
+    mutates: true,
+    needs: "an operation whose security requires a credential, and a scheme it does not list",
+    plan: (ctx) => andThen(securedPlan(ctx), () => {
+        const listed = new Set(ctx.security.alternatives.flat().map((requirement) => requirement.scheme));
+        const others = documentSchemes(ctx.model).filter((requirement) => !listed.has(requirement.scheme));
+        if (others.length === 0)
+            return cannot(`a scheme the document uses that ${ctx.subject} does not list`);
+        return andThen(addressOf(ctx), (address) => ready({ address, others }));
+    }),
+    async run(ctx, { address, others }) {
+        const probes = [];
+        const untested = [];
+        for (const { scheme, scopes } of others) {
+            const held = await ctx.probe.held({ principal: ctx.actor.id, scheme, scopes });
+            if (isUntested(held)) {
+                untested.push(held.untested);
+                continue;
+            }
+            probes.push({
+                exchange: await send(ctx, address, { forged: { derived: true, scheme, value: held.value } }),
+                sent: `${ctx.actor.id}'s ${scheme} credential, a scheme it does not list`,
+                summary: "an operation accepted a credential of a scheme it does not list",
+            });
+        }
+        return probes.length === 0 ? standDown(untested.join("; ")) : judgeRefusals(ctx, ID, probes);
+    },
+    subject: "operation",
+});
+//# sourceMappingURL=auth-wrong-scheme-refused.js.map

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

@@ -0,0 +1,70 @@
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import type { SafeMethod } from "../../../../spec/methods.ts";
+import { type Outcome } from "../../../finding.ts";
+import type { OperationContext } from "../../core/operation-context.ts";
+import { type Plan } from "../../core/plan.ts";
+/** The recipe step a check anchors on. */
+export type AnchorKind = "issue" | "refresh" | "revoke";
+/** Which step, and whether only a login recipe's counts. */
+export interface Anchoring {
+    kind: AnchorKind;
+    login?: true;
+}
+/**
+ * The schemes whose recipe, for the actor, names this operation for the step: the check runs here,
+ * once for each. Elsewhere it stands down naming where it runs; with no anchor at all, giving each
+ * scheme's reason.
+ */
+export declare function anchoredSchemes(ctx: OperationContext, anchoring: Anchoring): Plan<string[]>;
+/** The one read a lifecycle check proves a credential on. */
+export interface ReadRoute {
+    operation: OperationModel;
+    /** The method it is sent with: GET or HEAD. */
+    method: SafeMethod;
+    /** Its path, filled from the scope of the principal the credential is proven as (`acceptorOf`). */
+    path: string;
+    /** The scopes the scheme's alternative asks for, which a minted credential must carry. */
+    scopes: string[];
+}
+/**
+ * The read a lifecycle probe proves a credential on: a GET or HEAD that takes `scheme` alone and that
+ * The API tester can send whole. Its path is filled from the scope of the principal the probe acts as (the
+ * target's creator, which expects acceptance, else the actor), or a path parameter's declared enum;
+ * every required query, header and cookie parameter has a declared value (`unfilledRequired`). A
+ * read that cannot be sent whole never answers 2xx, and the check could never conclude. Among the
+ * reads that can, the first in document order of the best rank (`rankOf`).
+ */
+export declare function readRoute(ctx: OperationContext, scheme: string): ReadRoute | undefined;
+/** One scheme a lifecycle check runs for, the read it proves the credential on, and whose credential it is. */
+export interface Lifecycle {
+    scheme: string;
+    route: ReadRoute;
+    /** The principal whose dedicated credential is proven, then revoked or rotated (`acceptorOf`). */
+    actor: string;
+}
+/** Why a lifecycle check stands down when no scheme it anchors has a read `readRoute` can send. */
+export declare const NO_READ = "no read this credential protects that the API tester can send";
+/**
+ * A lifecycle check's plan: the schemes anchored on this operation, each with its read. A scheme
+ * with no such read is left out; with none left, the check stands down naming what it needs.
+ */
+export declare function lifecyclePlan(ctx: OperationContext, kind: AnchorKind): Plan<Lifecycle[]>;
+/** A refusal of a credential: 401, or 403. */
+export declare function isRefused(status: number): boolean;
+/** What probing one scheme came to: an outcome, or why that scheme could not be probed. */
+export type SchemeOutcome = Outcome | {
+    untested: string;
+};
+/**
+ * What `work` decided, or untested with why when a credential it sends cannot be: BLOCKED by a failed
+ * login, mint or renewal, or none that meets the security. `label` names whose request it was.
+ */
+export declare function unlessUnsatisfied<T = Outcome>(label: string, work: () => Promise<T>): Promise<T | {
+    untested: string;
+}>;
+/**
+ * One outcome for every scheme a check probed: a finding first, then an unresolved run, then a pass
+ * that notes what stayed untested. With no scheme tested, the check stands down with every reason.
+ */
+export declare function settle(outcomes: readonly SchemeOutcome[]): Outcome;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1,161 @@
+/*
+ * What the credential-lifecycle checks share. A session's issue, refresh and revoke are properties of
+ * the credential, not of a route, so each check anchors once per scheme on the operation the actor's
+ * recipe names for that step. It proves the credential on one read the API tester can send whole (`readRoute`).
+ * Per-route guard coverage is the missing- and invalid-credential checks'.
+ */
+import { UnsatisfiedSecurity } from "../../../../client/credential-source.js";
+import { unfilledRequired } from "../../../../spec/graph/parameters.js";
+import { SELF_IDENTITY } from "../../../../spec/sign-up.js";
+import { fillPath } from "../../../fill-path.js";
+import { ASSERTED, asserted, standDown } from "../../../finding.js";
+import { noSecurityReason } from "../../../no-security.js";
+import { isUntested } from "../../core/operation.js";
+import { andThen, cannot, ready } from "../../core/plan.js";
+import { acceptorOf } from "./probing.js";
+const NAMED = {
+    issue: "documented issuing step",
+    refresh: "refresh",
+    revoke: "revoke",
+};
+/* Why this recipe cannot anchor the step at all, or undefined when it names one. */
+function refusalOf(recipe, { kind, login }) {
+    if (login === true && recipe.kind !== "login")
+        return `${recipe.kind} recipes have no login step`;
+    return recipe[kind] === undefined ? `the ${recipe.kind} recipe declares no ${NAMED[kind]}` : undefined;
+}
+/**
+ * The schemes whose recipe, for the actor, names this operation for the step: the check runs here,
+ * once for each. Elsewhere it stands down naming where it runs; with no anchor at all, giving each
+ * scheme's reason.
+ */
+export function anchoredSchemes(ctx, anchoring) {
+    const here = [];
+    const elsewhere = new Set();
+    const reasons = [];
+    for (const scheme of ctx.model.securitySchemes) {
+        const recipe = ctx.probe.recipe({ principal: ctx.actor.id, scheme });
+        const refused = isUntested(recipe) ? recipe.untested : refusalOf(recipe, anchoring);
+        const anchor = isUntested(recipe) ? undefined : recipe[anchoring.kind];
+        if (refused !== undefined)
+            reasons.push(`${scheme}: ${refused}`);
+        else if (anchor === ctx.operation.operationId)
+            here.push(scheme);
+        else
+            elsewhere.add(anchor);
+    }
+    if (here.length > 0)
+        return ready(here);
+    if (elsewhere.size > 0) {
+        return cannot(`the ${anchoring.kind} operation of a recipe; this check runs on ${[...elsewhere].join(", ")}`);
+    }
+    return cannot(reasons.length > 0 ? reasons.join("; ") : "a declared security scheme");
+}
+/** The safe methods a credential is proven with: neither carries a body. */
+const PROVING = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+/**
+ * The read a lifecycle probe proves a credential on: a GET or HEAD that takes `scheme` alone and that
+ * The API tester can send whole. Its path is filled from the scope of the principal the probe acts as (the
+ * target's creator, which expects acceptance, else the actor), or a path parameter's declared enum;
+ * every required query, header and cookie parameter has a declared value (`unfilledRequired`). A
+ * read that cannot be sent whole never answers 2xx, and the check could never conclude. Among the
+ * reads that can, the first in document order of the best rank (`rankOf`).
+ */
+export function readRoute(ctx, scheme) {
+    const { scope } = acceptorOf(ctx);
+    let best;
+    for (const operation of ctx.model.operations) {
+        if (!PROVING.has(operation.method.toUpperCase()) || operation.security.source === "none")
+            continue;
+        const alone = operation.security.alternatives.find((set) => set.length === 1 && set[0]?.scheme === scheme)?.[0];
+        if (alone === undefined)
+            continue;
+        const raw = ctx.model.rawOperations.get(operation.operationId);
+        const values = pathValues(operation, raw, scope);
+        if (values === undefined || unfilledRequired(raw).length > 0)
+            continue;
+        const rank = rankOf(operation, raw);
+        if (best !== undefined && best.rank <= rank)
+            continue;
+        const path = fillPath(operation.path, values);
+        const method = operation.method.toUpperCase();
+        best = { rank, route: { method, operation, path, scopes: [...alone.scopes] } };
+    }
+    return best?.route;
+}
+/* Each path parameter's value from the scope, else its declared enum's first; undefined once one has neither. */
+function pathValues(operation, raw, scope) {
+    const values = {};
+    for (const name of operation.pathParams) {
+        const enumerated = raw.parameters?.find((param) => param.in === "path" && param.name === name)?.schema?.["enum"];
+        const value = Object.hasOwn(scope, name) ? scope[name] : Array.isArray(enumerated) ? enumerated[0] : undefined;
+        if (value === undefined || value === null)
+            return undefined;
+        values[name] = String(value);
+    }
+    return values;
+}
+/*
+ * Lower is better: a read that needs no parameter at all, then the caller's own read or a list, which
+ * any credential of the scheme should be let into, over a read of one record it may not reach. A GET
+ * breaks a tie with a HEAD: some stacks answer HEAD outside their auth middleware (an automatic
+ * HEAD, a static or proxy layer), and its 2xx would read a revoked credential as accepted.
+ */
+function rankOf(operation, raw) {
+    const bare = operation.pathParams.length === 0 && !(raw.parameters ?? []).some((param) => param.required === true);
+    const open = operation.identity === SELF_IDENTITY || operation.action === "list";
+    const head = operation.method.toUpperCase() === "HEAD";
+    return (bare ? 0 : 4) + (open ? 0 : 2) + (head ? 1 : 0);
+}
+/** Why a lifecycle check stands down when no scheme it anchors has a read `readRoute` can send. */
+export const NO_READ = "no read this credential protects that the API tester can send";
+/**
+ * A lifecycle check's plan: the schemes anchored on this operation, each with its read. A scheme
+ * with no such read is left out; with none left, the check stands down naming what it needs.
+ */
+export function lifecyclePlan(ctx, kind) {
+    const undeclared = noSecurityReason(ctx.operation);
+    if (undeclared !== undefined)
+        return cannot(undeclared);
+    const actor = acceptorOf(ctx).id;
+    return andThen(anchoredSchemes(ctx, { kind }), (schemes) => {
+        const planned = schemes.flatMap((scheme) => {
+            const route = readRoute(ctx, scheme);
+            return route === undefined ? [] : [{ actor, route, scheme }];
+        });
+        return planned.length > 0 ? ready(planned) : cannot(NO_READ);
+    });
+}
+/** A refusal of a credential: 401, or 403. */
+export function isRefused(status) {
+    return status === 401 || status === 403;
+}
+/**
+ * What `work` decided, or untested with why when a credential it sends cannot be: BLOCKED by a failed
+ * login, mint or renewal, or none that meets the security. `label` names whose request it was.
+ */
+export async function unlessUnsatisfied(label, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (!(error instanceof UnsatisfiedSecurity))
+            throw error;
+        return { untested: `${label}: ${error.reason}` };
+    }
+}
+/**
+ * One outcome for every scheme a check probed: a finding first, then an unresolved run, then a pass
+ * that notes what stayed untested. With no scheme tested, the check stands down with every reason.
+ */
+export function settle(outcomes) {
+    const ran = outcomes.filter((outcome) => !("untested" in outcome));
+    const untested = outcomes.flatMap((outcome) => ("untested" in outcome ? [outcome.untested] : []));
+    const decided = ran.find((outcome) => outcome.kind === "finding") ?? ran.find((o) => o.kind === "unresolved");
+    if (decided !== undefined)
+        return decided;
+    if (ran.length === 0)
+        return standDown(untested.join("; "));
+    return untested.length > 0 ? asserted(`untested: ${untested.join("; ")}`) : ASSERTED;
+}
+//# sourceMappingURL=lifecycle.js.map

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

@@ -0,0 +1,44 @@
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import { type Outcome } from "../../../finding.ts";
+import type { Actor } from "../../core/context.ts";
+import type { OperationContext, OperationWriteContext } from "../../core/operation-context.ts";
+import { type Plan } from "../../core/plan.ts";
+type Fields = Record<string, unknown>;
+/** A read that shows the account the sign-up made, and how it is sent. */
+export type ReadBack = 
+/** The account's own read, sent as the account. */
+{
+    kind: "self";
+    op: OperationModel;
+}
+/** The listing of the entity the sign-up makes, sent as `as`; the account's row is the one `identity` names. */
+ | {
+    kind: "listing";
+    op: OperationModel;
+    as: Actor;
+    path: string;
+    identity: Record<string, string>;
+}
+/** The sign-up's own answer. */
+ | {
+    kind: "answer";
+};
+/** The body the sign-up sends, each marked property with the value it is set to, and the reads that show it. */
+export interface SignUpProbe {
+    kind: "signup";
+    body: Fields;
+    values: ReadonlyArray<[path: string, value: unknown]>;
+    reads: readonly ReadBack[];
+}
+/** Whether the operation signs an account up: marked x-fresh-principal, or a sign-up the document leaves unmarked. */
+export declare function isSignUp(ctx: Pick<OperationContext, "model" | "operation">): boolean;
+/** What the sign-up probe sends and reads; a stand-down naming what is missing, before anything is sent. */
+export declare function signUpPlan(ctx: OperationContext): Plan<SignUpProbe>;
+/**
+ * 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 declare function signUpAndJudge(ctx: OperationWriteContext, probe: SignUpProbe): Promise<Outcome>;
+export {};
+//# sourceMappingURL=privileged-signup.d.ts.map