@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/script/types/api.js

@@ -0,0 +1,113 @@
+import { defaultRegistry } from '../../protocols.js';
+import { requireScripting } from '../lookup.js';
+const COMMON = `
+/** A case-insensitive list of headers (or gRPC metadata), in order. Names may repeat. */
+interface WbPairs {
+  get(name: string): string | undefined;
+  getAll(name: string): string[];
+  has(name: string): boolean;
+  list(): { name: string; value: string }[];
+  toObject(): Record<string, string>;
+}
+/** Headers a pre-request script can change. A value may not hold CR, LF or NUL. */
+interface WbWritablePairs extends WbPairs {
+  /** Replaces every entry of that name with one, where the first one was. */
+  set(name: string, value: string): void;
+  add(name: string, value: string): void;
+  delete(name: string): void;
+}
+
+interface WbExpectation<T> {
+  toBe(expected: T): void;
+  toEqual(expected: T): void;
+  toBeDefined(): void;
+  toBeUndefined(): void;
+  toBeNull(): void;
+  toBeTruthy(): void;
+  toBeFalsy(): void;
+  toContain(item: T extends readonly (infer I)[] ? I : string): void;
+  toMatch(pattern: RegExp | string): void;
+  toBeGreaterThan(value: number): void;
+  toBeLessThan(value: number): void;
+  toHaveLength(length: number): void;
+  toHaveProperty(path: string | readonly string[], value?: unknown): void;
+  readonly not: Omit<WbExpectation<T>, 'not'>;
+}
+
+/** This run's values: set here, read by later requests as \`\${#Sequence#name}\`. */
+declare const vars: {
+  get(name: string): string | undefined;
+  /** A value is used exactly as set: never expanded, always escaped where it lands. */
+  set(name: string, value: string | number | boolean, options?: { secret?: boolean }): void;
+};
+/** Resolved properties. A secret is never returned. */
+declare const props: { get(name: string): string | undefined };
+/** The secrets this request's \`scripts.secrets\` lists, and no others. */
+declare const secrets: { get(name: WbSecretName): string };
+declare const crypto: {
+  hash(algorithm: 'md5' | 'sha1' | 'sha256' | 'sha512', data: string, encoding?: 'hex' | 'base64'): string;
+  hmac(algorithm: 'sha1' | 'sha256' | 'sha512', key: string, data: string, encoding?: 'hex' | 'base64'): string;
+  randomUUID(): string;
+};
+declare const encoding: {
+  base64(text: string): string;
+  fromBase64(text: string): string;
+  base64url(text: string): string;
+  urlEncode(text: string): string;
+};
+declare function log(...values: unknown[]): void;
+declare const console: {
+  log(...values: unknown[]): void;
+  info(...values: unknown[]): void;
+  warn(...values: unknown[]): void;
+  error(...values: unknown[]): void;
+  debug(...values: unknown[]): void;
+};
+/** Records a test; a failed \`expect\` inside it fails the test, and the script goes on. */
+declare function test(name: string, check: () => void): void;
+declare function expect<T>(actual: T): WbExpectation<T>;
+`;
+/**
+ * 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 function apiDeclarations(scripting, phase, registry) {
+    return [COMMON, requireScripting(scripting, registry).declarations(phase)].join('\n');
+}
+/**
+ * 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 function scriptDeclarations(scripting, phase, secrets, generated, registry) {
+    return `${apiDeclarations(scripting, phase, registry)}\n${secretNameType(secrets)}\n${generated}`;
+}
+/** `type WbSecretName = ...` for the secrets a request lists (`never` when it lists none). */
+export function secretNameType(secrets) {
+    const names = secrets.map((name) => JSON.stringify(name));
+    return `type WbSecretName = ${names.length > 0 ? names.join(' | ') : 'never'};\n`;
+}
+/** Orders two protocols' sections by the title of the first, in code-unit order. */
+function byFirstTitle(a, b) {
+    const left = a[0]?.title ?? '';
+    const right = b[0]?.title ?? '';
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * 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 function apiReference(registry = defaultRegistry()) {
+    const perProtocol = registry.modules
+        .map((module) => module.scripting?.reference() ?? [])
+        .filter((sections) => sections.length > 0)
+        .sort(byFirstTitle);
+    return [{ title: 'Every script', declarations: COMMON }, ...perProtocol.flat()].map((section) => ({
+        title: section.title,
+        declarations: section.declarations.trim(),
+    }));
+}

package/dist/script/types/json-schema.d.ts

@@ -0,0 +1,26 @@
+/** A property name as a TypeScript key. */
+export declare function propertyKey(name: string): string;
+/**
+ * Types many schemas into one set of declarations, sharing aliases between them: `typeOf` returns a
+ * type expression, and `declarations()` the alias declarations those expressions use.
+ */
+export declare class JsonSchemaTypes {
+    private readonly prefix;
+    private readonly aliases;
+    private readonly declared;
+    private readonly shared;
+    private size;
+    constructor(prefix?: string);
+    /** Marks the nodes that need an alias: those reached twice, or that reach themselves. */
+    private scan;
+    private children;
+    typeOf(schema: unknown): string;
+    declarations(): string;
+    private expression;
+    private body;
+    private core;
+    /** The type the schema's own `type`, `properties` and `items` say, when they say anything. */
+    private ownType;
+    private arrayType;
+    private objectType;
+}

package/dist/script/types/json-schema.js

@@ -0,0 +1,206 @@
+/** Past these, a node is typed `unknown`. */
+const LIMITS = { depth: 32, aliases: 500, outputChars: 1_000_000 };
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function isSchema(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A property name as a TypeScript key. */
+export function propertyKey(name) {
+    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+/** A JSDoc line for a description, or nothing. `*\/` inside it cannot end the comment. */
+function docComment(description, indent) {
+    if (typeof description !== 'string' || description.trim() === '') {
+        return '';
+    }
+    const text = description.trim().replace(/\*\//g, '*\\/').split(/\r?\n/).join(`\n${indent} * `);
+    return `${indent}/** ${text} */\n`;
+}
+function literal(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function union(parts) {
+    const unique = [...new Set(parts)];
+    if (unique.length === 0)
+        return 'never';
+    if (unique.includes('unknown'))
+        return 'unknown';
+    return unique.length === 1 ? unique[0] : unique.map((p) => (p.includes('=>') ? `(${p})` : p)).join(' | ');
+}
+/**
+ * Types many schemas into one set of declarations, sharing aliases between them: `typeOf` returns a
+ * type expression, and `declarations()` the alias declarations those expressions use.
+ */
+export class JsonSchemaTypes {
+    prefix;
+    aliases = new Map();
+    declared = [];
+    shared = new Set();
+    size = 0;
+    constructor(prefix = 'WbT') {
+        this.prefix = prefix;
+    }
+    /** Marks the nodes that need an alias: those reached twice, or that reach themselves. */
+    scan(root) {
+        const seen = new Set();
+        const onPath = new Set();
+        const visit = (node, depth) => {
+            if (!isSchema(node) || depth > LIMITS.depth)
+                return;
+            if (onPath.has(node) || seen.has(node)) {
+                this.shared.add(node);
+                return;
+            }
+            seen.add(node);
+            onPath.add(node);
+            for (const child of this.children(node))
+                visit(child, depth + 1);
+            onPath.delete(node);
+        };
+        visit(root, 0);
+    }
+    children(node) {
+        const out = [];
+        if (isSchema(node.properties))
+            out.push(...Object.values(node.properties));
+        if (node.items !== undefined)
+            out.push(node.items);
+        if (isSchema(node.additionalProperties))
+            out.push(node.additionalProperties);
+        for (const list of [node.allOf, node.oneOf, node.anyOf])
+            if (Array.isArray(list))
+                out.push(...list);
+        return out;
+    }
+    typeOf(schema) {
+        this.scan(schema);
+        return this.expression(schema, 0);
+    }
+    declarations() {
+        return this.declared.join('');
+    }
+    expression(schema, depth) {
+        if (!isSchema(schema) || depth > LIMITS.depth || this.size > LIMITS.outputChars) {
+            return 'unknown';
+        }
+        const existing = this.aliases.get(schema);
+        if (existing !== undefined)
+            return existing;
+        if (!this.shared.has(schema))
+            return this.body(schema, depth);
+        if (this.aliases.size >= LIMITS.aliases)
+            return 'unknown';
+        const name = `${this.prefix}${String(this.aliases.size + 1)}`;
+        // Named before its body is built, so a cycle back to it refers to the name.
+        this.aliases.set(schema, name);
+        const body = this.body(schema, depth);
+        const declaration = `${docComment(schema.description, '')}type ${name} = ${body};\n`;
+        this.size += declaration.length;
+        this.declared.push(declaration);
+        return name;
+    }
+    body(schema, depth) {
+        if (typeof schema.$ref === 'string') {
+            // A reference the parser could not resolve.
+            return 'unknown';
+        }
+        const nullable = schema.nullable === true || (Array.isArray(schema.type) && schema.type.includes('null'));
+        let type = this.core(schema, depth);
+        if (nullable && type !== 'unknown' && !type.split(' | ').includes('null')) {
+            type = union([type, 'null']);
+        }
+        return type;
+    }
+    core(schema, depth) {
+        if (schema.const !== undefined) {
+            return literal(schema.const) ?? 'unknown';
+        }
+        if (Array.isArray(schema.enum)) {
+            const values = schema.enum.map(literal);
+            return values.every((v) => v !== undefined) ? union(values) : 'unknown';
+        }
+        const parts = [];
+        const own = this.ownType(schema, depth);
+        if (own !== undefined)
+            parts.push(own);
+        if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+            const all = schema.allOf.map((s) => this.expression(s, depth + 1));
+            if (all.includes('unknown'))
+                return 'unknown';
+            parts.push(...all);
+            return parts.length === 1 ? parts[0] : parts.map((p) => (p.includes('|') ? `(${p})` : p)).join(' & ');
+        }
+        for (const alternatives of [schema.oneOf, schema.anyOf]) {
+            if (Array.isArray(alternatives) && alternatives.length > 0) {
+                const choice = union(alternatives.map((s) => this.expression(s, depth + 1)));
+                if (choice === 'unknown')
+                    return 'unknown';
+                return own === undefined ? choice : `${own.includes('|') ? `(${own})` : own} & (${choice})`;
+            }
+        }
+        return own ?? 'unknown';
+    }
+    /** The type the schema's own `type`, `properties` and `items` say, when they say anything. */
+    ownType(schema, depth) {
+        const declared = schema.type === undefined ? [] : Array.isArray(schema.type) ? schema.type : [schema.type];
+        const types = declared.filter((t) => t !== 'null');
+        if (types.length === 0) {
+            if (isSchema(schema.properties) || schema.additionalProperties !== undefined)
+                return this.objectType(schema, depth);
+            if (schema.items !== undefined)
+                return this.arrayType(schema, depth);
+            return declared.includes('null') ? 'null' : undefined;
+        }
+        const mapped = types.map((type) => {
+            switch (type) {
+                case 'string':
+                    return 'string';
+                case 'integer':
+                case 'number':
+                    return 'number';
+                case 'boolean':
+                    return 'boolean';
+                case 'array':
+                    return this.arrayType(schema, depth);
+                case 'object':
+                    return this.objectType(schema, depth);
+                default:
+                    return 'unknown';
+            }
+        });
+        return union(mapped);
+    }
+    arrayType(schema, depth) {
+        const item = schema.items === undefined ? 'unknown' : this.expression(schema.items, depth + 1);
+        return /^[A-Za-z0-9_$]+$/.test(item) ? `${item}[]` : `(${item})[]`;
+    }
+    objectType(schema, depth) {
+        const indent = '  '.repeat(Math.min(depth, 8) + 1);
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const lines = [];
+        if (isSchema(schema.properties)) {
+            for (const [name, property] of Object.entries(schema.properties)) {
+                const optional = required.has(name) ? '' : '?';
+                const doc = isSchema(property) ? docComment(property.description, indent) : '';
+                lines.push(`${doc}${indent}${propertyKey(name)}${optional}: ${this.expression(property, depth + 1)};\n`);
+            }
+        }
+        const extra = schema.additionalProperties;
+        if (extra === true || (extra === undefined && !isSchema(schema.properties))) {
+            lines.push(`${indent}[key: string]: unknown;\n`);
+        }
+        else if (isSchema(extra)) {
+            // Beside declared properties an index signature must admit their types too, so it widens.
+            const value = lines.length > 0 ? 'unknown' : `${this.expression(extra, depth + 1)} | undefined`;
+            lines.push(`${indent}[key: string]: ${value};\n`);
+        }
+        const closing = '  '.repeat(Math.min(depth, 8));
+        return lines.length === 0 ? 'Record<string, never>' : `{\n${lines.join('')}${closing}}`;
+    }
+}

package/dist/secrets/env-names.d.ts

@@ -9,6 +9,12 @@
 import type { AuthConfig, EndpointAuth } from '../project/model.js';
 /** The prefix every secret-carrying environment variable name starts with. */
 export declare const SECRET_ENV_PREFIX = "WIREBENCH_SECRET_";
+/**
+ * The pseudo-ref a webhook signing secret is asked for when its node names only a CI variable
+ * (webhook-signatures §5.2): `webhook-signing:<secretEnv>`. Like a `${secret:name}` token's, its
+ * name is already stable, so only `WIREBENCH_SECRET_<secretEnv>` is read.
+ */
+export declare const SIGNING_PSEUDO_REF_PREFIX = "webhook-signing:";
 /** One secret a run must be given, and the friendlier name the file declares for it, if any. */
 export interface SecretNeed {
     /** The opaque reference in the file. */
@@ -22,6 +28,8 @@ export interface SecretNeed {
 export declare function secretNeedsOfAuth(auth: AuthConfig | EndpointAuth | undefined): SecretNeed[];
 /**
  * The variables a host reads for one secret, in order: the declared name, then the reference
- * itself. The reference form exists so a project nobody has annotated can still run in CI.
+ * itself. The reference form exists so a project nobody has annotated can still run in CI. A
+ * `${secret:name}` token's pseudo-ref has a stable name already, so it is read from
+ * `WIREBENCH_SECRET_<NAME>` alone.
  */
 export declare function envVariablesFor(secret: Pick<SecretNeed, 'ref' | 'envName'>): string[];

package/dist/secrets/env-names.js

@@ -6,8 +6,15 @@
  * friendlier `…Env` name beside the ref — not a secret, safe to commit — and this module is where
  * that name and the ref both turn into the environment variables a headless run is allowed to read.
  */
+import { parseSecretPseudoRef, secretEnvName } from './secret-token.js';
 /** The prefix every secret-carrying environment variable name starts with. */
 export const SECRET_ENV_PREFIX = 'WIREBENCH_SECRET_';
+/**
+ * The pseudo-ref a webhook signing secret is asked for when its node names only a CI variable
+ * (webhook-signatures §5.2): `webhook-signing:<secretEnv>`. Like a `${secret:name}` token's, its
+ * name is already stable, so only `WIREBENCH_SECRET_<secretEnv>` is read.
+ */
+export const SIGNING_PSEUDO_REF_PREFIX = 'webhook-signing:';
 function need(ref, envName, purpose) {
     return ref === undefined || ref.length === 0 ? [] : [{ ref, ...(envName !== undefined ? { envName } : {}), purpose }];
 }
@@ -32,9 +39,18 @@ export function secretNeedsOfAuth(auth) {
 }
 /**
  * The variables a host reads for one secret, in order: the declared name, then the reference
- * itself. The reference form exists so a project nobody has annotated can still run in CI.
+ * itself. The reference form exists so a project nobody has annotated can still run in CI. A
+ * `${secret:name}` token's pseudo-ref has a stable name already, so it is read from
+ * `WIREBENCH_SECRET_<NAME>` alone.
  */
 export function envVariablesFor(secret) {
+    if (secret.ref.startsWith(SIGNING_PSEUDO_REF_PREFIX)) {
+        return [`${SECRET_ENV_PREFIX}${secret.envName ?? secret.ref.slice(SIGNING_PSEUDO_REF_PREFIX.length)}`];
+    }
+    const name = parseSecretPseudoRef(secret.ref);
+    if (name !== undefined) {
+        return [`${SECRET_ENV_PREFIX}${secretEnvName(name)}`];
+    }
     const byRef = `${SECRET_ENV_PREFIX}${secret.ref.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
     return secret.envName !== undefined ? [`${SECRET_ENV_PREFIX}${secret.envName}`, byRef] : [byRef];
 }

package/dist/secrets/resolve.d.ts

@@ -1,11 +1,18 @@
 /**
  * Resolves an `EndpointAuth` (which only ever carries a `passwordRef`) into the plaintext shape
- * the engine's `importDefinition`/send path expects. Kept pure — the secret getter is injected —
+ * the engine's `importWsdl`/send path expects. Kept pure — the secret getter is injected —
  * so it needs no Electron and is trivially testable without a real `SecretStore`.
  */
-import type { AuthConfig, EndpointAuth } from '../project/model.js';
-import type { SendAuth } from '../types.js';
-/** Turns a `secretRef` into its value. The one seam every host fills in: a keychain, or `process.env`. */
+import type { AuthConfig, SoapOwnerAuth, EndpointAuth } from '../project/model.js';
+import type { SendAuth } from '../http/auth/send-auth.js';
+/**
+ * Turns a `secretRef` (or a `secret:<name>` pseudo-ref for a `${secret:name}` token) into its
+ * value. The one seam every host fills in: a keychain, or `process.env`.
+ *
+ * Masking contract: every value a `GetSecret` hands out must be masked by the host — in logs,
+ * History, reports and CLI output. The engine keeps no list of its own; the CLI's
+ * `createEnvSecrets` records what it returns for its masker, and every host must do the same.
+ */
 export type GetSecret = (ref: string) => Promise<string | undefined>;
 /**
  * The message for a `secret-missing` error: in a shared workspace, secret refs travel with the
@@ -56,3 +63,36 @@ export declare function toSendAuth(auth?: ResolvedAuth): SendAuth | undefined;
 export declare function resolveAuthConfig(auth: AuthConfig | undefined, getSecret: GetSecret, options?: {
     readonly accessToken?: string;
 }): Promise<SendAuth | undefined>;
+/**
+ * Resolves a SOAP request's owner-level {@link SoapOwnerAuth} into the engine's `SendAuth`.
+ *
+ * Basic and NTLM go through the same `resolveEndpointAuth`/`toSendAuth` pair the endpoint-only
+ * shape has always used, so their semantics (preemptive default, undefined on an incomplete pair)
+ * stay exactly as they were before owner auth grew the other schemes. Bearer, API key and OAuth2
+ * are resolved through {@link resolveAuthConfig}, the same one REST uses — one implementation of
+ * "turn a reference into a value" for every token scheme, SOAP or REST.
+ *
+ * A caller refusing a SOAP owner's OAuth2 (as `connectSoap` does, matching `connectRest`) should
+ * do so before calling this — reached with `options.accessToken` unset, an OAuth2 owner simply
+ * resolves to no credentials.
+ *
+ * @throws WirebenchError `secret-missing` — see {@link resolveEndpointAuth} and
+ * {@link resolveAuthConfig}.
+ */
+export declare function resolveSoapAuth(auth: SoapOwnerAuth | undefined, getSecret: GetSecret, options?: {
+    readonly accessToken?: string;
+}): Promise<SendAuth | undefined>;
+/**
+ * The message for a `secret-missing` error on a `${secret:name}` token with no value on this machine,
+ * as the desktop app shows it: it names the command that stores one (the CLI says which environment
+ * variable to set instead).
+ */
+export declare function secretTokenMissingMessage(name: string): string;
+/**
+ * The values of the `${secret:name}` tokens a send uses, keyed by name, for `PropertyScopes.secrets`.
+ * Each name resolves through `getSecret` as the pseudo-ref `secret:<name>`; a missing one refuses
+ * the send rather than expanding to nothing.
+ *
+ * @throws WirebenchError `secret-missing`, with the pseudo-ref as `details.ref`
+ */
+export declare function resolveSecretTokens(names: Iterable<string>, getSecret: GetSecret): Promise<Record<string, string>>;

package/dist/secrets/resolve.js

@@ -1,9 +1,11 @@
 /**
  * Resolves an `EndpointAuth` (which only ever carries a `passwordRef`) into the plaintext shape
- * the engine's `importDefinition`/send path expects. Kept pure — the secret getter is injected —
+ * the engine's `importWsdl`/send path expects. Kept pure — the secret getter is injected —
  * so it needs no Electron and is trivially testable without a real `SecretStore`.
  */
 import { WirebenchError } from '../errors.js';
+import { isEndpointAuth } from '../project/endpoints.js';
+import { secretPseudoRef } from './secret-token.js';
 /**
  * The message for a `secret-missing` error: in a shared workspace, secret refs travel with the
  * project but values stay in each member's local keychain-backed store, so a teammate who joins
@@ -121,6 +123,31 @@ export async function resolveAuthConfig(auth, getSecret, options = {}) {
             return undefined;
     }
 }
+/**
+ * Resolves a SOAP request's owner-level {@link SoapOwnerAuth} into the engine's `SendAuth`.
+ *
+ * Basic and NTLM go through the same `resolveEndpointAuth`/`toSendAuth` pair the endpoint-only
+ * shape has always used, so their semantics (preemptive default, undefined on an incomplete pair)
+ * stay exactly as they were before owner auth grew the other schemes. Bearer, API key and OAuth2
+ * are resolved through {@link resolveAuthConfig}, the same one REST uses — one implementation of
+ * "turn a reference into a value" for every token scheme, SOAP or REST.
+ *
+ * A caller refusing a SOAP owner's OAuth2 (as `connectSoap` does, matching `connectRest`) should
+ * do so before calling this — reached with `options.accessToken` unset, an OAuth2 owner simply
+ * resolves to no credentials.
+ *
+ * @throws WirebenchError `secret-missing` — see {@link resolveEndpointAuth} and
+ * {@link resolveAuthConfig}.
+ */
+export async function resolveSoapAuth(auth, getSecret, options = {}) {
+    if (auth === undefined) {
+        return undefined;
+    }
+    if (isEndpointAuth(auth)) {
+        return toSendAuth(await resolveEndpointAuth(auth, getSecret));
+    }
+    return resolveAuthConfig(auth, getSecret, options);
+}
 /** One reference resolved, or `undefined` when the scheme has none configured yet. */
 async function requireSecret(ref, getSecret) {
     if (ref === undefined || ref === '') {
@@ -134,3 +161,33 @@ async function requireSecret(ref, getSecret) {
     }
     return value;
 }
+/**
+ * The message for a `secret-missing` error on a `${secret:name}` token with no value on this machine,
+ * as the desktop app shows it: it names the command that stores one (the CLI says which environment
+ * variable to set instead).
+ */
+export function secretTokenMissingMessage(name) {
+    return `The secret "${name}" is not on this machine — set it with Set Secret Token Value… (Secrets).`;
+}
+/**
+ * The values of the `${secret:name}` tokens a send uses, keyed by name, for `PropertyScopes.secrets`.
+ * Each name resolves through `getSecret` as the pseudo-ref `secret:<name>`; a missing one refuses
+ * the send rather than expanding to nothing.
+ *
+ * @throws WirebenchError `secret-missing`, with the pseudo-ref as `details.ref`
+ */
+export async function resolveSecretTokens(names, getSecret) {
+    const values = {};
+    for (const name of names) {
+        if (Object.hasOwn(values, name)) {
+            continue;
+        }
+        const ref = secretPseudoRef(name);
+        const value = await getSecret(ref);
+        if (value === undefined) {
+            throw new WirebenchError('secret-missing', secretTokenMissingMessage(name), { details: { ref, name } });
+        }
+        values[name] = value;
+    }
+    return values;
+}

package/dist/secrets/scan/apply.d.ts

@@ -0,0 +1,36 @@
+import type { Project } from '../../project/model.js';
+import type { SecretFinding } from './walk.js';
+export interface SecretMove {
+    readonly finding: SecretFinding;
+    /** The secret name to write; must match `SECRET_NAME_PATTERN`. */
+    readonly name: string;
+}
+export interface SecretMovesResult {
+    /** The rewritten project (the input itself when nothing was applied). */
+    readonly project: Project;
+    /**
+     * Ids of the moves not applied: the stored text no longer holds the finding's value at its
+     * range, the location no longer exists, the range overlaps another move, or the name is invalid.
+     */
+    readonly stale: string[];
+    /**
+     * For each applied move, by finding id, the secret value to store: exactly the text replaced
+     * (`finding.value`), still escaped as the surrounding JSON, XML or URL had it. Expansion puts a
+     * `${secret:…}` value back verbatim, so storing the raw text restores the original bytes.
+     */
+    readonly values: Record<string, string>;
+}
+/**
+ * Replace each move's finding range with `${secret:name}`. Moves in the same text apply right to
+ * left, so earlier ranges stay valid; a REST or WS URL and its query table are separate texts. A move
+ * whose text no longer holds `finding.value` at `[valueStart, valueEnd)` is skipped and listed in
+ * `stale`. See {@link SecretMovesResult.values} for the value main stores.
+ */
+export declare function applySecretMoves(project: Project, moves: readonly SecretMove[]): SecretMovesResult;
+/**
+ * The name offered for `finding`: its header, query (in the table or the URL), metadata, field or
+ * property name, sanitised to `snake_case` (else a name from its rule: `url_password` for a URL's
+ * password), made unique against `taken` ignoring case with a `_2`, `_3`, … suffix. Always matches
+ * `SECRET_NAME_PATTERN`.
+ */
+export declare function proposeSecretName(finding: SecretFinding, taken: ReadonlySet<string>): string;