@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/script/sandbox/host-api.js

@@ -0,0 +1,101 @@
+/**
+ * The host functions a script's API is built on (ADR-0016). Each is a pure function of strings: no
+ * handle, object or prototype of the host ever reaches the sandbox, only the strings these return.
+ */
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import { evaluate } from '../../xpath/evaluate.js';
+import { SCRIPT_LIMITS } from './model.js';
+export const HASH_ALGORITHMS = ['md5', 'sha1', 'sha256', 'sha512'];
+export const HMAC_ALGORITHMS = ['sha1', 'sha256', 'sha512'];
+export const DIGEST_ENCODINGS = ['hex', 'base64'];
+/** Thrown into the script (as its message) when a host function is called with something it refuses. */
+export class HostCallError extends Error {
+}
+function oneOf(value, allowed, what) {
+    if (allowed.includes(value)) {
+        return value;
+    }
+    throw new HostCallError(`${what} must be one of ${allowed.join(', ')}; got "${value}"`);
+}
+function digestEncoding(value) {
+    return value === undefined ? 'hex' : oneOf(value, DIGEST_ENCODINGS, 'encoding');
+}
+export function hash(algorithm, data, encoding) {
+    return createHash(oneOf(algorithm, HASH_ALGORITHMS, 'algorithm'))
+        .update(data, 'utf8')
+        .digest(digestEncoding(encoding));
+}
+export function hmac(algorithm, key, data, encoding) {
+    return createHmac(oneOf(algorithm, HMAC_ALGORITHMS, 'algorithm'), key)
+        .update(data, 'utf8')
+        .digest(digestEncoding(encoding));
+}
+export function uuid() {
+    return randomUUID();
+}
+export function base64(text) {
+    return Buffer.from(text, 'utf8').toString('base64');
+}
+export function fromBase64(text) {
+    return Buffer.from(text, 'base64').toString('utf8');
+}
+export function base64url(text) {
+    return Buffer.from(text, 'utf8').toString('base64url');
+}
+export function urlEncode(text) {
+    return encodeURIComponent(text);
+}
+/**
+ * The strings an XPath expression selects in `xml`, as JSON text: each node's text, or each value.
+ * `namespacesJson` is a JSON object of prefix to URI.
+ */
+export function xpathStrings(xml, expression, namespacesJson) {
+    let namespaces = {};
+    try {
+        const parsed = JSON.parse(namespacesJson);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            namespaces = Object.fromEntries(Object.entries(parsed).filter((e) => typeof e[1] === 'string'));
+        }
+    }
+    catch {
+        throw new HostCallError('namespaces must be a JSON object');
+    }
+    const result = evaluate(xml, expression, { language: 'xpath', namespaces });
+    switch (result.kind) {
+        case 'error':
+            throw new HostCallError(result.message);
+        case 'empty':
+            return '[]';
+        default:
+            return JSON.stringify(result.items.map((item) => item.text));
+    }
+}
+const TRUNCATED_MARK = '… (log cut short)';
+/** Collects `log(...)` lines within the caps; anything past them is dropped and flagged. */
+export class LogCollector {
+    lines = [];
+    bytes = 0;
+    truncated = false;
+    add(line) {
+        if (this.truncated) {
+            return;
+        }
+        if (this.lines.length >= SCRIPT_LIMITS.logLines) {
+            this.truncated = true;
+            return;
+        }
+        const size = Buffer.byteLength(line, 'utf8');
+        const room = SCRIPT_LIMITS.logBytes - this.bytes;
+        if (size > room) {
+            this.lines.push(`${Buffer.from(line, 'utf8').subarray(0, Math.max(0, room)).toString('utf8')}${TRUNCATED_MARK}`);
+            this.bytes = SCRIPT_LIMITS.logBytes;
+            this.truncated = true;
+            return;
+        }
+        this.lines.push(line);
+        this.bytes += size;
+    }
+    result() {
+        return { lines: [...this.lines], truncated: this.truncated };
+    }
+}

package/dist/script/sandbox/host.d.ts

@@ -0,0 +1,18 @@
+import { type SandboxJob, type SandboxResult } from './model.js';
+/** How many jobs may wait behind the one running before new ones are refused. */
+export declare const SCRIPT_QUEUE_LIMIT = 16;
+export interface ScriptSandboxOptions {
+    /** The worker script; tests substitute one. Defaults to the compiled `worker.js`. */
+    readonly workerUrl?: URL;
+}
+export interface ScriptSandbox {
+    /** Runs one job. Never rejects: every failure is a result. */
+    run(job: SandboxJob): Promise<SandboxResult>;
+    /** Terminates the worker; jobs still waiting resolve as failed. */
+    dispose(): Promise<void>;
+    /** Workers started so far (a replaced one counts again). */
+    readonly spawned: number;
+}
+/** A job's time limit, clamped to what a request file may ask for. */
+export declare function clampTimeout(timeoutMs: number | undefined): number;
+export declare function createScriptSandbox(options?: ScriptSandboxOptions): ScriptSandbox;

package/dist/script/sandbox/host.js

@@ -0,0 +1,172 @@
+/**
+ * Script runs off the calling thread (ADR-0016).
+ *
+ * One long-lived worker runs scripts one at a time, each in a fresh QuickJS runtime with its own
+ * time, memory and stack limits. The interpreter's interrupt handler is what normally stops a
+ * script at its deadline; as a backstop, a worker that has not answered `SCRIPT_LIMITS.backstopMs`
+ * after the deadline is terminated and replaced, and the job ends as `script-timeout`. A worker
+ * whose job ran out of time or memory is replaced too, so no runtime state outlives a bad job.
+ *
+ * The pattern is `rest/contract-check-worker-host.ts`'s. The worker gets an explicit stack size:
+ * QuickJS's own stack check must trip before the host thread's stack runs out.
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { SCRIPT_LIMITS } from './model.js';
+/** How many jobs may wait behind the one running before new ones are refused. */
+export const SCRIPT_QUEUE_LIMIT = 16;
+/** The worker's stack, in MB: comfortably above the QuickJS stack limit. */
+const WORKER_STACK_MB = 8;
+/** Extra backstop time for the first job on a new worker, which loads the WebAssembly module first. */
+const SPAWN_GRACE_MS = 2_000;
+/**
+ * The compiled worker script: the sibling `.js` when running from `dist`, else — running from `src`
+ * under vitest — the package's `dist/script/sandbox/worker.js`.
+ */
+function defaultWorkerUrl() {
+    const sibling = new URL('./worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(sibling))) {
+        return sibling;
+    }
+    const fallback = import.meta.url.replace(/\/src\/script\/sandbox\/host\.ts$/, '/dist/script/sandbox/worker.js');
+    /* v8 ignore next 3 -- only reachable when the engine package has never been built */
+    if (fallback === import.meta.url) {
+        throw new Error('script sandbox worker not found: build the engine package first');
+    }
+    return new URL(fallback);
+}
+const EMPTY_LOG = { lines: [], truncated: false };
+const failed = (code, message) => ({
+    ok: false,
+    error: { code, message },
+    log: EMPTY_LOG,
+});
+/** A job's time limit, clamped to what a request file may ask for. */
+export function clampTimeout(timeoutMs) {
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return SCRIPT_LIMITS.defaultTimeoutMs;
+    }
+    return Math.min(Math.floor(timeoutMs), SCRIPT_LIMITS.maxTimeoutMs);
+}
+export function createScriptSandbox(options = {}) {
+    let url = options.workerUrl;
+    let worker;
+    let spawned = 0;
+    let disposed = false;
+    let nextId = 0;
+    let current;
+    let timer;
+    const queue = [];
+    const finish = (result) => {
+        const job = current;
+        if (job === undefined)
+            return;
+        current = undefined;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        job.resolve(result);
+        pump();
+    };
+    /** Drops the current worker without waiting for it; its late answer or exit is then ignored. */
+    const discard = () => {
+        const dead = worker;
+        worker = undefined;
+        if (dead !== undefined) {
+            dead.removeAllListeners();
+            // An 'error' after the listeners are gone would otherwise be an uncaught exception.
+            dead.on('error', () => undefined);
+            void dead.terminate();
+        }
+    };
+    const spawn = () => {
+        url ??= defaultWorkerUrl();
+        const next = new Worker(url, { resourceLimits: { stackSizeMb: WORKER_STACK_MB } });
+        spawned += 1;
+        // The sandbox must never be what keeps the process alive.
+        next.unref();
+        next.on('message', (answer) => {
+            if (current?.id !== answer.id)
+                return;
+            if (answer.recycle)
+                discard();
+            finish(answer.result);
+        });
+        const broken = (why) => {
+            if (worker !== next)
+                return;
+            discard();
+            finish(failed('script-error', why));
+        };
+        next.on('error', (error) => {
+            broken(`The script stopped: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        next.on('exit', () => {
+            broken('The script stopped unexpectedly');
+        });
+        return next;
+    };
+    function pump() {
+        if (current !== undefined || disposed)
+            return;
+        const job = queue.shift();
+        if (job === undefined)
+            return;
+        current = job;
+        const timeoutMs = clampTimeout(job.job.timeoutMs);
+        const fresh = worker === undefined;
+        try {
+            worker ??= spawn();
+            worker.postMessage({ id: job.id, job: { ...job.job, timeoutMs } });
+        }
+        catch (error) {
+            discard();
+            finish(failed('script-error', `The script could not start: ${error instanceof Error ? error.message : String(error)}`));
+            return;
+        }
+        // The deadline starts when the job reaches the worker, so one stuck script never costs the ones
+        // behind it their own time.
+        timer = setTimeout(() => {
+            discard();
+            finish(failed('script-timeout', 'The script ran past its time limit'));
+        }, timeoutMs + SCRIPT_LIMITS.backstopMs + (fresh ? SPAWN_GRACE_MS : 0));
+        timer.unref?.();
+    }
+    return {
+        run(job) {
+            if (disposed)
+                return Promise.resolve(failed('script-error', 'The script sandbox was stopped'));
+            if (queue.length >= SCRIPT_QUEUE_LIMIT) {
+                return Promise.resolve(failed('script-error', 'Too many scripts waiting to run'));
+            }
+            return new Promise((resolve) => {
+                nextId += 1;
+                queue.push({ id: nextId, job, resolve });
+                pump();
+            });
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const dead = worker;
+            worker = undefined;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            const waiting = [...(current !== undefined ? [current] : []), ...queue.splice(0)];
+            current = undefined;
+            for (const job of waiting)
+                job.resolve(failed('script-error', 'The script sandbox was stopped'));
+            if (dead !== undefined) {
+                dead.removeAllListeners();
+                dead.on('error', () => undefined);
+                await dead.terminate();
+            }
+        },
+        get spawned() {
+            return spawned;
+        },
+    };
+}

package/dist/script/sandbox/model.d.ts

@@ -0,0 +1,69 @@
+/**
+ * What a script run in the sandbox is given and what it hands back (ADR-0016).
+ *
+ * A job is plain data: the code to run, the prelude that installs the API over the host functions,
+ * the JSON the API reads (`input`) and the run's limits. The result is plain data too. Nothing
+ * crosses the boundary but strings and JSON-shaped values.
+ */
+/** The limits every script run is held to (spec §Sandbox). */
+export declare const SCRIPT_LIMITS: {
+    /** The default time one script may run, in milliseconds. */
+    readonly defaultTimeoutMs: 1000;
+    /** The most a request file may allow (`scripts.timeoutMs`). */
+    readonly maxTimeoutMs: 10000;
+    /** How long past its deadline the host waits before it terminates and replaces the worker. */
+    readonly backstopMs: 1000;
+    readonly memoryBytes: number;
+    readonly stackBytes: number;
+    readonly logBytes: number;
+    readonly logLines: 1000;
+    /** The largest result (`__finish()`'s JSON) a script may hand back. */
+    readonly outputBytes: number;
+    /** The largest script file (spec §Storage). */
+    readonly fileBytes: number;
+};
+/** One run of a script. */
+export interface SandboxJob {
+    /**
+     * Installs the script's API. It runs before the script, in the same context, and may use the host
+     * functions (`__host.*`) and `__input`. It must define `__finish()`, whose return value (JSON-shaped)
+     * is the job's `output`.
+     */
+    readonly prelude: string;
+    /** The script, already stripped of types. */
+    readonly code: string;
+    /** The name errors are reported against, e.g. `Checkout.pre.ts`. */
+    readonly filename: string;
+    /** JSON-shaped data the prelude reads as `__input`. */
+    readonly input: unknown;
+    /** Milliseconds the prelude and the script may run together. */
+    readonly timeoutMs: number;
+}
+/** Where a script failed, in the script's own file. Lines and columns are 1-based. */
+export interface ScriptPosition {
+    readonly line: number;
+    readonly column: number;
+}
+export type SandboxErrorCode = 'script-error' | 'script-timeout' | 'script-memory';
+export interface SandboxError {
+    readonly code: SandboxErrorCode;
+    readonly message: string;
+    /** Set when the failure is in the script itself (not the prelude) and its position is known. */
+    readonly position?: ScriptPosition;
+}
+export interface SandboxLog {
+    /** The text `log(...)` produced, capped (`SCRIPT_LIMITS.logBytes` / `logLines`). */
+    readonly lines: readonly string[];
+    /** True when lines were dropped or cut short to keep within the caps. */
+    readonly truncated: boolean;
+}
+export type SandboxResult = {
+    readonly ok: true;
+    readonly output: unknown;
+    readonly log: SandboxLog;
+} | {
+    readonly ok: false;
+    readonly error: SandboxError;
+    readonly log: SandboxLog;
+    readonly output?: unknown;
+};

package/dist/script/sandbox/model.js

@@ -0,0 +1,24 @@
+/**
+ * What a script run in the sandbox is given and what it hands back (ADR-0016).
+ *
+ * A job is plain data: the code to run, the prelude that installs the API over the host functions,
+ * the JSON the API reads (`input`) and the run's limits. The result is plain data too. Nothing
+ * crosses the boundary but strings and JSON-shaped values.
+ */
+/** The limits every script run is held to (spec §Sandbox). */
+export const SCRIPT_LIMITS = {
+    /** The default time one script may run, in milliseconds. */
+    defaultTimeoutMs: 1_000,
+    /** The most a request file may allow (`scripts.timeoutMs`). */
+    maxTimeoutMs: 10_000,
+    /** How long past its deadline the host waits before it terminates and replaces the worker. */
+    backstopMs: 1_000,
+    memoryBytes: 64 * 1024 * 1024,
+    stackBytes: 1024 * 1024,
+    logBytes: 64 * 1024,
+    logLines: 1_000,
+    /** The largest result (`__finish()`'s JSON) a script may hand back. */
+    outputBytes: 16 * 1024 * 1024,
+    /** The largest script file (spec §Storage). */
+    fileBytes: 256 * 1024,
+};

package/dist/script/sandbox/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/script/sandbox/worker.js

@@ -0,0 +1,20 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createScriptSandbox}. It loads the
+ * QuickJS WebAssembly module once, then runs each job it is sent (`{ id, job }`) in a fresh runtime,
+ * one at a time, and answers `{ id, result, recycle }`.
+ */
+import { parentPort } from 'node:worker_threads';
+import { newQuickJSWASMModuleFromVariant } from 'quickjs-emscripten-core';
+import { executeJob } from './execute.js';
+/* v8 ignore start -- runs only inside a real worker thread; covered end to end by sandbox.test.ts,
+   which coverage instrumentation does not follow across the thread. */
+if (parentPort !== null) {
+    const port = parentPort;
+    // Messages that arrive while the module loads wait in the port until the listener is attached.
+    const module = await newQuickJSWASMModuleFromVariant(import('@jitl/quickjs-wasmfile-release-sync'));
+    port.on('message', ({ id, job }) => {
+        const { result, recycle } = executeJob(module, job);
+        port.postMessage({ id, result, recycle });
+    });
+}
+/* v8 ignore stop */

package/dist/script/send.d.ts

@@ -0,0 +1,27 @@
+import type { KeyValueEntry } from '../http/entries.js';
+import { type GetSecret } from '../secrets/resolve.js';
+import type { HeaderPair } from './model.js';
+/** The placeholders one send's secrets stand behind until its pre-request script has run. */
+export declare class SecretPlaceholders {
+    private readonly nonce;
+    private readonly byName;
+    /** The placeholder for `name`, the same one every time within this send. */
+    placeholderFor(name: string): string;
+    /** A `secrets` scope that maps each name to its placeholder, for the given names. */
+    scopeFor(names: Iterable<string>): Record<string, string>;
+    get size(): number;
+    /** True when `text` holds one of this send's placeholders: a secret whose value is not in yet. */
+    holds(text: string): boolean;
+    /**
+     * `value` with every placeholder replaced by its secret's value, in every string it holds.
+     *
+     * @throws WirebenchError `secret-missing` when a secret cannot be read
+     */
+    restore<T>(value: T, getSecret: GetSecret): Promise<T>;
+}
+/** The enabled rows of a key-value table as header pairs, in order. */
+export declare const pairsOf: (entries: readonly KeyValueEntry[]) => HeaderPair[];
+/** Header pairs as enabled key-value rows. */
+export declare const entriesOf: (pairs: readonly HeaderPair[]) => KeyValueEntry[];
+/** A record's entries as header pairs. */
+export declare const recordPairs: (record: Readonly<Record<string, string>> | undefined) => HeaderPair[];

package/dist/script/send.js

@@ -0,0 +1,76 @@
+/**
+ * Between a prepared send and the script API (spec §What a pre-request script can change, §Secrets).
+ *
+ * A request with scripts is prepared with every `${secret:…}` in its text replaced by an
+ * unguessable placeholder, so a script sees neither the value nor text it could turn into a
+ * reference. After the script, the host puts each placeholder back as the secret's value — secrets
+ * are substituted raw by every expander, so the value lands exactly as it would have. A placeholder
+ * is alphanumeric, so no escaping along the way changes it, and a value a server chose can never
+ * name one: the nonce is new for every send.
+ *
+ * Each protocol's converters between a prepared send and the snapshot a script sees live in its
+ * own folder (`<protocol>/scripting.ts`); the helpers at the end of this file are what they share.
+ */
+import { randomUUID } from 'node:crypto';
+import { resolveSecretTokens } from '../secrets/resolve.js';
+/** The placeholders one send's secrets stand behind until its pre-request script has run. */
+export class SecretPlaceholders {
+    nonce = randomUUID().replace(/-/g, '');
+    byName = new Map();
+    /** The placeholder for `name`, the same one every time within this send. */
+    placeholderFor(name) {
+        let placeholder = this.byName.get(name);
+        if (placeholder === undefined) {
+            placeholder = `wbsec${this.nonce}n${String(this.byName.size)}z`;
+            this.byName.set(name, placeholder);
+        }
+        return placeholder;
+    }
+    /** A `secrets` scope that maps each name to its placeholder, for the given names. */
+    scopeFor(names) {
+        const out = {};
+        for (const name of names)
+            out[name] = this.placeholderFor(name);
+        return out;
+    }
+    get size() {
+        return this.byName.size;
+    }
+    /** True when `text` holds one of this send's placeholders: a secret whose value is not in yet. */
+    holds(text) {
+        for (const placeholder of this.byName.values()) {
+            if (text.includes(placeholder))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * `value` with every placeholder replaced by its secret's value, in every string it holds.
+     *
+     * @throws WirebenchError `secret-missing` when a secret cannot be read
+     */
+    async restore(value, getSecret) {
+        if (this.byName.size === 0)
+            return value;
+        const secrets = await resolveSecretTokens(this.byName.keys(), getSecret);
+        const replacements = new Map([...this.byName].map(([name, placeholder]) => [placeholder, secrets[name] ?? '']));
+        const pattern = new RegExp([...replacements.keys()].join('|'), 'g');
+        const walk = (node) => {
+            if (typeof node === 'string')
+                return node.replace(pattern, (hit) => replacements.get(hit) ?? hit);
+            if (Array.isArray(node))
+                return node.map(walk);
+            if (node !== null && typeof node === 'object') {
+                return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]));
+            }
+            return node;
+        };
+        return walk(value);
+    }
+}
+/** The enabled rows of a key-value table as header pairs, in order. */
+export const pairsOf = (entries) => entries.filter((e) => e.enabled).map((e) => [e.name, e.value]);
+/** Header pairs as enabled key-value rows. */
+export const entriesOf = (pairs) => pairs.map(([name, value]) => ({ name, value, enabled: true }));
+/** A record's entries as header pairs. */
+export const recordPairs = (record) => Object.entries(record ?? {}).map(([name, value]) => [name, value]);

package/dist/script/strip.d.ts

@@ -0,0 +1,5 @@
+/** Thrown when the script is not valid erasable TypeScript; carries Node's message. */
+export declare class StripError extends Error {
+}
+/** The script with its types erased, positions unchanged. */
+export declare function stripTypes(source: string): string;

package/dist/script/strip.js

@@ -0,0 +1,43 @@
+/**
+ * Turns a TypeScript script into the JavaScript the sandbox runs, by erasing its types.
+ *
+ * Node's `module.stripTypeScriptTypes` in `strip` mode replaces every type annotation with
+ * whitespace, so each remaining character keeps its line and column and a run-time error points at
+ * the right place in the file. It handles erasable syntax only; the checker (`erasableSyntaxOnly`)
+ * refuses the rest before a script gets here.
+ *
+ * Node 24 still marks the function experimental and warns on its first use. That one warning is
+ * silenced here; any other warning goes through untouched. A test pins the output of a fixture, so a
+ * change in a later Node shows up in CI.
+ */
+import { stripTypeScriptTypes } from 'node:module';
+let warningSilenced = false;
+function silenceStripWarning() {
+    if (warningSilenced) {
+        return;
+    }
+    warningSilenced = true;
+    const emit = process.emitWarning.bind(process);
+    process.emitWarning = (warning, ...rest) => {
+        const text = typeof warning === 'string' ? warning : warning.message;
+        const type = typeof rest[0] === 'string' ? rest[0] : rest[0]?.type;
+        if ((type === 'ExperimentalWarning' || (warning instanceof Error && warning.name === 'ExperimentalWarning')) &&
+            text.includes('stripTypeScriptTypes')) {
+            return;
+        }
+        emit(warning, ...rest);
+    };
+}
+/** Thrown when the script is not valid erasable TypeScript; carries Node's message. */
+export class StripError extends Error {
+}
+/** The script with its types erased, positions unchanged. */
+export function stripTypes(source) {
+    silenceStripWarning();
+    try {
+        return stripTypeScriptTypes(source, { mode: 'strip' });
+    }
+    catch (error) {
+        throw new StripError(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/script/types/api.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The static half of a script's types (spec §API): the declarations every script has, followed by
+ * the ones its protocol's scripting facet supplies for the phase. Those refer to aliases the
+ * generated half defines from the request's contract (`<protocol>/script-types.ts`), and to
+ * `WbSecretName`.
+ *
+ * A script is a global script, not a module: these are ambient declarations, one file per script.
+ */
+import type { ProtocolScripting } from '../../protocol/module.js';
+import type { ProtocolRegistry } from '../../protocol/registry.js';
+import type { ScriptPhase } from '../model.js';
+/**
+ * The API's declarations for one protocol and phase. `scripting` is the protocol's facet, or its
+ * `kind`, looked up in `registry` (the built-in one when absent).
+ *
+ * @throws WirebenchError `script-unsupported` when a `kind` has no scripting facet
+ */
+export declare function apiDeclarations(scripting: ProtocolScripting | string, phase: ScriptPhase, registry?: ProtocolRegistry): string;
+/**
+ * Everything a script is checked against: the API, its secret names, and the request's generated types.
+ *
+ * @throws WirebenchError `script-unsupported` when a `kind` has no scripting facet
+ */
+export declare function scriptDeclarations(scripting: ProtocolScripting | string, phase: ScriptPhase, secrets: readonly string[], generated: string, registry?: ProtocolRegistry): string;
+/** `type WbSecretName = ...` for the secrets a request lists (`never` when it lists none). */
+export declare function secretNameType(secrets: readonly string[]): string;
+/** One section of the published API reference: a heading and the declarations it shows. */
+export interface ApiReferenceSection {
+    readonly title: string;
+    readonly declarations: string;
+}
+/**
+ * The API's declarations as the docs site's reference shows them (`pnpm docs:script-api`): what
+ * every script has, then the sections of each protocol in `registry` that has a scripting facet.
+ * Protocols are ordered by title, not by registration, so the page does not depend on the order a
+ * host composed its modules in. The status literal types are described rather than listed.
+ */
+export declare function apiReference(registry?: ProtocolRegistry): readonly ApiReferenceSection[];