@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/credentials/store-plan.d.ts

@@ -0,0 +1,94 @@
+import type { PrincipalsConfig, Recipe } from "../config/types/security.ts";
+import type { SecurityScheme } from "../spec/security/schemes.ts";
+import type { CredentialRecord } from "./ports.ts";
+import type { AcquireCtx, Issued } from "./recipes/types.ts";
+import type { Blocked, Credential, CredentialKey, DedicatedHeld, HeldCredential, StoreOptions } from "./store-types.ts";
+/** A credential the store holds, as issued, and the revoke it registered. */
+export interface Entry {
+    key: HeldCredential;
+    credential: Credential;
+    issued: Issued;
+    /** Epoch ms the store took it in, which with its expiry gives its lifetime. */
+    issuedAt: number;
+    /** Its revoke's key in `StoreCtx.revokes`, when it registered one. */
+    revokeKey?: string;
+    /** The value a renewal replaced: refused again, it is not renewed twice, even when the server reissued it. */
+    renewedFrom?: string;
+}
+export type Settled = Entry | Blocked;
+/** A revoke teardown runs: whose credential it ends, by the principal a report names, and which scheme. */
+export interface Revoking {
+    principal: string;
+    scheme: string;
+    revoke: () => Promise<void>;
+    /** The record the revoke removes, for a minted credential. */
+    record?: CredentialRecord;
+}
+/**
+ * The store's entries by plan id: each one's issue as it was last set, and what that issue settled
+ * to once it has. The settled side answers without awaiting, so a request holding a client slot can
+ * ask whether its credential lapsed without waiting on a renewal that needs a slot itself.
+ */
+export declare class Entries {
+    private readonly pending;
+    private readonly done;
+    get(id: string): Promise<Settled> | undefined;
+    set(id: string, issue: Promise<Settled>): void;
+    values(): IterableIterator<Promise<Settled>>;
+    /** What the entry's latest issue settled to; undefined while it is still pending, or when there is none. */
+    settled(id: string): Settled | undefined;
+}
+export interface StoreCtx {
+    options: StoreOptions;
+    /** The config's principals and the ones the run enrolled. */
+    principals: PrincipalsConfig;
+    now: () => number;
+    bufferMs: number;
+    entries: Entries;
+    /** Principal × scheme pairs a failed refresh blocked. */
+    blocked: Map<string, Blocked>;
+    /** Identity credentials bound, by principal. */
+    bound: Map<string, Record<string, string>>;
+    /** Revokes teardown runs, in the order registered. A session's renewal replaces its own. */
+    revokes: Map<string, Revoking>;
+    /** Revokes registered so far, which keeps each mint's key distinct. */
+    registered: number;
+    /** The probe principals dedicated credentials are held under. */
+    dedicated: Set<string>;
+    /** Probe principals enrolled so far, which numbers the next. */
+    probes: number;
+    /** The dedicated credentials probes that never spend one share, by principal, scheme and scope set. */
+    shared: Map<string, Promise<DedicatedHeld | Blocked>>;
+    renew: (held: Entry, start: () => Promise<Settled>) => Promise<Settled>;
+}
+export interface Plan {
+    principal: string;
+    scheme: string;
+    spec: SecurityScheme;
+    recipe: Partial<Recipe>;
+    scopes: readonly string[];
+    pair: string;
+    id: string;
+}
+/** A store's state, empty: the config's principals copied, so enrolling never edits the config. */
+export declare function storeCtx(options: StoreOptions): StoreCtx;
+/** What blocked a credential, as a report names it: the step (a recipe kind, refresh or adopt), for whom, and why. */
+export declare function blockedBy(step: string, plan: Plan, error: unknown): string;
+/**
+ * Takes an issued credential in. Its revoke is registered for teardown, except a login's for a
+ * principal's own session: a login's revoke is for the dedicated sessions probes open, and ending a
+ * principal's own would strand what teardown still sends as it.
+ */
+export declare function record(ctx: StoreCtx, plan: Plan, issued: Issued): Entry;
+/** Registers a revoke teardown runs, under `key`; a later one under the same key replaces it. */
+export declare function registerRevoke(ctx: StoreCtx, plan: Plan, { key, ...revoking }: {
+    key: string;
+} & Omit<Revoking, "principal" | "scheme">): void;
+/** What a block holds for: the principal × scheme, whatever the scopes. */
+export declare function pairOf(key: Pick<CredentialKey, "principal" | "scheme">): string;
+export declare function planOf(ctx: StoreCtx, key: CredentialKey, how?: {
+    adopting?: boolean;
+}): Plan | Blocked;
+export declare function acquireCtx(ctx: StoreCtx, plan: Plan): AcquireCtx;
+export declare function identityOf(ctx: StoreCtx, principal: string): Readonly<Record<string, unknown>>;
+//# sourceMappingURL=store-plan.d.ts.map

package/dist/api/credentials/store-plan.js

@@ -0,0 +1,144 @@
+/*
+ * The store's internals, shared by store.ts and dedicated.ts: the state one store holds, how a key is
+ * planned against the config, and how an issued credential is recorded. Nothing here is exported
+ * beyond the credentials library.
+ */
+import { messageOf } from "../errors/message.js";
+import { effectiveRecipe, own } from "./effective.js";
+import { sendsFor } from "./placement.js";
+import { probeOwner, withoutProbes } from "./probe-principal.js";
+import { recipeKind } from "./recipes/acquire.js";
+import { createRenewals, DEFAULT_REFRESH_BUFFER_MS } from "./refresh.js";
+/**
+ * The store's entries by plan id: each one's issue as it was last set, and what that issue settled
+ * to once it has. The settled side answers without awaiting, so a request holding a client slot can
+ * ask whether its credential lapsed without waiting on a renewal that needs a slot itself.
+ */
+export class Entries {
+    pending = new Map();
+    done = new Map();
+    get(id) {
+        return this.pending.get(id);
+    }
+    set(id, issue) {
+        this.pending.set(id, issue);
+        this.done.delete(id);
+        issue.then((settled) => {
+            if (this.pending.get(id) === issue)
+                this.done.set(id, settled);
+        }, () => undefined);
+    }
+    values() {
+        return this.pending.values();
+    }
+    /** What the entry's latest issue settled to; undefined while it is still pending, or when there is none. */
+    settled(id) {
+        return this.done.get(id);
+    }
+}
+/** A store's state, empty: the config's principals copied, so enrolling never edits the config. */
+export function storeCtx(options) {
+    return {
+        blocked: new Map(),
+        bound: new Map(),
+        bufferMs: options.refreshBufferMs ?? DEFAULT_REFRESH_BUFFER_MS,
+        dedicated: new Set(),
+        entries: new Entries(),
+        now: options.now ?? Date.now,
+        options,
+        principals: { ...options.principals },
+        probes: 0,
+        registered: 0,
+        renew: createRenewals(),
+        revokes: new Map(),
+        shared: new Map(),
+    };
+}
+/* Config keys that grade a principal rather than identify it. */
+const GRADING = /* @__PURE__ */ new Set([
+    "created",
+    "fresh",
+    "inviteAs",
+    "rank",
+    "readOnly",
+    "security",
+]);
+/** What blocked a credential, as a report names it: the step (a recipe kind, refresh or adopt), for whom, and why. */
+export function blockedBy(step, plan, error) {
+    return `${step} for ${probeOwner(plan.principal)}/${plan.scheme}: ${withoutProbes(messageOf(error))}`;
+}
+/**
+ * Takes an issued credential in. Its revoke is registered for teardown, except a login's for a
+ * principal's own session: a login's revoke is for the dedicated sessions probes open, and ending a
+ * principal's own would strand what teardown still sends as it.
+ */
+export function record(ctx, plan, issued) {
+    const { secrets, sends } = sendsFor(plan.spec, plan.recipe, issued.value);
+    const credential = { expiresAt: issued.expiresAt, secrets, sends, value: issued.value };
+    if (issued.scopes !== undefined)
+        credential.scopes = issued.scopes;
+    if (issued.identity !== undefined) {
+        ctx.bound.set(plan.principal, { ...ctx.bound.get(plan.principal), ...issued.identity });
+    }
+    const key = { principal: plan.principal, scheme: plan.scheme, scopes: plan.scopes };
+    const entry = { credential, issued, issuedAt: ctx.now(), key: { ...key, credential } };
+    const login = recipeKind(plan.recipe) === "login";
+    if (issued.revoke !== undefined && (!login || ctx.dedicated.has(plan.principal))) {
+        /* A session is one credential however often it rotates; each mint is a key of its own. */
+        entry.revokeKey = login ? plan.id : `${plan.id}\u0000${ctx.registered}`;
+        const removes = issued.record === undefined ? {} : { record: issued.record };
+        registerRevoke(ctx, plan, { key: entry.revokeKey, revoke: issued.revoke, ...removes });
+    }
+    return entry;
+}
+/** Registers a revoke teardown runs, under `key`; a later one under the same key replaces it. */
+export function registerRevoke(ctx, plan, { key, ...revoking }) {
+    ctx.registered += 1;
+    ctx.revokes.set(key, { ...revoking, principal: probeOwner(plan.principal), scheme: plan.scheme });
+}
+/** What a block holds for: the principal × scheme, whatever the scopes. */
+export function pairOf(key) {
+    return `${key.principal}\u0000${key.scheme}`;
+}
+/* Adopting replaces a credential, so a pair a failed refresh blocked can still take one in. */
+export function planOf(ctx, key, how = {}) {
+    const { schemes, security } = ctx.options;
+    const entry = own(ctx.principals, key.principal);
+    if (entry === undefined)
+        return { blocked: `no principal "${key.principal}" in the config` };
+    const spec = schemes.get(key.scheme);
+    if (spec === undefined)
+        return { blocked: `the document declares no "${key.scheme}" scheme` };
+    const recipe = effectiveRecipe(own(security, key.scheme), entry.security?.[key.scheme]);
+    if (recipe === undefined) {
+        return { blocked: `principal "${key.principal}" has no recipe for the "${key.scheme}" scheme` };
+    }
+    const pair = pairOf(key);
+    const blocked = ctx.blocked.get(pair);
+    if (blocked !== undefined && how.adopting !== true)
+        return blocked;
+    const scopes = recipeKind(recipe) === "login" ? [] : [...(key.scopes ?? [])].sort();
+    return {
+        id: `${pair}\u0000${scopes.join(" ")}`,
+        pair,
+        principal: key.principal,
+        recipe,
+        scheme: key.scheme,
+        scopes,
+        spec,
+    };
+}
+export function acquireCtx(ctx, plan) {
+    return {
+        now: ctx.now,
+        ports: ctx.options.ports,
+        principal: { id: plan.principal, identity: identityOf(ctx, plan.principal) },
+        scheme: plan.spec,
+        scopes: plan.scopes,
+    };
+}
+export function identityOf(ctx, principal) {
+    const data = Object.entries(own(ctx.principals, principal) ?? {}).filter(([key]) => !GRADING.has(key));
+    return { ...Object.fromEntries(data), ...ctx.bound.get(principal) };
+}
+//# sourceMappingURL=store-plan.js.map

package/dist/api/credentials/store-types.d.ts

@@ -0,0 +1,133 @@
+import type { PrincipalEntry, PrincipalsConfig, SecurityConfig } from "../config/types/security.ts";
+import type { Secrets } from "./placement.ts";
+import type { CredentialPorts, Sends } from "./ports.ts";
+import type { SignupOperation } from "../spec/sign-up.ts";
+import type { SecurityScheme } from "../spec/security/schemes.ts";
+export interface StoreOptions {
+    security: SecurityConfig;
+    principals: PrincipalsConfig;
+    /** The document's schemes by name. */
+    schemes: ReadonlyMap<string, SecurityScheme>;
+    ports: CredentialPorts;
+    /** Epoch ms now. Default: the system clock. */
+    now?: () => number;
+    /** How long before it lapses a credential is renewed. Default: 30 s. */
+    refreshBufferMs?: number;
+    /** The document's account makers (`accountMakersOf`): a login that calls one is never renewed by running it again. */
+    signups?: readonly SignupOperation[];
+}
+/** Which credential: whose, for which scheme, carrying which scopes. */
+export interface CredentialKey {
+    principal: string;
+    scheme: string;
+    scopes?: readonly string[];
+}
+/** A held credential, placed and ready to send. */
+export interface Credential {
+    value: string;
+    expiresAt: number | null;
+    sends: Sends;
+    secrets: Secrets;
+    /** The scopes it was issued for, when its recipe asked for them. */
+    scopes?: readonly string[];
+}
+/** A credential the run cannot have, and why. It stays blocked for the rest of the run. */
+export interface Blocked {
+    blocked: string;
+}
+export type Held = Credential | Blocked;
+/** A credential the store holds, and whose it is. */
+export interface HeldCredential {
+    principal: string;
+    scheme: string;
+    /** The scope set it is keyed by, sorted: empty for a login, which holds whatever the server grants. */
+    scopes: readonly string[];
+    credential: Credential;
+}
+/** A credential the run was handed, for whom and which scheme. */
+export interface Adopting {
+    principal: string;
+    scheme: string;
+    value: string;
+    /** What came with it, a signup's `refresh_token` say: a login recipe's declared refresh runs from it. */
+    scope?: Readonly<Record<string, string>>;
+}
+/** A dedicated session after its recipe's refresh rotated it. */
+export interface Rotated {
+    credential: Credential;
+    /** Runs the refresh again from before the rotation; rejects with the reason when it is refused. */
+    replay(): Promise<void>;
+}
+/**
+ * How a probe uses a dedicated credential. `reusable`: it never spends it (no revoke, no rotation),
+ * so one per principal, scheme and scope set serves every such probe of the run.
+ */
+export interface DedicatedUse {
+    reusable?: boolean;
+}
+/**
+ * A credential for a probe alone, never the owner's own session: held under the probe principal
+ * `<owner>#probe-<n>`, and revoked at teardown when its recipe declares how.
+ */
+export interface DedicatedHeld {
+    principal: string;
+    owner: string;
+    scheme: string;
+    credential: Credential;
+    /** Revokes it now through the declared revoke; absent without one. Rejects with the reason, and teardown tries again. */
+    revoke?: () => Promise<void>;
+    /** Rotates it by the recipe's declared refresh; absent without one. */
+    rotate?: () => Promise<Rotated>;
+}
+/** A credential teardown could not revoke: a record the report lists as unremovable. */
+export interface RevokeFailure {
+    principal: string;
+    scheme: string;
+    reason: string;
+}
+export interface CredentialStore {
+    acquire(key: CredentialKey): Promise<Held>;
+    /**
+     * A credential of the principal's own that is not its session: a second login, a fresh mint, a new
+     * token grant, under a probe principal the store enrolls. Static and hook recipes cannot issue one.
+     */
+    acquireDedicated(key: CredentialKey, use?: DedicatedUse): Promise<DedicatedHeld | Blocked>;
+    /**
+     * Whether `value`, which a request placed for `key`, is no longer current: a renewal is pending,
+     * a newer value is held, or it is stale. Answers without awaiting. A blocked key never lapses:
+     * its next resolution says why.
+     */
+    lapsed(key: CredentialKey, value: string): boolean;
+    /** Renews the credential a refused request carried, once however many requests were refused. */
+    refresh(request: CredentialKey & {
+        sentValue: string;
+    }): Promise<Held>;
+    /**
+     * BLOCKS the principal × scheme for the rest of the run, as a failed renewal does: a control read
+     * showed the server refuses its credential anywhere. Adopting a credential lifts it.
+     */
+    block(key: CredentialKey, reason: string): void;
+    /**
+     * Holds `value` as the principal's credential for the scheme, placed like any acquired one: the
+     * credential an invite issued its delegate, or the one a signup answered with. It replaces what
+     * was held, a blocked login included.
+     */
+    adopt(input: Adopting): Promise<Held>;
+    /** Adds a principal of the run's own, a fresh or disposable one, which acquires by the shared recipes. */
+    enroll(id: string, entry: PrincipalEntry): void;
+    /** Every principal by id, the enrolled ones included. Live: an adapter reads it as enrolling adds to it. */
+    readonly principals: Readonly<PrincipalsConfig>;
+    /** The principal's identity: its config data, plus what its credentials bound. */
+    identityOf(principal: string): Readonly<Record<string, unknown>>;
+    /** Every credential held now, in the order first acquired; blocked ones are left out. */
+    snapshot(): Promise<HeldCredential[]>;
+    /** Revokes every credential that recorded a revoke; returns the ones that failed. */
+    revokeAll(): Promise<RevokeFailure[]>;
+    /**
+     * Ends each principal's own login session that `of` admits, by the login recipe's declared
+     * `revoke`, once per principal and scheme; returns the ones that failed. Nothing is sent for a
+     * login that declares no revoke.
+     */
+    revokeSessions(of: (principal: string) => boolean): Promise<RevokeFailure[]>;
+}
+//# sourceMappingURL=store-types.d.ts.map

package/dist/api/credentials/store-types.js

@@ -0,0 +1,3 @@
+/* What a run's credential store is given, holds and answers; `createStore` in store.ts makes one. */
+export {};
+//# sourceMappingURL=store-types.js.map

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

@@ -0,0 +1,5 @@
+import type { CredentialStore, StoreOptions } from "./store-types.ts";
+export type { Adopting, Blocked, Credential, CredentialKey, CredentialStore, DedicatedHeld, Held, HeldCredential, RevokeFailure, Rotated, StoreOptions, } from "./store-types.ts";
+/** A credential store for one run. */
+export declare function createStore(options: StoreOptions): CredentialStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/api/credentials/store.js

@@ -0,0 +1,222 @@
+import { messageOf } from "../errors/message.js";
+import { expiresAtOf } from "./expiry.js";
+import { own } from "./effective.js";
+import { acquireDedicated } from "./dedicated.js";
+import { acquireRecipe, recipeKind } from "./recipes/acquire.js";
+import { RefusedAnswer } from "./recipes/answer.js";
+import { heldLogin } from "./recipes/login.js";
+import { isStale } from "./refresh.js";
+import { signsUp } from "./signup.js";
+import { acquireCtx, blockedBy, identityOf, pairOf, planOf, record, storeCtx, } from "./store-plan.js";
+/** A credential store for one run. */
+export function createStore(options) {
+    const ctx = storeCtx(options);
+    return {
+        acquire: (key) => acquire(ctx, key),
+        acquireDedicated: (key, use) => acquireDedicated(ctx, key, use),
+        lapsed: (key, value) => lapsed(ctx, key, value),
+        adopt: (input) => adopt(ctx, input),
+        block: (key, reason) => {
+            ctx.blocked.set(pairOf(key), { blocked: reason });
+        },
+        enroll: (id, entry) => {
+            ctx.principals[id] = entry;
+        },
+        identityOf: (principal) => identityOf(ctx, principal),
+        principals: ctx.principals,
+        refresh: (request) => refresh(ctx, request),
+        revokeAll: () => revokeAll(ctx),
+        revokeSessions: (of) => revokeSessions(ctx, of),
+        snapshot: () => snapshot(ctx),
+    };
+}
+async function acquire(ctx, key) {
+    const plan = planOf(ctx, key);
+    if ("blocked" in plan)
+        return plan;
+    let pending = ctx.entries.get(plan.id);
+    if (pending === undefined) {
+        pending = issue(ctx, plan);
+        ctx.entries.set(plan.id, pending);
+    }
+    const held = await pending;
+    if ("blocked" in held)
+        return held;
+    const fresh = { expiresAt: held.credential.expiresAt, issuedAt: held.issuedAt };
+    if (!isStale(fresh, { bufferMs: ctx.bufferMs, now: ctx.now() }))
+        return held.credential;
+    return renewEntry(ctx, plan, held);
+}
+/*
+ * Whether `value` is no longer the key's current credential: a renewal is pending, a newer value is
+ * held, or the held one is stale. Never awaits, so a caller holding a client slot can ask.
+ */
+function lapsed(ctx, key, value) {
+    const plan = planOf(ctx, key);
+    if ("blocked" in plan)
+        return false;
+    const held = ctx.entries.settled(plan.id);
+    if (held === undefined)
+        return ctx.entries.get(plan.id) !== undefined;
+    if ("blocked" in held)
+        return false;
+    if (held.credential.value !== value)
+        return true;
+    return isStale({ expiresAt: held.credential.expiresAt, issuedAt: held.issuedAt }, { bufferMs: ctx.bufferMs, now: ctx.now() });
+}
+async function refresh(ctx, request) {
+    const plan = planOf(ctx, request);
+    if ("blocked" in plan)
+        return plan;
+    const pending = ctx.entries.get(plan.id);
+    if (pending === undefined)
+        return acquire(ctx, request);
+    const held = await pending;
+    if ("blocked" in held)
+        return held;
+    if (held.credential.value !== request.sentValue || held.renewedFrom === request.sentValue)
+        return held.credential;
+    return renewEntry(ctx, plan, held);
+}
+async function renewEntry(ctx, plan, held) {
+    const renewed = await ctx.renew(held, () => {
+        const from = held.credential.value;
+        const next = renewal(ctx, plan, held).then((settled) => "blocked" in settled ? settled : { ...settled, renewedFrom: from });
+        ctx.entries.set(plan.id, next);
+        return next;
+    });
+    return "blocked" in renewed ? renewed : renewed.credential;
+}
+/*
+ * A credential with no refresh of its own is renewed by acquiring afresh through its recipe, unless
+ * that would register the account again (its login calls the signup, or the principal is one the run
+ * `created` by its login): then it fails closed, never registering a second account.
+ */
+async function renewal(ctx, plan, held) {
+    const created = recipeKind(plan.recipe) === "login" && own(ctx.principals, plan.principal)?.created === true;
+    const signup = created || signsUp(plan.recipe, ctx.options.signups ?? []);
+    if (held.issued.refresh === undefined && signup) {
+        return blockPair(ctx, plan, `renewing ${plan.principal}/${plan.scheme} would sign up again; declare a refresh`);
+    }
+    try {
+        const renew = held.issued.refresh ?? (() => acquireRecipe(acquireCtx(ctx, plan), plan.recipe));
+        return record(ctx, plan, await renew());
+    }
+    catch (error) {
+        if (held.issued.refresh === undefined)
+            return blockPair(ctx, plan, blockedBy("refresh", plan, error));
+        if (signup)
+            return blockPair(ctx, plan, refusedSignup(plan, error));
+        /* A refused declared refresh falls back to one fresh login, shared by concurrent callers; only its failure blocks. */
+        const settled = await issue(ctx, plan, { refused: error });
+        return "blocked" in settled ? blockPair(ctx, plan, settled.blocked) : settled;
+    }
+}
+/* A refused refresh of a login that signs up: acquiring afresh would make a second account. */
+function refusedSignup(plan, error) {
+    const why = blockedBy("refresh", plan, error).slice(`refresh for ${plan.principal}/${plan.scheme}: `.length);
+    return `the refresh for ${plan.principal}/${plan.scheme} was refused, and acquiring afresh would sign up again: ${why}`;
+}
+/* A renewal that failed blocks the principal × scheme for every scope set, for the rest of the run. */
+function blockPair(ctx, plan, reason) {
+    const blocked = { blocked: reason };
+    ctx.blocked.set(plan.pair, blocked);
+    return blocked;
+}
+/* A credential through the recipe; as a refused refresh's fallback, a failure names the renewal. */
+async function issue(ctx, plan, after) {
+    try {
+        return record(ctx, plan, await acquireRecipe(acquireCtx(ctx, plan), plan.recipe));
+    }
+    catch (error) {
+        if (after === undefined)
+            return { blocked: blockedBy(recipeKind(plan.recipe) ?? "acquire", plan, error) };
+        const why = `the refresh failed (${messageOf(after.refused)}), then acquiring afresh failed (${messageOf(error)})`;
+        return { blocked: blockedBy("renewal", plan, new Error(why)) };
+    }
+}
+/*
+ * Taken in as a login's would be: an adopted value renews by the principal's own recipe. An empty
+ * value is no credential, so what is held stays.
+ */
+async function adopt(ctx, input) {
+    const plan = planOf(ctx, { principal: input.principal, scheme: input.scheme }, { adopting: true });
+    if ("blocked" in plan)
+        return plan;
+    const { value } = input;
+    if (value === "")
+        return { blocked: blockedBy("adopt", plan, new Error("an empty value is no credential")) };
+    const replaced = await ctx.entries.get(plan.id);
+    const session = replaced === undefined || "blocked" in replaced ? {} : { replaced: replaced.issued.refresh };
+    let entry;
+    try {
+        entry = record(ctx, plan, heldIssue(ctx, plan, { scope: input.scope ?? {}, value, ...session }));
+    }
+    catch (error) {
+        return { blocked: blockedBy("adopt", plan, error) };
+    }
+    ctx.blocked.delete(plan.pair);
+    ctx.entries.set(plan.id, Promise.resolve(entry));
+    return entry.credential;
+}
+/* An adopted login value renews by the recipe's declared refresh; any other is acquired afresh. */
+function heldIssue(ctx, plan, held) {
+    if (recipeKind(plan.recipe) === "login")
+        return heldLogin(acquireCtx(ctx, plan), held, plan.recipe);
+    const { value } = held;
+    return { expiresAt: expiresAtOf({ body: undefined, expiresIn: plan.recipe.expiresIn, now: ctx.now(), value }), value };
+}
+async function snapshot(ctx) {
+    const settled = await Promise.all(ctx.entries.values());
+    return settled.flatMap((held) => ("blocked" in held ? [] : [held.key]));
+}
+/*
+ * Each principal's own login session, ended by its declared revoke, one at a time: the run's last
+ * call. A dedicated session is revokeAll's, and a mint or a grant has no session to end.
+ */
+async function revokeSessions(ctx, of) {
+    const failures = [];
+    for (const held of await Promise.all(ctx.entries.values())) {
+        if ("blocked" in held || held.issued.revoke === undefined)
+            continue;
+        const { principal, scheme } = held.key;
+        const plan = planOf(ctx, { principal, scheme });
+        if (ctx.dedicated.has(principal) || !of(principal) || "blocked" in plan || recipeKind(plan.recipe) !== "login")
+            continue;
+        try {
+            await held.issued.revoke();
+        }
+        catch (error) {
+            failures.push({ principal, reason: messageOf(error), scheme });
+        }
+    }
+    return failures;
+}
+/*
+ * One at a time, so a teardown's revokes reach the backend in the order they were minted. A minted
+ * key whose record an accepted DELETE already removed is not revoked again, and one whose revoke a
+ * 4xx refused is no failure when a read of its record shows it gone.
+ */
+async function revokeAll(ctx) {
+    const { records } = ctx.options.ports;
+    const failures = [];
+    const revoking = [...ctx.revokes.values()];
+    ctx.revokes.clear();
+    for (const { principal, record: minted, revoke, scheme } of revoking) {
+        if (minted !== undefined && records.removed(minted))
+            continue;
+        try {
+            await revoke();
+        }
+        catch (error) {
+            if (minted !== undefined && refusedByClient(error) && (await records.gone(minted)))
+                continue;
+            failures.push({ principal, reason: messageOf(error), scheme });
+        }
+    }
+    return failures;
+}
+function refusedByClient(error) {
+    return error instanceof RefusedAnswer && error.status >= 400 && error.status < 500;
+}
+//# sourceMappingURL=store.js.map

package/dist/api/credentials/validate/document.d.ts

@@ -0,0 +1,10 @@
+import { type RawOf } from "../../config/types/raw.ts";
+import type { ApiConfig } from "../../config/types/config.ts";
+/** The parts of a document's view these checks read. */
+export interface DocumentView {
+    authFlows: boolean;
+    schemes: ReadonlyMap<string, unknown>;
+}
+/** Problems a config has with the primary document and each origin's that no recipe check sees. */
+export declare function documentProblems(config: RawOf<ApiConfig>, spec: DocumentView, origins?: Readonly<Record<string, DocumentView>>): string[];
+//# sourceMappingURL=document.d.ts.map

package/dist/api/credentials/validate/document.js

@@ -0,0 +1,52 @@
+/*
+ * What a config asks of a document beyond its recipes: that it no longer leans on the removed
+ * `x-auth-flows` tag, that every scenario step naming a `scheme` names one the document the step
+ * goes to declares (the step's origin's, else the scenario's, else the primary), and that
+ * `targetVersion.scheme` names one the primary document declares.
+ */
+import { isRaw, isRawUnion } from "../../config/types/raw.js";
+import { nearest } from "../../errors/suggest.js";
+import { declaredSchemes } from "./principals.js";
+/** Problems a config has with the primary document and each origin's that no recipe check sees. */
+export function documentProblems(config, spec, origins = {}) {
+    const tagged = spec.authFlows
+        ? ["the document's x-auth-flows tag is no longer read: declare a security.<scheme> recipe in config"]
+        : [];
+    const scenarios = Array.isArray(config.scenarios)
+        ? config.scenarios.filter((scenario) => isRaw(scenario))
+        : [];
+    return [
+        ...tagged,
+        ...scenarios.flatMap((scenario) => stepSchemeProblems(scenario, { origins, spec })),
+        ...targetVersionProblems(config, spec),
+    ];
+}
+/* The scheme an undocumented version path is read under, against the primary document. */
+function targetVersionProblems(config, spec) {
+    const scheme = isRaw(config.targetVersion) ? config.targetVersion.scheme : undefined;
+    if (typeof scheme !== "string" || spec.schemes.has(scheme))
+        return [];
+    return [unknownScheme({ path: "targetVersion.scheme", scheme, view: spec, where: "the document" })];
+}
+/* `<path> "<scheme>" names no scheme in <where>`, with the closest declared one and the full list. */
+function unknownScheme({ path, scheme, view, where }) {
+    const close = nearest(scheme, view.schemes.keys())[0];
+    return (`${path} "${scheme}" names no scheme in ${where}.` +
+        `${close === undefined ? "" : ` Did you mean "${close}"?`} ${declaredSchemes(view.schemes.keys())}`);
+}
+/* Each step's `scheme`, against the document the step goes to. An unknown origin is reported elsewhere. */
+function stepSchemeProblems(scenario, documents) {
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    return steps.flatMap((step, index) => {
+        if (!isRawUnion(step) || typeof step.scheme !== "string")
+            return [];
+        const origin = typeof step.origin === "string" ? step.origin : scenario.origin;
+        const view = typeof origin === "string" ? documents.origins[origin] : documents.spec;
+        if (view === undefined || view.schemes.has(step.scheme))
+            return [];
+        const where = typeof origin === "string" ? `origin ${origin}'s document` : "the document";
+        const path = `scenarios.${String(scenario.id)}.steps[${index}].scheme`;
+        return [unknownScheme({ path, scheme: step.scheme, view, where })];
+    });
+}
+//# sourceMappingURL=document.js.map