@wirebench/engine 2.1.1

package/dist/redact/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Masks secret-bearing values before they cross IPC into the renderer (HTTP log, and later
+ * history — Task 24 reuses these helpers). The engine's own in-memory `HttpExchange` stays
+ * unredacted; everything built for the wire (`engine-wire.ts`) goes through here unless the
+ * session's "show secrets" flag is on.
+ */
+/** The exact marker text every redaction helper below writes in place of a masked secret. */
+export declare const REDACTED_MARKER = "<redacted>";
+/** True when `text` contains the redaction marker — i.e. it was produced by a `redact*` helper. */
+export declare function containsRedaction(text: string): boolean;
+/** Masks the values of sensitive headers in a plain header map, case-insensitively. */
+export declare function redactHeaders(headers: Readonly<Record<string, string>>, opts?: {
+    show?: boolean;
+}): Record<string, string>;
+/**
+ * Masks the values of sensitive headers in a `[name, value]` pair list — the raw, duplicate-
+ * preserving header form (`Set-Cookie` appears once per cookie there, so this list is exactly
+ * where a naive copy leaks by default).
+ */
+export declare function redactHeaderPairs(pairs: readonly (readonly [string, string])[], opts?: {
+    show?: boolean;
+}): [string, string][];
+/**
+ * Masks the value of every sensitive query parameter in `url`, plus any parameter named in
+ * `extraParams` — which is how the send path masks the exact parameter an API key is configured to
+ * travel in, whatever it is called.
+ *
+ * A URL that cannot be parsed is returned unchanged: it is already not a URL, and mangling it would
+ * only hide what is wrong with it.
+ */
+export declare function redactUrl(url: string, opts?: {
+    show?: boolean;
+    extraParams?: readonly string[];
+}): string;
+/**
+ * The redaction pass for a response's attachment list. Nothing in `{index, contentId,
+ * contentType, size, name}` carries a secret today, so this is a copy — it exists as the one
+ * call site so that when a part's `Content-Disposition` (or a signed-URL-shaped name) does need
+ * masking, it is masked everywhere the list is built, including on a show-secrets re-render.
+ * It takes no `show` flag: both callers (`toResponseAttachmentWires` and
+ * `redactExchangeSummary`) decide for themselves whether to run it, because the summary built
+ * with `{ show: true }` is the unredacted master the `ExchangeCache` keeps.
+ */
+export declare function redactResponseAttachments<T>(attachments: readonly T[]): T[];
+/**
+ * Masks the text content of `wsse:Password` elements (any namespace prefix) in raw XML — except
+ * a `#PasswordDigest` value, which is a hash, not a secret, and must reach the wire intact.
+ */
+export declare function redactXml(text: string, opts?: {
+    show?: boolean;
+}): string;
+/** Body keys whose values are masked in JSON and form bodies, compared case-insensitively. */
+export declare const SECRET_BODY_KEYS: readonly string[];
+/**
+ * Masks secret-keyed values in a JSON (`application/json`, `+json`) or urlencoded form body;
+ * anything else, or JSON that does not parse, is returned as is.
+ */
+export declare function redactStructuredBody(text: string, contentType: string | undefined, opts?: {
+    show?: boolean;
+}): string;
+/**
+ * Redacts a raw HTTP message **on its bytes**, never assuming the whole message is UTF-8 text.
+ *
+ * The buffer is split at the first `\r\n\r\n` (falling back to `\n\n`); only the header block is
+ * decoded — as latin1, which is byte-preserving for the ASCII header grammar — so sensitive
+ * header lines can be masked while their original line terminators are re-joined verbatim. The
+ * body is decoded and masked (`wsse:Password`) only when the headers say it is uncompressed
+ * SOAP/XML/plain text; otherwise its bytes are copied through untouched, so a gzip or binary
+ * body round-trips byte-identically.
+ *
+ * `opts.encoding` says whether `input`/the return value is `'text'` (default) or a `'base64'`
+ * string, so callers can pass the wire's `rawRequestBase64`/`rawResponseBase64` straight through.
+ */
+export declare function redactRawHttp(input: string, opts?: {
+    show?: boolean;
+    encoding?: 'text' | 'base64';
+}): string;

package/dist/redact/index.js

@@ -0,0 +1,328 @@
+/**
+ * Masks secret-bearing values before they cross IPC into the renderer (HTTP log, and later
+ * history — Task 24 reuses these helpers). The engine's own in-memory `HttpExchange` stays
+ * unredacted; everything built for the wire (`engine-wire.ts`) goes through here unless the
+ * session's "show secrets" flag is on.
+ */
+const REDACTED = '<redacted>';
+/** The exact marker text every redaction helper below writes in place of a masked secret. */
+export const REDACTED_MARKER = REDACTED;
+/** True when `text` contains the redaction marker — i.e. it was produced by a `redact*` helper. */
+export function containsRedaction(text) {
+    return text.includes(REDACTED_MARKER);
+}
+/** Header names (case-insensitive) whose value is always masked. */
+const SENSITIVE_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie', 'set-cookie', 'x-api-key']);
+/** Masks the values of sensitive headers in a plain header map, case-insensitively. */
+export function redactHeaders(headers, opts) {
+    if (opts?.show) {
+        return { ...headers };
+    }
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        result[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+    }
+    return result;
+}
+/**
+ * Masks the values of sensitive headers in a `[name, value]` pair list — the raw, duplicate-
+ * preserving header form (`Set-Cookie` appears once per cookie there, so this list is exactly
+ * where a naive copy leaks by default).
+ */
+export function redactHeaderPairs(pairs, opts) {
+    const show = opts?.show ?? false;
+    return pairs.map(([name, value]) => [name, !show && SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value]);
+}
+/**
+ * Query-parameter names (case-insensitive) whose value is masked wherever a URL is logged, stored
+ * or shown. An API key that travels in the query string is as much a credential as one in a header,
+ * and a URL reaches more places than a header does: the HTTP log, history, the cURL export, a
+ * problem message.
+ */
+const SENSITIVE_QUERY_PARAMS = new Set([
+    'api_key',
+    'apikey',
+    'api-key',
+    'access_token',
+    'token',
+    'key',
+    'auth',
+    'signature',
+    'sig',
+]);
+/**
+ * Masks the value of every sensitive query parameter in `url`, plus any parameter named in
+ * `extraParams` — which is how the send path masks the exact parameter an API key is configured to
+ * travel in, whatever it is called.
+ *
+ * A URL that cannot be parsed is returned unchanged: it is already not a URL, and mangling it would
+ * only hide what is wrong with it.
+ */
+export function redactUrl(url, opts) {
+    if (opts?.show === true) {
+        return url;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    const extra = new Set((opts?.extraParams ?? []).map((name) => name.toLowerCase()));
+    let changed = false;
+    if (parsed.password !== '') {
+        parsed.password = REDACTED;
+        changed = true;
+    }
+    for (const name of [...parsed.searchParams.keys()]) {
+        const lower = name.toLowerCase();
+        if (SENSITIVE_QUERY_PARAMS.has(lower) || extra.has(lower)) {
+            parsed.searchParams.set(name, REDACTED);
+            changed = true;
+        }
+    }
+    // `URL` normalises as it serialises (a `+` becomes `%2B`, a default port disappears), so an
+    // untouched URL is returned as it came in rather than as the parser would have written it.
+    return changed ? parsed.toString() : url;
+}
+/**
+ * The redaction pass for a response's attachment list. Nothing in `{index, contentId,
+ * contentType, size, name}` carries a secret today, so this is a copy — it exists as the one
+ * call site so that when a part's `Content-Disposition` (or a signed-URL-shaped name) does need
+ * masking, it is masked everywhere the list is built, including on a show-secrets re-render.
+ * It takes no `show` flag: both callers (`toResponseAttachmentWires` and
+ * `redactExchangeSummary`) decide for themselves whether to run it, because the summary built
+ * with `{ show: true }` is the unredacted master the `ExchangeCache` keeps.
+ */
+export function redactResponseAttachments(attachments) {
+    return [...attachments];
+}
+/**
+ * The start of an (optionally namespace-prefixed) `<Password` open tag, and a matching close tag.
+ *
+ * Used by a scanner rather than as one `/(<…Password[^>]*>)([\\s\\S]*?)(<\\/…Password>)/gi`: that
+ * pattern's lazy body backtracks to the end of the text for every open tag that has no close tag,
+ * which is O(n²) — and this runs over a *response*, so the text is whatever server answered.
+ */
+const PASSWORD_OPEN_RE = /<(?:[\w-]+:)?Password\b/gi;
+const PASSWORD_CLOSE_RE = /<\/(?:[\w-]+:)?Password>/gi;
+/** Matches a `Type` attribute in a `Password` open tag, capturing its value. */
+const TYPE_ATTR_RE = /\bType\s*=\s*"([^"]*)"|\bType\s*=\s*'([^']*)'/i;
+/**
+ * Whether a `<Password>` open tag's `Type` attribute marks the value as a `#PasswordDigest` —
+ * not a secret, and never masked. Any other `Type` (including the WSS `#PasswordText` profile
+ * URI) or a missing `Type` attribute is treated as a plaintext password and masked.
+ */
+function isPasswordDigest(openTag) {
+    const match = TYPE_ATTR_RE.exec(openTag);
+    const value = match?.[1] ?? match?.[2];
+    return value !== undefined && value.endsWith('#PasswordDigest');
+}
+/**
+ * Masks the text content of `wsse:Password` elements (any namespace prefix) in raw XML — except
+ * a `#PasswordDigest` value, which is a hash, not a secret, and must reach the wire intact.
+ */
+export function redactXml(text, opts) {
+    if (opts?.show) {
+        return text;
+    }
+    // One forward pass. Each open tag is paired with the first close tag after it (what the lazy
+    // match did), and the scan resumes past that close tag. An open tag with no `>` or no close tag
+    // ends the pass: nothing later could pair either, which is exactly when the regex found nothing.
+    const open = new RegExp(PASSWORD_OPEN_RE.source, 'gi');
+    const close = new RegExp(PASSWORD_CLOSE_RE.source, 'gi');
+    let out = '';
+    let from = 0;
+    for (;;) {
+        open.lastIndex = from;
+        const opened = open.exec(text);
+        if (opened === null) {
+            break;
+        }
+        const tagEnd = text.indexOf('>', opened.index + opened[0].length);
+        if (tagEnd === -1) {
+            break;
+        }
+        close.lastIndex = tagEnd + 1;
+        const closed = close.exec(text);
+        if (closed === null) {
+            break;
+        }
+        const openTag = text.slice(opened.index, tagEnd + 1);
+        const content = isPasswordDigest(openTag) ? text.slice(tagEnd + 1, closed.index) : REDACTED;
+        out += `${text.slice(from, tagEnd + 1)}${content}${closed[0]}`;
+        from = closed.index + closed[0].length;
+    }
+    return out + text.slice(from);
+}
+/** Body keys whose values are masked in JSON and form bodies, compared case-insensitively. */
+export const SECRET_BODY_KEYS = [
+    'password',
+    'passwd',
+    'secret',
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'client_secret',
+    'api_key',
+    'apikey',
+    'authorization',
+];
+const SECRET_BODY_KEY_SET = new Set(SECRET_BODY_KEYS);
+function mediaTypeOf(contentType) {
+    return (contentType.split(';')[0] ?? '').trim().toLowerCase();
+}
+function isJsonType(contentType) {
+    const type = mediaTypeOf(contentType);
+    return type === 'application/json' || type.endsWith('+json');
+}
+function isFormType(contentType) {
+    return mediaTypeOf(contentType) === 'application/x-www-form-urlencoded';
+}
+/** A copy with every secret-keyed value replaced whole — a nested object or array under one too. */
+function maskJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(maskJson);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, inner]) => [
+            key,
+            SECRET_BODY_KEY_SET.has(key.toLowerCase()) ? REDACTED : maskJson(inner),
+        ]));
+    }
+    return value;
+}
+/** The indentation of the input's second line, so a pretty body stays pretty and a compact one compact. */
+function indentOf(text) {
+    const match = /\n( +)\S/.exec(text);
+    return match?.[1]?.length;
+}
+function maskFormPair(pair) {
+    const eq = pair.indexOf('=');
+    const rawKey = eq < 0 ? pair : pair.slice(0, eq);
+    let key;
+    try {
+        key = decodeURIComponent(rawKey.replace(/\+/g, ' '));
+    }
+    catch {
+        key = rawKey;
+    }
+    return SECRET_BODY_KEY_SET.has(key.toLowerCase()) ? `${rawKey}=${encodeURIComponent(REDACTED)}` : pair;
+}
+/**
+ * Masks secret-keyed values in a JSON (`application/json`, `+json`) or urlencoded form body;
+ * anything else, or JSON that does not parse, is returned as is.
+ */
+export function redactStructuredBody(text, contentType, opts) {
+    if (opts?.show === true || contentType === undefined) {
+        return text;
+    }
+    if (isJsonType(contentType)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+        return JSON.stringify(maskJson(parsed), null, indentOf(text));
+    }
+    if (isFormType(contentType)) {
+        return text.split('&').map(maskFormPair).join('&');
+    }
+    return text;
+}
+/** Masks a single raw `name: value` header line (no terminator), case-insensitively. */
+function redactHeaderLine(line) {
+    const idx = line.indexOf(':');
+    if (idx < 0) {
+        return line;
+    }
+    const name = line.slice(0, idx).trim().toLowerCase();
+    if (!SENSITIVE_HEADERS.has(name)) {
+        return line;
+    }
+    return `${line.slice(0, idx + 1)} ${REDACTED}`;
+}
+/** Content types whose body is text we may safely decode, mask and re-encode. */
+const TEXTUAL_CONTENT_TYPES = ['text/xml', 'application/soap+xml', 'application/xml', 'text/plain'];
+/** Reads the (first) value of `name` out of an already-decoded header block. */
+function headerValue(headerBlock, name) {
+    for (const line of headerBlock.split(/\r?\n/)) {
+        const idx = line.indexOf(':');
+        if (idx > 0 && line.slice(0, idx).trim().toLowerCase() === name) {
+            return line.slice(idx + 1).trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether the body bytes may be decoded as text and masked: only for a SOAP/XML/plain content
+ * type, and never when a `content-encoding` says the bytes are compressed (decoding those as
+ * text would corrupt them irrecoverably).
+ */
+function bodyIsIdentityEncoded(headerBlock) {
+    const encoding = headerValue(headerBlock, 'content-encoding');
+    return encoding === undefined || encoding.length === 0 || encoding.toLowerCase() === 'identity';
+}
+function bodyIsMaskableText(headerBlock) {
+    if (!bodyIsIdentityEncoded(headerBlock)) {
+        return false;
+    }
+    const contentType = headerValue(headerBlock, 'content-type')?.toLowerCase() ?? '';
+    return TEXTUAL_CONTENT_TYPES.some((type) => contentType.startsWith(type));
+}
+/**
+ * Redacts a raw HTTP message **on its bytes**, never assuming the whole message is UTF-8 text.
+ *
+ * The buffer is split at the first `\r\n\r\n` (falling back to `\n\n`); only the header block is
+ * decoded — as latin1, which is byte-preserving for the ASCII header grammar — so sensitive
+ * header lines can be masked while their original line terminators are re-joined verbatim. The
+ * body is decoded and masked (`wsse:Password`) only when the headers say it is uncompressed
+ * SOAP/XML/plain text; otherwise its bytes are copied through untouched, so a gzip or binary
+ * body round-trips byte-identically.
+ *
+ * `opts.encoding` says whether `input`/the return value is `'text'` (default) or a `'base64'`
+ * string, so callers can pass the wire's `rawRequestBase64`/`rawResponseBase64` straight through.
+ */
+export function redactRawHttp(input, opts) {
+    if (opts?.show) {
+        return input;
+    }
+    const isBase64 = opts?.encoding === 'base64';
+    const buffer = isBase64 ? Buffer.from(input, 'base64') : Buffer.from(input, 'utf8');
+    let separator = '\r\n\r\n';
+    let splitIndex = buffer.indexOf(separator);
+    if (splitIndex < 0) {
+        separator = '\n\n';
+        splitIndex = buffer.indexOf(separator);
+    }
+    const headerEnd = splitIndex >= 0 ? splitIndex : buffer.length;
+    const headerBlock = buffer.subarray(0, headerEnd).toString('latin1');
+    const bodyBytes = splitIndex >= 0 ? buffer.subarray(headerEnd + separator.length) : Buffer.alloc(0);
+    // Split keeping the terminators so `\r\n` and `\n` mixes survive the round trip verbatim.
+    const redactedHeaderBlock = headerBlock
+        .split(/(\r\n|\n)/)
+        .map((part, index) => (index % 2 === 0 ? redactHeaderLine(part) : part))
+        .join('');
+    // XML first (a `wsse:Password` element), then JSON and form bodies by key. A compressed body is
+    // left alone: its bytes are not the text either pass reads.
+    let bodyText = bodyIsMaskableText(headerBlock) ? redactXml(bodyBytes.toString('utf8')) : undefined;
+    const contentType = headerValue(headerBlock, 'content-type');
+    if (contentType !== undefined && bodyIsIdentityEncoded(headerBlock)) {
+        const before = bodyText ?? bodyBytes.toString('utf8');
+        const structured = redactStructuredBody(before, contentType);
+        if (structured !== before) {
+            bodyText = structured;
+        }
+    }
+    const redactedBody = bodyText === undefined ? bodyBytes : Buffer.from(bodyText, 'utf8');
+    const parts = [Buffer.from(redactedHeaderBlock, 'latin1')];
+    if (splitIndex >= 0) {
+        parts.push(Buffer.from(separator, 'latin1'), redactedBody);
+    }
+    const out = Buffer.concat(parts);
+    return isBase64 ? out.toString('base64') : out.toString('utf8');
+}

package/dist/redact/literal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Masks known secret *values* wherever they turn up. The pattern-based helpers beside this one
+ * know where a secret usually sits (an `Authorization` header, a `wsse:Password`); a runner also
+ * knows the values themselves, because it just read them from the environment, so it can catch the
+ * one that was interpolated somewhere no pattern looks — a query parameter, an assertion's
+ * "actual" text, an error message.
+ */
+/**
+ * Builds a function that replaces every occurrence of `values` — and the base64, percent-, form-,
+ * XML- and JSON-escaped forms of each — with the redaction marker.
+ */
+export declare function createSecretMasker(values: readonly string[]): (text: string) => string;

package/dist/redact/literal.js

@@ -0,0 +1,68 @@
+/**
+ * Masks known secret *values* wherever they turn up. The pattern-based helpers beside this one
+ * know where a secret usually sits (an `Authorization` header, a `wsse:Password`); a runner also
+ * knows the values themselves, because it just read them from the environment, so it can catch the
+ * one that was interpolated somewhere no pattern looks — a query parameter, an assertion's
+ * "actual" text, an error message.
+ */
+import { REDACTED_MARKER } from './index.js';
+/** Below this length a value is too likely to occur by chance; masking it would shred the text. */
+const MIN_MASKED_LENGTH = 4;
+/**
+ * The forms a value takes on the wire besides itself — each one the engine (or its XML serializer,
+ * or `URLSearchParams`) really writes somewhere:
+ * - percent-encoded, as `encodeURIComponent` puts it in a URL;
+ * - `application/x-www-form-urlencoded`, both as `rest/body.ts`'s `formEncode` writes a form body
+ *   and as `URLSearchParams` writes an OAuth2 token request (they differ on `~`);
+ * - XML text with the three entities `entitizeValue` and a DOM serializer emit (the SOAP envelope,
+ *   a WS-Security `wsse:Password`), and with all five, as `escapeForLanguage` escapes an XML body;
+ * - a JSON string's content, as `escapeForLanguage` escapes a JSON body or `JSON.stringify` writes
+ *   an error detail.
+ * A server echoing the value back is free to use any of them too.
+ */
+function encodedForms(value) {
+    const xml3 = value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return [
+        encodeURIComponent(value),
+        encodeURIComponent(value)
+            .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+            .replace(/%20/g, '+'),
+        new URLSearchParams({ v: value }).toString().slice(2),
+        xml3,
+        xml3.replace(/"/g, '&quot;').replace(/'/g, '&apos;'),
+        JSON.stringify(value).slice(1, -1),
+    ];
+}
+/**
+ * Builds a function that replaces every occurrence of `values` — and the base64, percent-, form-,
+ * XML- and JSON-escaped forms of each — with the redaction marker.
+ */
+export function createSecretMasker(values) {
+    const plain = values.filter((value) => value.length >= MIN_MASKED_LENGTH);
+    const needles = new Set();
+    for (const value of plain) {
+        needles.add(value);
+        for (const form of encodedForms(value)) {
+            // An escaped form is never shorter than the value, but the floor is kept explicit per needle.
+            if (form.length >= MIN_MASKED_LENGTH) {
+                needles.add(form);
+            }
+        }
+    }
+    // Longest first: a value that is a prefix of another must not leave the other's tail behind.
+    const ordered = [...needles].sort((a, b) => b.length - a.length);
+    return (text) => {
+        let out = maskBasicCredentials(text, plain);
+        for (const needle of ordered) {
+            out = out.split(needle).join(REDACTED_MARKER);
+        }
+        return out;
+    };
+}
+/** A Basic credential is base64 of `user:password`, so the password never appears literally. */
+function maskBasicCredentials(text, values) {
+    return text.replace(/\bBasic\s+([A-Za-z0-9+/=]{8,})/g, (whole, encoded) => {
+        const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+        return values.some((value) => decoded.includes(value)) ? `Basic ${REDACTED_MARKER}` : whole;
+    });
+}

package/dist/rest/auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Working out which credentials a REST request uses, and turning them into what goes on the wire.
+ *
+ * Two halves, both pure. {@link resolveAuthChain} walks the inheritance chain — request, then each
+ * folder outwards, then the API — and answers with the first configuration that is not `inherit`.
+ * {@link applyAuth} takes credentials the host has already resolved (values, not `secretRef`s) and
+ * says what to add to the headers or the query string.
+ *
+ * Basic and NTLM are deliberately *not* applied here: they may need a challenge round trip, which
+ * is the transport's job (`http/auth/*`), and this module never touches the network.
+ */
+import type { AuthConfig } from '../project/model.js';
+import type { SendAuth } from '../types.js';
+import type { KeyValueEntry } from './model.js';
+/**
+ * The credentials that actually apply, given a request's own configuration followed by its
+ * folders from the inside out and finally its API's.
+ *
+ * `inherit` means "ask the next one up", and an `undefined` link — a folder or API that configures
+ * nothing — is the same thing. Running out of chain means `none`: an API with no credentials
+ * authenticates its requests with none, rather than with whatever a sibling API happens to use.
+ */
+export declare function resolveAuthChain(chain: readonly (AuthConfig | undefined)[]): AuthConfig;
+/** Which link of a chain supplied the effective credentials, for the editor to explain. */
+export declare function resolveAuthChainIndex(chain: readonly (AuthConfig | undefined)[]): number;
+/** What {@link applyAuth} adds to a request. */
+export interface AppliedAuth {
+    /** Headers to merge in. A header the request set itself wins over these (see `rest/send.ts`). */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Query rows to append, for an API key that travels in the query string. */
+    readonly query: readonly KeyValueEntry[];
+    /**
+     * Credentials the transport has to handle itself, because they may need a challenge round trip:
+     * Basic and NTLM. Passed through to `sendHttp` untouched.
+     */
+    readonly transportAuth?: SendAuth;
+}
+/**
+ * Turns resolved credentials into headers, query rows, or a transport handoff.
+ *
+ * A Basic credential marked preemptive is still handed to the transport rather than encoded here,
+ * so there is exactly one implementation of the header and one of the challenge flow.
+ */
+export declare function applyAuth(auth: SendAuth | undefined): AppliedAuth;
+/**
+ * Whether a configuration still needs a secret the host has not resolved — a token, key or client
+ * secret whose reference is missing or empty.
+ *
+ * Used to tell "not configured yet" (a request being written) from "configured and broken" (a
+ * reference whose secret is gone, e.g. a project opened on another machine), which are different
+ * problems with different fixes.
+ */
+export declare function missingSecretRef(auth: AuthConfig): 'tokenRef' | 'valueRef' | 'clientSecretRef' | undefined;

package/dist/rest/auth.js

@@ -0,0 +1,80 @@
+/**
+ * Working out which credentials a REST request uses, and turning them into what goes on the wire.
+ *
+ * Two halves, both pure. {@link resolveAuthChain} walks the inheritance chain — request, then each
+ * folder outwards, then the API — and answers with the first configuration that is not `inherit`.
+ * {@link applyAuth} takes credentials the host has already resolved (values, not `secretRef`s) and
+ * says what to add to the headers or the query string.
+ *
+ * Basic and NTLM are deliberately *not* applied here: they may need a challenge round trip, which
+ * is the transport's job (`http/auth/*`), and this module never touches the network.
+ */
+/** Nothing configured anywhere in a chain means no credentials at all. */
+const NO_AUTH = { type: 'none' };
+/**
+ * The credentials that actually apply, given a request's own configuration followed by its
+ * folders from the inside out and finally its API's.
+ *
+ * `inherit` means "ask the next one up", and an `undefined` link — a folder or API that configures
+ * nothing — is the same thing. Running out of chain means `none`: an API with no credentials
+ * authenticates its requests with none, rather than with whatever a sibling API happens to use.
+ */
+export function resolveAuthChain(chain) {
+    for (const link of chain) {
+        if (link !== undefined && link.type !== 'inherit') {
+            return link;
+        }
+    }
+    return NO_AUTH;
+}
+/** Which link of a chain supplied the effective credentials, for the editor to explain. */
+export function resolveAuthChainIndex(chain) {
+    return chain.findIndex((link) => link !== undefined && link.type !== 'inherit');
+}
+/**
+ * Turns resolved credentials into headers, query rows, or a transport handoff.
+ *
+ * A Basic credential marked preemptive is still handed to the transport rather than encoded here,
+ * so there is exactly one implementation of the header and one of the challenge flow.
+ */
+export function applyAuth(auth) {
+    if (auth === undefined) {
+        return { headers: {}, query: [] };
+    }
+    switch (auth.type) {
+        case 'bearer':
+            return { headers: { Authorization: `${auth.scheme ?? 'Bearer'} ${auth.token}` }, query: [] };
+        case 'oauth2':
+            return { headers: { Authorization: `Bearer ${auth.accessToken}` }, query: [] };
+        case 'api-key':
+            return auth.in === 'header'
+                ? { headers: { [auth.name]: auth.value }, query: [] }
+                : { headers: {}, query: [{ name: auth.name, value: auth.value, enabled: true }] };
+        default:
+            return { headers: {}, query: [], transportAuth: auth };
+    }
+}
+/**
+ * Whether a configuration still needs a secret the host has not resolved — a token, key or client
+ * secret whose reference is missing or empty.
+ *
+ * Used to tell "not configured yet" (a request being written) from "configured and broken" (a
+ * reference whose secret is gone, e.g. a project opened on another machine), which are different
+ * problems with different fixes.
+ */
+export function missingSecretRef(auth) {
+    switch (auth.type) {
+        case 'bearer':
+            return auth.tokenRef === undefined || auth.tokenRef === '' ? 'tokenRef' : undefined;
+        case 'api-key':
+            return auth.valueRef === undefined || auth.valueRef === '' ? 'valueRef' : undefined;
+        case 'oauth2':
+            // A public client legitimately has no secret, so only a confidential one is incomplete
+            // without it: `clientAuth: 'basic'` is the confidential form.
+            return auth.clientAuth === 'basic' && (auth.clientSecretRef === undefined || auth.clientSecretRef === '')
+                ? 'clientSecretRef'
+                : undefined;
+        default:
+            return undefined;
+    }
+}