@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/run/send-helpers.js

@@ -0,0 +1,255 @@
+/**
+ * What the protocol modules share when they prepare and send a request in a run: secret tokens,
+ * the project-folder boundary, keystores and TLS, OAuth2 tokens, the base URL an environment
+ * overrides, and the secret a keystore needs. Core code: it names no protocol.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { WirebenchError } from '../errors.js';
+import { isInsideRealDir } from '../fs.js';
+import { resolveApiBaseUrl } from '../project/environments.js';
+import { toKeystoreDef } from '../project/keystores.js';
+import { secretNamesIn } from '../project/properties.js';
+import { urlOrigin } from '../project/sequence-guards.js';
+import { resolveAuthConfig, resolveSecretTokens } from '../secrets/resolve.js';
+import { resolveWorkspaceApiBaseUrl, withActiveEnvironment } from '../workspace/environments.js';
+import { loadKeystore, toTlsClientIdentity } from '../keystore/index.js';
+import { scopesFor } from './context.js';
+import { createRunTokenSource, requiredSecret } from './oauth2-token.js';
+/**
+ * The `${secret:name}` names anywhere in `value`'s strings — a send input or a saved request —
+ * following property values through `scopes`, in first-use order. Binary data is skipped.
+ */
+export function secretNamesInValue(value, scopes) {
+    const found = new Set();
+    const visit = (current) => {
+        if (typeof current === 'string') {
+            if (current.includes('${')) {
+                for (const name of secretNamesIn(current, scopes)) {
+                    found.add(name);
+                }
+            }
+        }
+        else if (Array.isArray(current)) {
+            current.forEach(visit);
+        }
+        else if (current !== null && typeof current === 'object' && !ArrayBuffer.isView(current)) {
+            Object.values(current).forEach(visit);
+        }
+    };
+    visit(value);
+    return [...found];
+}
+/**
+ * `scopes` with the value of every `${secret:name}` token `input` reaches. Each value comes from
+ * `getSecret`, so a host that masks what it hands out (the CLI's `createEnvSecrets`) masks these too.
+ */
+export async function withSecrets(input, scopes, getSecret, placeholders) {
+    const names = secretNamesInValue(input, scopes);
+    if (names.length === 0)
+        return scopes;
+    return {
+        ...scopes,
+        secrets: placeholders !== undefined ? placeholders.scopeFor(names) : await resolveSecretTokens(names, getSecret),
+    };
+}
+/**
+ * The refusal for a request whose text holds property references nothing resolves, under the code
+ * its protocol raises (spec §8).
+ */
+export function unresolvedError(code, path, unresolved) {
+    const exprs = unresolved.map((ref) => ref.expr);
+    return new WirebenchError(code, `"${path}" has property references nothing resolves: ${exprs.join(', ')}`, {
+        details: { path, unresolved: exprs },
+    });
+}
+/**
+ * `path` resolved against the project folder, refused when it lands outside it. The app also
+ * accepts a file its user picked through a dialog; a pipeline has no such user, so the project
+ * folder is the whole boundary.
+ */
+export async function insideProject(context, path, code, name) {
+    const resolved = resolvePath(context.projectDir, path);
+    if (!(await isInsideRealDir(context.projectDir, resolved))) {
+        throw new WirebenchError(code, `"${name}" resolves outside the project folder.`, { details: { path } });
+    }
+    return resolved;
+}
+/**
+ * Mirrors the app's keystore loading, minus its cache and its picked files: a run loads each keystore
+ * it needs, from inside the project folder. Reached through {@link keystoreFor} only.
+ */
+async function loadKeystoreById(context, keystoreId) {
+    const ref = context.project.wss.keystores.find((candidate) => candidate.id === keystoreId);
+    if (ref === undefined) {
+        return undefined;
+    }
+    const def = toKeystoreDef(ref);
+    const path = await insideProject(context, def.path, 'keystore-outside-project', def.name);
+    try {
+        await stat(path);
+    }
+    catch (error) {
+        throw new WirebenchError('keystore-unreadable', `The keystore file "${def.path}" could not be read.`, {
+            details: { id: def.id },
+            cause: error,
+        });
+    }
+    const password = def.passwordSecretRef === undefined
+        ? undefined
+        : await requiredSecret(def.passwordSecretRef, context.host.getSecret);
+    return loadKeystore(await readFile(path), { type: def.type, ...(password !== undefined ? { password } : {}) });
+}
+/** A keystore by its entry id: through the host's loader when it lends one, else from the project folder. */
+export async function keystoreFor(context, keystoreId) {
+    const { keystoreFor: lent } = context.host;
+    return lent !== undefined ? await lent(keystoreId) : await loadKeystoreById(context, keystoreId);
+}
+/** The `cert`/`key` a request's own keystore presents; there is no global keystore in a run. */
+export async function clientIdentityFor(context, keystoreId) {
+    if (keystoreId === undefined || keystoreId.length === 0) {
+        return undefined;
+    }
+    const keystore = await keystoreFor(context, keystoreId);
+    const def = context.project.wss.keystores.find((candidate) => candidate.id === keystoreId);
+    if (keystore === undefined || def === undefined) {
+        throw new WirebenchError('keystore-missing', 'This request selects a keystore the project no longer has.', {
+            details: { keystoreId },
+        });
+    }
+    const identity = toTlsClientIdentity(keystore, toKeystoreDef(def).defaultAlias);
+    return { cert: identity.cert, key: identity.key };
+}
+/** Identity, then the only two trust opt-outs a run honours: `--insecure` and the file's own flag. */
+export async function tlsFor(context, keystoreId, trustInvalid) {
+    const { tls } = context.host;
+    const identity = tls?.identityFor !== undefined ? await tls.identityFor(keystoreId) : await clientIdentityFor(context, keystoreId);
+    const skipVerify = context.insecure === true || trustInvalid;
+    const anchors = tls?.anchors;
+    if (identity === undefined && !skipVerify && anchors === undefined)
+        return undefined;
+    return {
+        ...(identity !== undefined ? { cert: identity.cert, key: identity.key } : {}),
+        ...(anchors !== undefined ? { ca: [...anchors] } : {}),
+        ...(skipVerify ? { rejectUnauthorized: false } : {}),
+    };
+}
+/** The run's shared token source, or a fresh one for a send outside a run. */
+export function tokenSourceOf(context) {
+    return (context.host.tokens ??
+        createRunTokenSource({
+            getSecret: context.host.getSecret,
+            ...(context.host.onSecretValue !== undefined ? { onSecretValue: context.host.onSecretValue } : {}),
+        }));
+}
+/**
+ * A request's effective auth with its secrets resolved. OAuth2 client credentials obtains a token
+ * (the token request uses the request's own TLS, the proxy for the token URL and the run's
+ * timeout); the authorization-code grant needs a browser a pipeline does not have, and is refused.
+ *
+ * @throws WirebenchError `auth-grant-unsupported` | `secret-missing` | `unresolved-properties` |
+ * `oauth2-token-error` | `oauth2-token-malformed`
+ */
+export async function authFor(configured, path, context, tls) {
+    if (configured.type !== 'oauth2') {
+        return reportedAuth(await resolveAuthConfig(configured, context.host.getSecret), context);
+    }
+    const accessToken = await tokenSourceOf(context).accessTokenFor(configured, {
+        scopes: scopesFor(context),
+        ...(tls !== undefined ? { tls } : {}),
+        ...(context.host.proxyFor !== undefined ? { proxy: context.host.proxyFor } : {}),
+        ...(context.timeoutMs !== undefined ? { timeoutMs: context.timeoutMs } : {}),
+        ...(context.signal !== undefined ? { signal: context.signal } : {}),
+    });
+    return reportedAuth(await resolveAuthConfig(configured, context.host.getSecret, { accessToken }), context);
+}
+/**
+ * Tells the host each credential a resolved auth puts on the wire, in the form it travels there,
+ * so a server that echoes one back has it masked: an API key's value, a bearer or OAuth2 access
+ * token, and Basic's `base64(user:password)`. A password is never reported bare — people choose
+ * them, so one is often ordinary text — and NTLM's password never travels at all.
+ */
+export function reportedAuth(auth, context) {
+    const report = context.host.onSecretValue;
+    if (report === undefined || auth === undefined)
+        return auth;
+    switch (auth.type) {
+        case 'api-key':
+            report(auth.value);
+            break;
+        case 'bearer':
+            report(auth.token);
+            break;
+        case 'oauth2':
+            report(auth.accessToken);
+            break;
+        case 'basic':
+            report(Buffer.from(`${auth.username}:${auth.password}`, 'utf-8').toString('base64'));
+            break;
+        default:
+            break;
+    }
+    return auth;
+}
+/**
+ * An API's base URL (or target) and where it came from, through the workspace's environment when
+ * the run has a workspace: what a preview reports beside the URL.
+ */
+export function resolvedBaseUrl(context, api) {
+    const { project, environmentId, workspace } = context;
+    return workspace === undefined
+        ? resolveApiBaseUrl(project, environmentId, api)
+        : resolveWorkspaceApiBaseUrl({
+            workspace: withActiveEnvironment(workspace.workspace, environmentId),
+            project,
+            projectSlug: workspace.projectSlug,
+            api,
+        });
+}
+/** An API's base URL (or target), through the workspace's environment likewise. */
+export function baseUrlFor(context, api) {
+    return resolvedBaseUrl(context, api).url;
+}
+/**
+ * After a server refused the credentials a send carried, drops the run's OAuth2 token among them,
+ * so the next request behind that configuration fetches a new one instead of repeating the refusal.
+ * The refused request itself is never sent again.
+ */
+export function dropRefusedToken(context, auth, refused) {
+    if (refused && auth?.type === 'oauth2') {
+        context.host.tokens?.reject(auth.accessToken);
+    }
+}
+/** The origin a request went to, as a sent request reports it; nothing for a URL without one. */
+export function originOf(url) {
+    const origin = urlOrigin(url);
+    return origin !== undefined ? { origin } : {};
+}
+/** True for a reference that is set: neither absent nor empty. */
+export const present = (id) => id !== undefined && id.length > 0;
+/** A keystore's password, when the registry entry has one; an unreadable entry needs nothing here. */
+export function keystoreNeeds(project, keystoreId) {
+    if (!present(keystoreId)) {
+        return [];
+    }
+    const ref = project.wss.keystores.find((candidate) => candidate.id === keystoreId);
+    if (ref === undefined) {
+        return [];
+    }
+    try {
+        const def = toKeystoreDef(ref);
+        return present(def.passwordSecretRef)
+            ? [
+                {
+                    ref: def.passwordSecretRef,
+                    ...(def.passwordEnv !== undefined ? { envName: def.passwordEnv } : {}),
+                    purpose: `keystore password for "${def.name}"`,
+                },
+            ]
+            : [];
+    }
+    catch {
+        // The module's send refuses such a request with its own error; it needs no secret before then.
+        return [];
+    }
+}

package/dist/run/tree.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Walking a container's tree of folders and requests, as the REST, gRPC and WebSocket modules all
+ * keep one. Core code: it names no protocol.
+ */
+/** Explorer order: by `order`, then by name. */
+export declare const byOrder: <T extends {
+    readonly order: number;
+    readonly name: string;
+}>(a: T, b: T) => number;
+/** Why a request its contract no longer has cannot be a sequence step. */
+export declare const ORPHANED_STEP_REASON = "The request is no longer in its contract (orphaned)";
+/** What a tree's request has, as far as the walk cares. */
+export interface TreeRequest {
+    readonly order: number;
+    readonly name: string;
+    readonly slug: string;
+}
+/** What a tree's folder has, as far as the walk cares. */
+export interface TreeFolder<F, R> {
+    readonly order: number;
+    readonly name: string;
+    readonly slug: string;
+    readonly folders: readonly F[];
+    readonly requests: readonly R[];
+}
+/**
+ * Walks a request tree in explorer order. `make` turns a request the protocol can run into its
+ * selection, or answers `undefined` for one it skips (orphaned, streaming). Each selection is pushed
+ * to `out` with the request's path on disk, without the `.request.yaml` suffix.
+ */
+export declare function walkTree<F extends TreeFolder<F, R>, R extends TreeRequest, S>(node: {
+    readonly folders: readonly F[];
+    readonly requests: readonly R[];
+}, chain: readonly F[], group: string, diskDir: string, make: (request: R, chain: readonly F[], group: string) => S | undefined, out: {
+    item: S;
+    diskPath: string;
+}[]): void;
+/** A tree of folders and requests, as far as a lookup by id cares. */
+export interface RequestTree<R extends {
+    readonly id: string;
+} = {
+    readonly id: string;
+}> {
+    readonly folders: readonly RequestTree<R>[];
+    readonly requests: readonly R[];
+}
+/** The request with `id` anywhere in `tree`, depth-first. */
+export declare function findInTree<R extends {
+    readonly id: string;
+}>(tree: RequestTree<R>, id: string): R | undefined;

package/dist/run/tree.js

@@ -0,0 +1,54 @@
+/**
+ * Walking a container's tree of folders and requests, as the REST, gRPC and WebSocket modules all
+ * keep one. Core code: it names no protocol.
+ */
+/** Explorer order: by `order`, then by name. */
+export const byOrder = (a, b) => a.order - b.order || a.name.localeCompare(b.name);
+/** Why a request its contract no longer has cannot be a sequence step. */
+export const ORPHANED_STEP_REASON = 'The request is no longer in its contract (orphaned)';
+/**
+ * Walks a request tree in explorer order. `make` turns a request the protocol can run into its
+ * selection, or answers `undefined` for one it skips (orphaned, streaming). Each selection is pushed
+ * to `out` with the request's path on disk, without the `.request.yaml` suffix.
+ */
+export function walkTree(node, chain, group, diskDir, make, out) {
+    const children = [
+        ...node.requests.map((request) => ({
+            tag: 'request',
+            order: request.order,
+            name: request.name,
+            request,
+        })),
+        ...node.folders.map((folder) => ({
+            tag: 'folder',
+            order: folder.order,
+            name: folder.name,
+            folder,
+        })),
+    ].sort(byOrder);
+    for (const child of children) {
+        if (child.tag === 'request') {
+            const item = make(child.request, chain, group);
+            if (item !== undefined) {
+                out.push({ item, diskPath: `${diskDir}/${child.request.slug}` });
+            }
+        }
+        else {
+            walkTree(child.folder, [...chain, child.folder], `${group}/${child.folder.name}`, `${diskDir}/${child.folder.slug}`, make, out);
+        }
+    }
+}
+/** The request with `id` anywhere in `tree`, depth-first. */
+export function findInTree(tree, id) {
+    const own = tree.requests.find((request) => request.id === id);
+    if (own !== undefined) {
+        return own;
+    }
+    for (const folder of tree.folders) {
+        const found = findInTree(folder, id);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The Postman layer (spec §Postman): `pm`, `postman`, `CryptoJS`, `btoa` and `atob`, as JavaScript
+ * that runs inside the sandbox after the API and before an imported script. It is written over the
+ * same API a typed script uses — `vars`, `props`, `test`, `request`, `response`, `crypto`,
+ * `encoding` — so it can do nothing a typed script cannot.
+ *
+ * It covers what imported collections mostly use. Anything else throws `ScriptUnsupported` naming
+ * the call, which the host reports as `script-unsupported`.
+ */
+export declare const POSTMAN_LAYER: string;

package/dist/script/api/postman.js

@@ -0,0 +1,264 @@
+/**
+ * The Postman layer (spec §Postman): `pm`, `postman`, `CryptoJS`, `btoa` and `atob`, as JavaScript
+ * that runs inside the sandbox after the API and before an imported script. It is written over the
+ * same API a typed script uses — `vars`, `props`, `test`, `request`, `response`, `crypto`,
+ * `encoding` — so it can do nothing a typed script cannot.
+ *
+ * It covers what imported collections mostly use. Anything else throws `ScriptUnsupported` naming
+ * the call, which the host reports as `script-unsupported`.
+ */
+export const POSTMAN_LAYER = String.raw `
+const unsupported = (name) => () => {
+  throw new ScriptUnsupported(name + ' is not supported: a script cannot send requests, keep cookies or control the run');
+};
+
+const asValue = (value) => (value === undefined || value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : value);
+const variables = Object.freeze({
+  get: (name) => { const v = vars.get(name); return v !== undefined ? v : props.get(name); },
+  set: (name, value) => vars.set(name, asValue(value)),
+  unset: (name) => vars.set(name, ''),
+  has: (name) => vars.get(name) !== undefined || props.get(name) !== undefined,
+  clear: unsupported('Clearing variables'),
+  toObject: () => ({}),
+  replaceIn: (text) => String(text).replace(/\{\{\s*([^{}]*?)\s*\}\}/g, (whole, name) => {
+    const v = variables.get(name);
+    return v === undefined ? whole : String(v);
+  }),
+});
+
+// --- expect: the chai chains collections use ---------------------------------------------------
+const typeName = (value) => {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (value instanceof RegExp) return 'regexp';
+  return typeof value;
+};
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const chain = (actual, flags) => {
+  const assert = (passed, message) => {
+    if (passed === flags.not) throw new ExpectationFailed('expected ' + show(actual) + (flags.not ? ' not ' : ' ') + message);
+    return self;
+  };
+  const self = {};
+  const word = (name) => Object.defineProperty(self, name, { get: () => self });
+  for (const w of ['to', 'be', 'been', 'is', 'that', 'which', 'and', 'has', 'have', 'with', 'at', 'of', 'same', 'but', 'does', 'still', 'also']) word(w);
+  Object.defineProperty(self, 'not', { get: () => chain(actual, { ...flags, not: !flags.not }) });
+  Object.defineProperty(self, 'deep', { get: () => chain(actual, { ...flags, deep: true }) });
+  const equal = (expected) => assert(flags.deep ? same(actual, expected) : Object.is(actual, expected), 'to equal ' + show(expected));
+  self.equal = self.equals = self.eq = equal;
+  self.eql = self.eqls = (expected) => assert(same(actual, expected), 'to deeply equal ' + show(expected));
+  self.a = self.an = (type) => assert(typeName(actual) === String(type).toLowerCase(), 'to be a ' + type);
+  self.include = self.includes = self.contain = self.contains = (item) => assert(
+    typeof actual === 'string' ? actual.includes(String(item))
+      : Array.isArray(actual) ? actual.some((x) => (flags.deep ? same(x, item) : Object.is(x, item)))
+      : actual !== null && typeof actual === 'object' && item !== null && typeof item === 'object'
+        ? Object.keys(item).every((k) => same(actual[k], item[k]))
+        : false,
+    'to include ' + show(item));
+  self.property = (name, ...value) => {
+    const has = actual !== null && actual !== undefined && typeof actual === 'object' && name in actual;
+    assert(has && (value.length === 0 || same(actual[name], value[0])), 'to have property ' + name + (value.length === 0 ? '' : ' of ' + show(value[0])));
+    return has && !flags.not ? chain(actual[name], {}) : self;
+  };
+  self.above = self.gt = self.greaterThan = (n) => assert(actual > n, 'to be above ' + n);
+  self.below = self.lt = self.lessThan = (n) => assert(actual < n, 'to be below ' + n);
+  self.least = self.gte = (n) => assert(actual >= n, 'to be at least ' + n);
+  self.most = self.lte = (n) => assert(actual <= n, 'to be at most ' + n);
+  self.within = (lo, hi) => assert(actual >= lo && actual <= hi, 'to be within ' + lo + '..' + hi);
+  self.lengthOf = (n) => assert(actual !== null && actual !== undefined && actual.length === n, 'to have length ' + n);
+  self.oneOf = (list) => assert(list.some((x) => same(x, actual)), 'to be one of ' + show(list));
+  self.match = self.matches = (re) => assert(re instanceof RegExp && re.test(String(actual)), 'to match ' + String(re));
+  self.string = (text) => assert(typeof actual === 'string' && actual.includes(text), 'to contain ' + show(text));
+  self.keys = self.key = (...names) => {
+    const list = names.length === 1 && Array.isArray(names[0]) ? names[0] : names;
+    return assert(actual !== null && typeof actual === 'object' && list.every((k) => k in actual), 'to have keys ' + show(list));
+  };
+  const getter = (name, test, message) => Object.defineProperty(self, name, { get: () => assert(test(), message) });
+  getter('true', () => actual === true, 'to be true');
+  getter('false', () => actual === false, 'to be false');
+  getter('ok', () => Boolean(actual), 'to be ok');
+  getter('null', () => actual === null, 'to be null');
+  getter('undefined', () => actual === undefined, 'to be undefined');
+  getter('exist', () => actual !== null && actual !== undefined, 'to exist');
+  getter('empty', () => (typeof actual === 'string' || Array.isArray(actual) ? actual.length === 0 : actual !== null && typeof actual === 'object' ? Object.keys(actual).length === 0 : false), 'to be empty');
+  getter('NaN', () => Number.isNaN(actual), 'to be NaN');
+  self.length = (n) => self.lengthOf(n);
+  return self;
+};
+const pmExpect = (actual) => chain(actual, { not: false, deep: false });
+
+// --- pm.request / pm.response ------------------------------------------------------------------
+const pairs = (list) => Object.freeze({
+  get: (name) => list.get(name),
+  has: (name, value) => (value === undefined ? list.has(name) : list.get(name) === String(value)),
+  toObject: () => list.toObject(),
+  all: () => list.list().map((h) => ({ key: h.name, value: h.value })),
+  each: (fn) => list.list().forEach((h) => fn({ key: h.name, value: h.value })),
+});
+
+const pmRequest = () => {
+  const writable = input.phase === 'pre';
+  const headers = {
+    ...pairs(request.headers),
+    add: (header) => request.headers.add(String(header.key), String(header.value)),
+    upsert: (header) => request.headers.set(String(header.key), String(header.value)),
+    remove: (name) => request.headers.delete(typeof name === 'object' ? String(name.key) : String(name)),
+  };
+  const body = {};
+  if (request.body !== undefined && typeof request.body === 'object' && 'text' in request.body) {
+    Object.defineProperty(body, 'raw', {
+      get: () => (request.body.kind === 'other' ? undefined : request.body.text),
+      set: (text) => { request.body.text = String(text); },
+    });
+    Object.defineProperty(body, 'mode', { get: () => (request.body.kind === 'text' ? 'raw' : request.body.kind) });
+  }
+  const url = {
+    toString: () => String(request.url),
+    getHost: () => /^[a-z]+:\/\/([^/?#:]+)/i.exec(String(request.url))?.[1] ?? '',
+    getPath: () => /^[a-z]+:\/\/[^/?#]*([^?#]*)/i.exec(String(request.url))?.[1] ?? '',
+    query: request.query === undefined ? undefined : {
+      get: (name) => request.query.get(name),
+      add: (q) => request.query.add(String(q.key), String(q.value)),
+      upsert: (q) => request.query.set(String(q.key), String(q.value)),
+      remove: (name) => request.query.delete(String(name)),
+      toObject: () => Object.fromEntries(request.query.list().map((q) => [q.name, q.value])),
+    },
+  };
+  return {
+    get method() { return request.method; },
+    set method(value) { if (writable) request.method = String(value); },
+    url,
+    headers,
+    body,
+  };
+};
+
+const pmResponse = () => {
+  if (input.phase !== 'post') return undefined;
+  const status = response.status;
+  const code = typeof status === 'number' ? status : status.code;
+  const text = response.text !== undefined ? response.text : response.message === undefined ? '' : JSON.stringify(response.message);
+  const res = {
+    code,
+    status: response.statusText !== undefined ? response.statusText : String(code),
+    headers: pairs(response.headers !== undefined ? response.headers : response.metadata),
+    responseTime: response.durationMs,
+    responseSize: text.length,
+    json: () => (response.json !== undefined ? response.json() : JSON.parse(text)),
+    text: () => text,
+  };
+  const has = {
+    status: (expected) => {
+      const passed = typeof expected === 'number' ? code === expected : res.status === String(expected);
+      if (!passed) throw new ExpectationFailed('expected response to have status ' + show(expected) + ' but got ' + code);
+    },
+    header: (name, value) => {
+      const actual = res.headers.get(name);
+      if (actual === undefined || (value !== undefined && actual !== String(value))) {
+        throw new ExpectationFailed('expected response to have header ' + name + (value === undefined ? '' : ' with value ' + show(value)));
+      }
+    },
+    body: (value) => {
+      if (value !== undefined && text !== String(value)) throw new ExpectationFailed('expected response body to be ' + show(value));
+    },
+    jsonBody: (path) => {
+      const body = res.json();
+      if (path !== undefined && !(String(path).split('.').reduce((o, k) => (o !== null && typeof o === 'object' && k in o ? o[k] : undefined), body) !== undefined)) {
+        throw new ExpectationFailed('expected response JSON to have ' + path);
+      }
+    },
+  };
+  const be = {
+    get ok() { if (code < 200 || code > 299) throw new ExpectationFailed('expected a 2xx response but got ' + code); return undefined; },
+    get success() { return be.ok; },
+    get clientError() { if (code < 400 || code > 499) throw new ExpectationFailed('expected a 4xx response but got ' + code); return undefined; },
+    get serverError() { if (code < 500 || code > 599) throw new ExpectationFailed('expected a 5xx response but got ' + code); return undefined; },
+    get error() { if (code < 400) throw new ExpectationFailed('expected an error response but got ' + code); return undefined; },
+    get notFound() { if (code !== 404) throw new ExpectationFailed('expected 404 but got ' + code); return undefined; },
+    get json() { res.json(); return undefined; },
+  };
+  res.to = { have: has, be };
+  return res;
+};
+
+// --- CryptoJS: hashes, HMACs and the encoders, over crypto and encoding --------------------------
+const Hex = { name: 'hex' };
+const Base64 = {
+  name: 'base64',
+  stringify: (words) => words.toString(Base64),
+  parse: (text) => words({ utf8: encoding.fromBase64(String(text)) }),
+};
+const Utf8 = {
+  name: 'utf8',
+  stringify: (w) => w.toString(Utf8),
+  parse: (text) => words({ utf8: String(text) }),
+};
+const Latin1 = Utf8;
+const words = (source) => ({
+  toString(encoder) {
+    const target = encoder === undefined ? Hex : encoder;
+    if (source.utf8 !== undefined) {
+      if (target === Base64) return encoding.base64(source.utf8);
+      if (target === Utf8) return source.utf8;
+      throw new ScriptUnsupported('CryptoJS: hex of a text word array');
+    }
+    if (target === Utf8) throw new ScriptUnsupported('CryptoJS: a hash as UTF-8 text');
+    return source.digest(target === Base64 ? 'base64' : 'hex');
+  },
+});
+const text = (value) => (value !== null && typeof value === 'object' && typeof value.toString === 'function' ? value.toString(Utf8) : String(value));
+const hashOf = (algorithm) => (data) => words({ digest: (enc) => crypto.hash(algorithm, text(data), enc) });
+const hmacOf = (algorithm) => (data, key) => words({ digest: (enc) => crypto.hmac(algorithm, text(key), text(data), enc) });
+const CryptoJS = Object.freeze({
+  MD5: hashOf('md5'),
+  SHA1: hashOf('sha1'),
+  SHA256: hashOf('sha256'),
+  SHA512: hashOf('sha512'),
+  HmacSHA1: hmacOf('sha1'),
+  HmacSHA256: hmacOf('sha256'),
+  HmacSHA512: hmacOf('sha512'),
+  enc: Object.freeze({ Hex, Base64, Utf8, Latin1 }),
+  AES: Object.freeze({ encrypt: unsupported('CryptoJS.AES'), decrypt: unsupported('CryptoJS.AES') }),
+});
+
+// --- pm, postman and the globals -----------------------------------------------------------------
+const pmObject = {
+  test: (name, check) => test(name, () => check()),
+  expect: pmExpect,
+  environment: variables,
+  collectionVariables: variables,
+  globals: variables,
+  variables,
+  info: Object.freeze({
+    requestName: input.info.requestName,
+    eventName: input.phase === 'pre' ? 'prerequest' : 'test',
+    iteration: 0,
+    iterationCount: 1,
+  }),
+  request: pmRequest(),
+  sendRequest: unsupported('pm.sendRequest'),
+  cookies: Object.freeze({ get: () => undefined, has: () => false, toObject: () => ({}), jar: unsupported('pm.cookies.jar') }),
+  visualizer: Object.freeze({ set: unsupported('pm.visualizer') }),
+  execution: Object.freeze({ setNextRequest: unsupported('pm.execution.setNextRequest'), skipRequest: unsupported('pm.execution.skipRequest') }),
+  iterationData: Object.freeze({ get: unsupported('pm.iterationData') }),
+  vault: Object.freeze({ get: unsupported('pm.vault') }),
+  require: unsupported('pm.require'),
+};
+const pmResponseValue = pmResponse();
+if (pmResponseValue !== undefined) pmObject.response = pmResponseValue;
+define('pm', Object.freeze(pmObject));
+define('postman', Object.freeze({
+  setNextRequest: unsupported('postman.setNextRequest'),
+  setEnvironmentVariable: (name, value) => variables.set(name, value),
+  getEnvironmentVariable: (name) => variables.get(name),
+  setGlobalVariable: (name, value) => variables.set(name, value),
+  getGlobalVariable: (name) => variables.get(name),
+  clearEnvironmentVariable: (name) => variables.unset(name),
+}));
+define('CryptoJS', CryptoJS);
+define('btoa', (value) => encoding.base64(String(value)));
+define('atob', (value) => encoding.fromBase64(String(value)));
+define('require', unsupported('require'));
+define('tests', {});
+define('responseCode', pmResponseValue === undefined ? undefined : { code: pmResponseValue.code });
+`;

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

@@ -0,0 +1,20 @@
+/**
+ * The script API, as JavaScript that runs inside the sandbox before the script (spec §API).
+ *
+ * It is built over `__host` (plain functions of strings) and `__host.inputJson` (the request, the
+ * response and the run's values as JSON). It defines the globals a script uses and `__finish()`,
+ * which hands back the tests, the values and — for a pre-request script — the changed request. The
+ * host checks everything `__finish` returns (`../apply.ts`, `../run.ts`): a script can call
+ * `__finish` or `__host` itself, and gains nothing by it.
+ *
+ * Errors a rule raises carry a name the host maps to a code: `ScriptSecretDenied` →
+ * `script-secret-denied`, `ScriptValueInvalid` → `script-value-invalid`, `ScriptUnsupported` →
+ * `script-unsupported`.
+ */
+import type { ProtocolScripting } from '../../protocol/module.js';
+import type { ScriptApi, ScriptPhase } from '../model.js';
+/**
+ * The prelude for one script: the common API, the protocol's `request`/`response` from its
+ * scripting facet, any extra layer and `__finish`.
+ */
+export declare function buildPrelude(scripting: ProtocolScripting, phase: ScriptPhase, api: ScriptApi, layer?: string): string;