@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/conformance/unique/document.d.ts

@@ -0,0 +1,12 @@
+/** The unique suite's document cases: how `x-unique` parses, and where plan and doctor show it. */
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { ParserResult } from "../harness/result.ts";
+/** The plan of `model`, which tags its widget `[name]`, shows the sets. */
+export declare function planCase(model: SpecModel): ParserResult;
+/** The doctor report of `model`, which tags its widget `[name]`, shows the sets. */
+export declare function doctorCase(model: SpecModel): ParserResult;
+/** Every case about the document alone, in the order the suite reports them. */
+export declare function documentCases(): ParserResult[];
+/** `text`, the doctor report of a widget with no tag, names the checks the tag would unlock. */
+export declare function untaggedDoctorCase(text: string): ParserResult;
+//# sourceMappingURL=document.d.ts.map

package/dist/api/conformance/unique/document.js

@@ -0,0 +1,106 @@
+/** The unique suite's document cases: how `x-unique` parses, and where plan and doctor show it. */
+import { report } from "../../report/console/report.js";
+import { formatUniqueSets, readUnique } from "../../spec/extensions/unique.js";
+import { buildModel } from "../../spec/graph/build.js";
+import { dereference } from "../../spec/load/dereference.js";
+import { widgetSpec } from "./spec.js";
+const parsed = (tag) => readUnique({ "x-unique": tag });
+function shapesCase() {
+    const shapes = [
+        ["list of sets", [["email"], ["workspace_id", "slug"]]],
+        ["column objects", [{ columns: ["email"] }, { columns: ["workspace_id", "slug"] }]],
+        ["single string[]", ["email"]],
+    ];
+    const sets = shapes.map(([, tag]) => parsed(tag));
+    return {
+        detail: shapes.map(([name], i) => `${name}=${JSON.stringify(sets[i])}`).join("; "),
+        name: "accepted x-unique shapes parse to column sets",
+        ok: JSON.stringify(sets[0]) === JSON.stringify([["email"], ["workspace_id", "slug"]]) &&
+            JSON.stringify(sets[1]) === JSON.stringify([["email"], ["workspace_id", "slug"]]) &&
+            JSON.stringify(sets[2]) === JSON.stringify([["email"]]),
+        why: "list of sets, {columns}, and a single string[] are the documented forms",
+    };
+}
+function malformedCase() {
+    const { doc } = dereference({
+        info: { title: "malformed", version: "1" },
+        openapi: "3.1.0",
+        paths: {
+            "/v1/things": {
+                post: {
+                    operationId: "thing.create",
+                    responses: { "201": { description: "ok" } },
+                    "x-entity": { action: "create", identity: "id", name: "thing" },
+                    "x-unique": { not: "an array" },
+                },
+            },
+        },
+    });
+    const model = buildModel(doc);
+    const gap = model.gaps.gaps.some((g) => g.tag === "x-unique");
+    const unique = model.byOperationId.get("thing.create")?.unique;
+    return {
+        detail: `unique=${String(unique)} gap=${String(gap)}`,
+        name: "malformed x-unique is absent plus a doctor gap",
+        ok: unique === null && gap,
+        why: "non-array is not a guess",
+    };
+}
+/** The plan of `model`, which tags its widget `[name]`, shows the sets. */
+export function planCase(model) {
+    const plan = report.plan(model, false);
+    const unique = model.entities.get("widget")?.unique ?? null;
+    const shown = plan.includes("x-unique:");
+    return {
+        detail: shown ? formatUniqueSets(unique) : "missing from plan",
+        name: "plan lists x-unique",
+        ok: shown && plan.includes("[name]") && unique !== null,
+        why: "doctor / plan should show the effective sets",
+    };
+}
+/** The doctor report of `model`, which tags its widget `[name]`, shows the sets. */
+export function doctorCase(model) {
+    const { text } = report.doctor(model);
+    const shown = text.includes("x-unique:");
+    return {
+        detail: shown ? "shown" : "missing from doctor",
+        name: "doctor lists x-unique",
+        ok: shown && text.includes("[name]"),
+        why: "doctor / plan should show the effective sets",
+    };
+}
+/** Every case about the document alone, in the order the suite reports them. */
+export function documentCases() {
+    const empty = JSON.stringify(parsed([[], []]));
+    const tagged = buildModel(widgetSpec({ tag: [["name"], ["email"]] }));
+    const none = JSON.stringify(buildModel(widgetSpec({ tag: [] })).byOperationId.get("widget.create")?.unique);
+    return [
+        shapesCase(),
+        {
+            detail: empty,
+            name: "empty sets are dropped",
+            ok: empty === "[]",
+            why: "[[]] after filtering is explicit none",
+        },
+        malformedCase(),
+        planCase(tagged),
+        doctorCase(tagged),
+        {
+            detail: none,
+            name: "[] after filter does not run unique checks",
+            ok: none === "[]",
+            why: "explicit none",
+        },
+    ];
+}
+/** `text`, the doctor report of a widget with no tag, names the checks the tag would unlock. */
+export function untaggedDoctorCase(text) {
+    const named = text.includes("x-unique");
+    return {
+        detail: named ? "named" : "missing from doctor",
+        name: "doctor says unique checks do not run without the tag",
+        ok: named && text.includes("create.unique-conflict-rejected"),
+        why: "TAG_UNLOCKS names the locked checks",
+    };
+}
+//# sourceMappingURL=document.js.map

package/dist/api/conformance/unique/judges.d.ts

@@ -0,0 +1,28 @@
+/** How the unique suite judges what one run saw: each judge is one result the suite reports. */
+import type { Outcome } from "./backend.ts";
+export interface Verdict {
+    ok: boolean;
+    detail: string;
+}
+export declare function untaggedNotProbed({ result }: Outcome): Verdict;
+export declare function createNotProbed({ result }: Outcome): Verdict;
+export declare function updateNotProbed({ result }: Outcome): Verdict;
+export declare function noneProbed({ result }: Outcome): Verdict;
+export declare function duplicateRefused({ result }: Outcome): Verdict;
+export declare function duplicateInserted({ result }: Outcome): Verdict;
+export declare function listKept({ result }: Outcome): Verdict;
+export declare function oneSetInserted({ result }: Outcome): Verdict;
+export declare function updateRefused({ result }: Outcome): Verdict;
+export declare function updateApplied({ result }: Outcome): Verdict;
+/** No probe after the seed sends the seed's own Idempotency-Key again. */
+export declare function freshKey({ posts, result }: Outcome): Verdict;
+export declare function driftReported({ result }: Outcome): Verdict;
+/** The probe answered with something that is neither a 409 nor an insert: a gap, never a pass or a bug. */
+export declare function coverageNotPass({ result }: Outcome): Verdict;
+export declare function seedAdopted({ result }: Outcome): Verdict;
+export declare function probedAfterAdopt({ result }: Outcome): Verdict;
+export declare function seedNotEvidence({ result }: Outcome): Verdict;
+export declare function seedBlocked({ result }: Outcome): Verdict;
+export declare function untaggedNotAdopted({ result }: Outcome): Verdict;
+export declare function distinctInserted({ result }: Outcome): Verdict;
+//# sourceMappingURL=judges.d.ts.map

package/dist/api/conformance/unique/judges.js

@@ -0,0 +1,118 @@
+/** How the unique suite judges what one run saw: each judge is one result the suite reports. */
+import { isRootCause } from "../../runtime/finding.js";
+const CREATE = "create.unique-conflict-rejected";
+const UPDATE = "update.unique-conflict-rejected";
+function found(result, check, verdict) {
+    return result.findings.find((f) => f.check === check && f.verdict === verdict);
+}
+function seedOf(result) {
+    return result.findings.find((f) => f.check === "world.seed" && f.entity === "widget");
+}
+function seedDetail(seed) {
+    return `seed=${seed?.verdict ?? "none"} ${seed?.detail ?? ""}`;
+}
+/** A check that must not run: `ok` while it is absent, said as `[ran, absent]`. */
+function absent(ran, [yes, no]) {
+    return { detail: ran ? yes : no, ok: !ran };
+}
+/** A BACKEND_BUG on `check` that must be found: its detail, or `missing` when it is not. */
+function bug(result, check, missing) {
+    const hit = found(result, check, "BACKEND_BUG");
+    return { detail: hit === undefined ? missing() : hit.detail, ok: hit !== undefined };
+}
+export function untaggedNotProbed({ result }) {
+    return absent(result.checksRun.includes(CREATE), [`${CREATE} ran`, "absent from checksRun"]);
+}
+export function createNotProbed({ result }) {
+    return absent(result.checksRun.includes(CREATE), ["ran", "skipped"]);
+}
+export function updateNotProbed({ result }) {
+    return absent(result.checksRun.includes(UPDATE), ["ran", "skipped"]);
+}
+export function noneProbed({ result }) {
+    return absent(result.checksRun.includes(CREATE) || result.checksRun.includes(UPDATE), ["ran", "absent"]);
+}
+export function duplicateRefused({ result }) {
+    const bugs = result.findings.filter(isRootCause).filter((f) => f.check === CREATE);
+    const ran = result.checksRun.includes(CREATE);
+    return {
+        detail: `ran=${String(ran)} bugs=${bugs.map((f) => f.verdict).join(",") || "none"}`,
+        ok: ran && bugs.length === 0,
+    };
+}
+export function duplicateInserted({ result }) {
+    return bug(result, CREATE, () => result.findings.map((f) => `${f.verdict}:${f.check}`).join(",") || "no finding");
+}
+export function listKept({ result }) {
+    const grew = result.findings.some((f) => f.check === CREATE && f.summary.includes("grew"));
+    return { detail: grew ? "cardinality finding" : "no growth finding", ok: !grew };
+}
+export function oneSetInserted({ result }) {
+    return bug(result, CREATE, () => "no BACKEND_BUG");
+}
+export function updateRefused({ result }) {
+    const hit = found(result, UPDATE, "BACKEND_BUG");
+    const ran = result.checksRun.includes(UPDATE);
+    return { detail: `ran=${String(ran)} bug=${hit?.detail ?? "none"}`, ok: ran && hit === undefined };
+}
+export function updateApplied({ result }) {
+    return bug(result, UPDATE, () => "no finding");
+}
+/** No probe after the seed sends the seed's own Idempotency-Key again. */
+export function freshKey({ posts, result }) {
+    const first = posts[0]?.headers["idempotency-key"];
+    const reused = posts.slice(1).some((post) => {
+        const value = post.headers["idempotency-key"];
+        return typeof value === "string" && typeof first === "string" && value === first && value !== "";
+    });
+    return { detail: reused ? "reused seed key" : "fresh or omitted", ok: result.checksRun.includes(CREATE) && !reused };
+}
+export function driftReported({ result }) {
+    const drift = result.findings.find((f) => f.check === "schema.error-response-matches-document");
+    return {
+        detail: drift === undefined ? result.findings.map((f) => f.check).join(",") || "none" : drift.verdict,
+        ok: drift !== undefined,
+    };
+}
+/** The probe answered with something that is neither a 409 nor an insert: a gap, never a pass or a bug. */
+export function coverageNotPass({ result }) {
+    const hit = found(result, CREATE, "BACKEND_BUG");
+    const gap = found(result, CREATE, "COVERAGE_GAP");
+    return {
+        detail: `bug=${hit?.verdict ?? "none"} gap=${gap?.verdict ?? "none"}`,
+        ok: hit === undefined && gap !== undefined,
+    };
+}
+function adopted(seed) {
+    return seed?.verdict === "COVERAGE_GAP" && seed.detail.includes("x-unique");
+}
+export function seedAdopted({ result }) {
+    const seed = seedOf(result);
+    return { detail: seedDetail(seed), ok: adopted(seed) };
+}
+export function probedAfterAdopt({ result }) {
+    const ran = result.checksRun.includes(CREATE);
+    return { detail: ran ? "ran" : `checksRun=${result.checksRun.join(",")}`, ok: ran };
+}
+export function seedNotEvidence({ result }) {
+    const asSeed = result.findings.some((f) => f.check === CREATE && f.verdict !== "BACKEND_BUG" && f.evidence.length === 0);
+    return { detail: asSeed ? "scored seed as unique pass" : "seed is not unique-check evidence", ok: !asSeed };
+}
+export function seedBlocked({ result }) {
+    const seed = seedOf(result);
+    return { detail: seedDetail(seed), ok: seed?.verdict === "BLOCKED" };
+}
+export function untaggedNotAdopted({ result }) {
+    const adopts = adopted(seedOf(result));
+    return { detail: adopts ? "adopted without a tag" : "not unique-adopt", ok: !adopts };
+}
+export function distinctInserted({ result }) {
+    const bugs = result.findings
+        .filter(isRootCause)
+        .filter((f) => f.check.startsWith("create.unique") || f.check.startsWith("update.unique"));
+    return {
+        detail: `bugs=${bugs.map((f) => f.check).join(",") || "none"} entities=${result.entitiesTested.join(",")}`,
+        ok: bugs.length === 0 && result.entitiesTested.includes("widget"),
+    };
+}
+//# sourceMappingURL=judges.js.map

package/dist/api/conformance/unique/spec.d.ts

@@ -0,0 +1,14 @@
+/** The widget document the unique suite runs the API tester against: one entity, its sets tagged as asked. */
+import type { OpenApiDocument } from "../../spec/types.ts";
+export interface SpecOptions {
+    tag?: unknown;
+    omitTag?: boolean;
+    generated?: string[];
+    immutable?: string[];
+    idempotencyRequired?: boolean;
+    featureGate?: string;
+    updateBody?: string[];
+}
+/** Widgets under an org: list and create, then read, update and delete one. */
+export declare function widgetSpec(options?: SpecOptions): OpenApiDocument;
+//# sourceMappingURL=spec.d.ts.map

package/dist/api/conformance/unique/spec.js

@@ -0,0 +1,139 @@
+/** The widget document the unique suite runs the API tester against: one entity, its sets tagged as asked. */
+import { bearerSecurity } from "../harness/security.js";
+const ITEM = {
+    properties: { email: { type: "string" }, id: { type: "string" }, name: { type: "string" }, slug: { type: "string" } },
+    required: ["id", "name"],
+    type: "object",
+};
+const ERROR_SCHEMA = {
+    properties: { error_key: { type: "string" }, status: { type: "integer" } },
+    required: ["error_key"],
+    type: "object",
+};
+const GATE_SCHEMA = {
+    properties: {
+        error_key: { type: "string" },
+        vars: { additionalProperties: true, type: "object" },
+    },
+    type: "object",
+};
+/** The tags both writes carry: the unique sets, unless omitted, and the feature gate, when asked. */
+function writeTags(options) {
+    return {
+        ...(options.omitTag === true ? {} : { "x-unique": options.tag === undefined ? [["name"]] : options.tag }),
+        ...(options.featureGate === undefined ? {} : { "x-feature-gate": options.featureGate }),
+    };
+}
+function orgParam() {
+    return { in: "path", name: "org_id", required: true, schema: { type: "string" } };
+}
+function itemParams() {
+    return [orgParam(), { in: "path", name: "widget_id", required: true, schema: { type: "string" } }];
+}
+function json(schema) {
+    return { "application/json": { schema } };
+}
+function createBody() {
+    return { email: { type: "string" }, name: { type: "string", maxLength: 128 }, slug: { type: "string" } };
+}
+function createOperation(options) {
+    return {
+        operationId: "widget.create",
+        parameters: [
+            orgParam(),
+            {
+                in: "header",
+                name: "Idempotency-Key",
+                required: options.idempotencyRequired === true,
+                schema: { type: "string" },
+            },
+        ],
+        requestBody: {
+            content: json({ additionalProperties: false, properties: createBody(), required: ["name"], type: "object" }),
+            required: true,
+        },
+        responses: {
+            "201": { content: json(ITEM), description: "created" },
+            "402": { description: "plan limit" },
+            "403": { content: json(GATE_SCHEMA), description: "forbidden" },
+            "409": { content: json(ERROR_SCHEMA), description: "conflict" },
+        },
+        "x-entity": { action: "create", identity: "id", name: "widget" },
+        "x-generated": options.generated ?? ["id"],
+        ...writeTags(options),
+    };
+}
+function updateOperation(options) {
+    const known = createBody();
+    const properties = {};
+    for (const name of options.updateBody ?? ["email", "name", "slug"])
+        properties[name] = known[name] ?? { type: "string" };
+    return {
+        operationId: "widget.update",
+        parameters: itemParams(),
+        requestBody: { content: json({ additionalProperties: false, properties, type: "object" }) },
+        responses: {
+            "200": { content: json(ITEM), description: "ok" },
+            "402": { description: "plan limit" },
+            "403": { content: json(GATE_SCHEMA), description: "forbidden" },
+            "409": { content: json(ERROR_SCHEMA), description: "conflict" },
+        },
+        "x-entity": { action: "update", identity: "id", name: "widget" },
+        "x-immutable": options.immutable ?? [],
+        ...writeTags(options),
+    };
+}
+function listOperation() {
+    return {
+        operationId: "widget.list",
+        parameters: [orgParam()],
+        responses: {
+            "200": {
+                content: json({
+                    properties: { widgets: { items: ITEM, type: "array" } },
+                    required: ["widgets"],
+                    type: "object",
+                }),
+                description: "ok",
+            },
+        },
+        "x-entity": { action: "list", identity: "id", name: "widget" },
+    };
+}
+function itemPath(options) {
+    return {
+        delete: {
+            operationId: "widget.delete",
+            parameters: itemParams(),
+            responses: { "204": { description: "gone" } },
+            "x-entity": { action: "delete", identity: "id", name: "widget" },
+        },
+        get: {
+            operationId: "widget.read",
+            parameters: itemParams(),
+            responses: {
+                "200": { content: json(ITEM), description: "ok" },
+                "404": { content: json(ERROR_SCHEMA), description: "missing" },
+            },
+            "x-entity": { action: "read", identity: "id", name: "widget" },
+        },
+        patch: updateOperation(options),
+    };
+}
+/** Widgets under an org: list and create, then read, update and delete one. */
+export function widgetSpec(options = {}) {
+    return {
+        info: { title: "unique harness", version: "1" },
+        openapi: "3.1.0",
+        paths: {
+            "/v1/orgs/{org_id}/widgets": {
+                get: listOperation(),
+                parameters: [orgParam()],
+                post: createOperation(options),
+            },
+            "/v1/orgs/{org_id}/widgets/{widget_id}": itemPath(options),
+        },
+        ...bearerSecurity(),
+    };
+}
+//# sourceMappingURL=spec.js.map

package/dist/api/conformance/unique.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `x-unique` is a declared fact. These cases prove a 409 duplicate is a pass, a 2xx is
+ * BACKEND_BUG, and that missing / malformed tags do not invent a unique check.
+ */
+import { type Via } from "./harness/launch.ts";
+import type { ParserResult } from "./harness/result.ts";
+/** The document cases, every run through `via`, then the doctor of an untagged widget. */
+export declare function runUniqueSuite(via?: Via): Promise<ParserResult[]>;
+//# sourceMappingURL=unique.d.ts.map

package/dist/api/conformance/unique.js

@@ -0,0 +1,19 @@
+/**
+ * `x-unique` is a declared fact. These cases prove a 409 duplicate is a pass, a 2xx is
+ * BACKEND_BUG, and that missing / malformed tags do not invent a unique check.
+ */
+import { report } from "../report/console/report.js";
+import { buildModel } from "../spec/graph/build.js";
+import { listening } from "./harness/launch.js";
+import { runCase, UNIQUE_CASES } from "./unique/cases.js";
+import { documentCases, untaggedDoctorCase } from "./unique/document.js";
+import { widgetSpec } from "./unique/spec.js";
+/** The document cases, every run through `via`, then the doctor of an untagged widget. */
+export async function runUniqueSuite(via = listening) {
+    const results = documentCases();
+    for (const unique of UNIQUE_CASES)
+        results.push(...(await runCase(via, unique)));
+    results.push(untaggedDoctorCase(report.doctor(buildModel(widgetSpec({ omitTag: true }))).text));
+    return results;
+}
+//# sourceMappingURL=unique.js.map

package/dist/api/conformance/worker.d.ts

@@ -0,0 +1,3 @@
+/** One conformance task per message, in a forked process; see `pool.ts` and `serve-tasks.ts`. */
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/api/conformance/worker.js

@@ -0,0 +1,5 @@
+/** One conformance task per message, in a forked process; see `pool.ts` and `serve-tasks.ts`. */
+import { listening } from "./harness/launch.js";
+import { serveTasks } from "./serve-tasks.js";
+serveTasks(process, listening);
+//# sourceMappingURL=worker.js.map

package/dist/api/credentials/anchors.d.ts

@@ -0,0 +1,24 @@
+import type { Recipe, RecipeKind } from "../config/types/security.ts";
+import type { AuthStep } from "../config/types/steps.ts";
+/** A recipe's kind, and the operations behind its credential that the document declares. */
+export interface RecipeAnchors {
+    kind: RecipeKind;
+    /** The step that issues it: the login step whose answer `from` reads, or the mint's operation. */
+    issue?: string;
+    /** The step of the declared refresh that issues the renewed credential. */
+    refresh?: string;
+    /** The declared revoke: a login's `revoke`, or a mint's. */
+    revoke?: string;
+}
+/** The documented operation a step calls, or undefined when it calls none this document declares. */
+export type StepOperation = (step: AuthStep) => string | undefined;
+/**
+ * The recipe's anchors, or undefined for a recipe that names no kind: a fresh object of operation
+ * ids alone, holding no reference to the recipe, so no value, body template or credential is reachable.
+ */
+export declare function recipeAnchors(recipe: Partial<Recipe>, operationOf: StepOperation): RecipeAnchors | undefined;
+/** A login's revoke, named alone or with a body, as its operationId. */
+export declare function revokeOperationId(revoke: string | {
+    operationId: string;
+} | undefined): string | undefined;
+//# sourceMappingURL=anchors.d.ts.map

package/dist/api/credentials/anchors.js

@@ -0,0 +1,32 @@
+/*
+ * The operations a recipe issues, refreshes and revokes its credential through: what a security
+ * probe anchors on once per scheme, rather than per route. Read from the principal's effective
+ * recipe; a step is resolved to an operation by the caller, which knows the document.
+ */
+import { recipeKind } from "./recipes/acquire.js";
+/**
+ * The recipe's anchors, or undefined for a recipe that names no kind: a fresh object of operation
+ * ids alone, holding no reference to the recipe, so no value, body template or credential is reachable.
+ */
+export function recipeAnchors(recipe, operationOf) {
+    const kind = recipeKind(recipe);
+    if (kind === undefined)
+        return undefined;
+    const { login, mint, refresh } = recipe;
+    const found = {
+        issue: login === undefined ? mint?.operationId : issuing(login.steps, login.from, operationOf),
+        refresh: refresh === undefined ? undefined : issuing(refresh.steps, refresh.from, operationOf),
+        revoke: login === undefined ? mint?.revoke : revokeOperationId(login.revoke),
+    };
+    return { kind, ...Object.fromEntries(Object.entries(found).filter(([, id]) => typeof id === "string")) };
+}
+/** A login's revoke, named alone or with a body, as its operationId. */
+export function revokeOperationId(revoke) {
+    return typeof revoke === "object" ? revoke.operationId : revoke;
+}
+/* The step `from` reads: the last that saved a scope key of that name, else the last step, whose answer it is. */
+function issuing(steps, from, operationOf) {
+    const saving = steps.findLast((step) => "saveAs" in step && step.saveAs !== undefined && Object.hasOwn(step.saveAs, from));
+    return operationOf(saving ?? steps.at(-1));
+}
+//# sourceMappingURL=anchors.js.map

package/dist/api/credentials/dedicated.d.ts

@@ -0,0 +1,8 @@
+import { type StoreCtx } from "./store-plan.ts";
+import type { Blocked, CredentialKey, DedicatedHeld, DedicatedUse } from "./store-types.ts";
+/**
+ * A dedicated credential of `key.principal`'s for `key.scheme`, or why there can be none: a new one
+ * each time, unless the probe never spends it, when the run's first for that scope set serves again.
+ */
+export declare function acquireDedicated(ctx: StoreCtx, key: CredentialKey, use?: DedicatedUse): Promise<DedicatedHeld | Blocked>;
+//# sourceMappingURL=dedicated.d.ts.map

package/dist/api/credentials/dedicated.js

@@ -0,0 +1,106 @@
+/*
+ * A credential for a probe alone: a second login, a fresh mint, a new token grant. It is held under a
+ * probe principal the store enrolls with the owner's identity, `<owner>#probe-<n>`, so revoking or
+ * rotating it never touches the owner's own session. A mint is made with the owner's own `with`
+ * session, which outlives it; any other recipe signs the probe principal in. Static and hook recipes
+ * hold one value, so they cannot issue a second.
+ */
+import { probePrincipal } from "./probe-principal.js";
+import { acquireRecipe, recipeKind } from "./recipes/acquire.js";
+import { signsUp } from "./signup.js";
+import { acquireCtx, blockedBy, planOf, record, registerRevoke, } from "./store-plan.js";
+import { own } from "./effective.js";
+/**
+ * A dedicated credential of `key.principal`'s for `key.scheme`, or why there can be none: a new one
+ * each time, unless the probe never spends it, when the run's first for that scope set serves again.
+ */
+export function acquireDedicated(ctx, key, use = {}) {
+    if (use.reusable !== true)
+        return issueDedicated(ctx, key);
+    const id = [key.principal, key.scheme, ...(key.scopes ?? []).toSorted()].join("\u0000");
+    let held = ctx.shared.get(id);
+    if (held === undefined) {
+        held = issueDedicated(ctx, key);
+        ctx.shared.set(id, held);
+    }
+    return held;
+}
+/* A new dedicated credential under a probe principal of its own. */
+async function issueDedicated(ctx, key) {
+    const owner = planOf(ctx, key);
+    if ("blocked" in owner)
+        return owner;
+    const refused = await refusal(ctx, owner);
+    if (refused !== undefined)
+        return refused;
+    const plan = planOf(ctx, { ...key, principal: enroll(ctx, owner.principal) });
+    const kind = recipeKind(plan.recipe);
+    const issuing = acquireCtx(ctx, kind === "mint" ? owner : plan);
+    let entry;
+    try {
+        entry = record(ctx, plan, await acquireRecipe(issuing, plan.recipe));
+    }
+    catch (error) {
+        return { blocked: blockedBy(kind, owner, error) };
+    }
+    ctx.entries.set(plan.id, Promise.resolve(entry));
+    return heldOf(ctx, { entry, owner, plan });
+}
+/* Why the owner's recipe cannot issue a second credential: its kind, a signup, or the owner BLOCKED. */
+async function refusal(ctx, owner) {
+    const kind = recipeKind(owner.recipe);
+    if (kind === "static" || kind === "hook")
+        return { blocked: `${kind} recipes cannot issue a dedicated credential` };
+    if (signsUp(owner.recipe, ctx.options.signups ?? [])) {
+        return { blocked: `a second login for ${owner.principal}/${owner.scheme} would sign it up again` };
+    }
+    const settled = await ctx.entries.get(owner.id);
+    return settled !== undefined && "blocked" in settled ? settled : undefined;
+}
+/* Enrolls the next probe principal of `owner`, with the owner's identity and recipes and what its login bound. */
+function enroll(ctx, owner) {
+    ctx.probes += 1;
+    const principal = probePrincipal(owner, ctx.probes);
+    ctx.dedicated.add(principal);
+    const { created: _created, fresh: _fresh, ...entry } = own(ctx.principals, owner);
+    ctx.principals[principal] = entry;
+    ctx.bound.set(principal, { ...ctx.bound.get(owner) });
+    return principal;
+}
+function heldOf(ctx, { entry, owner, plan }) {
+    const held = {
+        credential: entry.credential,
+        owner: owner.principal,
+        principal: plan.principal,
+        scheme: plan.scheme,
+    };
+    const { revokeKey } = entry;
+    if (revokeKey !== undefined)
+        held.revoke = () => revokeNow(ctx, revokeKey);
+    if (entry.issued.refresh !== undefined)
+        held.rotate = () => rotate(ctx, plan, entry);
+    return held;
+}
+/* Revokes it now, once: teardown then has nothing left to revoke. A failure stays for teardown. */
+async function revokeNow(ctx, key) {
+    const revoking = ctx.revokes.get(key);
+    if (revoking === undefined)
+        return;
+    await revoking.revoke();
+    ctx.revokes.delete(key);
+}
+/* The refresh that rotated it, kept so a replay runs it again from before the rotation. */
+async function rotate(ctx, plan, before) {
+    const refresh = before.issued.refresh;
+    const after = record(ctx, plan, await refresh());
+    ctx.entries.set(plan.id, Promise.resolve(after));
+    return { credential: after.credential, replay: () => replay(ctx, plan, refresh) };
+}
+/* Rejects when the reuse is refused. An accepted one opened a session: teardown revokes it too. */
+async function replay(ctx, plan, refresh) {
+    /* The spent refresh token, sent again: meant to be refused, so a probe. */
+    const { revoke } = await refresh({ probe: true });
+    if (revoke !== undefined)
+        registerRevoke(ctx, plan, { key: `${plan.id}\u0000replay ${ctx.registered}`, revoke });
+}
+//# sourceMappingURL=dedicated.js.map

package/dist/api/credentials/effective.d.ts

@@ -0,0 +1,5 @@
+import type { Recipe } from "../config/types/security.ts";
+export declare function effectiveRecipe(base: Partial<Recipe> | undefined, override: Partial<Recipe> | undefined): Partial<Recipe> | undefined;
+/** A config map's own entry: a principal or scheme named `constructor` is not the prototype's. */
+export declare function own<T>(map: Readonly<Record<string, T>>, key: string): T | undefined;
+//# sourceMappingURL=effective.d.ts.map