@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/server-errors.js

@@ -0,0 +1,74 @@
+/**
+ * A server error is a failure wherever it shows up. Checks judge the answers they asked for, and a
+ * check that needed an action to succeed before it could look at anything reports the failed
+ * action as a gap in what it could verify. That is true of the check, and it leaves the 5xx itself
+ * unreported. This pass closes that: after everything has run, every 5xx in the transcript that no
+ * check already reported as a defect becomes one, on the operation that answered with it. A
+ * document that lists 500 does not make a crash correct.
+ */
+import { ASSERTED } from "./finding.js";
+import { describeServerError } from "./rate-limit/retry-after.js";
+import { TARGET_VERSION_READ } from "./target-version.js";
+export const SERVER_ERROR_CHECK_ID = "response.no-server-error";
+export const serverErrorCheck = {
+    id: SERVER_ERROR_CHECK_ID,
+    needs: "a response from the backend",
+    plan: () => ({ ok: false }),
+    run: () => Promise.resolve(ASSERTED),
+    /* Runs after every check, scenario, contract call and teardown. `reportServerErrors` does. */
+    subjects: () => [],
+};
+/** Sequence numbers restart per client, so an exchange is named by where it went as well. */
+function exchangeKey(exchange) {
+    return `${exchange.seq}|${exchange.method}|${exchange.url}`;
+}
+const EVIDENCE_PER_OPERATION = 3;
+export function reportServerErrors(input) {
+    input.checksRun.add(SERVER_ERROR_CHECK_ID);
+    for (const [key, exchanges] of unreported(input))
+        reportOperation(input, key, exchanges);
+}
+/** Every server error no check reported, by the operation that answered it (or its method and path). */
+function unreported(input) {
+    const reported = new Set(input.findings.findings
+        .filter((finding) => finding.verdict === "BACKEND_BUG" || finding.verdict === "SECURITY")
+        .flatMap((finding) => finding.evidence.map(exchangeKey)));
+    const byOperation = new Map();
+    for (const exchange of input.transcripts.flat()) {
+        if (!isServerError(exchange, input.networkDown) || reported.has(exchangeKey(exchange)))
+            continue;
+        if (exchange.operationId === undefined ? input.mode !== "full" : !input.inScope(exchange.operationId))
+            continue;
+        const key = exchange.operationId ?? `${exchange.method} ${new URL(exchange.url).pathname}`;
+        const seen = byOperation.get(key) ?? [];
+        seen.push(exchange);
+        byOperation.set(key, seen);
+    }
+    return byOperation;
+}
+/** A 5xx, or a timeout on a host that went on answering, outside the version read and not superseded. */
+function isServerError(exchange, networkDown) {
+    const timedOut = exchange.status === 0 && exchange.network?.kind === "timeout" && !networkDown;
+    if ((exchange.status < 500 && !timedOut) || exchange.superseded === true)
+        return false;
+    return exchange.check !== TARGET_VERSION_READ;
+}
+function reportOperation(input, key, exchanges) {
+    const op = input.model.byOperationId.get(key);
+    const operations = op === undefined ? [] : [op.operationId];
+    const statuses = [...new Set(exchanges.map((exchange) => exchange.status))].join(", ");
+    const last = exchanges.at(-1);
+    if (op !== undefined)
+        input.grades.graded(operations, SERVER_ERROR_CHECK_ID);
+    input.findings
+        .attributed(operations)
+        .ownedBy(SERVER_ERROR_CHECK_ID)
+        .backend(SERVER_ERROR_CHECK_ID, op?.entity ?? "run", {
+        summary: `${key} ${describeServerError(last)}`,
+        detail: `${exchanges.length} request(s) to ${key} returned ${statuses}. A server error is a failure ` +
+            "even where the document lists it, and even when the check that sent the request could " +
+            "only report what it was then unable to verify.",
+        evidence: exchanges.slice(0, EVIDENCE_PER_OPERATION),
+    });
+}
+//# sourceMappingURL=server-errors.js.map

package/dist/api/runtime/sse.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Server-Sent Events frames.
+ *
+ * A success response that lists `text/event-stream` is a stream, not a JSON document. Split
+ * `event:` / `data:` the way the browser does; parse `data` as JSON only when it looks like JSON.
+ * Feed chunks through `SseParser` so a live stream never has to become one concatenated string.
+ */
+export interface SseEvent {
+    event: string;
+    /** JSON object/array when `data` starts with `{` / `[` and parses; otherwise the raw string. */
+    data: unknown;
+    raw: string;
+}
+/** Citeable SSE frame: event name + parsed data, without the duplicated `raw` payload. */
+export type SseFrame = Pick<SseEvent, "event" | "data">;
+/**
+ * Incremental SSE decoder. Incomplete lines stay in an internal buffer; dispatched frames
+ * are the only retained payload.
+ */
+export declare class SseParser {
+    private buffer;
+    private event;
+    private readonly dataLines;
+    readonly events: SseEvent[];
+    push(chunk: string): void;
+    /** Treat any remainder as a final line, then flush a trailing frame. */
+    finish(): SseEvent[];
+    private handleLine;
+    private flush;
+}
+/** Split a complete SSE body into frames. An empty `data` is not dispatched. */
+export declare function parseSse(text: string): SseEvent[];
+/** SSE text when the body is a string that carries `event:` / `data:` frames, or already-parsed frames. */
+export declare function sseEvents(body: unknown): SseEvent[] | null;
+/** Drop the duplicated `raw` field so a transcript can keep frames without twice the bytes. */
+export declare function sseFramesOf(events: readonly SseEvent[]): SseFrame[];
+export declare function isSseFrameList(body: unknown): body is SseFrame[];
+//# sourceMappingURL=sse.d.ts.map

package/dist/api/runtime/sse.js

@@ -0,0 +1,115 @@
+/**
+ * Server-Sent Events frames.
+ *
+ * A success response that lists `text/event-stream` is a stream, not a JSON document. Split
+ * `event:` / `data:` the way the browser does; parse `data` as JSON only when it looks like JSON.
+ * Feed chunks through `SseParser` so a live stream never has to become one concatenated string.
+ */
+/**
+ * Incremental SSE decoder. Incomplete lines stay in an internal buffer; dispatched frames
+ * are the only retained payload.
+ */
+export class SseParser {
+    buffer = "";
+    event = "message";
+    dataLines = [];
+    events = [];
+    push(chunk) {
+        this.buffer += chunk;
+        for (;;) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            let line = this.buffer.slice(0, newline);
+            this.buffer = this.buffer.slice(newline + 1);
+            if (line.endsWith("\r"))
+                line = line.slice(0, -1);
+            this.handleLine(line);
+        }
+    }
+    /** Treat any remainder as a final line, then flush a trailing frame. */
+    finish() {
+        if (this.buffer.length > 0) {
+            this.handleLine(this.buffer);
+            this.buffer = "";
+        }
+        this.flush();
+        return this.events;
+    }
+    handleLine(line) {
+        if (line === "") {
+            this.flush();
+            return;
+        }
+        if (line.startsWith(":"))
+            return;
+        const colon = line.indexOf(":");
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            this.event = value;
+        else if (field === "data")
+            this.dataLines.push(value);
+    }
+    flush() {
+        if (this.dataLines.length === 0) {
+            this.event = "message";
+            return;
+        }
+        const raw = this.dataLines.join("\n");
+        this.dataLines.length = 0;
+        const name = this.event;
+        this.event = "message";
+        this.events.push({ data: parseData(raw), event: name, raw });
+    }
+}
+/** Split a complete SSE body into frames. An empty `data` is not dispatched. */
+export function parseSse(text) {
+    const parser = new SseParser();
+    parser.push(text);
+    return parser.finish();
+}
+/** SSE text when the body is a string that carries `event:` / `data:` frames, or already-parsed frames. */
+export function sseEvents(body) {
+    if (isSseFrameList(body)) {
+        return body.map((frame) => ({
+            data: frame.data,
+            event: frame.event,
+            raw: typeof frame.data === "string" ? frame.data : JSON.stringify(frame.data),
+        }));
+    }
+    if (typeof body !== "string")
+        return null;
+    if (!/^(?:event|data):/m.test(body))
+        return null;
+    return parseSse(body);
+}
+/** Drop the duplicated `raw` field so a transcript can keep frames without twice the bytes. */
+export function sseFramesOf(events) {
+    return events.map((event) => ({ data: event.data, event: event.event }));
+}
+export function isSseFrameList(body) {
+    if (!Array.isArray(body) || body.length === 0)
+        return false;
+    return body.every(isSseFrame);
+}
+function isSseFrame(item) {
+    if (item === null || typeof item !== "object")
+        return false;
+    const rec = item;
+    return typeof rec.event === "string" && "data" in rec;
+}
+function parseData(raw) {
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/api/runtime/steps/engine.d.ts

@@ -0,0 +1,27 @@
+import type { AuthStep } from "../../config/types/steps.ts";
+import type { Exchange } from "../exchange.ts";
+import { type StepContext } from "./request.ts";
+type Scope = Record<string, string>;
+/** An answer as the steps read it. */
+export interface StepAnswer {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+}
+/** How a chain starts. */
+export interface RunStepsOptions {
+    /** Bindings the chain starts from; copied, never written. */
+    scope?: Readonly<Scope>;
+    /** Every hop is meant to be refused, a spent refresh token replayed say: each exchange is labeled a probe. */
+    probe?: true;
+}
+/** Runs `steps` in order, returning the bound scope and the last answer (none when nothing was sent). */
+export declare function runSteps(ctx: StepContext, steps: readonly AuthStep[], options?: RunStepsOptions): Promise<{
+    scope: Scope;
+    last: StepAnswer | undefined;
+}>;
+/** An exchange as a step, or a recipe, reads its answer, with the cookies its hops set. */
+export declare function answerOf(exchange: Exchange): StepAnswer;
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/api/runtime/steps/engine.js

@@ -0,0 +1,134 @@
+/*
+ * The step engine. A chain of steps runs against a scope: each step is an operation from the
+ * document, a raw request, or a value delivered outside HTTP, and what an answer carries is bound
+ * by path for the steps after it. The engine returns the scope and the last answer; what the
+ * caller makes of them, a credential say, is the caller's to read.
+ */
+import { answerBody, describeAnswerType, readSaveAs } from "../cookies/save-as.js";
+import { cookiesFromRecordedHeaders } from "../cookies/set-cookie.js";
+import { readPath } from "../../client/read-path.js";
+import { interpolate } from "./interpolate.js";
+import { jwtClaims } from "../../credentials/jwt.js";
+import { claimsToken } from "./jwt.js";
+import { resolveOutOfBandValue, triggerSentAt } from "./out-of-band.js";
+import { resolveRequest } from "./request.js";
+/** Runs `steps` in order, returning the bound scope and the last answer (none when nothing was sent). */
+export async function runSteps(ctx, steps, options = {}) {
+    const scope = { ...options.scope };
+    const sent = [];
+    let last;
+    for (const [index, step] of steps.entries()) {
+        const turn = { index, probe: options.probe === true, scope };
+        bindLiterals(step, scope);
+        if ("outOfBand" in step) {
+            scope[step.outOfBand.as] = await awaitDelivery(ctx, step, { sent, turn });
+            continue;
+        }
+        const exchange = await send(ctx, step, turn);
+        sent.push(exchange);
+        last = answerOf(exchange);
+        saveAnswer(ctx, step, { answer: last, turn });
+    }
+    return { last, scope };
+}
+/** A step's `bind` literals, filled from the scope before the step runs. */
+function bindLiterals(step, scope) {
+    const stepBind = "bind" in step ? step.bind : undefined;
+    for (const [name, literal] of Object.entries(stepBind ?? {})) {
+        scope[name] = String(interpolate(literal, scope));
+    }
+}
+/** The value an out-of-band step waits for, asked of the hook. */
+async function awaitDelivery(ctx, step, at) {
+    const { scope } = at.turn;
+    const address = String(interpolate(step.outOfBand.address, scope));
+    const since = step.outOfBand.sentEarlier === true ? undefined : triggerSentAt(at.sent, address);
+    return resolveOutOfBandValue(ctx.hooks.resolveOutOfBand, address, {
+        kind: step.outOfBand.kind,
+        label: `principal "${ctx.principalId}"`,
+        scope: { ...scope },
+        ...(since === undefined ? {} : { since }),
+        ...(ctx.outOfBand === undefined ? {} : { outOfBand: ctx.outOfBand }),
+    });
+}
+/** Sends an HTTP step and fails closed on a status it does not accept. */
+async function send(ctx, step, turn) {
+    const request = await resolveRequest(ctx, step, turn.scope, turn.index);
+    const exchange = await request.client.request(request.method, request.path, {
+        ...(request.body === undefined ? {} : { body: request.body }),
+        ...(request.contentType === undefined ? {} : { contentType: request.contentType }),
+        headers: request.headers ?? {},
+        ...(request.query === undefined ? {} : { query: request.query }),
+        /* A login or refresh hop acts as nobody, so it is never refreshed or retried: a hop that
+         * refreshed would wait on its own login. What it sends is what the step names. It is a real
+         * exchange of its operation, labeled a probe only when it is meant to be refused. */
+        as: { anonymous: true },
+        ...(turn.probe ? { probe: true } : {}),
+        ...("operationId" in step ? { operationId: step.operationId } : {}),
+        ...(request.redirect === undefined ? {} : { redirect: request.redirect }),
+    });
+    accept(ctx, step, { exchange, index: turn.index, request });
+    return exchange;
+}
+/** Throws unless the status is one the step expects, or any 2xx when it names none. */
+function accept(ctx, step, sent) {
+    const { exchange, request } = sent;
+    const acceptable = ("expect" in step ? step.expect : undefined) ?? [];
+    const ok = acceptable.length > 0 ? acceptable.includes(exchange.status) : exchange.status < 300;
+    if (ok)
+        return;
+    throw new Error(`testing api: principal "${ctx.principalId}" failed at auth step ${sent.index + 1} ` +
+        `(${request.method} ${request.path}): expected ` +
+        `${acceptable.length > 0 ? acceptable.join("/") : "2xx"}, got ${exchange.status} — ` +
+        `${JSON.stringify(exchange.responseBody).slice(0, 200)}`);
+}
+/** An exchange as a step, or a recipe, reads its answer, with the cookies its hops set. */
+export function answerOf(exchange) {
+    return {
+        body: exchange.responseBody,
+        cookies: exchange.cookies ?? cookiesFromRecordedHeaders(exchange.responseHeaders),
+        headers: exchange.responseHeaders,
+        status: exchange.status,
+    };
+}
+/** Binds a step's `saveAs` paths, then its `saveClaimsFrom` claims, from the answer: a form answer's by its fields. */
+function saveAnswer(ctx, step, at) {
+    const { answer, turn } = at;
+    const saveAs = "saveAs" in step ? step.saveAs : undefined;
+    for (const [name, template] of Object.entries(saveAs ?? {})) {
+        const path = String(interpolate(template, turn.scope));
+        const value = readSaveAs(path, {
+            body: answerBody(answer),
+            cookies: answer.cookies,
+            headers: answer.headers,
+            readJson: readPath,
+        });
+        if (value === undefined || value === null) {
+            throw new Error(`testing api: auth step ${turn.index + 1} for "${ctx.principalId}" declares saveAs.${name} = ` +
+                `"${path}", which is not present in the response (${describeAnswerType(answer.headers)})`);
+        }
+        turn.scope[name] = String(value);
+    }
+    const saveClaimsFrom = "saveClaimsFrom" in step ? step.saveClaimsFrom : undefined;
+    if (saveClaimsFrom !== undefined)
+        saveClaims(ctx, saveClaimsFrom, { answer, turn });
+}
+/** Binds claims out of the JWT a step's answer (or the scope) carries. */
+function saveClaims(ctx, from, at) {
+    const { index, scope } = at.turn;
+    const token = claimsToken(from.token, at.answer.body, scope);
+    const claims = typeof token === "string" ? jwtClaims(token) : null;
+    if (claims === null) {
+        throw new Error(`testing api: auth step ${index + 1} for "${ctx.principalId}" expected a JWT at ` +
+            `${from.token}, but it is absent or not decodable`);
+    }
+    for (const [name, claimPath] of Object.entries(from.bind)) {
+        const value = readPath(claims, claimPath);
+        if (value === undefined || value === null) {
+            throw new Error(`testing api: auth step ${index + 1} binds ${name} to claim "${claimPath}", which the token ` +
+                `does not carry. Available claims: ${Object.keys(claims).join(", ")}`);
+        }
+        scope[name] = String(value);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/api/runtime/steps/interpolate.d.ts

@@ -0,0 +1,3 @@
+/** `value` with every `{name}` in its text replaced from `scope`, and each kept value whole, walking arrays and objects. */
+export declare function interpolate(value: unknown, scope: Record<string, string>, kept?: ReadonlyMap<string, unknown>): unknown;
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/api/runtime/steps/interpolate.js

@@ -0,0 +1,30 @@
+/*
+ * `{name}` placeholders in a step's path, body, headers and query, filled from the scope the steps
+ * before it bound. A name the scope lacks stays as written here; the request a step sends refuses it.
+ * A field that is exactly `{name}` of a kept value (an object a response or a hook handed back, a
+ * number, a boolean) is that value itself, sent as it is: text inside it is never read as a
+ * placeholder, so a URL template it carries goes byte for byte.
+ */
+import { isBytes, PLACEHOLDER, WHOLE_PLACEHOLDER } from "../../config/types/placeholder.js";
+/** `value` with every `{name}` in its text replaced from `scope`, and each kept value whole, walking arrays and objects. */
+export function interpolate(value, scope, kept = new Map()) {
+    if (typeof value === "string") {
+        const whole = WHOLE_PLACEHOLDER.exec(value)?.[1];
+        if (whole !== undefined && kept.has(whole))
+            return kept.get(whole);
+        return value.replace(PLACEHOLDER, (match, key) => scope[key] ?? match);
+    }
+    if (Array.isArray(value))
+        return value.map((item) => interpolate(item, scope, kept));
+    if (isBytes(value))
+        return value;
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = interpolate(item, scope, kept);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/api/runtime/steps/jwt.d.ts

@@ -0,0 +1,3 @@
+/** JWT from a JSON body path, or a scope key bound by a prior / same-step `saveAs`. */
+export declare function claimsToken(address: string, body: unknown, scope: Record<string, string>): unknown;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/api/runtime/steps/jwt.js

@@ -0,0 +1,13 @@
+/*
+ * Where a step finds the token to read claims from. The claims themselves decode in
+ * credentials/jwt.ts, the one reader every caller shares.
+ */
+import { readPath } from "../../client/read-path.js";
+/** JWT from a JSON body path, or a scope key bound by a prior / same-step `saveAs`. */
+export function claimsToken(address, body, scope) {
+    if (!address.startsWith("$") && !address.includes(".") && scope[address] !== undefined) {
+        return scope[address];
+    }
+    return readPath(body, address);
+}
+//# sourceMappingURL=jwt.js.map

package/dist/api/runtime/steps/out-of-band.d.ts

@@ -0,0 +1,27 @@
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { Exchange } from "../exchange.ts";
+import { type BackoffConfig } from "../poll.ts";
+/** When an exchange's request left: its answer's time less how long it took. */
+export declare function sentAt(exchange: Pick<Exchange, "at" | "durationMs">): number;
+/**
+ * When the request a value delivered to `address` answers was sent: the latest of `sent` that names
+ * the address in its URL or body, since that request told the backend where to deliver. A later
+ * request naming someone else does not move it; when none names the address, the API tester cannot tell.
+ */
+export declare function triggerSentAt(sent: readonly Pick<Exchange, "at" | "durationMs" | "requestBody" | "url">[], address: string): number | undefined;
+/** What a value is, who is waiting for it, and what the hook is told alongside the address. */
+export interface OutOfBandOptions {
+    kind: string;
+    label: string;
+    outOfBand?: Partial<BackoffConfig>;
+    scope?: Record<string, string>;
+    /** When the request this value answers was sent; see `OutOfBandRequest.since`. */
+    since?: number;
+}
+/**
+ * Out-of-band values usually land in an eventually-consistent store, so the hook is polled with
+ * backoff rather than called once. A single read that happens to race the write looks exactly
+ * like a broken delivery mechanism.
+ */
+export declare function resolveOutOfBandValue(hook: Hooks["resolveOutOfBand"], address: string, options: OutOfBandOptions): Promise<string>;
+//# sourceMappingURL=out-of-band.d.ts.map

package/dist/api/runtime/steps/out-of-band.js

@@ -0,0 +1,53 @@
+/*
+ * Values delivered outside HTTP: verification tokens, OTPs, magic links. The API tester asks the
+ * `resolveOutOfBand` hook for them, and tells it when the request that triggered the delivery
+ * was sent, so an inbox holding older deliveries can tell them apart.
+ */
+import { isAbsentValue, pollWithBackoff, resolveBackoff, worstCaseWaitMs } from "../poll.js";
+/** When an exchange's request left: its answer's time less how long it took. */
+export function sentAt(exchange) {
+    return exchange.at - exchange.durationMs;
+}
+/**
+ * When the request a value delivered to `address` answers was sent: the latest of `sent` that names
+ * the address in its URL or body, since that request told the backend where to deliver. A later
+ * request naming someone else does not move it; when none names the address, the API tester cannot tell.
+ */
+export function triggerSentAt(sent, address) {
+    if (address === "")
+        return undefined;
+    const forms = [address, encodeURIComponent(address)];
+    const trigger = sent.findLast((exchange) => {
+        const body = typeof exchange.requestBody === "string" ? exchange.requestBody : JSON.stringify(exchange.requestBody ?? "");
+        return forms.some((form) => exchange.url.includes(form) || body.includes(form));
+    });
+    return trigger === undefined ? undefined : sentAt(trigger);
+}
+/**
+ * Out-of-band values usually land in an eventually-consistent store, so the hook is polled with
+ * backoff rather than called once. A single read that happens to race the write looks exactly
+ * like a broken delivery mechanism.
+ */
+export async function resolveOutOfBandValue(hook, address, options) {
+    const { kind } = options;
+    if (hook === undefined) {
+        throw new Error(`testing api: ${options.label} needs a "${kind}" value delivered outside HTTP, ` +
+            "but the config declares no resolveOutOfBand hook. The API tester cannot read your mail catcher, " +
+            "KV store or webhook sink — supply a function that can.");
+    }
+    const backoff = resolveBackoff(options.outOfBand);
+    const scope = options.scope ?? {};
+    const value = await pollWithBackoff((attempt) => hook({
+        address,
+        attempt,
+        kind,
+        scope,
+        ...(options.since === undefined ? {} : { since: options.since }),
+    }), backoff, isAbsentValue);
+    if (typeof value === "string" && value !== "")
+        return value;
+    throw new Error(`testing api: no "${kind}" value arrived for ${address} after ${backoff.attempts} attempts ` +
+        `(~${worstCaseWaitMs(backoff)}ms worst-case wait). The delivery mechanism is ` +
+        "either slow beyond the backoff window or not firing at all.");
+}
+//# sourceMappingURL=out-of-band.js.map

package/dist/api/runtime/steps/request.d.ts

@@ -0,0 +1,39 @@
+import type { Client } from "../../client/client.ts";
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { AuthStep, OperationStep, RequestStep } from "../../config/types/steps.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { BackoffConfig } from "../poll.ts";
+/** A named origin's client and the document it serves. */
+export interface OriginClient {
+    client: Client;
+    model: SpecModel;
+}
+/** What a chain of steps runs against, and whose chain it is. */
+export interface StepContext {
+    client: Client;
+    model: SpecModel;
+    hooks: Hooks;
+    principalId: string;
+    outOfBand?: Partial<BackoffConfig>;
+    originClients?: ReadonlyMap<string, OriginClient>;
+    /** Values a scenario keeps whole: a field that is exactly `{name}` of one sends it as it is. */
+    kept?: ReadonlyMap<string, unknown>;
+}
+/** The request a step sends, and the client it goes through. */
+export interface ResolvedRequest {
+    method: string;
+    path: string;
+    body?: unknown;
+    contentType?: string | null;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    client: Client;
+    redirect?: "follow" | "manual";
+}
+/** True for a step that names an operation from the document. */
+export declare function isOperationStep(step: AuthStep): step is OperationStep;
+/** True for a step that gives a raw method and path. */
+export declare function isRequestStep(step: AuthStep): step is RequestStep;
+/** Step `index` of a chain resolved against `scope`; throws when it cannot be sent. */
+export declare function resolveRequest(ctx: StepContext, step: AuthStep, scope: Record<string, string>, index: number): Promise<ResolvedRequest>;
+//# sourceMappingURL=request.d.ts.map