@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/schema.js

@@ -0,0 +1,265 @@
+/**
+ * One reading of an OpenAPI schema, shared by everything that interprets one.
+ *
+ * The validator, the value generator and the model each used to interpret JSON Schema on their
+ * own, and they disagreed: one stripped `example` anywhere it appeared — including a property
+ * *named* example — another ignored `writeOnly`, a third read OpenAPI 3.0's boolean
+ * `exclusiveMinimum` as a number. A schema is now translated once into JSON Schema 2020-12, for a
+ * stated direction, and every consumer reads the result.
+ *
+ * Direction matters because OpenAPI schemas are shared between requests and responses:
+ * `readOnly` properties never appear in a request and `writeOnly` ones never in a response.
+ */
+import { PRIVILEGED } from "./extensions/privileged.js";
+import { DANGLING_KEY, DISCRIMINATOR_KEY } from "./load/walk.js";
+/** Keywords whose value is one subschema. */
+const SINGLE = /* @__PURE__ */ new Set([
+    "items",
+    "additionalItems",
+    "additionalProperties",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+]);
+/** Keywords whose value is a list of subschemas. */
+const LIST = /* @__PURE__ */ new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+/** Keywords whose value maps names to subschemas. */
+const MAP = /* @__PURE__ */ new Set([
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+    "dependentSchemas",
+]);
+/** Annotations that are not JSON Schema keywords, OpenAPI's and the API tester's — removed from schema nodes only. */
+const OPENAPI_ONLY = /* @__PURE__ */ new Set([
+    "nullable",
+    "example",
+    "discriminator",
+    DISCRIMINATOR_KEY,
+    DANGLING_KEY,
+    "xml",
+    "externalDocs",
+]);
+/** OpenAPI 3.0 exclusive bounds are booleans qualifying `minimum` / `maximum`. */
+const BOUNDS = [
+    ["exclusiveMinimum", "minimum"],
+    ["exclusiveMaximum", "maximum"],
+];
+function isSchema(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Translates `schema` into JSON Schema 2020-12 as seen in `direction`. Never mutates its input. */
+export function normalizeSchema(schema, options) {
+    return visit({ direction: options.direction, ordinary: options.ordinary === true, seen: new Map() }, schema);
+}
+function visit(ctx, node) {
+    const cached = ctx.seen.get(node);
+    if (cached !== undefined)
+        return cached;
+    const out = {};
+    ctx.seen.set(node, out);
+    for (const [key, value] of Object.entries(node)) {
+        if (!OPENAPI_ONLY.has(key))
+            translate(ctx, out, key, value);
+    }
+    resolveExclusiveBounds(out);
+    pinTags(ctx, node, out);
+    /* Properties that do not travel in this direction are neither allowed nor required. */
+    dropProperties(out, ctx.direction === "request" ? "readOnly" : "writeOnly");
+    if (ctx.ordinary)
+        dropPrivileged(out);
+    /* `nullable` widens whatever the schema otherwise allows. 3.1 has no such keyword, but
+     * generators still emit it, and reading it there costs nothing. */
+    if (node.nullable === true)
+        return nullable(out);
+    return out;
+}
+/** Writes one keyword of a schema node into `out`, translating any subschemas it holds. */
+function translate(ctx, out, key, value) {
+    if (SINGLE.has(key) && isSchema(value))
+        out[key] = visit(ctx, value);
+    else if (LIST.has(key) && Array.isArray(value))
+        out[key] = visitEach(ctx, value);
+    /* Draft-04 tuple form: positional item schemas. */
+    else if (key === "items" && Array.isArray(value))
+        out.prefixItems = visitEach(ctx, value);
+    else if (MAP.has(key) && isSchema(value)) {
+        const map = {};
+        for (const [name, sub] of Object.entries(value))
+            map[name] = isSchema(sub) ? visit(ctx, sub) : sub;
+        out[key] = map;
+    }
+    else
+        out[key] = value;
+}
+function visitEach(ctx, items) {
+    return items.map((item) => (isSchema(item) ? visit(ctx, item) : item));
+}
+/**
+ * A discriminated union, as `dereference` recorded it: each branch requires the tag and allows only
+ * its own values, so a body whose tag names one branch and whose fields fit another fits neither,
+ * and a generated body carries the tag of the branch it was made from. A tag that does not travel
+ * in this direction (`readOnly` in a request) is left alone, along with the union.
+ */
+function pinTags(ctx, node, out) {
+    const tags = node[DISCRIMINATOR_KEY];
+    const key = out.oneOf === undefined ? "anyOf" : "oneOf";
+    const union = out[key];
+    if (!isTags(tags) || !Array.isArray(union) || union.length !== tags.values.length)
+        return;
+    const hidden = ctx.direction === "request" ? "readOnly" : "writeOnly";
+    const sources = [node, ...node[key]];
+    if (sources.some((source) => isSchema(source) && hides(source, tags.propertyName, hidden)))
+        return;
+    out[key] = union.map((branch, index) => pinned(branch, tags.propertyName, tags.values[index]));
+}
+function isTags(value) {
+    if (value === null || typeof value !== "object" || !("propertyName" in value) || !("values" in value))
+        return false;
+    return typeof value.propertyName === "string" && Array.isArray(value.values);
+}
+function hides(schema, tag, hidden) {
+    const property = isSchema(schema.properties) ? schema.properties[tag] : undefined;
+    return isSchema(property) && property[hidden] === true;
+}
+/* A copy of `branch` whose `tag` is required and holds one of `values`; the branch itself is shared. */
+function pinned(branch, tag, values) {
+    if (!isSchema(branch))
+        return branch;
+    const properties = isSchema(branch.properties) ? branch.properties : {};
+    const own = properties[tag];
+    const required = Array.isArray(branch.required) ? branch.required : [];
+    return {
+        ...branch,
+        properties: { ...properties, [tag]: { ...(isSchema(own) ? own : {}), enum: values } },
+        required: required.includes(tag) ? required : [...required, tag],
+    };
+}
+function resolveExclusiveBounds(out) {
+    for (const [flag, bound] of BOUNDS) {
+        if (typeof out[flag] !== "boolean")
+            continue;
+        if (out[flag] === true && typeof out[bound] === "number") {
+            out[flag] = out[bound];
+            delete out[bound];
+        }
+        else
+            delete out[flag];
+    }
+}
+function dropProperties(out, hidden) {
+    if (!isSchema(out.properties))
+        return;
+    const properties = { ...out.properties };
+    const dropped = Object.entries(properties)
+        .filter(([, sub]) => isSchema(sub) && sub[hidden] === true)
+        .map(([name]) => name);
+    for (const name of dropped)
+        delete properties[name];
+    out.properties = properties;
+    if (Array.isArray(out.required))
+        out.required = out.required.filter((name) => !dropped.includes(String(name)));
+}
+/* An optional property marked x-privileged: an ordinary writer never sends it. */
+function dropPrivileged(out) {
+    if (!isSchema(out.properties))
+        return;
+    const required = Array.isArray(out.required) ? out.required : [];
+    out.properties = Object.fromEntries(Object.entries(out.properties).filter(([name, sub]) => !isSchema(sub) || sub[PRIVILEGED] !== true || required.includes(name)));
+}
+/** `schema` or null — by widening `type` and `enum` where that is exact, by a union where not. */
+function nullable(schema) {
+    const type = schema.type;
+    const typed = typeof type === "string" || Array.isArray(type);
+    const composite = ["allOf", "anyOf", "oneOf", "$ref", "not", "const"].some((key) => key in schema);
+    if (typed && !composite) {
+        const out = { ...schema };
+        const types = Array.isArray(type) ? [...type] : [type];
+        if (!types.includes("null"))
+            types.push("null");
+        out.type = types;
+        if (Array.isArray(out.enum) && !out.enum.includes(null))
+            out.enum = [...out.enum, null];
+        return out;
+    }
+    return { anyOf: [schema, { type: "null" }] };
+}
+const SCALAR_KINDS = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean"]);
+/* What makes an allOf branch say something about the type, rather than annotate it. */
+const TYPING_KEYS = ["type", "oneOf", "anyOf", "allOf", "enum", "const", "properties", "items"];
+/**
+ * The scalar kinds a property's schema admits, nulls aside, or `undefined` when it is not a scalar
+ * field: an object, an array, a schema that admits only null, or one that says nothing.
+ *
+ * Every spelling of a nullable scalar reads the same: a 3.1 type list (`["string", "null"]`), 3.0
+ * `nullable: true` beside the type, and a `oneOf` or `anyOf` with a `{type: "null"}` branch. An
+ * untyped `enum` or `const` is read by its values, and an `allOf` with one typed branch — a `$ref`
+ * with a description beside it, once dereferenced — by that branch.
+ */
+export function scalarKinds(schema) {
+    if (!isSchema(schema))
+        return undefined;
+    const kinds = kindsOf(schema);
+    return kinds === undefined || kinds.length === 0 ? undefined : [...new Set(kinds)];
+}
+/* The scalar kinds of `schema`; empty when it admits only null, `undefined` when not a scalar. */
+function kindsOf(schema) {
+    const { type } = schema;
+    if (typeof type === "string")
+        return type === "null" ? [] : kindsOfTypes([type]);
+    if (Array.isArray(type))
+        return type.length === 0 ? undefined : kindsOfTypes(type);
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(branches))
+        return kindsOfBranches(branches);
+    if (Array.isArray(schema.allOf))
+        return kindsOfAll(schema.allOf);
+    if (Array.isArray(schema.enum))
+        return kindsOfValues(schema.enum);
+    return "const" in schema ? kindsOfValues([schema.const]) : undefined;
+}
+function kindsOfTypes(types) {
+    const kinds = [];
+    for (const type of types) {
+        if (type === "null")
+            continue;
+        if (typeof type !== "string" || !SCALAR_KINDS.has(type))
+            return undefined;
+        kinds.push(type);
+    }
+    return kinds;
+}
+/* Every branch a scalar or null; the kinds of them all. */
+function kindsOfBranches(branches) {
+    const kinds = [];
+    for (const branch of branches) {
+        const branchKinds = isSchema(branch) ? kindsOf(branch) : undefined;
+        if (branchKinds === undefined)
+            return undefined;
+        kinds.push(...branchKinds);
+    }
+    return kinds;
+}
+function kindsOfAll(branches) {
+    const typed = branches.filter((branch) => isSchema(branch) && TYPING_KEYS.some((key) => key in branch));
+    return typed.length === 1 ? kindsOf(typed[0]) : undefined;
+}
+function kindsOfValues(values) {
+    const kinds = [];
+    for (const value of values) {
+        if (value === null)
+            continue;
+        const kind = typeof value;
+        if (kind !== "string" && kind !== "number" && kind !== "boolean")
+            return undefined;
+        kinds.push(kind);
+    }
+    return kinds;
+}
+//# sourceMappingURL=schema.js.map

package/dist/api/spec/security/placement.d.ts

@@ -0,0 +1,11 @@
+import type { ApiKeyLocation, SecurityScheme } from "./schemes.ts";
+export interface Placement {
+    in: ApiKeyLocation;
+    /** The header, query parameter or cookie name. */
+    name: string;
+    template: string;
+    /** How the credential is encoded before it fills the template. */
+    encode?: "base64";
+}
+export declare function placementOf(scheme: SecurityScheme): Placement | null;
+//# sourceMappingURL=placement.d.ts.map

package/dist/api/spec/security/placement.js

@@ -0,0 +1,16 @@
+const AUTHORIZATION = "Authorization";
+export function placementOf(scheme) {
+    switch (scheme.kind) {
+        case "bearer":
+        case "oauth2":
+        case "openIdConnect":
+            return { in: "header", name: AUTHORIZATION, template: "Bearer {credential}" };
+        case "basic":
+            return { encode: "base64", in: "header", name: AUTHORIZATION, template: "Basic {credential}" };
+        case "apiKey":
+            return { in: scheme.in, name: scheme.param, template: "{credential}" };
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=placement.js.map

package/dist/api/spec/security/requirements.d.ts

@@ -0,0 +1,19 @@
+import type { OpenApiDocument, OperationObject } from "../types.ts";
+/** One scheme an alternative needs, with the scopes it must carry. */
+export interface Requirement {
+    scheme: string;
+    scopes: string[];
+}
+export interface ResolvedSecurity {
+    /** Any one of these satisfies the operation; `[]` is the anonymous alternative. */
+    alternatives: Requirement[][];
+    /** Where the requirement came from: the operation, the document root, or nowhere. */
+    source: "operation" | "root" | "none";
+    /** Schemes a requirement names that the document never declares. */
+    undeclared: string[];
+    /** Schemes a requirement gives scopes that are not a list: each was read as needing no scopes. */
+    malformedScopes: string[];
+}
+/** The requirement an operation carries, resolved against its document. */
+export declare function resolveSecurity(op: OperationObject, doc: OpenApiDocument): ResolvedSecurity;
+//# sourceMappingURL=requirements.d.ts.map

package/dist/api/spec/security/requirements.js

@@ -0,0 +1,21 @@
+function alternativesOf(declared) {
+    if (declared.length === 0)
+        return [[]];
+    return declared.map((set) => Object.entries(set).map(([scheme, scopes]) => ({ scheme, scopes: Array.isArray(scopes) ? [...scopes] : [] })));
+}
+/* The schemes `declared` gives scopes that are not a list, each once. */
+function malformedScopesOf(declared) {
+    const named = declared.flatMap((set) => Object.entries(set).filter(([, scopes]) => !Array.isArray(scopes)));
+    return [...new Set(named.map(([scheme]) => scheme))].toSorted();
+}
+/** The requirement an operation carries, resolved against its document. */
+export function resolveSecurity(op, doc) {
+    const declared = op.security ?? doc.security;
+    const source = op.security !== undefined ? "operation" : doc.security !== undefined ? "root" : "none";
+    const alternatives = alternativesOf(declared ?? []);
+    const schemes = doc.components?.securitySchemes ?? {};
+    const named = new Set(alternatives.flat().map((requirement) => requirement.scheme));
+    const undeclared = [...named].filter((scheme) => !Object.hasOwn(schemes, scheme)).toSorted();
+    return { alternatives, malformedScopes: malformedScopesOf(declared ?? []), source, undeclared };
+}
+//# sourceMappingURL=requirements.js.map

package/dist/api/spec/security/schemes.d.ts

@@ -0,0 +1,40 @@
+import type { OpenApiDocument } from "../types.ts";
+export type ApiKeyLocation = "header" | "query" | "cookie";
+export type FlowName = "authorizationCode" | "clientCredentials" | "deviceAuthorization" | "implicit" | "password";
+export interface OAuthFlow {
+    authorizationUrl?: string;
+    deviceAuthorizationUrl?: string;
+    refreshUrl?: string;
+    tokenUrl?: string;
+    /** The scope names the flow can grant. */
+    scopes: string[];
+}
+interface SchemeBase {
+    name: string;
+    /** OAS 3.2: the scheme is on its way out; still sent. */
+    deprecated: boolean;
+}
+export type SecurityScheme = SchemeBase & ({
+    kind: "bearer";
+    bearerFormat?: string;
+} | {
+    kind: "basic";
+} | {
+    kind: "apiKey";
+    in: ApiKeyLocation;
+    param: string;
+} | {
+    kind: "oauth2";
+    flows: Partial<Record<FlowName, OAuthFlow>>;
+    oauth2MetadataUrl?: string;
+} | {
+    kind: "openIdConnect";
+    openIdConnectUrl: string;
+} | {
+    kind: "unsupported";
+    unsupported: string;
+});
+/** Every scheme under `components.securitySchemes`, by name. */
+export declare function readSchemes(doc: OpenApiDocument): ReadonlyMap<string, SecurityScheme>;
+export {};
+//# sourceMappingURL=schemes.d.ts.map

package/dist/api/spec/security/schemes.js

@@ -0,0 +1,86 @@
+import { isRaw } from "../../config/types/raw.js";
+const FLOWS = [
+    "authorizationCode",
+    "clientCredentials",
+    "deviceAuthorization",
+    "implicit",
+    "password",
+];
+const FLOW_URLS = ["authorizationUrl", "deviceAuthorizationUrl", "refreshUrl", "tokenUrl"];
+const LOCATIONS = /* @__PURE__ */ new Set(["header", "query", "cookie"]);
+const text = (value) => (typeof value === "string" ? value : undefined);
+function unsupported(name, deprecated, why) {
+    return { deprecated, kind: "unsupported", name, unsupported: why };
+}
+function readHttp(name, raw, deprecated) {
+    const scheme = (text(raw.scheme) ?? "").toLowerCase();
+    if (scheme === "basic")
+        return { deprecated, kind: "basic", name };
+    if (scheme === "bearer") {
+        const format = text(raw.bearerFormat);
+        return { deprecated, kind: "bearer", name, ...(format === undefined ? {} : { bearerFormat: format }) };
+    }
+    if (scheme === "digest")
+        return unsupported(name, deprecated, "http digest needs a challenge-response round trip");
+    return unsupported(name, deprecated, `http scheme "${scheme}" is not one the API tester can send`);
+}
+function readApiKey(name, raw, deprecated) {
+    const location = text(raw.in);
+    const param = text(raw.name);
+    if (location === undefined || !LOCATIONS.has(location) || param === undefined) {
+        return unsupported(name, deprecated, "an apiKey scheme needs `in` (header, query or cookie) and a `name`");
+    }
+    return { deprecated, in: location, kind: "apiKey", name, param };
+}
+function readFlow(raw) {
+    const flow = isRaw(raw) ? raw : {};
+    const scopes = flow.scopes !== null && typeof flow.scopes === "object" ? Object.keys(flow.scopes) : [];
+    const out = { scopes };
+    for (const key of FLOW_URLS) {
+        const url = text(flow[key]);
+        if (url !== undefined)
+            out[key] = url;
+    }
+    return out;
+}
+function readOAuth2(name, raw, deprecated) {
+    const declared = isRaw(raw.flows) ? raw.flows : {};
+    const flows = {};
+    for (const flow of FLOWS)
+        if (declared[flow] !== undefined)
+            flows[flow] = readFlow(declared[flow]);
+    const metadata = text(raw.oauth2MetadataUrl);
+    return { deprecated, flows, kind: "oauth2", name, ...(metadata === undefined ? {} : { oauth2MetadataUrl: metadata }) };
+}
+function readOpenIdConnect(name, raw, deprecated) {
+    const url = text(raw.openIdConnectUrl);
+    if (url === undefined)
+        return unsupported(name, deprecated, "an openIdConnect scheme needs an `openIdConnectUrl`");
+    return { deprecated, kind: "openIdConnect", name, openIdConnectUrl: url };
+}
+function readScheme(name, value) {
+    if (!isRaw(value))
+        return unsupported(name, false, "the scheme is not an object");
+    const raw = value;
+    const deprecated = raw.deprecated === true;
+    switch (raw.type) {
+        case "http":
+            return readHttp(name, raw, deprecated);
+        case "apiKey":
+            return readApiKey(name, raw, deprecated);
+        case "oauth2":
+            return readOAuth2(name, raw, deprecated);
+        case "openIdConnect":
+            return readOpenIdConnect(name, raw, deprecated);
+        case "mutualTLS":
+            return unsupported(name, deprecated, "mutualTLS is a TLS client certificate, not a request credential");
+        default:
+            return unsupported(name, deprecated, `scheme type "${String(raw.type)}" is not one the API tester knows`);
+    }
+}
+/** Every scheme under `components.securitySchemes`, by name. */
+export function readSchemes(doc) {
+    const declared = doc.components?.securitySchemes ?? {};
+    return new Map(Object.entries(declared).map(([name, value]) => [name, readScheme(name, value)]));
+}
+//# sourceMappingURL=schemes.js.map

package/dist/api/spec/sign-in.d.ts

@@ -0,0 +1,4 @@
+/** How a document names its sign-in routes, as the API tester reads them when nothing is tagged. */
+/** A path or name that signs a caller in, mints a token, or opens a session. */
+export declare const SIGN_IN: RegExp;
+//# sourceMappingURL=sign-in.d.ts.map

package/dist/api/spec/sign-in.js

@@ -0,0 +1,4 @@
+/** How a document names its sign-in routes, as the API tester reads them when nothing is tagged. */
+/** A path or name that signs a caller in, mints a token, or opens a session. */
+export const SIGN_IN = /login|token|session/i;
+//# sourceMappingURL=sign-in.js.map

package/dist/api/spec/sign-up.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The operations that make an account, the one rule every reader of it shares: the operation the
+ * document marks `x-fresh-principal`, a create of the `identity: self` entity, and a sign-up the
+ * document leaves unmarked. The ledger records what is sent there, teardown removes it, and the
+ * credential store never renews a login by calling one again.
+ *
+ * An unmarked sign-up is an open POST named as a sign-up, or an open collection create that takes a
+ * password and resets, recovers or changes none. The API tester ledgers what it sends there like any sign-up,
+ * so an account it makes on an untagged document is named, never left silent. Tagging the
+ * operation lets the API tester sign in as the account and remove it.
+ */
+import type { OperationModel, SpecModel } from "./graph/types.ts";
+/** `x-entity.identity: self`: the signed-up caller is the record. */
+export declare const SELF_IDENTITY = "self";
+/** An operation that makes an account, as the credential store matches a login step against it. */
+export interface SignupOperation {
+    operationId: string;
+    method: string;
+    /** Its path template, below the primary base URL. */
+    path: string;
+}
+export declare function unmarkedSignUp(op: OperationModel, model: SpecModel): boolean;
+/**
+ * How sending an operation makes an account: `always`, a sign-up; `anonymously`, a create of the
+ * caller's own record anyone may send, which makes one only when it carries no credential, since a
+ * caller who carries one already has its account; or `null`, never.
+ */
+export type AccountMaking = "always" | "anonymously" | null;
+export declare function accountMaking(op: OperationModel, model: SpecModel): AccountMaking;
+/** Whether sending `op` can make an account. */
+export declare function makesAccount(op: OperationModel, model: SpecModel): boolean;
+/** Every operation of the document that can make an account, in document order. */
+export declare function accountMakersOf(model: Pick<SpecModel, "operations" | "rawOperations">): SignupOperation[];
+//# sourceMappingURL=sign-up.d.ts.map

package/dist/api/spec/sign-up.js

@@ -0,0 +1,77 @@
+/**
+ * The operations that make an account, the one rule every reader of it shares: the operation the
+ * document marks `x-fresh-principal`, a create of the `identity: self` entity, and a sign-up the
+ * document leaves unmarked. The ledger records what is sent there, teardown removes it, and the
+ * credential store never renews a login by calling one again.
+ *
+ * An unmarked sign-up is an open POST named as a sign-up, or an open collection create that takes a
+ * password and resets, recovers or changes none. The API tester ledgers what it sends there like any sign-up,
+ * so an account it makes on an untagged document is named, never left silent. Tagging the
+ * operation lets the API tester sign in as the account and remove it.
+ */
+import { requestSchema } from "./collection/request.js";
+import { SIGN_IN } from "./sign-in.js";
+/** `x-entity.identity: self`: the signed-up caller is the record. */
+export const SELF_IDENTITY = "self";
+/* A name's words, in order: split on `-`, `_`, `/`, `.`, spaces and camelCase, lowercased. */
+function words(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[-_/.\s]+/)
+        .filter((word) => word !== "")
+        .join(" ")
+        .toLowerCase();
+}
+const SIGN_UP = /(?:^| )(?:register|registration|signup|sign up)$/;
+/* The words of a route that sets a password on an account that already exists. */
+const PASSWORD_ONLY = /(?:^| )(?:reset|forgot|recover|change)(?: |$)/;
+/* The path's last segment, unless it is a parameter. */
+function lastSegment(path) {
+    const segment = path
+        .split("/")
+        .filter((part) => part !== "")
+        .at(-1);
+    return segment === undefined || segment.startsWith("{") ? undefined : segment;
+}
+/* A top-level property that carries a password. */
+function takesPassword(schema) {
+    const properties = schema?.properties;
+    if (properties === null || typeof properties !== "object")
+        return false;
+    return Object.entries(properties).some(([name, property]) => /^(password|passphrase)$/i.test(name) || property?.format === "password");
+}
+export function unmarkedSignUp(op, model) {
+    if (op.method.toUpperCase() !== "POST")
+        return false;
+    if (!op.security.alternatives.every((alternative) => alternative.length === 0))
+        return false;
+    const segment = lastSegment(op.path);
+    const names = segment === undefined ? [op.operationId] : [op.operationId, segment];
+    if (names.some((name) => SIGN_UP.test(words(name))))
+        return true;
+    /* A collection create, not a sign-in: an item route's POST changes a record, not who exists. */
+    if (segment === undefined || names.some((name) => SIGN_IN.test(name)))
+        return false;
+    /* A password reset, forgotten, recovered or changed takes one too, and makes no account. */
+    if (names.some((name) => PASSWORD_ONLY.test(words(name))))
+        return false;
+    /* Every operation of a built model has its raw operation. */
+    return takesPassword(requestSchema(model.rawOperations.get(op.operationId)));
+}
+export function accountMaking(op, model) {
+    if (op.freshPrincipal || unmarkedSignUp(op, model))
+        return "always";
+    const self = op.action === "create" && op.identity === SELF_IDENTITY;
+    return self && op.security.alternatives.some((alternative) => alternative.length === 0) ? "anonymously" : null;
+}
+/** Whether sending `op` can make an account. */
+export function makesAccount(op, model) {
+    return accountMaking(op, model) !== null;
+}
+/** Every operation of the document that can make an account, in document order. */
+export function accountMakersOf(model) {
+    return model.operations
+        .filter((op) => makesAccount(op, model))
+        .map((op) => ({ method: op.method, operationId: op.operationId, path: op.path }));
+}
+//# sourceMappingURL=sign-up.js.map

package/dist/api/spec/tags/checks.d.ts

@@ -0,0 +1,23 @@
+/** The checks the API tester tag's value is held to: each returns what is wrong with it, or `null`. */
+export type Check = (value: unknown) => string | null;
+/** A tag object's fields, each with the check its value must pass. */
+export type Fields = Readonly<Record<string, Check>>;
+/** The checks for a tag shaped like `T`: only `T`'s keys, so a misspelled one does not compile. */
+export type FieldsOf<T> = {
+    readonly [K in keyof T]?: Check;
+};
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;
+export declare const text: Check;
+export declare const flag: Check;
+export declare const route: Check;
+export declare const texts: Check;
+export declare const positive: Check;
+export declare const integer: Check;
+export declare const textMap: Check;
+/** `value` is one of `allowed`. */
+export declare function oneOf(value: unknown, allowed: readonly string[]): string | null;
+/** An object with these fields; `required` must be present, the rest are checked when present. */
+export declare function checkShape(value: unknown, fields: Fields, required?: readonly string[]): string | null;
+/** One query axis: field names, structured rows, or `null` for an explicit "none". */
+export declare function checkAxis(value: unknown, row: Fields): string | null;
+//# sourceMappingURL=checks.d.ts.map

package/dist/api/spec/tags/checks.js

@@ -0,0 +1,47 @@
+/** The checks the API tester tag's value is held to: each returns what is wrong with it, or `null`. */
+export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const ROUTE = /^[A-Za-z]+\s+\/\S*$/;
+export const text = (value) => (typeof value === "string" && value !== "" ? null : "must be a non-empty string");
+export const flag = (value) => (typeof value === "boolean" ? null : "must be true or false");
+export const route = (value) => typeof value === "string" && ROUTE.test(value.trim()) ? null : 'must be a route like "GET /path"';
+export const texts = (value) => Array.isArray(value) && value.every((item) => typeof item === "string") ? null : "must be an array of strings";
+export const positive = (value) => (typeof value === "number" && value > 0 ? null : "must be a positive number");
+export const integer = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? null : "must be a positive integer";
+export const textMap = (value) => isObject(value) && Object.values(value).every((item) => typeof item === "string") ? null : "must map names to strings";
+/** `value` is one of `allowed`. */
+export function oneOf(value, allowed) {
+    return allowed.includes(value) ? null : `must be one of ${allowed.map((a) => `"${a}"`).join(", ")}`;
+}
+/** An object with these fields; `required` must be present, the rest are checked when present. */
+export function checkShape(value, fields, required = []) {
+    if (!isObject(value))
+        return "must be an object";
+    for (const key of required)
+        if (value[key] === undefined)
+            return `needs "${key}"`;
+    for (const [key, entry] of Object.entries(value)) {
+        const check = fields[key];
+        if (check === undefined || entry === undefined)
+            continue;
+        const problem = check(entry);
+        if (problem !== null)
+            return `"${key}" ${problem}`;
+    }
+    return null;
+}
+/** One query axis: field names, structured rows, or `null` for an explicit "none". */
+export function checkAxis(value, row) {
+    if (value === null)
+        return null;
+    if (!Array.isArray(value))
+        return "must be an array of field names or { field } rows";
+    for (const item of value) {
+        if (typeof item === "string")
+            continue;
+        const problem = checkShape(item, row, ["field"]);
+        if (problem !== null)
+            return `has a row that ${problem}`;
+    }
+    return null;
+}
+//# sourceMappingURL=checks.js.map

package/dist/api/spec/tags/query.d.ts

@@ -0,0 +1,4 @@
+/** `x-query`, as `docs/api/tags.md` documents it. */
+import { type Check } from "./checks.ts";
+export declare const xQuery: Check;
+//# sourceMappingURL=query.d.ts.map