@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/run/pipeline.js

@@ -0,0 +1,96 @@
+import { teardownAccounts } from "./accounts.js";
+import { buildRegistry } from "../checks/core/define.js";
+import { CHECKS } from "../checks/registry.js";
+import { connect, disposeClients } from "./client-setup.js";
+import { contractFloor } from "./contract-floor.js";
+import { disposable } from "./disposable.js";
+import { errorText } from "./errors.js";
+import { createExclusion } from "./exclusion.js";
+import { noteLateStop } from "./interrupt.js";
+import { runLanes } from "./lanes.js";
+import { runReadSecurity, runWriteSecurity } from "./security.js";
+import { load } from "./load.js";
+import { runSecondaryOrigins } from "./origins.js";
+import { resolvePrincipals } from "./principals.js";
+import { publicGets } from "./public-gets.js";
+import { earlyResult, finalResult, scopeReport, settle } from "./result.js";
+import { scenarios } from "./scenarios.js";
+import { planScope } from "./scope-plan.js";
+import { serverErrors } from "./server-errors.js";
+import { readVersion } from "./target-version.js";
+import { reportUnremovable, revokeCredentials, revokeSessions, trackCreates, unwind } from "./teardown.js";
+/**
+ * Run orchestrator: model → world → checks → findings.
+ *
+ * The world is seeded once and outlives every check. A seeding failure is recorded once and
+ * everything downstream is reported BLOCKED against that single cause, rather than re-failing per
+ * case. The matrix's fixtures go before the scenarios: a scenario sets its own scene, and a record
+ * a check left (a pending invite) would refuse the scenario's own as a duplicate.
+ */
+export async function run(options) {
+    /* A registry with a duplicate id or a dependency out of order would grade nothing correctly. */
+    buildRegistry(CHECKS);
+    const connected = connect(await load(options));
+    /* However the run ends (done, stopped or thrown), no client's spooled bodies stay on disk. */
+    try {
+        return await runConnected(connected);
+    }
+    finally {
+        await disposeClients(connected);
+    }
+}
+async function runConnected(connected) {
+    const planned = planScope(connected);
+    const principals = await resolvePrincipals(planned);
+    if (principals === null)
+        return earlyResult(planned);
+    const authed = { ...planned, principals };
+    const ctx = { ...authed, exclusion: createExclusion(authed), targetVersion: await readVersion(authed) };
+    trackCreates(ctx);
+    await publicGets(ctx);
+    /* Read-only security probes before the lanes; the write and mutating ones after, while the
+     * records the lanes and disposable sessions created are still there to be targeted. */
+    await runReadSecurity(ctx);
+    await runLanes(ctx);
+    await disposable(ctx);
+    await runWriteSecurity(ctx);
+    await unwind(ctx);
+    await scenarios(ctx);
+    await contractFloor(ctx);
+    noteLateStop(ctx);
+    /* What scenarios and contract calls created since. */
+    await unwind(ctx);
+    serverErrors(ctx);
+    reportUnremovable(ctx);
+    const coverage = scopeReport(ctx);
+    await closeOut(ctx, { coverage, runOrigin: run });
+    /* After the last calls, so they are journaled and the principals are snapshot as those calls left them. */
+    const settled = await settle(ctx);
+    ctx.progress.tick({ message: "done", phase: "done", requests: ctx.progress.requests });
+    return finalResult(ctx, settled, coverage);
+}
+/**
+ * The run's last calls, in this order: the secondary origins, which send its minted keys too; then
+ * the revokes of every key minted; then the accounts it signed up, whose sessions those revokes
+ * were sent with; and last, the configured principals' own sessions, where the login declares how.
+ */
+export async function closeOut(ctx, runs) {
+    const { options } = ctx;
+    if ((options.origins ?? []).length > 0 && options.skipPrincipalTeardown !== true)
+        await secondaryOrigins(ctx, runs);
+    await revokeCredentials(ctx);
+    await teardownAccounts(ctx);
+    await revokeSessions(ctx);
+}
+async function secondaryOrigins(ctx, runs) {
+    try {
+        await runSecondaryOrigins(ctx, runs);
+    }
+    catch (error) {
+        ctx.findings.blocked("run.error", "origins", {
+            summary: "the secondary origins stopped on an unexpected error",
+            cause: errorText(error),
+        });
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/api/runtime/run/principals.d.ts

@@ -0,0 +1,19 @@
+import type { PrincipalEntry } from "../../config/types/security.ts";
+import type { CredentialStore } from "../../credentials/store.ts";
+import type { Planned, RunPrincipal, RunPrincipals } from "./context.ts";
+/**
+ * The run's principals, signed in. `null` when the network went away while signing them in (the
+ * outage is noted), or when none of them could be: the run has nobody to act as.
+ */
+export declare function resolvePrincipals(planned: Planned): Promise<RunPrincipals | null>;
+/** Runs each login the principal's recipes name, as the principals stage does; the first failure's reason. */
+export declare function logIn(planned: Planned, id: string, entry: PrincipalEntry): Promise<string | undefined>;
+/**
+ * Whether the run made this principal's account, so teardown removes it: a `fresh` one, one declared
+ * `created`, or one whose login recipe registers it through an operation that makes an account
+ * (`accountMakersOf`). Never a configured account, whatever its login binds or answers.
+ */
+export declare function createdByRun(planned: Pick<Planned, "model" | "options" | "store">, id: string): boolean;
+/** The principal as the store holds it, once its logins bound their claims. */
+export declare function runPrincipal(store: CredentialStore, id: string): RunPrincipal;
+//# sourceMappingURL=principals.d.ts.map

package/dist/api/runtime/run/principals.js

@@ -0,0 +1,134 @@
+import { effectiveRecipe } from "../../credentials/effective.js";
+import { signsUp } from "../../credentials/signup.js";
+import { recipeKind } from "../../credentials/recipes/acquire.js";
+import { isNetworkError } from "../../errors/network.js";
+import { accountMakersOf } from "../../spec/sign-up.js";
+import { provision } from "./fresh.js";
+import { boundOf } from "./identity.js";
+import { peerOf } from "./peer.js";
+/**
+ * The run's principals, signed in. `null` when the network went away while signing them in (the
+ * outage is noted), or when none of them could be: the run has nobody to act as.
+ */
+export async function resolvePrincipals(planned) {
+    const { findings, network, options, progress } = planned;
+    const all = [];
+    const blocked = [];
+    for (const [id, entry] of Object.entries(options.principals)) {
+        let reason;
+        try {
+            reason = await signIn(planned, id, entry);
+        }
+        catch (error) {
+            if (!isNetworkError(error))
+                throw error;
+            await network.note(error, "auth");
+        }
+        if (network.outcome !== undefined)
+            return null;
+        if (reason === undefined) {
+            all.push(runPrincipal(planned.store, id));
+            continue;
+        }
+        blocked.push({ id, reason });
+        findings.blocked("auth.blocked", id, {
+            summary: `principal "${id}" is BLOCKED`,
+            cause: reason,
+        });
+    }
+    progress.tick({ message: `${all.length} principal(s)`, phase: "auth", requests: progress.requests });
+    return all.length === 0 ? null : runPrincipals(planned, { all, blocked });
+}
+/* Signs the principal up when it is fresh, then runs each login it has; the first failure's reason. */
+async function signIn(planned, id, entry) {
+    if (entry.fresh === true) {
+        const made = await provision(planned, { entry, id, label: id });
+        if ("blocked" in made)
+            return made.blocked;
+    }
+    return logIn(planned, id, entry);
+}
+/** Runs each login the principal's recipes name, as the principals stage does; the first failure's reason. */
+export async function logIn(planned, id, entry) {
+    const { options, store } = planned;
+    const security = options.security ?? {};
+    for (const scheme of new Set([...Object.keys(security), ...Object.keys(entry.security ?? {})])) {
+        const recipe = effectiveRecipe(security[scheme], entry.security?.[scheme]);
+        if (recipe === undefined || recipeKind(recipe) !== "login")
+            continue;
+        const held = await store.acquire({ principal: id, scheme });
+        if ("blocked" in held)
+            return held.blocked;
+    }
+    return undefined;
+}
+/**
+ * Whether the run made this principal's account, so teardown removes it: a `fresh` one, one declared
+ * `created`, or one whose login recipe registers it through an operation that makes an account
+ * (`accountMakersOf`). Never a configured account, whatever its login binds or answers.
+ */
+export function createdByRun(planned, id) {
+    const entry = planned.store.principals[id];
+    if (entry.fresh === true || entry.created === true)
+        return true;
+    const makers = accountMakersOf(planned.model);
+    const security = planned.options.security ?? {};
+    return [...new Set([...Object.keys(security), ...Object.keys(entry.security ?? {})])].some((scheme) => {
+        const recipe = effectiveRecipe(security[scheme], entry.security?.[scheme]);
+        return recipe !== undefined && signsUp(recipe, makers);
+    });
+}
+/** The principal as the store holds it, once its logins bound their claims. */
+export function runPrincipal(store, id) {
+    const entry = store.principals[id];
+    const { identity, scope, tenant } = boundOf(store.identityOf(id));
+    return {
+        fresh: entry.fresh === true,
+        id,
+        identity,
+        rank: entry.rank ?? 0,
+        scope,
+        ...(tenant === undefined ? {} : { tenant }),
+        ...(entry.inviteAs === undefined ? {} : { inviteAs: entry.inviteAs }),
+        ...(entry.readOnly === true ? { readOnly: true } : {}),
+    };
+}
+function runPrincipals(planned, signed) {
+    const { ledger } = planned;
+    const { all, blocked } = signed;
+    const alpha = all[0];
+    const byId = new Map(all.map((principal) => [principal.id, principal]));
+    return {
+        all,
+        alpha,
+        blocked,
+        byId,
+        fallbackDeleters: (owner) => {
+            const creator = byId.get(owner.id);
+            if (creator === undefined)
+                return [];
+            return all
+                .filter((principal) => principal.id !== creator.id && sameTenant(principal, creator))
+                .sort((a, b) => b.rank - a.rank)
+                .map(ownerOf);
+        },
+        ownerOf,
+        peerOf: (principal) => peerOf([principal, ...all]),
+        recordCreated: (created, principal) => {
+            const sender = principal === undefined ? undefined : byId.get(principal);
+            ledger.record(created, ownerOf(sender ?? alpha));
+        },
+        recorder: (owner) => (entity, id, scope) => ledger.record({ entity, id, scope }, owner),
+        sameTenant,
+        unidentified: (entity, operationId, exchange) => ledger.unidentified(entity, operationId, exchange),
+    };
+}
+/** Two principals are of one tenant when their tenants agree: no tenant at all is one tenant too. */
+function sameTenant(a, b) {
+    return a.tenant === b.tenant;
+}
+/** Who owns what a principal creates: removed as it. */
+function ownerOf(principal) {
+    return { id: principal.id };
+}
+//# sourceMappingURL=principals.js.map

package/dist/api/runtime/run/probe-credentials.d.ts

@@ -0,0 +1,9 @@
+import type { ProbeCredentials } from "../checks/core/operation-context.ts";
+import { type StepOperation } from "../../credentials/anchors.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { RunContext } from "./context.ts";
+/** The run's probe credentials. */
+export declare function probeCredentials(ctx: Pick<RunContext, "store" | "model" | "options">): ProbeCredentials;
+/** A step's operation in this document: its operationId, or the operation documented at a raw step's method and path. */
+export declare function stepOperation(model: SpecModel): StepOperation;
+//# sourceMappingURL=probe-credentials.d.ts.map

package/dist/api/runtime/run/probe-credentials.js

@@ -0,0 +1,68 @@
+/*
+ * The credentials an operation check probes with, over the run's store: a dedicated credential that
+ * is never a principal's own session, and the value a principal's own credential holds, to derive a
+ * forged one from. What the store refuses is the check's reason to stay untested.
+ */
+import { recipeAnchors } from "../../credentials/anchors.js";
+import { effectiveRecipe } from "../../credentials/effective.js";
+import { pathTemplateParams } from "../../spec/routes.js";
+import { messageOf } from "../../errors/message.js";
+/** The run's probe credentials. */
+export function probeCredentials(ctx) {
+    const { store } = ctx;
+    return {
+        dedicated: async ({ reusable, ...key }) => {
+            const held = await store.acquireDedicated(key, { reusable: reusable === true });
+            return "blocked" in held ? { untested: held.blocked } : dedicatedOf(held);
+        },
+        held: async (request) => {
+            const held = await store.acquire(request);
+            return "blocked" in held ? { untested: held.blocked } : { value: held.value };
+        },
+        recipe: (request) => anchorsOf(ctx, request),
+    };
+}
+/* The principal's effective recipe for the scheme, read for the operations behind its credential. */
+function anchorsOf({ model, options, store }, { principal, scheme }) {
+    if (!Object.hasOwn(store.principals, principal))
+        return { untested: `no principal "${principal}" in the config` };
+    const base = Object.hasOwn(options.security ?? {}, scheme) ? options.security?.[scheme] : undefined;
+    const recipe = effectiveRecipe(base, store.principals[principal]?.security?.[scheme]);
+    const anchors = recipe === undefined ? undefined : recipeAnchors(recipe, stepOperation(model));
+    return anchors ?? { untested: `principal "${principal}" has no recipe for the "${scheme}" scheme` };
+}
+/** A step's operation in this document: its operationId, or the operation documented at a raw step's method and path. */
+export function stepOperation(model) {
+    return (step) => {
+        if ("origin" in step && step.origin !== undefined)
+            return undefined;
+        if ("operationId" in step)
+            return step.operationId;
+        if (!("method" in step))
+            return undefined;
+        const method = step.method.toUpperCase();
+        return model.operations.find((op) => op.method === method && pathTemplateParams(op.path, step.path) !== null)
+            ?.operationId;
+    };
+}
+function dedicatedOf(held) {
+    const credential = {
+        actor: { principal: held.principal },
+        owner: held.owner,
+        scheme: held.scheme,
+        value: held.credential.value,
+    };
+    if (held.revoke !== undefined)
+        credential.revoke = held.revoke;
+    const { rotate } = held;
+    if (rotate !== undefined)
+        credential.rotate = async () => rotationOf(await rotate());
+    return credential;
+}
+function rotationOf(rotated) {
+    return {
+        replay: () => rotated.replay().then(() => ({ accepted: true }), (error) => ({ accepted: false, reason: messageOf(error) })),
+        value: rotated.credential.value,
+    };
+}
+//# sourceMappingURL=probe-credentials.js.map

package/dist/api/runtime/run/progress.d.ts

@@ -0,0 +1,49 @@
+import type { HttpHooks } from "../../client/types.ts";
+import type { Exchange } from "../exchange.ts";
+import type { ProgressHandler, ProgressSnapshot } from "../progress/types.ts";
+type Phase = ProgressSnapshot["phase"];
+/** What a tick moves the run to. Each field left out keeps what the run was already on. */
+export interface Tick {
+    phase: Phase;
+    entity?: string | undefined;
+    entityIndex?: number | undefined;
+    entityTotal?: number | undefined;
+    check?: string | undefined;
+    message?: string | undefined;
+    requests?: number | undefined;
+}
+/**
+ * Where the run is, for the live status: the phase, entity and check it is on, the last answer,
+ * and the requests still in flight. Every stage moves it; `onProgress` sees each move.
+ */
+export declare class RunProgress {
+    private readonly handler;
+    private readonly startedAt;
+    private readonly defects;
+    phase: Phase;
+    entity: string | undefined;
+    check: string | undefined;
+    entityIndex: number | undefined;
+    entityTotal: number | undefined;
+    private last;
+    private readonly inflight;
+    private requestCount;
+    constructor(handler: ProgressHandler | undefined, startedAt: number, defects: () => number);
+    /** Counts requests from the client, once there is one. */
+    countRequests(count: () => number): void;
+    get requests(): number;
+    tick(partial: Tick): void;
+    /** A stage after the checks names itself, so `teardown` means records are being removed. */
+    enter(phase: Phase, message: string): void;
+    /** An answer arrived: it is the last one. */
+    remember(exchange: Exchange): void;
+    /** The last answer is shown, then the oldest request still out. */
+    announce(): void;
+    /** Tracks each request from dispatch to answer. */
+    readonly httpHooks: HttpHooks;
+    private publish;
+    private snapshot;
+    private oldestInflight;
+}
+export {};
+//# sourceMappingURL=progress.d.ts.map

package/dist/api/runtime/run/progress.js

@@ -0,0 +1,128 @@
+/**
+ * Where the run is, for the live status: the phase, entity and check it is on, the last answer,
+ * and the requests still in flight. Every stage moves it; `onProgress` sees each move.
+ */
+export class RunProgress {
+    handler;
+    startedAt;
+    defects;
+    phase = "load";
+    entity;
+    check;
+    entityIndex;
+    entityTotal;
+    last;
+    inflight = new Set();
+    requestCount = () => 0;
+    constructor(handler, startedAt, defects) {
+        this.handler = handler;
+        this.startedAt = startedAt;
+        this.defects = defects;
+    }
+    /** Counts requests from the client, once there is one. */
+    countRequests(count) {
+        this.requestCount = count;
+    }
+    get requests() {
+        return this.requestCount();
+    }
+    tick(partial) {
+        this.phase = partial.phase;
+        if (partial.entity !== undefined)
+            this.entity = partial.entity;
+        if (partial.entityIndex !== undefined)
+            this.entityIndex = partial.entityIndex;
+        if (partial.entityTotal !== undefined)
+            this.entityTotal = partial.entityTotal;
+        if (partial.check !== undefined)
+            this.check = partial.check;
+        this.publish({
+            ...(partial.message === undefined ? {} : { message: partial.message }),
+            ...(partial.requests === undefined ? {} : { requests: partial.requests }),
+        });
+    }
+    /** A stage after the checks names itself, so `teardown` means records are being removed. */
+    enter(phase, message) {
+        this.check = undefined;
+        this.tick({ message, phase, requests: this.requests });
+    }
+    /** An answer arrived: it is the last one. */
+    remember(exchange) {
+        this.last = lastOf(exchange);
+    }
+    /** The last answer is shown, then the oldest request still out. */
+    announce() {
+        this.publish({ omitInflight: true });
+        const remaining = this.oldestInflight();
+        if (remaining !== undefined)
+            this.publish({ inflight: remaining });
+    }
+    /** Tracks each request from dispatch to answer. */
+    httpHooks = {
+        end: (probe) => {
+            this.inflight.delete(probe);
+        },
+        start: (probe) => {
+            this.inflight.add(probe);
+            this.publish({ inflight: displayed(probe) });
+        },
+    };
+    publish(extra) {
+        this.handler?.(this.snapshot(extra));
+    }
+    snapshot(extra) {
+        const snap = {
+            elapsedMs: Date.now() - this.startedAt,
+            findings: this.defects(),
+            phase: this.phase,
+            requests: extra.requests ?? this.requests,
+        };
+        if (this.check !== undefined)
+            snap.check = this.check;
+        if (this.entity !== undefined)
+            snap.entity = this.entity;
+        if (this.entityIndex !== undefined)
+            snap.entityIndex = this.entityIndex;
+        if (this.entityTotal !== undefined)
+            snap.entityTotal = this.entityTotal;
+        if (extra.message !== undefined)
+            snap.message = extra.message;
+        if (this.last !== undefined)
+            snap.last = this.last;
+        if (extra.omitInflight !== true) {
+            const live = extra.inflight ?? this.oldestInflight();
+            if (live !== undefined)
+                snap.inflight = live;
+        }
+        return snap;
+    }
+    oldestInflight() {
+        let oldest;
+        for (const probe of this.inflight) {
+            if (oldest === undefined || probe.at < oldest.at)
+                oldest = probe;
+        }
+        return oldest === undefined ? undefined : displayed(oldest);
+    }
+}
+function displayed(probe) {
+    const shown = { at: probe.at, method: probe.method, url: probe.url };
+    if (probe.requestId !== "")
+        shown.requestId = probe.requestId;
+    shown.requestBytes = probe.requestBytes;
+    return shown;
+}
+function lastOf(exchange) {
+    return {
+        at: exchange.at,
+        durationMs: exchange.durationMs,
+        method: exchange.method,
+        requestBytes: exchange.requestBytes,
+        requestId: exchange.requestId,
+        responseBytes: exchange.responseBytes,
+        status: exchange.status,
+        url: exchange.url,
+        ...(exchange.network === undefined ? {} : { network: exchange.network.kind }),
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/api/runtime/run/public-gets.d.ts

@@ -0,0 +1,4 @@
+import type { RunContext } from "./context.ts";
+/** Each GET that needs no auth and no fixture, read once before the entities. */
+export declare function publicGets({ state, client, findings, grades, scope, model }: RunContext): Promise<void>;
+//# sourceMappingURL=public-gets.d.ts.map

package/dist/api/runtime/run/public-gets.js

@@ -0,0 +1,14 @@
+import { runPublicGets } from "../one-shot.js";
+/** Each GET that needs no auth and no fixture, read once before the entities. */
+export async function publicGets({ state, client, findings, grades, scope, model }) {
+    await runPublicGets({
+        checksRun: state.checksRun,
+        client,
+        findings,
+        grades,
+        inScope: (operationId) => scope.inScope(operationId),
+        mode: scope.mode,
+        model,
+    });
+}
+//# sourceMappingURL=public-gets.js.map

package/dist/api/runtime/run/record-scope.d.ts

@@ -0,0 +1,4 @@
+import type { OperationModel, SpecModel } from "../../spec/graph/types.ts";
+/** `scope` with `op`'s last path parameter bound to the record's identity when nothing named like it is. */
+export declare function recordScope(model: Pick<SpecModel, "entities">, op: Pick<OperationModel, "entity" | "pathParams">, scope: Readonly<Record<string, string>>): Record<string, string>;
+//# sourceMappingURL=record-scope.d.ts.map

package/dist/api/runtime/run/record-scope.js

@@ -0,0 +1,17 @@
+/*
+ * A minted credential is a record, and the operations that address it (its revoke, its entity's
+ * read and delete) take its identity as their last path parameter, whatever they call it: an
+ * `{api_key_id}` the mint answer names `id`. The record's scope is what the mint answered and what
+ * the principal binds; the last parameter, when nothing there is named like it, is the record's
+ * identity, the field the model knows for the operation's entity, else `id`.
+ */
+/** `scope` with `op`'s last path parameter bound to the record's identity when nothing named like it is. */
+export function recordScope(model, op, scope) {
+    const last = op.pathParams.at(-1);
+    if (last === undefined || scope[last] !== undefined)
+        return { ...scope };
+    const field = (op.entity === null ? undefined : model.entities.get(op.entity)?.identity) ?? "id";
+    const id = scope[field] ?? scope["id"];
+    return id === undefined ? { ...scope } : { ...scope, [last]: id };
+}
+//# sourceMappingURL=record-scope.js.map

package/dist/api/runtime/run/result.d.ts

@@ -0,0 +1,22 @@
+import { type KeptCredential, type PersistedPrincipal } from "../principals.ts";
+import { type ScopeReport } from "../scope/types.ts";
+import type { Planned, RunContext } from "./context.ts";
+import type { RunResult } from "./types.ts";
+/** What the run graded, per operation, from the transcript and the grades as they stand. */
+export declare function scopeReport({ authCreates, options, findings, grades, model, scope, client }: Planned): ScopeReport;
+/** The principals as the run leaves them, and with `keepCredentials` the values they held. */
+export interface Settled {
+    principals: PersistedPrincipal[];
+    credentials?: KeptCredential[];
+}
+/**
+ * The run's last writes, once its closing calls are sent: the journal flushed. Returns the principals as they stand for
+ * `principals.json`, the BLOCKED ones with why, holding no credential
+ * value; the values come back only when the run was asked to keep them.
+ */
+export declare function settle(ctx: RunContext): Promise<Settled>;
+/** The result of a run the network cut short before any principal could act. */
+export declare function earlyResult(planned: Planned): Promise<RunResult>;
+/** The result of a run that went the whole way. */
+export declare function finalResult(ctx: RunContext, settled: Settled, coverage: ScopeReport): RunResult;
+//# sourceMappingURL=result.d.ts.map