@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/credentials/recipes/hook.d.ts

@@ -0,0 +1,9 @@
+import type { Recipe } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/**
+ * The value `hooks.resolveCredential(scheme, principal)` returns, asked afresh on every acquire so a
+ * TOTP code or a vault lease is current. Its own `expiresIn` wins over the recipe's. It serves a scoped
+ * operation only for the scopes the recipe `holds`.
+ */
+export declare function acquireHook(ctx: AcquireCtx, options: Partial<Recipe>): Promise<Issued>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/api/credentials/recipes/hook.js

@@ -0,0 +1,21 @@
+import { expiresAtOf } from "../expiry.js";
+import { assertHolds } from "./answer.js";
+/**
+ * The value `hooks.resolveCredential(scheme, principal)` returns, asked afresh on every acquire so a
+ * TOTP code or a vault lease is current. Its own `expiresIn` wins over the recipe's. It serves a scoped
+ * operation only for the scopes the recipe `holds`.
+ */
+export async function acquireHook(ctx, options) {
+    const hook = ctx.ports.resolveCredential;
+    if (hook === undefined) {
+        throw new Error(`the ${ctx.scheme.name} recipe is \`hook: true\`, but the config sets no hooks.resolveCredential`);
+    }
+    assertHolds(ctx, options.holds);
+    const answer = await hook(ctx.scheme.name, ctx.principal);
+    if (answer === null) {
+        throw new Error(`hooks.resolveCredential gave no credential for "${ctx.principal.id}" on scheme "${ctx.scheme.name}"`);
+    }
+    const { value, expiresIn = options.expiresIn } = typeof answer === "string" ? { value: answer } : answer;
+    return { expiresAt: expiresAtOf({ body: undefined, expiresIn, now: ctx.now(), value }), value };
+}
+//# sourceMappingURL=hook.js.map

package/dist/api/credentials/recipes/login.d.ts

@@ -0,0 +1,18 @@
+import type { LoginRecipe, Recipe } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/** Signs the principal in by the login recipe; `options` are the recipe's shared options. */
+export declare function acquireLogin(ctx: AcquireCtx, login: LoginRecipe, options: Partial<Recipe>): Promise<Issued>;
+/**
+ * A login credential the run was handed rather than signed in for, a signup's answer or an
+ * invite's: it renews by the recipe's declared refresh from `held.scope` (a `refresh_token`, say),
+ * as a signed-in one does from what its steps saved. When that refresh reads a value `held.scope`
+ * lacks, it renews as `held.replaced`, the session it took the place of, whose steps saved those
+ * values; with no such session, that refresh fails naming the value. With no refresh declared, the
+ * store signs in again.
+ */
+export declare function heldLogin(ctx: AcquireCtx, held: {
+    value: string;
+    scope: Readonly<Record<string, string>>;
+    replaced?: Issued["refresh"];
+}, options: Partial<Recipe>): Issued;
+//# sourceMappingURL=login.d.ts.map

package/dist/api/credentials/recipes/login.js

@@ -0,0 +1,146 @@
+import { expiresAtOf } from "../expiry.js";
+import { fillCredential, fillPrincipal, principalValues } from "../interpolate.js";
+import { jwtClaims } from "../jwt.js";
+import { unfilledIn } from "../placeholders.js";
+import { readPath } from "../../client/read-path.js";
+import { answerBody, describeAnswerType } from "../../runtime/cookies/save-as.js";
+import { readAnswer } from "../read.js";
+import { answered } from "./answer.js";
+/** Signs the principal in by the login recipe; `options` are the recipe's shared options. */
+export async function acquireLogin(ctx, login, options) {
+    return issue(ctx, {
+        login,
+        options,
+        ran: await run(ctx, login.steps, { scope: {}, secrets: secretsOf(login, options), what: "login" }),
+    }, login);
+}
+async function run(ctx, steps, at) {
+    const unfilled = unfilledIn(steps, Object.keys(at.scope));
+    if (unfilled !== undefined) {
+        throw new Error(`${at.what} for "${ctx.principal.id}" reads {${unfilled.name}} at step ${unfilled.step}, ` +
+            "which nothing it started from or an earlier step saved fills");
+    }
+    const input = {
+        principal: ctx.principal.id,
+        scope: at.scope,
+        secrets: at.secrets,
+        ...(at.probe ? { probe: at.probe } : {}),
+    };
+    const filled = fillPrincipal(ctx.principal, steps);
+    for (const value of principalValues(ctx.principal, steps.map(sentBy)))
+        ctx.ports.secrets.register(value);
+    return ctx.ports.steps.run(filled, input);
+}
+/* What a step sends, or binds for a later one to send; an out-of-band address never reaches the wire. */
+function sentBy(step) {
+    if ("outOfBand" in step)
+        return null;
+    return [step.bind, step.body, step.headers, step.query, "path" in step ? step.path : null];
+}
+/* Every address a login or its refresh reads a value from: each is a credential, or what renews one. */
+function secretsOf(login, options) {
+    const steps = [...login.steps, ...(options.refresh?.steps ?? [])];
+    const saved = steps.flatMap((step) => "saveAs" in step && step.saveAs !== undefined ? Object.values(step.saveAs) : []);
+    return [...new Set([login.from, ...(options.refresh === undefined ? [] : [options.refresh.from]), ...saved])];
+}
+/* A step that saves `credential` names the credential itself; `from` is read only when none does. */
+function savesCredential(steps) {
+    return steps.some((step) => "outOfBand" in step ? step.outOfBand.as === "credential" : step.saveAs?.["credential"] !== undefined);
+}
+function issue(ctx, issuing, read) {
+    const { login, options, ran } = issuing;
+    const { from } = read;
+    const value = savesCredential(read.steps)
+        ? ran.scope["credential"]
+        : (readAnswer(ran.answer, from) ?? ran.scope[from]);
+    if (value === undefined || value === "") {
+        const type = describeAnswerType(ran.answer.headers);
+        throw new Error(`login for "${ctx.principal.id}" answered no credential at ${from} (${type})`);
+    }
+    const expiresAt = expiresAtOf({ body: answerBody(ran.answer), expiresIn: options.expiresIn, now: ctx.now(), value });
+    const issued = { expiresAt, value };
+    if (login.claims !== undefined)
+        issued.identity = claimsOf(ctx, login.claims, { ...ran, value });
+    const { revoke } = login;
+    if (revoke !== undefined)
+        issued.revoke = () => revokeSession(ctx, { ran, revoke, value });
+    return renewable(ctx, issuing, issued);
+}
+/*
+ * Ends one session: its revoke operation, sent with exactly that session's value, which fills the
+ * body too. A 401 counts as revoked; any other refusal is a session the run could not end.
+ */
+async function revokeSession(ctx, session) {
+    const { ran, value } = session;
+    const { body, operationId } = typeof session.revoke === "string" ? { operationId: session.revoke } : session.revoke;
+    const as = { principal: ctx.principal.id, scheme: ctx.scheme.name };
+    const call = { as, operationId, scope: { ...ran.scope, credential: value }, value };
+    const sent = body === undefined ? call : { ...call, body: fillCredential(body, value) };
+    const answer = await ctx.ports.operations.call(sent);
+    /* It carried the very session it ends: a 401 says that session is unusable already, which is the revoke's aim. */
+    if (answer.status !== 401)
+        answered(answer, `revoke ${operationId}`);
+}
+/* The recipe's declared refresh, run with the scope the credential came with plus the credential itself. */
+function renewable(ctx, issuing, issued) {
+    const refresh = issuing.options.refresh;
+    if (refresh === undefined)
+        return issued;
+    issued.refresh = async (hop = {}) => {
+        const scope = { ...issuing.ran.scope, credential: issued.value };
+        const secrets = secretsOf(issuing.login, issuing.options);
+        const renewed = await run(ctx, refresh.steps, { scope, secrets, what: "refresh", ...hop });
+        return issue(ctx, { ...issuing, ran: renewed }, refresh);
+    };
+    return issued;
+}
+/**
+ * A login credential the run was handed rather than signed in for, a signup's answer or an
+ * invite's: it renews by the recipe's declared refresh from `held.scope` (a `refresh_token`, say),
+ * as a signed-in one does from what its steps saved. When that refresh reads a value `held.scope`
+ * lacks, it renews as `held.replaced`, the session it took the place of, whose steps saved those
+ * values; with no such session, that refresh fails naming the value. With no refresh declared, the
+ * store signs in again.
+ */
+export function heldLogin(ctx, held, options) {
+    const { value } = held;
+    const expiresAt = expiresAtOf({ body: undefined, expiresIn: options.expiresIn, now: ctx.now(), value });
+    const ran = { answer: { body: undefined, cookies: {}, headers: {}, status: 200 }, scope: { ...held.scope } };
+    const given = [...Object.keys(held.scope), "credential"];
+    const { refresh } = options;
+    if (held.replaced !== undefined && refresh !== undefined && unfilledIn(refresh.steps, given) !== undefined) {
+        return { expiresAt, refresh: held.replaced, value };
+    }
+    return renewable(ctx, { login: options.login, options, ran }, { expiresAt, value });
+}
+/*
+ * A `$` path reads the answer body, as `from` does; any other value names a claim of the token,
+ * which must then be a JWT. Either one missing is refused, naming it.
+ */
+function claimsOf(ctx, claims, issued) {
+    const who = `login for "${ctx.principal.id}"`;
+    const named = Object.values(claims).some((claim) => !claim.startsWith("$"));
+    const decoded = named ? jwtClaims(issued.value) : {};
+    if (decoded === null)
+        throw new Error(`${who} binds claims, but its credential is not a JWT`);
+    const identity = {};
+    for (const [name, path] of Object.entries(claims)) {
+        if (path.startsWith("$")) {
+            const found = readAnswer(issued.answer, path);
+            if (found === undefined) {
+                const type = describeAnswerType(issued.answer.headers);
+                throw new Error(`${who} binds ${name} to "${path}", which the answer does not carry (${type})`);
+            }
+            identity[name] = found;
+            continue;
+        }
+        const claim = readPath(decoded, path);
+        if (claim === undefined || claim === null) {
+            throw new Error(`${who} binds ${name} to claim "${path}", which the token does not carry ` +
+                `(it has ${Object.keys(decoded).join(", ")})`);
+        }
+        identity[name] = String(claim);
+    }
+    return identity;
+}
+//# sourceMappingURL=login.js.map

package/dist/api/credentials/recipes/mint.d.ts

@@ -0,0 +1,5 @@
+import type { MintRecipe, Recipe } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/** Mints the credential by the mint recipe; `options` are the recipe's shared options. */
+export declare function acquireMint(ctx: AcquireCtx, mint: MintRecipe, options: Partial<Recipe>): Promise<Issued>;
+//# sourceMappingURL=mint.d.ts.map

package/dist/api/credentials/recipes/mint.js

@@ -0,0 +1,60 @@
+import { expiresAtOf } from "../expiry.js";
+import { fillPrincipal, principalValues } from "../interpolate.js";
+import { answerBody } from "../../runtime/cookies/save-as.js";
+import { answered, valueAt } from "./answer.js";
+/*
+ * Make a credential by calling an operation as the principal with another scheme's credential: an
+ * API key created with a session, say. `{scopes}` in the body is the scope set the operation needs, as an array where
+ * it is the whole value and space-joined inside text. Each identity value the body sends is registered
+ * as a secret before it is sent. The minted credential records how to revoke it.
+ */
+const SCOPES = "{scopes}";
+/** Mints the credential by the mint recipe; `options` are the recipe's shared options. */
+export async function acquireMint(ctx, mint, options) {
+    const body = mint.body === undefined ? {} : { body: withScopes(fillPrincipal(ctx.principal, mint.body), ctx.scopes) };
+    const call = { as: asWith(ctx, mint), operationId: mint.operationId, secrets: [mint.from], ...body };
+    for (const value of principalValues(ctx.principal, mint.body))
+        ctx.ports.secrets.register(value);
+    const answer = await ctx.ports.operations.call(call);
+    answered(answer, `mint ${mint.operationId}`);
+    const value = valueAt(answer, mint.from, `mint ${mint.operationId}`);
+    const issued = {
+        expiresAt: expiresAtOf({ body: answerBody(answer), expiresIn: options.expiresIn, now: ctx.now(), value }),
+        scopes: ctx.scopes,
+        value,
+    };
+    const revoke = mint.revoke;
+    if (revoke === undefined)
+        return issued;
+    /* The revoke operation's path parameters come from the minted value and the mint answer's own fields. */
+    const record = {
+        as: asWith(ctx, mint),
+        operationId: revoke,
+        scope: { ...scalarFields(answer.body), credential: value },
+    };
+    issued.record = record;
+    issued.revoke = async () => answered(await ctx.ports.operations.call(record), `revoke ${revoke}`);
+    return issued;
+}
+/* The principal, sending the scheme the recipe mints with. */
+function asWith(ctx, mint) {
+    return { principal: ctx.principal.id, scheme: mint.with };
+}
+function scalarFields(body) {
+    if (body === null || typeof body !== "object")
+        return {};
+    const scalars = Object.entries(body).filter(([, value]) => ["string", "number", "boolean"].includes(typeof value));
+    return Object.fromEntries(scalars.map(([key, value]) => [key, String(value)]));
+}
+function withScopes(value, scopes) {
+    if (value === SCOPES)
+        return [...scopes];
+    if (typeof value === "string")
+        return value.replaceAll(SCOPES, scopes.join(" "));
+    if (Array.isArray(value))
+        return value.map((item) => withScopes(item, scopes));
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, withScopes(item, scopes)]));
+}
+//# sourceMappingURL=mint.js.map

package/dist/api/credentials/recipes/oauth2.d.ts

@@ -0,0 +1,5 @@
+import type { OAuth2Recipe, Recipe } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/** Gets an access token by the recipe's grant; `options` are the recipe's shared options. */
+export declare function acquireOAuth2(ctx: AcquireCtx, oauth2: OAuth2Recipe, options: Partial<Recipe>): Promise<Issued>;
+//# sourceMappingURL=oauth2.d.ts.map

package/dist/api/credentials/recipes/oauth2.js

@@ -0,0 +1,54 @@
+import { expiresAtOf } from "../expiry.js";
+import { fillPrincipal, principalValues } from "../interpolate.js";
+import { answerBody } from "../../runtime/cookies/save-as.js";
+import { readAnswer } from "../read.js";
+import { answered, valueAt } from "./answer.js";
+/*
+ * An OAuth 2 grant the API tester performs itself (RFC 6749 §4.3, §4.4): a form POST to the token URL the
+ * scheme declares for the flow. Each identity value the form sends (a password grant's username and
+ * password, say) is registered as a secret before it is sent. The scope is the set the operation
+ * needs, else the recipe's own.
+ * The lifetime is the recipe's `expiresIn`, else the answer's `expires_in`, else the JWT's `exp`.
+ * An answer with a `refresh_token` renews by that grant, keeping a rotated one; without one, the
+ * store renews by running the grant again.
+ */
+const GRANT = { clientCredentials: "client_credentials", password: "password" };
+/** Gets an access token by the recipe's grant; `options` are the recipe's shared options. */
+export async function acquireOAuth2(ctx, oauth2, options) {
+    const scheme = ctx.scheme;
+    const tokenUrl = scheme.kind === "oauth2" ? scheme.flows[oauth2.flow]?.tokenUrl : undefined;
+    if (tokenUrl === undefined) {
+        throw new Error(`the "${scheme.name}" scheme declares no tokenUrl for the ${oauth2.flow} flow`);
+    }
+    const filled = fillPrincipal(ctx.principal, oauth2);
+    for (const value of principalValues(ctx.principal, oauth2))
+        ctx.ports.secrets.register(value);
+    const scopes = ctx.scopes.length > 0 ? ctx.scopes : (filled.scopes ?? []);
+    const client = { client_id: filled.clientId };
+    if (filled.clientSecret !== undefined)
+        client["client_secret"] = filled.clientSecret;
+    if (scopes.length > 0)
+        client["scope"] = scopes.join(" ");
+    const form = { ...client, grant_type: GRANT[filled.flow] };
+    if (filled.username !== undefined)
+        form["username"] = filled.username;
+    if (filled.password !== undefined)
+        form["password"] = filled.password;
+    const expiresIn = options.expiresIn ?? { from: "$.expires_in" };
+    return token(ctx, { client, expiresIn, scopes, tokenUrl }, form);
+}
+/* One token request. A refresh token, new or carried forward, renews by the refresh_token grant (§6). */
+async function token(ctx, grant, form, hop) {
+    const answer = await ctx.ports.tokens.post(grant.tokenUrl, form, hop);
+    answered(answer, "oauth2 token request");
+    const value = valueAt(answer, "$.access_token", "oauth2 token request");
+    const expiresAt = expiresAtOf({ body: answerBody(answer), expiresIn: grant.expiresIn, now: ctx.now(), value });
+    const issued = { expiresAt, scopes: grant.scopes, value };
+    const refreshToken = readAnswer(answer, "$.refresh_token") ?? grant.refreshToken;
+    if (refreshToken !== undefined) {
+        const renewal = { ...grant.client, grant_type: "refresh_token", refresh_token: refreshToken };
+        issued.refresh = (again) => token(ctx, { ...grant, refreshToken }, renewal, again);
+    }
+    return issued;
+}
+//# sourceMappingURL=oauth2.js.map

package/dist/api/credentials/recipes/static.d.ts

@@ -0,0 +1,8 @@
+import type { Recipe, StaticRecipe } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/**
+ * A value fixed in config. A basic pair is `user:pass`, which the basic placement base64-encodes.
+ * It serves a scoped operation only for the scopes it `holds`.
+ */
+export declare function acquireStatic(ctx: AcquireCtx, fixed: StaticRecipe, options: Partial<Recipe>): Promise<Issued>;
+//# sourceMappingURL=static.d.ts.map

package/dist/api/credentials/recipes/static.js

@@ -0,0 +1,14 @@
+import { expiresAtOf } from "../expiry.js";
+import { fillPrincipal } from "../interpolate.js";
+import { assertHolds } from "./answer.js";
+/**
+ * A value fixed in config. A basic pair is `user:pass`, which the basic placement base64-encodes.
+ * It serves a scoped operation only for the scopes it `holds`.
+ */
+export async function acquireStatic(ctx, fixed, options) {
+    assertHolds(ctx, options.holds);
+    const filled = fillPrincipal(ctx.principal, fixed);
+    const value = typeof filled === "string" ? filled : `${filled.username}:${filled.password}`;
+    return { expiresAt: expiresAtOf({ body: undefined, expiresIn: options.expiresIn, now: ctx.now(), value }), value };
+}
+//# sourceMappingURL=static.js.map

package/dist/api/credentials/recipes/types.d.ts

@@ -0,0 +1,31 @@
+import type { CredentialPrincipal } from "../../config/types/hooks.ts";
+import type { SecurityScheme } from "../../spec/security/schemes.ts";
+import type { CredentialPorts, CredentialRecord, Hop } from "../ports.ts";
+/** What a recipe acquires a credential with: the run's ports, who it is for, and what it must carry. */
+export interface AcquireCtx {
+    ports: CredentialPorts;
+    principal: CredentialPrincipal;
+    /** The scheme the credential is for; an oauth2 scheme also names the token URL. */
+    scheme: SecurityScheme;
+    /** The scopes the operation needs, sorted. Empty when it names none. */
+    scopes: readonly string[];
+    /** Epoch ms now; a run passes its clock so tests can move it. */
+    now: () => number;
+}
+/** A credential a recipe issued. */
+export interface Issued {
+    value: string;
+    /** Epoch ms it lapses, or null when it never does as far as the API tester can tell. */
+    expiresAt: number | null;
+    /** Renews it. Absent: the store acquires a fresh one by the same recipe. */
+    refresh?: (hop?: Hop) => Promise<Issued>;
+    /** Revokes it when the run is done with it. */
+    revoke?: () => Promise<void>;
+    /** The record its revoke removes, for a minted credential: one the run removed already is not revoked again. */
+    record?: CredentialRecord;
+    /** Identity the credential bound, e.g. a login's `claims`. */
+    identity?: Record<string, string>;
+    /** The scopes it was issued for, when the recipe asked for them. */
+    scopes?: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/credentials/recipes/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,13 @@
+/** How long before it lapses a credential counts as stale. */
+export declare const DEFAULT_REFRESH_BUFFER_MS = 30000;
+/** Whether a credential issued at `issuedAt` and lapsing at `expiresAt` is due for renewal at `now`. */
+export declare function isStale(held: {
+    expiresAt: number | null;
+    issuedAt: number;
+}, at: {
+    now: number;
+    bufferMs: number;
+}): boolean;
+/** A single-flight renewal per held entry: the first caller starts it, the rest share it. */
+export declare function createRenewals<E extends object, R>(): (held: E, start: () => Promise<R>) => Promise<R>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/api/credentials/refresh.js

@@ -0,0 +1,30 @@
+/*
+ * When a held credential is renewed, and how often. A credential is stale once it is within the
+ * buffer of lapsing, so a request never leaves with one that lapses in flight. A renewal is
+ * single-flight per held credential: however many callers find it stale or refused at once, one
+ * renewal runs and they all share its result. The renewals live on the store a run creates.
+ * The buffer is at most half the credential's lifetime, so a 30 s TOTP code or a short JWT is not
+ * stale the moment it is issued.
+ */
+/** How long before it lapses a credential counts as stale. */
+export const DEFAULT_REFRESH_BUFFER_MS = 30_000;
+/** Whether a credential issued at `issuedAt` and lapsing at `expiresAt` is due for renewal at `now`. */
+export function isStale(held, at) {
+    if (held.expiresAt === null)
+        return false;
+    const buffer = Math.min(at.bufferMs, (held.expiresAt - held.issuedAt) / 2);
+    return held.expiresAt - buffer <= at.now;
+}
+/** A single-flight renewal per held entry: the first caller starts it, the rest share it. */
+export function createRenewals() {
+    const renewals = new WeakMap();
+    return (held, start) => {
+        const running = renewals.get(held);
+        if (running !== undefined)
+            return running;
+        const renewal = start();
+        renewals.set(held, renewal);
+        return renewal;
+    };
+}
+//# sourceMappingURL=refresh.js.map

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

@@ -0,0 +1,13 @@
+import type { Recipe } from "../config/types/security.ts";
+import type { Requirement, ResolvedSecurity } from "../spec/security/requirements.ts";
+/** The alternative to send, or why none can be. `[]` is the anonymous alternative: send nothing. */
+export type Satisfied = {
+    alternative: Requirement[];
+} | {
+    unsatisfied: string;
+};
+/** The principal's effective recipe for a scheme, or undefined when it has none. */
+export type RecipesFor = (scheme: string) => Partial<Recipe> | undefined;
+/** The first alternative of `security` that `recipesFor` can satisfy, or the reasons none can. */
+export declare function satisfy(security: Pick<ResolvedSecurity, "alternatives">, recipesFor: RecipesFor): Satisfied;
+//# sourceMappingURL=satisfy.d.ts.map

package/dist/api/credentials/satisfy.js

@@ -0,0 +1,35 @@
+import { recipeKind } from "./recipes/acquire.js";
+/** The first alternative of `security` that `recipesFor` can satisfy, or the reasons none can. */
+export function satisfy(security, recipesFor) {
+    const reasons = new Set();
+    for (const alternative of security.alternatives) {
+        const missing = alternative.map((requirement) => missingFor(requirement, recipesFor)).find(Boolean);
+        if (missing === undefined)
+            return { alternative };
+        reasons.add(missing);
+    }
+    return { unsatisfied: [...reasons].join("; ") };
+}
+/* Why one requirement is not met, or undefined when it is. */
+function missingFor(requirement, recipesFor) {
+    const recipe = recipesFor(requirement.scheme);
+    const kind = recipe === undefined ? undefined : recipeKind(recipe);
+    if (recipe === undefined || kind === undefined)
+        return `no credential for ${requirement.scheme}`;
+    if (kind === "login" || kind === "oauth2" || asksForScopes(recipe.mint?.body))
+        return undefined;
+    const held = new Set(recipe.holds ?? []);
+    const lacking = requirement.scopes.filter((scope) => !held.has(scope));
+    return lacking.length === 0 ? undefined : `no credential for ${requirement.scheme} holding ${lacking.join(", ")}`;
+}
+/* Whether a mint body, anywhere inside it, leaves the scope set to the operation. */
+function asksForScopes(body) {
+    if (typeof body === "string")
+        return body.includes("{scopes}");
+    if (Array.isArray(body))
+        return body.some(asksForScopes);
+    if (body === null || typeof body !== "object")
+        return false;
+    return Object.values(body).some(asksForScopes);
+}
+//# sourceMappingURL=satisfy.js.map

package/dist/api/credentials/sign-in-fields.d.ts

@@ -0,0 +1,4 @@
+import type { Recipe } from "../config/types/security.ts";
+/** The identity keys `recipe` signs in with, and the request fields that carry them. */
+export declare function signInFields(recipe: Partial<Recipe>): Set<string>;
+//# sourceMappingURL=sign-in-fields.d.ts.map

package/dist/api/credentials/sign-in-fields.js

@@ -0,0 +1,36 @@
+import { principalKeysIn } from "./interpolate.js";
+/*
+ * What a principal signs in with, by name: each identity key a recipe's sign-in reads as
+ * `{principal.<key>}` (its login and refresh steps, an out-of-band address, a mint's body, an oauth2
+ * grant), and the field each is sent under. A write that changes one of those on the principal's
+ * own record changes how it signs in. A static or hooked recipe reads no identity key here.
+ */
+/** The identity keys `recipe` signs in with, and the request fields that carry them. */
+export function signInFields(recipe) {
+    const steps = [...(recipe.login?.steps ?? []), ...(recipe.refresh?.steps ?? [])];
+    const found = new Set();
+    walk([steps.map(readBy), recipe.mint?.body, recipe.oauth2], undefined, found);
+    return found;
+}
+/* Everything a step reads an identity key into: what it sends, binds, or is mailed at. */
+function readBy(step) {
+    if ("outOfBand" in step)
+        return step.outOfBand.address;
+    return [step.bind, step.body, step.headers, step.query, "path" in step ? step.path : null];
+}
+function walk(value, field, found) {
+    if (typeof value === "string") {
+        const keys = principalKeysIn(value);
+        for (const key of keys)
+            found.add(key);
+        if (keys.length > 0 && field !== undefined)
+            found.add(field);
+    }
+    else if (Array.isArray(value))
+        for (const item of value)
+            walk(item, undefined, found);
+    else if (value !== null && typeof value === "object")
+        for (const [key, item] of Object.entries(value))
+            walk(item, key, found);
+}
+//# sourceMappingURL=sign-in-fields.js.map

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

@@ -0,0 +1,9 @@
+import type { Recipe } from "../config/types/security.ts";
+import type { SignupOperation } from "../spec/sign-up.ts";
+/**
+ * Whether a recipe's login steps call one of the account makers on the primary origin: by its
+ * operationId, or by a raw step to its method and path. A step on another origin calls another
+ * document's operation.
+ */
+export declare function signsUp(recipe: Partial<Recipe>, makers: readonly SignupOperation[]): boolean;
+//# sourceMappingURL=signup.d.ts.map

package/dist/api/credentials/signup.js

@@ -0,0 +1,24 @@
+/*
+ * Whether renewing a login would sign its principal up again. A login recipe with no `refresh` is
+ * renewed by running its steps once more, and a refused refresh falls back to the same; when a step
+ * calls an operation that makes an account (`accountMakersOf`), that would register another one,
+ * so the store refuses the renewal.
+ */
+/**
+ * Whether a recipe's login steps call one of the account makers on the primary origin: by its
+ * operationId, or by a raw step to its method and path. A step on another origin calls another
+ * document's operation.
+ */
+export function signsUp(recipe, makers) {
+    if (recipe.login === undefined)
+        return false;
+    return recipe.login.steps.some((step) => makers.some((maker) => callsSignup(step, maker)));
+}
+function callsSignup(step, signup) {
+    if ("origin" in step && step.origin !== undefined)
+        return false;
+    if ("operationId" in step)
+        return step.operationId === signup.operationId;
+    return "method" in step && step.method.toUpperCase() === signup.method.toUpperCase() && step.path === signup.path;
+}
+//# sourceMappingURL=signup.js.map