@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/run/context.d.ts

@@ -0,0 +1,86 @@
+import type { Project, PropertyMap } from '../project/model.js';
+import type { HeldSoapDefinition } from '../protocols.js';
+import type { PropertyScopes } from '../project/properties.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
+import type { RequestScripting } from '../script/request-scripts.js';
+import type { SecretPlaceholders } from '../script/send.js';
+import type { Workspace } from '../workspace/model.js';
+import type { CurrentValues } from './current-values.js';
+import type { SendHost } from './host.js';
+import type { SelectedRequest } from './select.js';
+/**
+ * The workspace a project is run inside, and the slug its manifest addresses the project by (the
+ * first half of a workspace environment's `<projectSlug>/<interfaceSlug>` endpoint key).
+ */
+export interface RunWorkspace {
+    readonly workspace: Workspace;
+    readonly projectSlug: string;
+}
+/** Everything a run supplies around the saved requests it sends. */
+export interface RunContext {
+    readonly project: Project;
+    /** The project folder: keystores, attachments and file bodies are read from inside it only. */
+    readonly projectDir: string;
+    /**
+     * The environment the run resolves under. Inside a workspace it is a *workspace* environment's
+     * id, as it is in the app: the project's own environments apply only through the one linked to
+     * it by slug.
+     */
+    readonly environmentId?: string;
+    /**
+     * The workspace the project sits inside. Its properties become the `${#Workspace#…}` scope, and
+     * its environment (with the linked project one laid over it) the `${…}` shorthand's.
+     */
+    readonly workspace?: RunWorkspace;
+    /** `--var` overrides, laid over the environment's properties. */
+    readonly overrides: PropertyMap;
+    /** The host's global properties, the `${#Global#…}` scope. Absent: none. */
+    readonly globals?: PropertyMap;
+    /**
+     * The session's current values (cookie jar spec §5.2), each laid over the committed values of its
+     * own scope. `overrides` still win over them. Typed by the user, never response-derived.
+     */
+    readonly current?: CurrentValues;
+    /** What the host lends each send: secrets, proxy, TLS, tokens, preferences (spec §3.1). */
+    readonly host: SendHost;
+    readonly timeoutMs?: number;
+    readonly insecure?: boolean;
+    readonly signal?: AbortSignal;
+    /**
+     * The WSDL-derived default `wsa:Action` for a SOAP request, as the app takes it from the
+     * interface's imported definition. Absent (or returning `''`) when no definition is at hand:
+     * an explicit `wsa:Action` or the request's SOAPAction then still applies.
+     */
+    readonly defaultWsaActionFor?: (selected: Extract<SelectedRequest, {
+        kind: 'soap';
+    }>) => string;
+    /**
+     * The definition a host already holds for a SOAP request's interface (the app's, imported and
+     * compiled), so a send neither reads nor compiles the definition cache. Absent, or answering
+     * undefined: the run reads the interface's cached definition itself, once per run scope.
+     */
+    readonly loadedDefinitionFor?: (selected: Extract<SelectedRequest, {
+        kind: 'soap';
+    }>) => HeldSoapDefinition | undefined;
+    /** A sequence step's `${#Sequence#…}` values, from the responses of the steps before it. */
+    readonly sequence?: PropertyMap;
+    /**
+     * Set for a request with a pre-request script: every `${secret:…}` in the request's text becomes
+     * one of these placeholders, and the script's host puts the values back after it (#63).
+     */
+    readonly secretPlaceholders?: SecretPlaceholders;
+    /**
+     * Runs requests' scripts (#63). A run without it refuses a request whose scripts are switched on,
+     * rather than send it without them.
+     */
+    readonly scripting?: RequestScripting;
+    /** True when a value holds a credential the run knows; such a script value is treated as secret. */
+    readonly containsKnownSecret?: (value: string) => boolean;
+    /**
+     * The protocol modules this run dispatches through, with their feature switches. Absent: the
+     * built-in four with every feature on (`defaultRegistry()`).
+     */
+    readonly registry?: ProtocolRegistry;
+}
+/** The property scopes a request of this run expands against, secrets not yet added. */
+export declare function scopesFor(context: RunContext): PropertyScopes;

package/dist/run/context.js

@@ -0,0 +1,31 @@
+/**
+ * What a run supplies around the saved requests it sends, and the property scopes they expand
+ * against. Apart from the run's own files so a protocol module can take a `RunContext` without
+ * importing the run loop.
+ */
+import { resolveScopes } from '../project/environments.js';
+import { resolveWorkspaceScopes, withActiveEnvironment } from '../workspace/environments.js';
+import { withCurrentValues } from './current-values.js';
+/** The property scopes a request of this run expands against, secrets not yet added. */
+export function scopesFor(context) {
+    const { environmentId } = context;
+    const { project, workspace, globals } = withCurrentValues({
+        project: context.project,
+        ...(context.workspace !== undefined ? { workspace: context.workspace.workspace } : {}),
+        globals: context.globals ?? {},
+    }, context.current);
+    const scopes = workspace === undefined
+        ? resolveScopes(project, environmentId, globals, process.env)
+        : resolveWorkspaceScopes({
+            workspace: withActiveEnvironment(workspace, environmentId),
+            project,
+            globals,
+            system: process.env,
+        });
+    return {
+        ...scopes,
+        env: { ...(scopes.env ?? {}), ...context.overrides },
+        // A sequence step's `${#Sequence#…}` values: literal, explicit-only and guarded (ADR-0015).
+        ...(context.sequence !== undefined ? { sequence: context.sequence } : {}),
+    };
+}

package/dist/run/current-values.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Current values (cookie jar and current values spec §5.2): the session's own value for a variable,
+ * laid over its committed value in the same scope before resolution. A host hands them in through
+ * `RunContext.current`.
+ *
+ * A current value is typed by the user, never taken from a response, so it is a template like a
+ * committed value and ADR-0015 is untouched. It only replaces a name its scope defines, and since
+ * resolution drops disabled names afterwards, a disabled variable's current value does not apply.
+ */
+import type { Project, PropertyMap } from '../project/model.js';
+import type { Workspace } from '../workspace/model.js';
+/** The overlays of one run, keyed like the scopes they land on; environments by id. */
+export interface CurrentValues {
+    readonly global?: PropertyMap;
+    readonly workspace?: PropertyMap;
+    readonly workspaceEnvironments?: Readonly<Record<string, PropertyMap>>;
+    readonly project?: PropertyMap;
+    /** The run's project's own environments. */
+    readonly projectEnvironments?: Readonly<Record<string, PropertyMap>>;
+}
+/** `properties` with each name it defines replaced by `current`'s value; the same map when nothing changes. */
+export declare function overlayCurrent(properties: PropertyMap, current: PropertyMap | undefined): PropertyMap;
+/** The project, workspace and globals a run resolves, each scope with its current values laid over it. */
+export declare function withCurrentValues(input: {
+    readonly project: Project;
+    readonly workspace?: Workspace;
+    readonly globals: PropertyMap;
+}, current: CurrentValues | undefined): {
+    readonly project: Project;
+    readonly workspace?: Workspace;
+    readonly globals: PropertyMap;
+};

package/dist/run/current-values.js

@@ -0,0 +1,43 @@
+/** `properties` with each name it defines replaced by `current`'s value; the same map when nothing changes. */
+export function overlayCurrent(properties, current) {
+    if (current === undefined) {
+        return properties;
+    }
+    let laid;
+    for (const [name, value] of Object.entries(current)) {
+        if (Object.hasOwn(properties, name)) {
+            laid ??= { ...properties };
+            laid[name] = value;
+        }
+    }
+    return laid ?? properties;
+}
+/** The project, workspace and globals a run resolves, each scope with its current values laid over it. */
+export function withCurrentValues(input, current) {
+    if (current === undefined) {
+        return input;
+    }
+    const project = {
+        ...input.project,
+        properties: overlayCurrent(input.project.properties, current.project),
+        environments: input.project.environments.map((environment) => ({
+            ...environment,
+            properties: overlayCurrent(environment.properties, current.projectEnvironments?.[environment.id]),
+        })),
+    };
+    const workspace = input.workspace === undefined
+        ? undefined
+        : {
+            ...input.workspace,
+            properties: overlayCurrent(input.workspace.properties, current.workspace),
+            environments: input.workspace.environments.map((environment) => ({
+                ...environment,
+                properties: overlayCurrent(environment.properties, current.workspaceEnvironments?.[environment.id]),
+            })),
+        };
+    return {
+        project,
+        ...(workspace !== undefined ? { workspace } : {}),
+        globals: overlayCurrent(input.globals, current.global),
+    };
+}

package/dist/run/event-queue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The live events of one exchange, as an async iterable. A disabled queue drops everything: nobody
+ * reads its events (a run), so a long stream costs no memory beyond the exchange it records anyway.
+ */
+export declare class EventQueue<T> implements AsyncIterable<T> {
+    private readonly enabled;
+    private readonly buffered;
+    private waiting;
+    private ended;
+    constructor(enabled: boolean);
+    push(event: T): void;
+    end(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/run/event-queue.js

@@ -0,0 +1,46 @@
+/**
+ * The live events of one exchange, as an async iterable. A disabled queue drops everything: nobody
+ * reads its events (a run), so a long stream costs no memory beyond the exchange it records anyway.
+ */
+export class EventQueue {
+    enabled;
+    buffered = [];
+    waiting;
+    ended = false;
+    constructor(enabled) {
+        this.enabled = enabled;
+    }
+    push(event) {
+        if (!this.enabled || this.ended)
+            return;
+        const waiting = this.waiting;
+        if (waiting !== undefined) {
+            this.waiting = undefined;
+            waiting({ value: event, done: false });
+        }
+        else {
+            this.buffered.push(event);
+        }
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const waiting = this.waiting;
+        this.waiting = undefined;
+        waiting?.({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.buffered.length > 0)
+                    return Promise.resolve({ value: this.buffered.shift(), done: false });
+                if (this.ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => {
+                    this.waiting = resolve;
+                });
+            },
+        };
+    }
+}

package/dist/run/exchange.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One send, whoever sends it (spec §3.2): the desktop, a run, a sequence step. A protocol's run facet
+ * builds its handle with `exchangeController`; `openExchange` (run/open.ts) hands an item to its
+ * facet. Core code: it names no protocol.
+ */
+import { WirebenchError } from '../errors.js';
+import type { PropertyScopes } from '../project/properties.js';
+import type { RunScope, ScriptedSend } from '../protocol/module.js';
+import { EventQueue } from './event-queue.js';
+import type { SentRequest } from './run.js';
+export interface LiveEventBase {
+    readonly protocol: string;
+    readonly kind: string;
+}
+/**
+ * A message pushed on an open exchange: text (expanded when `expand`), or binary as base64. A text
+ * expands against `scopes` when the host brings them (its properties as they are at the push, an
+ * environment switched since the open included), else against the exchange's own.
+ */
+export type PushMessage = {
+    readonly text: string;
+    readonly expand?: boolean;
+    readonly scopes?: PropertyScopes;
+} | {
+    readonly base64: string;
+};
+export interface ExchangeOptions {
+    readonly scope: RunScope;
+    readonly scripts?: ScriptedSend;
+    /** The host drives push, halfClose and close; otherwise the saved messages are sent (spec §5.2). */
+    readonly interactive: boolean;
+    /** True when the caller reads `events`. By default nothing is buffered. */
+    readonly live?: boolean;
+    /**
+     * True for a run's send (spec §5.2): a stream waits for its answer within the run timeout, and one
+     * the timeout cuts fails with `timeout`. A host's own send is not a run, interactive or not.
+     */
+    readonly run?: boolean;
+}
+export interface StreamingSide {
+    /** Resolves with what was sent: a gRPC message's canonical JSON, a WebSocket frame. */
+    push(message: PushMessage): Promise<unknown>;
+    halfClose(): void;
+    close(code?: number, reason?: string): void;
+}
+export interface ExchangeHandle<E extends LiveEventBase = LiveEventBase> extends StreamingSide {
+    readonly events: AsyncIterable<E>;
+    /** Aborts this send only. False when it has already settled or been cancelled. */
+    cancel(): boolean;
+    /** Rejects with the send's error; `events` has ended by then. */
+    readonly result: Promise<SentRequest>;
+}
+export interface ExchangeController<E extends LiveEventBase> {
+    /** This exchange's own signal, which also follows the run's. */
+    readonly signal: AbortSignal;
+    readonly queue: EventQueue<E>;
+    /** The handle: its result is `run`'s, and its events end when `run` settles. */
+    handle(run: () => Promise<SentRequest>, streaming?: StreamingSide): ExchangeHandle<E>;
+}
+/** The refusal of a push, half-close or close on an exchange that takes no messages. */
+export declare function notStreaming(kind: string): WirebenchError;
+export declare function exchangeController<E extends LiveEventBase>(kind: string, options: ExchangeOptions): ExchangeController<E>;

package/dist/run/exchange.js

@@ -0,0 +1,65 @@
+/**
+ * One send, whoever sends it (spec §3.2): the desktop, a run, a sequence step. A protocol's run facet
+ * builds its handle with `exchangeController`; `openExchange` (run/open.ts) hands an item to its
+ * facet. Core code: it names no protocol.
+ */
+import { WirebenchError } from '../errors.js';
+import { EventQueue } from './event-queue.js';
+/** The refusal of a push, half-close or close on an exchange that takes no messages. */
+export function notStreaming(kind) {
+    return new WirebenchError('exchange-not-streaming', `This ${kind} request takes no messages once it is sent`, {
+        details: { protocol: kind },
+    });
+}
+export function exchangeController(kind, options) {
+    const abort = new AbortController();
+    const outer = options.scope.context.signal;
+    const follow = () => abort.abort(outer?.reason);
+    if (outer !== undefined) {
+        if (outer.aborted)
+            abort.abort(outer.reason);
+        else
+            outer.addEventListener('abort', follow, { once: true });
+    }
+    const queue = new EventQueue(options.live === true);
+    let settled = false;
+    return {
+        signal: abort.signal,
+        queue,
+        handle(run, streaming) {
+            const result = (async () => {
+                try {
+                    return await run();
+                }
+                finally {
+                    settled = true;
+                    outer?.removeEventListener('abort', follow);
+                    queue.end();
+                }
+            })();
+            // Observed here, so a rejection nobody awaits yet is never reported as unhandled.
+            result.catch(() => undefined);
+            return {
+                events: queue,
+                result,
+                push: (message) => (streaming !== undefined ? streaming.push(message) : Promise.reject(notStreaming(kind))),
+                halfClose: () => {
+                    if (streaming === undefined)
+                        throw notStreaming(kind);
+                    streaming.halfClose();
+                },
+                close: (code, reason) => {
+                    if (streaming === undefined)
+                        throw notStreaming(kind);
+                    streaming.close(code, reason);
+                },
+                cancel: () => {
+                    if (settled || abort.signal.aborted)
+                        return false;
+                    abort.abort();
+                    return true;
+                },
+            };
+        },
+    };
+}

package/dist/run/host.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a host lends the engine for one send (spec §3.1). Only the secret getter is required.
+ * Where any other member is absent, the send behaves as the command line's does.
+ */
+import type { CookieJarHost } from '../http/cookies.js';
+import type { ProxyOptions } from '../http/types.js';
+import type { Keystore } from '../keystore/index.js';
+import type { Preferences } from '../project/preferences.js';
+import type { SelectedBase } from '../protocol/module.js';
+import type { GetSecret } from '../secrets/resolve.js';
+import type { RunTokenSource } from './oauth2-token.js';
+export interface ClientIdentity {
+    readonly cert: string;
+    readonly key: string;
+}
+export interface AttemptedRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface SendFailure {
+    readonly stage: 'prepare' | 'send';
+    readonly error: unknown;
+    /** `Date.now()` when the failed stage began: the prepare stage, or the send stage after it. */
+    readonly startedAt: number;
+    /**
+     * How long the failed stage ran. A send-stage failure counts the send stage's own time only, never
+     * resolve, a script, a token fetch or a proxy lookup; a host's History records it as the duration.
+     */
+    readonly durationMs: number;
+    /**
+     * What was about to go, or went, on the wire; absent when resolution itself failed. It can hold
+     * live values — a `${secret:…}` expanded into a header or a metadata row — so a host redacts it
+     * before it is shown or logged.
+     */
+    readonly attempted?: AttemptedRequest;
+    /**
+     * The protocol's input at the stage that failed, for a host that records the send whole. It holds
+     * live credentials — resolved auth, a signing secret, a proxy password, TLS keys — so a host reads
+     * only what it records and never logs or serialises it.
+     */
+    readonly input?: unknown;
+    /**
+     * What the protocol recorded of an exchange that failed part way, for a host that records the
+     * attempt whole: a session cancelled before it opened keeps its transcript. Redacted as `input` is.
+     */
+    readonly exchange?: unknown;
+}
+export interface SendHost {
+    readonly getSecret: GetSecret;
+    /** Told every OAuth2 access token the send obtains, so the host can mask it in all it prints. */
+    readonly onSecretValue?: (value: string) => void;
+    readonly proxyFor?: (url: string) => Promise<ProxyOptions | undefined>;
+    readonly tls?: {
+        /** Added to every TLS connection's trust: the system roots, a CA bundle, test anchors. */
+        readonly anchors?: readonly string[];
+        /** A request's keystore, or the host's default identity when the request names none. */
+        identityFor?(keystoreId: string | undefined): Promise<ClientIdentity | undefined>;
+    };
+    /**
+     * A WS-Security keystore by its project entry id, for signing, encryption, response verification
+     * and decryption alike; undefined when the project has no such entry. The app lends its own
+     * loader, which also reads a file its user picked this session; absent, a keystore is read from
+     * inside the project folder only.
+     */
+    readonly keystoreFor?: (keystoreId: string) => Promise<Keystore | undefined>;
+    /** The OAuth2 token source; a run creates one per run when the host brings none. */
+    readonly tokens?: RunTokenSource;
+    readonly preferences?: Preferences;
+    readonly events?: {
+        onFailed?(item: SelectedBase, failure: SendFailure): void;
+        /** A row the host logs that is not the send's result (the WebSocket handshake). */
+        onExchange?(item: SelectedBase, exchange: unknown): void;
+    };
+    /**
+     * The cookie jar (cookie jar spec §1.4): every REST send stores what each response sets, redirect
+     * hops included, and a request whose `sendCookies` setting is on carries what matches each hop's
+     * URL. Absent: nothing is stored or sent.
+     */
+    readonly cookies?: CookieJarHost;
+    /** The response checked against the request's contract. Absent: nothing is checked.
+     * A rejection means nothing was checked: the send still succeeds, without a contract.
+     * `sent` is the protocol's input as it went out, which the operation is looked up from. */
+    readonly contractFor?: (item: SelectedBase, exchange: unknown, sent?: unknown) => Promise<unknown>;
+    /** A webhook item's callback URL, used in place of its target; undefined keeps the target. */
+    readonly callbackUrlFor?: (item: SelectedBase) => Promise<string | undefined>;
+    /** An API's schema (a ProtoSet; the gRPC module narrows it), in place of the definition cache. */
+    readonly protoSetFor?: (item: SelectedBase) => Promise<unknown>;
+}

package/dist/run/host.js

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

package/dist/run/index.d.ts

@@ -1,8 +1,21 @@
-export { selectRequests } from './select.js';
-export type { SelectedRequest } from './select.js';
-export { prepareSend } from './prepare.js';
-export type { PreparedSend, RunContext } from './prepare.js';
-export { runRequests } from './run.js';
-export type { RequestOutcome, RequestResult, RunOptions, RunResult, RunSummary } from './run.js';
-export { secretNeedsOf } from './secret-needs.js';
+export { findStepRequest, selectRequests } from './select.js';
+export type { SelectedRequest, StepRequestLookup } from './select.js';
+export { scopesFor } from './context.js';
+export { overlayCurrent, withCurrentValues } from './current-values.js';
+export type { CurrentValues } from './current-values.js';
+export type { AttemptedRequest, ClientIdentity, SendFailure, SendHost } from './host.js';
+export type { RunContext, RunWorkspace } from './context.js';
+export { cappedExchange, checkRunScripts, createRunSender, deferredSession, errorOf, runRequests, scriptReport, } from './run.js';
+export type { BaselineSink, BaselineSource, RequestOutcome, RequestResult, RunOptions, RunRequestSender, RunResult, RunSendOverrides, LiveEvent, RunSummary, SentExchange, SentRequest, } from './run.js';
+export { secretNamesInValue, secretNeedsOf } from './secret-needs.js';
 export type { LocatedSecretNeed } from './secret-needs.js';
+export { createRunTokenSource } from './oauth2-token.js';
+export type { RunTokenSource, RunTokenSourceOptions, TokenRequestContext } from './oauth2-token.js';
+export { mergeScriptValues, scriptAssertions, scriptSession, listedSecrets } from './script-support.js';
+export type { ScriptSession, ScriptSessionOptions, SentScripts } from './script-support.js';
+export { EventQueue } from './event-queue.js';
+export { exchangeController, notStreaming } from './exchange.js';
+export { openExchange, resolveExchange } from './open.js';
+export { createRunScope } from './scope.js';
+export { resolvedBaseUrl } from './send-helpers.js';
+export type { ExchangeController, ExchangeHandle, ExchangeOptions, LiveEventBase, PushMessage, StreamingSide, } from './exchange.js';

package/dist/run/index.js

@@ -1,4 +1,12 @@
-export { selectRequests } from './select.js';
-export { prepareSend } from './prepare.js';
-export { runRequests } from './run.js';
-export { secretNeedsOf } from './secret-needs.js';
+export { findStepRequest, selectRequests } from './select.js';
+export { scopesFor } from './context.js';
+export { overlayCurrent, withCurrentValues } from './current-values.js';
+export { cappedExchange, checkRunScripts, createRunSender, deferredSession, errorOf, runRequests, scriptReport, } from './run.js';
+export { secretNamesInValue, secretNeedsOf } from './secret-needs.js';
+export { createRunTokenSource } from './oauth2-token.js';
+export { mergeScriptValues, scriptAssertions, scriptSession, listedSecrets } from './script-support.js';
+export { EventQueue } from './event-queue.js';
+export { exchangeController, notStreaming } from './exchange.js';
+export { openExchange, resolveExchange } from './open.js';
+export { createRunScope } from './scope.js';
+export { resolvedBaseUrl } from './send-helpers.js';

package/dist/run/oauth2-token.d.ts

@@ -0,0 +1,42 @@
+import type { HttpExchange, HttpRequest, ProxyOptions, TlsOptions } from '../http/types.js';
+import type { OAuth2Auth } from '../project/model.js';
+import type { PropertyScopes } from '../project/properties.js';
+import type { GetSecret } from '../secrets/resolve.js';
+export interface RunTokenSourceOptions {
+    readonly getSecret: GetSecret;
+    /** Sends the token request. The engine's `sendHttp` by default; a stub in tests. */
+    readonly send?: (request: HttpRequest) => Promise<HttpExchange>;
+    readonly now?: () => Date;
+    /** Told every access token obtained, so a host can keep it out of everything it prints. */
+    readonly onSecretValue?: (value: string) => void;
+}
+/** What one token request needs beyond the configuration: the requesting send's own surroundings. */
+export interface TokenRequestContext {
+    /** The request's property scopes: token URL, client id, scopes and audience expand against them. */
+    readonly scopes: PropertyScopes;
+    readonly tls?: TlsOptions;
+    /** The proxy for the token URL, chosen after it is expanded. */
+    readonly proxy?: (tokenUrl: string) => Promise<ProxyOptions | undefined>;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface RunTokenSource {
+    /**
+     * The cached token for the configuration, or a new one when there is none, it is about to lapse,
+     * or it was rejected.
+     *
+     * @throws WirebenchError `unresolved-properties` | `secret-missing` | `oauth2-no-token-url` |
+     * `oauth2-token-error` | `oauth2-token-malformed`, or the send's own error
+     */
+    accessTokenFor(config: OAuth2Auth, request: TokenRequestContext): Promise<string>;
+    /**
+     * Drops `accessToken` from the cache after a server refused it (a REST or SOAP `401`, a gRPC
+     * `UNAUTHENTICATED`), so the next request behind its configuration fetches a new one. It never
+     * re-sends the refused request: that one may already have done something. A token the cache no
+     * longer holds is ignored.
+     */
+    reject(accessToken: string): void;
+}
+export declare function createRunTokenSource(options: RunTokenSourceOptions): RunTokenSource;
+/** A secret the project names but the run was not given: refused, never sent without. */
+export declare function requiredSecret(ref: string, getSecret: GetSecret): Promise<string>;

package/dist/run/oauth2-token.js

@@ -0,0 +1,92 @@
+/**
+ * OAuth2 access tokens for a run, which has no browser, no keychain and no token cache of its own
+ * beyond the run itself. Only the client-credentials grant can work headless; this source refuses
+ * authorization-code (a host's own source may serve it).
+ *
+ * One token per configuration per run: two requests behind the same configuration share one token
+ * request, and a token is fetched again when `needsRefresh` says it is about to lapse, or after a
+ * server rejected it (`reject`). A failed fetch is never cached, so the next request behind the
+ * configuration tries again.
+ */
+import { WirebenchError } from '../errors.js';
+import { sendHttp } from '../http/client.js';
+import { expand } from '../project/properties.js';
+import { buildTokenRequest, needsRefresh, parseTokenResponse } from '../http/auth/oauth2.js';
+/** The configuration with its property references expanded; unresolved ones refuse the fetch. */
+function expandConfig(config, scopes) {
+    const unresolved = [];
+    const one = (text) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        return result.text;
+    };
+    const expanded = {
+        ...config,
+        tokenUrl: one(config.tokenUrl),
+        clientId: one(config.clientId),
+        scopes: config.scopes.map(one),
+        ...(config.audience !== undefined ? { audience: one(config.audience) } : {}),
+    };
+    if (unresolved.length > 0) {
+        const exprs = unresolved.map((ref) => ref.expr);
+        throw new WirebenchError('unresolved-properties', `The OAuth2 configuration has property references nothing resolves: ${exprs.join(', ')}`, { details: { unresolved: exprs } });
+    }
+    return expanded;
+}
+/** The expanded fields a token belongs to. Kept in memory only, never printed. */
+function cacheKey(config) {
+    return [config.tokenUrl, config.clientId, [...config.scopes].sort().join(' '), config.audience ?? ''].join('\u0000');
+}
+export function createRunTokenSource(options) {
+    const tokens = new Map();
+    const now = options.now ?? (() => new Date());
+    const send = options.send ?? ((request) => sendHttp(request));
+    return {
+        async accessTokenFor(config, request) {
+            if (config.grant === 'authorization-code') {
+                throw new WirebenchError('auth-grant-unsupported', 'This request signs in through a browser (OAuth2 authorization code), which a pipeline cannot do.', { details: { grant: config.grant } });
+            }
+            const expanded = expandConfig(config, request.scopes);
+            const key = cacheKey(expanded);
+            const cached = tokens.get(key);
+            if (cached !== undefined && !needsRefresh(cached, now())) {
+                return cached.accessToken;
+            }
+            const clientSecret = await clientSecretOf(expanded, options.getSecret);
+            const built = buildTokenRequest(expanded, clientSecret !== undefined ? { clientSecret } : {}, { grant: 'client-credentials' }, {
+                ...(request.timeoutMs !== undefined ? { timeoutMs: request.timeoutMs } : {}),
+                ...(request.signal !== undefined ? { signal: request.signal } : {}),
+            });
+            const proxy = await request.proxy?.(expanded.tokenUrl);
+            const exchange = await send({
+                ...built,
+                ...(request.tls !== undefined ? { tls: request.tls } : {}),
+                ...(proxy !== undefined ? { proxy } : {}),
+            });
+            const token = parseTokenResponse({ status: exchange.status, body: exchange.body, now });
+            options.onSecretValue?.(token.accessToken);
+            tokens.set(key, token);
+            return token.accessToken;
+        },
+        reject(accessToken) {
+            for (const [key, token] of tokens) {
+                if (token.accessToken === accessToken) {
+                    tokens.delete(key);
+                }
+            }
+        },
+    };
+}
+/** A secret the project names but the run was not given: refused, never sent without. */
+export async function requiredSecret(ref, getSecret) {
+    const value = await getSecret(ref);
+    if (value === undefined) {
+        throw new WirebenchError('secret-missing', `Secret ${ref} was not supplied to this run.`, { details: { ref } });
+    }
+    return value;
+}
+/** A configured client secret the run was not given is refused, never sent as a public client. */
+async function clientSecretOf(config, getSecret) {
+    const ref = config.clientSecretRef;
+    return ref === undefined || ref === '' ? undefined : requiredSecret(ref, getSecret);
+}