@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,27 @@
+import { type RawOf } from "../../config/types/raw.ts";
+import type { ApiConfig } from "../../config/types/config.ts";
+import { type OriginSchemes } from "../origin-recipes.ts";
+import type { ResolvedSecurity } from "../../spec/security/requirements.ts";
+import type { SecurityScheme } from "../../spec/security/schemes.ts";
+type Config = RawOf<ApiConfig>;
+/** What these checks read from a document: its schemes, and what each operation's security asks. */
+interface SpecView {
+    schemes: ReadonlyMap<string, SecurityScheme>;
+    operations: ReadonlyArray<{
+        security: ResolvedSecurity;
+    }>;
+}
+/** An origin scheme a recipe shares by name, used with no mapping that says which recipe it takes. */
+export declare function originProblems(config: Config, origins: Readonly<Record<string, SpecView>>, recipes: ReadonlySet<string>): string[];
+export type OriginView = OriginSchemes & {
+    id: string;
+    view: SpecView;
+};
+/** Each origin the config declares and the run loaded, in config order. */
+export declare function originViews(config: Config, origins: Readonly<Record<string, SpecView>>): OriginView[];
+/** The primary's schemes, then each origin's, for a recipe that names a scheme none of them maps. */
+export declare function declaredEverywhere(spec: SpecView, views: readonly OriginView[]): string;
+/** The recipes some operation needs with scopes: a primary scheme's by name, an origin scheme's by its mapping. */
+export declare function scopedRecipes(spec: SpecView, views: readonly OriginView[]): ReadonlySet<string>;
+export {};
+//# sourceMappingURL=origins.d.ts.map

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

@@ -0,0 +1,41 @@
+import { isRaw, isRecord } from "../../config/types/raw.js";
+import { mappedPairs } from "../origin-recipes.js";
+import { declaredSchemes } from "./principals.js";
+/** An origin scheme a recipe shares by name, used with no mapping that says which recipe it takes. */
+export function originProblems(config, origins, recipes) {
+    const declared = Array.isArray(config.origins) ? config.origins.filter((origin) => isRaw(origin)) : [];
+    return Object.entries(origins).flatMap(([id, view]) => {
+        const mapping = declared.find((origin) => origin.id === id)?.security;
+        const mapped = isRecord(mapping) ? mapping : {};
+        return [...view.schemes.keys()]
+            .filter((scheme) => recipes.has(scheme) && !(scheme in mapped))
+            .map((scheme) => `origins.${id} declares scheme "${scheme}" too; say which recipe it uses: origins[].security: { ${scheme}: "${scheme}" }`);
+    });
+}
+/** Each origin the config declares and the run loaded, in config order. */
+export function originViews(config, origins) {
+    const declared = Array.isArray(config.origins) ? config.origins.filter((origin) => isRaw(origin)) : [];
+    return declared.flatMap((origin) => {
+        const view = typeof origin.id === "string" ? origins[origin.id] : undefined;
+        return view === undefined
+            ? []
+            : [{ id: origin.id, mapping: origin.security, schemes: view.schemes, view }];
+    });
+}
+/** The primary's schemes, then each origin's, for a recipe that names a scheme none of them maps. */
+export function declaredEverywhere(spec, views) {
+    const ofOrigins = views
+        .filter((origin) => origin.schemes.size > 0)
+        .map((origin) => `; origins.${origin.id} declares: ${[...origin.schemes.keys()].toSorted().join(", ")}`);
+    return `${declaredSchemes(spec.schemes.keys())}${ofOrigins.join("")}`;
+}
+/** The recipes some operation needs with scopes: a primary scheme's by name, an origin scheme's by its mapping. */
+export function scopedRecipes(spec, views) {
+    const needs = (view) => view.operations.flatMap((op) => op.security.alternatives.flat().filter((need) => need.scopes.length > 0));
+    const ofOrigins = views.flatMap((origin) => {
+        const recipeOf = new Map(mappedPairs(origin));
+        return needs(origin.view).flatMap((need) => recipeOf.get(need.scheme) ?? []);
+    });
+    return new Set([...needs(spec).map((need) => need.scheme), ...ofOrigins]);
+}
+//# sourceMappingURL=origins.js.map

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

@@ -0,0 +1,28 @@
+import { type RawOf } from "../../config/types/raw.ts";
+import type { ApiConfig } from "../../config/types/config.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+type Config = RawOf<ApiConfig>;
+/** Every `{principal.<key>}` a value uses, wherever it is nested. */
+export declare function placeholders(value: unknown): Set<string>;
+/** What a document declares, said after a name it lacks: its scheme names, sorted, or that it has none. */
+export declare function declaredSchemes(schemes: Iterable<string>): string;
+/** The document's `x-fresh-principal` operation, and the top-level properties its request body names. */
+export interface FreshView {
+    operationId: string;
+    properties: readonly string[];
+}
+/** The operation a fresh principal is signed up by, when the document marks one. */
+export declare function freshView(model: Pick<SpecModel, "operations" | "rawOperations">): FreshView | undefined;
+/** What is wrong with `config.principals` that needs no document: its shape, removed fields and placeholders. */
+export declare function principalMapProblems(config: Config): string[];
+/**
+ * What is wrong with `config.principals`, against the declared schemes, the recipes and the
+ * document's signup (`fresh`, absent when it marks none).
+ */
+export declare function principalProblems(config: Config, schemes: ReadonlySet<string>, fresh?: FreshView): string[];
+/** The top-level config keys 0.25.0 removed. */
+export declare const REMOVED_KEYS: readonly string[];
+/** Top-level fields 0.25.0 removed, with their replacement: keys the current config type no longer has. */
+export declare function removedProblems(config: object): string[];
+export {};
+//# sourceMappingURL=principals.d.ts.map

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

@@ -0,0 +1,184 @@
+/*
+ * The principals map, the `{principal.<key>}` placeholders recipes use, and the fields 0.25.0
+ * removed. Each problem names the path and, for a removed field, what replaces it.
+ */
+import { effectiveRecipe } from "../effective.js";
+import { isRaw, isRecord } from "../../config/types/raw.js";
+import { requestSchema } from "../../spec/collection/request.js";
+/* What replaces each field 0.25.0 removed from a principal, said for the principal at `path`. */
+const REMOVED_ON_PRINCIPAL = {
+    auth: () => "put the flow in security.<scheme>: { login: { steps, from } }",
+    headers: () => "a fixed credential is security.<scheme>: { static: … }",
+    roots: (path) => `bind its parameters with ${path}.scope and its tenant with tenant`,
+    rootsFromFlow: () => "bind token claims with security.<scheme>.login.claims",
+};
+const FIELD_CHECKS = [
+    ["created", (value) => typeof value === "boolean", "must be true or false"],
+    ["fresh", (value) => typeof value === "boolean", "must be true or false"],
+    ["inviteAs", (value) => typeof value === "string", "must be a string"],
+    ["rank", (value) => Number.isSafeInteger(value), "must be an integer"],
+    ["readOnly", (value) => value === true, "must be true, or left out"],
+    ["tenant", (value) => typeof value === "string", "must be a string"],
+];
+/** Every `{principal.<key>}` a value uses, wherever it is nested. */
+export function placeholders(value) {
+    const found = new Set();
+    const visit = (node) => {
+        if (typeof node === "string")
+            for (const [, key] of node.matchAll(/\{principal\.([\w-]+)\}/g))
+                found.add(String(key));
+        else if (Array.isArray(node))
+            node.forEach(visit);
+        else if (isRecord(node))
+            Object.values(node).forEach(visit);
+    };
+    visit(value);
+    return found;
+}
+/** `scope`: the path or query parameters bound for this principal, each to a string. */
+function scopeProblems(path, scope) {
+    if (scope === undefined)
+        return [];
+    if (!isRecord(scope))
+        return [`${path}.scope must be a map of parameter → value`];
+    return Object.entries(scope)
+        .filter(([, value]) => typeof value !== "string")
+        .map(([name]) => `${path}.scope.${name} must be a string`);
+}
+function entryProblems(id, entry) {
+    const path = `principals.${id}`;
+    const problems = [];
+    for (const [field, why] of Object.entries(REMOVED_ON_PRINCIPAL)) {
+        if (field in entry)
+            problems.push(`${path}.${field} was removed in 0.25.0: ${why(path)}`);
+    }
+    problems.push(...scopeProblems(path, entry.scope));
+    for (const [field, valid, need] of FIELD_CHECKS) {
+        if (field in entry && !valid(entry[field]))
+            problems.push(`${path}.${field} ${need}`);
+    }
+    return problems;
+}
+/** What a document declares, said after a name it lacks: its scheme names, sorted, or that it has none. */
+export function declaredSchemes(schemes) {
+    const names = [...schemes].toSorted();
+    return names.length === 0 ? "The document declares no security scheme" : `The document declares: ${names.join(", ")}`;
+}
+/* Overrides for a scheme the document does not declare. */
+function overrideSchemeProblems(id, entry, schemes) {
+    const overrides = isRecord(entry.security) ? Object.keys(entry.security) : [];
+    const declared = declaredSchemes(schemes);
+    return overrides
+        .filter((name) => !schemes.has(name))
+        .map((scheme) => `principals.${id}.security.${scheme} names no scheme in the document. ${declared}`);
+}
+/** The operation a fresh principal is signed up by, when the document marks one. */
+export function freshView(model) {
+    const op = model.operations.find((candidate) => candidate.freshPrincipal);
+    if (op === undefined)
+        return undefined;
+    /* Every operation of a built model has its raw operation. */
+    const schema = requestSchema(model.rawOperations.get(op.operationId));
+    return { operationId: op.operationId, properties: Object.keys(isRecord(schema?.properties) ? schema.properties : {}) };
+}
+/* Placeholders of the recipes this principal will use, by scheme, that its entry has no key for. */
+function missingKeys(entry, security) {
+    const overrides = isRecord(entry.security) ? entry.security : {};
+    const schemes = new Set([...Object.keys(security), ...Object.keys(overrides)]);
+    return [...schemes].flatMap((scheme) => {
+        const recipe = effectiveRecipe(security[scheme], overrides[scheme]);
+        return [...placeholders(recipe)].filter((key) => !(key in entry)).map((key) => [scheme, key]);
+    });
+}
+/*
+ * Placeholders the recipes use that the principal's config data lacks. A fresh principal's identity
+ * is its signup body too, which only the document says, so `freshProblems` checks it against that.
+ */
+function placeholderProblems(id, entry, security) {
+    if (entry.fresh === true)
+        return [];
+    return missingKeys(entry, security).map(([scheme, key]) => `principals.${id} has no "${key}", which security.${scheme} uses as {principal.${key}}`);
+}
+/* A fresh principal needs the document's signup, and each placeholder from its entry or that signup's body. */
+function freshProblems(id, entry, against) {
+    if (entry.fresh !== true)
+        return [];
+    const { fresh } = against;
+    if (fresh === undefined) {
+        return [`principals.${id} is fresh, but the document marks no x-fresh-principal operation to sign it up`];
+    }
+    return missingKeys(entry, against.security)
+        .filter(([, key]) => !fresh.properties.includes(key))
+        .map(([scheme, key]) => `principals.${id} has no "${key}", and ${fresh.operationId}'s request body names no such property, ` +
+        `which security.${scheme} uses as {principal.${key}}`);
+}
+/* The principals' entries, when `config.principals` is a non-empty map; otherwise why it is not. */
+function entriesOf(config) {
+    const principals = config.principals;
+    if (Array.isArray(principals))
+        return "principals is a map of id → identity data now: { alpha: { email: …, tenant: … } }";
+    if (!isRecord(principals))
+        return "principals must be a map of id → identity data";
+    const entries = Object.entries(principals);
+    return entries.length === 0 ? "principals declares no principal" : entries;
+}
+/** What is wrong with `config.principals` that needs no document: its shape, removed fields and placeholders. */
+export function principalMapProblems(config) {
+    const entries = entriesOf(config);
+    if (typeof entries === "string")
+        return [entries];
+    const security = isRecord(config.security) ? config.security : {};
+    return entries.flatMap(([id, entry]) => isRaw(entry)
+        ? [...entryProblems(id, entry), ...placeholderProblems(id, entry, security)]
+        : [`principals.${id} must be an object of identity data`]);
+}
+/**
+ * What is wrong with `config.principals`, against the declared schemes, the recipes and the
+ * document's signup (`fresh`, absent when it marks none).
+ */
+export function principalProblems(config, schemes, fresh) {
+    /* Only a run needs principals, and configProblems asks for them there; doctor and plan read a config without. */
+    if (config.principals === undefined)
+        return [];
+    const entries = entriesOf(config);
+    const security = isRecord(config.security) ? config.security : {};
+    const against = { fresh, security };
+    const documented = typeof entries === "string"
+        ? []
+        : entries.flatMap(([id, entry]) => isRaw(entry)
+            ? [...overrideSchemeProblems(id, entry, schemes), ...freshProblems(id, entry, against)]
+            : []);
+    return [...principalMapProblems(config), ...documented, ...scenarioPrincipalProblems(config, entries)];
+}
+/* Every principal a scenario or one of its steps sends as must be declared: a run cannot sign in an unknown id. */
+function scenarioPrincipalProblems(config, entries) {
+    if (typeof entries === "string" || !Array.isArray(config.scenarios))
+        return [];
+    const declared = new Set(entries.map(([id]) => id));
+    const unknown = (path, named) => typeof named.principal === "string" && !declared.has(named.principal)
+        ? [`${path}.principal names "${named.principal}", which principals does not declare`]
+        : [];
+    return config.scenarios.filter(isRecord).flatMap((scenario) => {
+        const path = `scenarios.${String(scenario.id)}`;
+        const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+        return [
+            ...unknown(path, scenario),
+            ...steps.flatMap((step, index) => (isRecord(step) ? unknown(`${path}.steps[${index}]`, step) : [])),
+        ];
+    });
+}
+/* What replaces each top-level key 0.25.0 removed. */
+const REMOVED_TOP_LEVEL = {
+    roots: "bind parameters per principal with principals.<id>.scope",
+    rootsFromFlow: "bind token claims with security.<scheme>.login.claims",
+    "x-auth-flows": "declare a security.<scheme> recipe for each scheme the document declares",
+};
+/** The top-level config keys 0.25.0 removed. */
+export const REMOVED_KEYS = /* @__PURE__ */ Object.keys(REMOVED_TOP_LEVEL);
+/** Top-level fields 0.25.0 removed, with their replacement: keys the current config type no longer has. */
+export function removedProblems(config) {
+    return Object.entries(REMOVED_TOP_LEVEL)
+        .filter(([key]) => key in config)
+        .map(([key, replacement]) => `${key} was removed in 0.25.0: ${replacement}`);
+}
+//# sourceMappingURL=principals.js.map

package/dist/api/credentials/validate/recipe-shape.d.ts

@@ -0,0 +1,22 @@
+import { type RawOfUnion } from "../../config/types/raw.ts";
+import type { ExtraPlacement, LoginRecipe, Recipe } from "../../config/types/security.ts";
+import type { SecurityScheme } from "../../spec/security/schemes.ts";
+type RawRecipe = RawOfUnion<Recipe>;
+/** A login's revoke in its object form: the operation, and the body it sends. */
+export type RevokeOperation = Exclude<LoginRecipe["revoke"], string | undefined>;
+/** An extra placement the API tester can send: a known location, a name, and a template that holds the credential. */
+export declare const validPlacement: (value: unknown) => value is ExtraPlacement;
+/** What is wrong with the options a recipe of any kind carries: its lifetime, held scopes and extra placements. */
+export declare function optionProblems(path: string, recipe: RawRecipe): string[];
+/** What is wrong with a recipe that names no kind, or more than one. */
+export declare function kindProblems(path: string, recipe: RawRecipe): string[];
+/** What a recipe's shape is checked for: its scheme, whether a credential hook exists, and whether the document signs principals up. */
+export interface ShapeFor {
+    scheme: SecurityScheme;
+    hasHook: boolean;
+    signsUp: boolean;
+}
+/** What is wrong with the shape of a recipe of exactly one kind, for its scheme. */
+export declare function kindShapeProblems(path: string, recipe: RawRecipe, { hasHook, scheme, signsUp }: ShapeFor): string[];
+export {};
+//# sourceMappingURL=recipe-shape.d.ts.map

package/dist/api/credentials/validate/recipe-shape.js

@@ -0,0 +1,169 @@
+import { isRaw, isRecord } from "../../config/types/raw.js";
+import { capturedBy, unfilledIn } from "../placeholders.js";
+const isString = (value) => typeof value === "string";
+const stringList = (value) => Array.isArray(value) && value.every(isString);
+const article = (word) => (/^[aeiou]/i.test(word) ? "an" : "a");
+const LOCATIONS = /* @__PURE__ */ new Set(["header", "query", "cookie"]);
+const validExpiry = (value) => typeof value === "number"
+    ? value > 0
+    : isRaw(value) && typeof value.from === "string";
+/** An extra placement the API tester can send: a known location, a name, and a template that holds the credential. */
+export const validPlacement = (value) => isRaw(value) &&
+    LOCATIONS.has(value.in) &&
+    typeof value.name === "string" &&
+    (value.template === undefined || (typeof value.template === "string" && value.template.includes("{credential}")));
+/** What is wrong with the options a recipe of any kind carries: its lifetime, held scopes and extra placements. */
+export function optionProblems(path, recipe) {
+    const problems = [];
+    if (recipe.expiresIn !== undefined && !validExpiry(recipe.expiresIn)) {
+        problems.push(`${path}.expiresIn must be seconds above 0 or { from: <json path> }`);
+    }
+    const holds = recipe.holds;
+    if (holds !== undefined && !(Array.isArray(holds) && holds.every((scope) => typeof scope === "string"))) {
+        problems.push(`${path}.holds must be a list of scope names`);
+    }
+    if (recipe.placements !== undefined && !Array.isArray(recipe.placements)) {
+        problems.push(`${path}.placements must be a list`);
+    }
+    const placements = Array.isArray(recipe.placements) ? recipe.placements : [];
+    placements.forEach((placement, index) => {
+        if (!validPlacement(placement)) {
+            problems.push(`${path}.placements[${index}] must be { in: header | query | cookie, name, template? containing {credential} }`);
+        }
+    });
+    return problems;
+}
+/** `steps` and `from`: what a login and a refresh both run. */
+function stepsShape(path, value) {
+    const raw = isRaw(value) ? value : {};
+    return [
+        ...(Array.isArray(raw.steps) && raw.steps.length > 0 ? [] : [`${path}.steps must be a non-empty list of steps`]),
+        ...(isString(raw.from) ? [] : [`${path}.from must be a JSON path string`]),
+    ];
+}
+const stepsOf = (value) => (isRaw(value) && Array.isArray(value.steps) ? value.steps : []);
+/*
+ * A `{name}` the login's steps read that no earlier step binds, or the refresh's that neither the
+ * login saves nor an earlier refresh step binds (`credential` is the session's own value): it
+ * would be sent as written. Where the document signs principals up, a session may be taken from the
+ * signup's answer and refresh from what it carries, which only the run sees: the store refuses it then.
+ */
+function placeholderProblems(path, recipe, signsUp) {
+    const login = stepsOf(recipe.login);
+    const problems = [];
+    const loginGap = unfilledIn(login, []);
+    if (loginGap !== undefined) {
+        problems.push(`${path}.login.steps[${loginGap.step - 1}] reads {${loginGap.name}}, which no earlier login step binds`);
+    }
+    const refreshGap = signsUp ? undefined : unfilledIn(stepsOf(recipe.refresh), [...capturedBy(login), "credential"]);
+    if (refreshGap !== undefined) {
+        problems.push(`${path}.refresh.steps[${refreshGap.step - 1}] reads {${refreshGap.name}}, ` +
+            "which neither the login saves nor an earlier refresh step binds");
+    }
+    return problems;
+}
+/* A claim binds the principal's tenant, or one of its scope parameters: nothing else is the principal's to bind. */
+const CLAIM_TARGET = /^(?:tenant|scope\.[\w-]+)$/;
+/** `login.claims`: target → the claim name or JSON path in the answer that fills it. */
+function claimsShape(path, login) {
+    if (!isRaw(login) || login.claims === undefined)
+        return [];
+    if (!isRecord(login.claims))
+        return [`${path}.claims must be a map of target → claim`];
+    return Object.entries(login.claims).flatMap(([target, claim]) => {
+        if (!CLAIM_TARGET.test(target)) {
+            return [`${path}.claims.${target} binds nothing: a claim binds tenant or scope.<parameter>`];
+        }
+        return isString(claim) ? [] : [`${path}.claims.${target} must be a claim name or JSON path string`];
+    });
+}
+/** `login.revoke`: the operation that revokes a session, for the dedicated sessions probes open. */
+function revokeShape(path, login) {
+    if (!isRaw(login) || login.revoke === undefined || isString(login.revoke))
+        return [];
+    if (isRaw(login.revoke) && isString(login.revoke.operationId))
+        return [];
+    return [`${path}.revoke must be an operationId, or { operationId, body? }`];
+}
+function mintShape(path, mint) {
+    return ["with", "operationId"]
+        .filter((field) => !isString(mint[field]))
+        .map((field) => `${path}.mint.${field} must be a string`)
+        .concat(isString(mint.from) ? [] : [`${path}.mint.from must be a JSON path string`]);
+}
+function staticShape(path, value, scheme) {
+    if (scheme.kind === "basic") {
+        const pair = isRaw(value) && isString(value.username) && isString(value.password);
+        return pair ? [] : [`${path}.static must be { username, password } for a basic scheme`];
+    }
+    return isString(value) ? [] : [`${path}.static must be a string for ${article(scheme.kind)} ${scheme.kind} scheme`];
+}
+function oauth2Shape(path, oauth2) {
+    const problems = [];
+    if (!isString(oauth2.clientId))
+        problems.push(`${path}.oauth2.clientId must be a string`);
+    if (oauth2.scopes !== undefined && !stringList(oauth2.scopes)) {
+        problems.push(`${path}.oauth2.scopes must be a list of scope names`);
+    }
+    if (oauth2.flow === "password") {
+        for (const field of ["username", "password"]) {
+            if (!isString(oauth2[field]))
+                problems.push(`${path}.oauth2.${field} must be a string for the password flow`);
+        }
+    }
+    return problems;
+}
+function hookShape(path, hook, hasHook) {
+    if (hook !== true)
+        return [`${path}.hook must be true`];
+    return hasHook ? [] : [`${path}.hook needs hooks.resolveCredential in the config`];
+}
+const KINDS = ["login", "mint", "static", "hook", "oauth2"];
+/** What is wrong with a recipe that names no kind, or more than one. */
+export function kindProblems(path, recipe) {
+    const present = KINDS.filter((kind) => recipe[kind] !== undefined);
+    if (present.length === 1)
+        return [];
+    if (present.length === 0)
+        return [`${path} needs exactly one of ${KINDS.join(", ")}`];
+    return [`${path} has ${present.join(" and ")}; keep exactly one`];
+}
+/* Why `holds` does not fit a kind whose credential's scopes come from elsewhere. */
+const HOLDS_ELSEWHERE = {
+    login: "holds is for a static or hook recipe",
+    mint: "holds is not for a mint recipe: it holds the scopes its body asks for",
+    oauth2: "holds is not for an oauth2 recipe: it holds the oauth2.scopes it asks for",
+};
+/** Options that describe one kind's credential, on a recipe of another kind. */
+function fitProblems(path, recipe) {
+    const kind = KINDS.find((name) => recipe[name] !== undefined);
+    const problems = [];
+    if (recipe.refresh !== undefined && kind !== "login")
+        problems.push(`${path}.refresh is for a login recipe only`);
+    if (isRecord(recipe.expiresIn) && (kind === "static" || kind === "hook")) {
+        problems.push(`${path}.expiresIn.from reads the answer that issued the credential; a ${kind} recipe has none`);
+    }
+    const elsewhere = HOLDS_ELSEWHERE[kind];
+    if (stringList(recipe.holds) && elsewhere !== undefined)
+        problems.push(`${path}.${elsewhere}`);
+    return problems;
+}
+/** What is wrong with the shape of a recipe of exactly one kind, for its scheme. */
+export function kindShapeProblems(path, recipe, { hasHook, scheme, signsUp }) {
+    return [
+        ...fitProblems(path, recipe),
+        ...(recipe.login === undefined ? [] : stepsShape(`${path}.login`, recipe.login)),
+        ...claimsShape(`${path}.login`, recipe.login),
+        ...revokeShape(`${path}.login`, recipe.login),
+        ...(recipe.refresh === undefined ? [] : stepsShape(`${path}.refresh`, recipe.refresh)),
+        ...placeholderProblems(path, recipe, signsUp),
+        ...(isRaw(recipe.mint) ? mintShape(path, recipe.mint) : []),
+        ...(recipe.static === undefined ? [] : staticShape(path, recipe.static, scheme)),
+        ...(isRaw(recipe.oauth2) ? oauth2Shape(path, recipe.oauth2) : []),
+        ...(recipe.hook === undefined ? [] : hookShape(path, recipe.hook, hasHook)),
+        ...(recipe.format === undefined || (isString(recipe.format) && recipe.format.includes("{credential}"))
+            ? []
+            : [`${path}.format must contain {credential}`]),
+    ];
+}
+//# sourceMappingURL=recipe-shape.js.map

package/dist/api/credentials/validate/scenario-placeholders.d.ts

@@ -0,0 +1,7 @@
+import type { ApiConfig } from "../../config/types/config.ts";
+import { type RawOf } from "../../config/types/raw.ts";
+type Config = RawOf<ApiConfig>;
+/** One problem per scenario whose step reads a `{name}` nothing before it fills. */
+export declare function scenarioPlaceholderProblems(config: Config): string[];
+export {};
+//# sourceMappingURL=scenario-placeholders.d.ts.map

package/dist/api/credentials/validate/scenario-placeholders.js

@@ -0,0 +1,106 @@
+/*
+ * The `{name}` placeholders a scenario reads, checked against what fills them. A scenario starts
+ * from its principal's scope: the entry's `scope`, its own `scope.<param>` keys, and each login
+ * claim bound as `scope.<param>`, by a configured scheme or the principal's own recipe override.
+ * Each step then binds in the order the scenario runner does: its `bind` entries, then what its
+ * request, out-of-band address or external input reads, its asserts, then its `saveAs` entries one
+ * by one, and last its claims or out-of-band and external `as`. A name nothing fills would be sent
+ * as written, so the config is refused, naming the scenario, the step and the name.
+ */
+import { placeholderNames } from "../../config/types/placeholder.js";
+import { isRecord } from "../../config/types/raw.js";
+const SCOPED = "scope.";
+const recordOf = (value) => (isRecord(value) ? value : {});
+const listOf = (value) => (Array.isArray(value) ? value : []);
+/* The parameters keys written `scope.<param>` bind. */
+const scoped = (keys) => keys.filter((key) => key.startsWith(SCOPED)).map((key) => key.slice(SCOPED.length));
+/*
+ * Every parameter a login claim binds into a principal's scope, over every scheme: which one a
+ * principal holds is decided at sign-in. `security` is the config's schemes, or a principal's own
+ * recipe overrides; counting both over-approximates the merged recipe, which can only miss a typo.
+ */
+function claimedScope(security) {
+    return Object.values(recordOf(security)).flatMap((scheme) => scoped(Object.keys(recordOf(recordOf(recordOf(scheme)["login"])["claims"]))));
+}
+/* The principal a scenario that names none runs as: the writer the config declares, else the first, as a run orders them. */
+function writerOf(config, principals) {
+    const writer = config.writer;
+    return typeof writer === "string" && writer in principals ? writer : Object.keys(principals)[0];
+}
+/*
+ * The scope a scenario starts from: its principal's, else the writer's. A principal the config
+ * does not declare is the principals check's to name, so this check stands down.
+ */
+function startingScope(config, scenario) {
+    const principals = recordOf(config.principals);
+    const id = typeof scenario["principal"] === "string" ? scenario["principal"] : writerOf(config, principals);
+    if (id !== undefined && !(id in principals))
+        return undefined;
+    const entry = recordOf(principals[id ?? ""]);
+    return new Set([
+        ...Object.keys(recordOf(entry["scope"])),
+        ...scoped(Object.keys(entry)),
+        ...claimedScope(config.security),
+        ...claimedScope(entry["security"]),
+    ]);
+}
+/* What a step reads after its binds: an out-of-band address, an external's input, or a request and its asserts. */
+function reads(step) {
+    if (step["outOfBand"] !== undefined)
+        return [recordOf(step["outOfBand"])["address"]];
+    if (step["external"] !== undefined)
+        return [step["input"]];
+    const raw = step["method"] === undefined ? null : step["path"];
+    const asserts = [step["assert"] ?? []].flat().map((assert) => {
+        const { observes: _observes, ...read } = recordOf(assert);
+        return read;
+    });
+    return [raw, step["body"], step["headers"], step["query"], asserts];
+}
+/* The names a step binds once it is answered, beside `saveAs`. */
+function binds(step) {
+    const out = recordOf(step["outOfBand"])["as"];
+    const as = step["external"] === undefined ? out : step["as"];
+    return [...Object.keys(recordOf(recordOf(step["saveClaimsFrom"])["bind"])), ...(typeof as === "string" ? [as] : [])];
+}
+/* The first name `step` reads that `bound` lacks, binding what the step binds as it goes. */
+function unfilledStep(step, bound) {
+    const missing = (value) => placeholderNames(value).find((name) => !bound.has(name));
+    const bindAll = (entries) => {
+        for (const [name, template] of Object.entries(recordOf(entries))) {
+            const read = missing(template);
+            if (read !== undefined)
+                return read;
+            bound.add(name);
+        }
+        return undefined;
+    };
+    const read = bindAll(step["bind"]) ?? missing(reads(step)) ?? bindAll(step["saveAs"]);
+    if (read !== undefined)
+        return read;
+    for (const name of binds(step))
+        bound.add(name);
+    return undefined;
+}
+function scenarioProblem(config, scenario) {
+    const bound = startingScope(config, scenario);
+    if (bound === undefined)
+        return [];
+    for (const [index, step] of listOf(scenario["steps"]).entries()) {
+        const name = unfilledStep(recordOf(step), bound);
+        if (name === undefined)
+            continue;
+        return [
+            `scenarios.${String(scenario["id"])}.steps[${index}] reads {${name}}, ` +
+                "which no earlier step, the principal's scope or a login claim provides",
+        ];
+    }
+    return [];
+}
+/** One problem per scenario whose step reads a `{name}` nothing before it fills. */
+export function scenarioPlaceholderProblems(config) {
+    return listOf(config.scenarios)
+        .filter(isRecord)
+        .flatMap((scenario) => scenarioProblem(config, scenario));
+}
+//# sourceMappingURL=scenario-placeholders.js.map

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

@@ -0,0 +1,37 @@
+import { type RawOf } from "../../config/types/raw.ts";
+import type { ApiConfig } from "../../config/types/config.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { ResolvedSecurity } from "../../spec/security/requirements.ts";
+import type { SecurityScheme } from "../../spec/security/schemes.ts";
+import type { OpenApiDocument } from "../../spec/types.ts";
+import { type FreshView } from "./principals.ts";
+/** What validation reads from a document. */
+export interface SpecView {
+    schemes: ReadonlyMap<string, SecurityScheme>;
+    operations: ReadonlyArray<{
+        operationId: string;
+        security: ResolvedSecurity;
+    }>;
+    /** The document still carries the removed `x-auth-flows` tag. */
+    authFlows: boolean;
+    /** The operation that signs a fresh principal up; absent when the document marks none. */
+    fresh?: FreshView;
+}
+/** The parts of a document's model validation reads. */
+export type ModelView = Pick<SpecModel, "operations" | "rawOperations" | "schemes">;
+/** What validation reads from a document: its model, whether it still has `x-auth-flows`, and its signup. */
+export declare function specView(model: ModelView, doc: OpenApiDocument): SpecView;
+type Config = RawOf<ApiConfig>;
+/** What is wrong with `config.security` that needs no document: its shape, and each recipe's kind and options. */
+export declare function securityMapProblems(config: Config): string[];
+/** Every problem with a config's `security` and `principals`, against the primary document and each origin's. */
+export declare function securityProblems(config: Config, spec: SpecView, origins?: Readonly<Record<string, SpecView>>): string[];
+/** A document and its model: what a run, `doctor` and `plan` check a config against. */
+export interface ModeledDocument {
+    doc: OpenApiDocument;
+    model: ModelView;
+}
+/** Throws a UsageError naming every `securityProblems` problem against the primary document and each origin's. */
+export declare function assertSecurity(config: Config, primary: ModeledDocument, origins?: ReadonlyMap<string, ModeledDocument>): void;
+export {};
+//# sourceMappingURL=security.d.ts.map