@wirebench/engine 2.2.1 → 3.1.0

package/dist/secrets/scan/apply.js

@@ -0,0 +1,194 @@
+import { SECRET_NAME_PATTERN, secretToken } from '../secret-token.js';
+/** The stored text a location is in: a URL finding's query key is left out, as the URL is one text. */
+function locationKey(location) {
+    if (location.kind === 'rest-url' || location.kind === 'ws-url') {
+        return JSON.stringify({ kind: location.kind, requestId: location.requestId });
+    }
+    return JSON.stringify(location);
+}
+/** Rewrites stored texts; records which moves applied and the raw values they replaced. */
+class Rewriter {
+    applied = new Map();
+    byKey = new Map();
+    constructor(moves) {
+        for (const move of moves) {
+            if (!SECRET_NAME_PATTERN.test(move.name))
+                continue;
+            const key = locationKey(move.finding.location);
+            const list = this.byKey.get(key) ?? [];
+            list.push(move);
+            this.byKey.set(key, list);
+        }
+    }
+    /** `text` with every move at `location` applied right to left; the same string when none apply. */
+    text(location, text) {
+        const moves = this.byKey.get(locationKey(location));
+        if (moves === undefined)
+            return text;
+        const sorted = [...moves].sort((a, b) => b.finding.valueStart - a.finding.valueStart);
+        let out = text;
+        let limit = Infinity;
+        for (const { finding, name } of sorted) {
+            const { valueStart: start, valueEnd: end, value, id } = finding;
+            // Compare against the original `text`: ranges index into it, and moves to the right only change `out` past `limit`.
+            if (this.applied.has(id) || end > limit || start >= end || text.slice(start, end) !== value)
+                continue;
+            out = out.slice(0, start) + secretToken(name) + out.slice(end);
+            limit = start;
+            this.applied.set(id, value);
+        }
+        return out;
+    }
+}
+/** `list` mapped by `fn`, or `list` itself when no element changed. */
+function mapShared(list, fn) {
+    let changed = false;
+    const out = list.map((item, index) => {
+        const next = fn(item, index);
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    return changed ? out : list;
+}
+function patch(obj, next) {
+    for (const key of Object.keys(next)) {
+        if (next[key] !== obj[key])
+            return { ...obj, ...next };
+    }
+    return obj;
+}
+function mapTree(node, fn) {
+    return patch(node, {
+        requests: mapShared(node.requests, fn),
+        folders: mapShared(node.folders, (folder) => mapTree(folder, fn)),
+    });
+}
+function keyedEntries(rw, kind, owner, entries) {
+    return mapShared(entries, (entry, index) => {
+        const location = { kind, ...owner, name: entry.name, index };
+        return patch(entry, { value: rw.text(location, entry.value) });
+    });
+}
+function properties(rw, props, location) {
+    let out;
+    for (const [name, value] of Object.entries(props)) {
+        const next = rw.text(location(name), value);
+        if (next !== value)
+            (out ??= { ...props })[name] = next;
+    }
+    return out ?? props;
+}
+function restBody(rw, requestId, body) {
+    if (body.kind === 'raw') {
+        return patch(body, { text: rw.text({ kind: 'rest-body', requestId }, body.text) });
+    }
+    // Built in the key order `walk.ts` uses: the location's JSON is the rewriter's key.
+    const field = (entry, index) => 'value' in entry
+        ? patch(entry, {
+            value: rw.text({ kind: 'rest-body', requestId, field: index, name: entry.name }, entry.value),
+        })
+        : entry;
+    if (body.kind === 'form')
+        return patch(body, { fields: mapShared(body.fields, field) });
+    if (body.kind === 'multipart')
+        return patch(body, { parts: mapShared(body.parts, field) });
+    return body;
+}
+function restRequest(rw, request) {
+    const requestId = request.id;
+    return patch(request, {
+        url: rw.text({ kind: 'rest-url', requestId }, request.url),
+        query: keyedEntries(rw, 'rest-query', { requestId }, request.query),
+        headers: keyedEntries(rw, 'rest-header', { requestId }, request.headers),
+        body: restBody(rw, requestId, request.body),
+    });
+}
+/**
+ * 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 function applySecretMoves(project, moves) {
+    const rw = new Rewriter(moves);
+    const next = patch(project, {
+        properties: properties(rw, project.properties, (name) => ({ kind: 'project-property', name })),
+        environments: mapShared(project.environments, (env) => patch(env, {
+            properties: properties(rw, env.properties, (name) => ({
+                kind: 'env-property',
+                environmentId: env.id,
+                name,
+            })),
+        })),
+        interfaces: mapShared(project.interfaces, (iface) => patch(iface, {
+            operations: mapShared(iface.operations, (operation) => patch(operation, {
+                requests: mapShared(operation.requests, (request) => patch(request, {
+                    headers: keyedEntries(rw, 'soap-header', { requestId: request.id }, request.headers),
+                    envelopeXml: rw.text({ kind: 'soap-body', requestId: request.id }, request.envelopeXml),
+                })),
+            })),
+        })),
+        apis: mapShared(project.apis, (api) => mapTree(api, (request) => restRequest(rw, request))),
+        ...(project.webhooks === undefined
+            ? {}
+            : { webhooks: mapTree(project.webhooks, (request) => restRequest(rw, request)) }),
+        grpcApis: mapShared(project.grpcApis, (api) => mapTree(patch(api, { metadata: keyedEntries(rw, 'grpc-api-metadata', { apiId: api.id }, api.metadata) }), (request) => patch(request, {
+            metadata: keyedEntries(rw, 'grpc-metadata', { requestId: request.id }, request.metadata),
+            message: rw.text({ kind: 'grpc-message', requestId: request.id }, request.message),
+        }))),
+        wsApis: mapShared(project.wsApis, (api) => mapTree(patch(api, { headers: keyedEntries(rw, 'ws-api-header', { apiId: api.id }, api.headers) }), (request) => patch(request, {
+            url: rw.text({ kind: 'ws-url', requestId: request.id }, request.url),
+            query: keyedEntries(rw, 'ws-query', { requestId: request.id }, request.query),
+            headers: keyedEntries(rw, 'ws-header', { requestId: request.id }, request.headers),
+            messages: mapShared(request.messages, (message) => message.format !== 'text'
+                ? message
+                : patch(message, {
+                    content: rw.text({ kind: 'ws-message', requestId: request.id, messageId: message.id }, message.content),
+                })),
+        }))),
+    });
+    const stale = moves.map((m) => m.finding.id).filter((id) => !rw.applied.has(id));
+    return { project: next, stale: [...new Set(stale)], values: Object.fromEntries(rw.applied) };
+}
+const RULE_NAMES = {
+    'sensitive-name': 'secret',
+    jwt: 'jwt',
+    bearer: 'bearer_token',
+    basic: 'basic_auth',
+    'url-credentials': 'url_password',
+    'aws-key': 'aws_access_key',
+    'private-key': 'private_key',
+    'vendor-token': 'api_token',
+    'high-entropy': 'secret',
+};
+function sanitize(raw) {
+    const name = raw
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+    if (name === '')
+        return '';
+    return /^[0-9]/.test(name) ? `_${name}` : name;
+}
+/**
+ * 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 function proposeSecretName(finding, taken) {
+    const { location } = finding;
+    const source = 'name' in location ? (location.name ?? '') : '';
+    const base = sanitize(source) || RULE_NAMES[finding.rule];
+    const lower = new Set([...taken].map((t) => t.toLowerCase()));
+    if (!lower.has(base))
+        return base;
+    for (let n = 2;; n++) {
+        const candidate = `${base}_${n}`;
+        if (!lower.has(candidate))
+            return candidate;
+    }
+}

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

@@ -0,0 +1,32 @@
+export type SecretRule = 'sensitive-name' | 'jwt' | 'bearer' | 'basic' | 'url-credentials' | 'aws-key' | 'private-key' | 'vendor-token' | 'high-entropy';
+/** One detected credential: its rule and its `[start, end)` range in the scanned text. */
+export interface SecretMatch {
+    readonly rule: SecretRule;
+    readonly start: number;
+    readonly end: number;
+    /** The decoded key of the form pair (a URL's query parameter) the value was found under. */
+    readonly name?: string;
+}
+export interface DetectContext {
+    /** The body's content type; `application/x-www-form-urlencoded` turns on form-pair detection. */
+    readonly contentType?: string;
+    /**
+     * The name the text is stored under (a header, query parameter, form field or property). When
+     * given, the text is one value: a non-empty value under a sensitive name is a finding as a whole.
+     */
+    readonly fieldName?: string;
+    /** Which name list {@link fieldName} is checked against; every list when absent. */
+    readonly nameKind?: 'header' | 'query' | 'field' | 'property';
+}
+/** Text beyond this many characters is not scanned (spec: bodies over 1 MiB, first 1 MiB only). */
+export declare const SECRET_TEXT_SCAN_LIMIT: number;
+/** Shannon entropy of `text`, in bits per character. */
+export declare function shannonEntropy(text: string): number;
+/**
+ * Every credential in `text`. With `context.fieldName` the text is one stored value (a header, a
+ * query parameter, a form field, a property); without it, a body, where JSON keys (a string or a
+ * number value), form fields and XML element local names (text content, or one CDATA section) in
+ * `SECRET_BODY_KEYS` count as sensitive names. Only the first
+ * {@link SECRET_TEXT_SCAN_LIMIT} characters are scanned.
+ */
+export declare function detectInText(text: string, context?: DetectContext): SecretMatch[];

package/dist/secrets/scan/rules.js

@@ -0,0 +1,346 @@
+/**
+ * Detection rules for the secret scanner (docs/specs/2026-09-22-secret-scanning-design.md §7):
+ * a value under a sensitive name, and credential shapes that are recognisable anywhere. Every match
+ * is the credential part only (`Bearer eyJ…` matches `eyJ…`), so replacing `[start, end)` with a
+ * `${secret:name}` token leaves the rest of the text as it was. A match that touches a `${…}`
+ * expansion is dropped: that value is already a reference, not a secret.
+ *
+ * `url-credentials` (the password of a `scheme://user:password@host` URL) is a shape rule, like
+ * `basic`: the credential is recognisable by where it sits in the text, not by a name it is stored
+ * under, so it applies to every scanned text — a URL, a property holding a connection string, a
+ * body.
+ *
+ * Pure module: no I/O.
+ */
+import { isSensitiveHeaderName, isSensitiveQueryParam, SECRET_BODY_KEYS } from '../../redact/index.js';
+/** Text beyond this many characters is not scanned (spec: bodies over 1 MiB, first 1 MiB only). */
+export const SECRET_TEXT_SCAN_LIMIT = 1024 * 1024;
+const BODY_KEY_SET = new Set(SECRET_BODY_KEYS);
+/** Name parts that make a name credential-like on their own (`dbPassword`, `client_secret`). */
+const CREDENTIAL_PARTS = new Set(['secret', 'token', 'password', 'passwd', 'credential', 'credentials']);
+/** Parts that make a following `key` credential-like (`apiKey`, `secret_key`); `cacheKey` is not. */
+const KEY_QUALIFIERS = new Set(['api', 'secret', 'access', 'private', 'signing', 'client', 'auth', 'master']);
+const HIGH_ENTROPY_MIN_LENGTH = 20;
+const HIGH_ENTROPY_MIN_BITS = 3.5;
+/** When two matches overlap, the one whose rule comes first here wins. */
+const RULE_PRIORITY = [
+    'private-key',
+    'jwt',
+    'vendor-token',
+    'aws-key',
+    'bearer',
+    'basic',
+    'url-credentials',
+    'sensitive-name',
+    'high-entropy',
+];
+const PEM_RE = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----/g;
+const JWT_RE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g;
+const VENDOR_RE = /(?<![A-Za-z0-9_])(?:gh[pos]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abpr]-[A-Za-z0-9-]{10,})/g;
+const AWS_RE = /(?<![A-Za-z0-9])(?:AKIA|ASIA)[A-Z0-9]{16}(?![A-Za-z0-9])/g;
+const BEARER_RE = /\bBearer[ \t]+([A-Za-z0-9._~+/-]+=*)/g;
+const BASIC_RE = /\bBasic[ \t]+([A-Za-z0-9+/]{8,}={0,2})(?![A-Za-z0-9+/=])/g;
+/**
+ * `scheme://user:password@`: group 1 is the password, which may be empty-user (`redis://:pw@`).
+ * Neither part crosses a delimiter, whitespace or a quote, so `host:8080/a@b` is a port, not a pair.
+ * The user may hold whole `${…}` expansions (`${env:user}`), colons inside them included. The
+ * scheme starts only where a run of scheme-like characters does (not after a letter, digit, `_`,
+ * `+`, `.` or `-`), so a long `a-a-a…` run is walked once, not once per letter.
+ */
+const URL_CREDENTIALS_RE = /(?<![\w+.-])[A-Za-z][A-Za-z0-9+.-]*:\/\/(?:\$\{[^{}]*\}|\$(?!\{)|[^\s/?#@:"'<>$])*:([^\s/?#@"'<>]+)(?=@)/g;
+/** URL passwords that stand for one rather than being one (`user:password@`, `u:****@`). */
+const PLACEHOLDER_PASSWORDS = new Set(['password', 'pass', 'passwd', 'secret']);
+/** A scheme prefix on a sensitive header's value, left in place when the credential is replaced. */
+const SCHEME_PREFIX_RE = /^(?:Bearer|Basic|Token|Digest|Negotiate|NTLM)[ \t]+/i;
+/**
+ * A key and its string value (group 2) or number value (group 3); `true`, `false`, `null` and the
+ * other kinds are not matched. The lookahead refuses a number that runs on (`12ab`).
+ */
+const JSON_PAIR_RE = /"((?:[^"\\\n]|\\.){1,128})"\s*:\s*(?:"((?:[^"\\]|\\.)*)"|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)(?![\w.+-]))/g;
+const XML_ELEMENT_RE = /<((?:[\w.-]+:)?([\w.-]+))((?:\s[^<>]*)?)>([^<]*)<\/\1>/g;
+/** An element's start tag, matched where it starts (sticky). */
+const XML_START_TAG_RE = /<((?:[\w.-]+:)?([\w.-]+))((?:\s[^<>]*)?)>/y;
+const CDATA_OPEN = '<![CDATA[';
+const CDATA_CLOSE = ']]>';
+const FORM_PAIR_RE = /(?:^|[&?])([^=&?#]+)=([^&#]*)/g;
+/** Shannon entropy of `text`, in bits per character. */
+export function shannonEntropy(text) {
+    if (text.length === 0)
+        return 0;
+    const counts = new Map();
+    for (const ch of text)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let bits = 0;
+    for (const count of counts.values()) {
+        const p = count / text.length;
+        bits -= p * Math.log2(p);
+    }
+    return bits;
+}
+/** `[start, end)` of every `${…}` expansion in `text`, nested braces included. */
+function expansionRanges(text) {
+    const ranges = [];
+    let from = 0;
+    for (;;) {
+        const open = text.indexOf('${', from);
+        if (open < 0)
+            return ranges;
+        let depth = 0;
+        let end = -1;
+        for (let i = open + 1; i < text.length; i++) {
+            const ch = text.charCodeAt(i);
+            if (ch === 123 /* { */)
+                depth++;
+            else if (ch === 125 /* } */ && --depth === 0) {
+                end = i + 1;
+                break;
+            }
+        }
+        if (end < 0)
+            return ranges;
+        ranges.push([open, end]);
+        from = end;
+    }
+}
+/** `dbPassword`, `api_key`, `X-Client-Secret` → lower-case word parts. */
+function nameParts(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((part) => part !== '');
+}
+/** True when a word part of `name` says it holds a credential. */
+function isCredentialLikeName(name) {
+    const parts = nameParts(name);
+    return parts.some((part, i) => CREDENTIAL_PARTS.has(part) || (part === 'key' && i > 0 && KEY_QUALIFIERS.has(parts[i - 1])));
+}
+function isSensitiveName(name, kind) {
+    const lower = name.trim().toLowerCase();
+    if (kind === 'property')
+        return BODY_KEY_SET.has(lower) || isCredentialLikeName(name);
+    if (kind === 'header')
+        return isSensitiveHeaderName(lower) || BODY_KEY_SET.has(lower);
+    if (kind === 'query')
+        return isSensitiveQueryParam(lower) || BODY_KEY_SET.has(lower);
+    if (kind === 'field')
+        return BODY_KEY_SET.has(lower);
+    return isSensitiveHeaderName(lower) || isSensitiveQueryParam(lower) || BODY_KEY_SET.has(lower);
+}
+function basicLooksReal(encoded) {
+    try {
+        return Buffer.from(encoded, 'base64').toString('latin1').includes(':');
+    }
+    catch {
+        return false;
+    }
+}
+function isPlaceholderPassword(password) {
+    return /^(?:\*+|[xX]+)$/.test(password) || PLACEHOLDER_PASSWORDS.has(password.toLowerCase());
+}
+function pushAll(out, re, text, rule, group) {
+    re.lastIndex = 0;
+    for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+        if (group === undefined) {
+            out.push({ rule, start: m.index, end: m.index + m[0].length });
+            continue;
+        }
+        const part = m[group];
+        const start = m.index + m[0].length - part.length;
+        // A token-shaped run of 16+ characters; words joined by `/` ("Bearer tokens/credentials") are prose.
+        if (rule === 'bearer' && (part.length < 16 || /^[A-Za-z]+(?:\/[A-Za-z]+)+$/.test(part)))
+            continue;
+        if (rule === 'basic' && !basicLooksReal(part))
+            continue;
+        if (rule === 'url-credentials' && isPlaceholderPassword(part))
+            continue;
+        out.push({ rule, start, end: start + part.length });
+    }
+}
+function shapeMatches(text) {
+    const out = [];
+    if (text.includes('-----BEGIN'))
+        pushAll(out, PEM_RE, text, 'private-key');
+    if (text.includes('eyJ'))
+        pushAll(out, JWT_RE, text, 'jwt');
+    if (text.includes('gh') || text.includes('github_pat_') || text.includes('xox'))
+        pushAll(out, VENDOR_RE, text, 'vendor-token');
+    if (text.includes('AKIA') || text.includes('ASIA'))
+        pushAll(out, AWS_RE, text, 'aws-key');
+    if (text.includes('Bearer'))
+        pushAll(out, BEARER_RE, text, 'bearer', 1);
+    if (text.includes('Basic'))
+        pushAll(out, BASIC_RE, text, 'basic', 1);
+    if (text.includes('://'))
+        pushAll(out, URL_CREDENTIALS_RE, text, 'url-credentials', 1);
+    return out;
+}
+/**
+ * The name-based match for one value stored under `name`, offset by `offset` in the scanned text:
+ * `sensitive-name` for a listed name (whatever the value looks like), else `high-entropy` for a
+ * long, random-looking value under a name that merely sounds secret.
+ */
+function nameMatch(value, offset, name, kind) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && /\s/.test(value[start]))
+        start++;
+    while (end > start && /\s/.test(value[end - 1]))
+        end--;
+    const scheme = SCHEME_PREFIX_RE.exec(value.slice(start, end));
+    if (scheme !== null && kind !== 'field' && kind !== 'property')
+        start += scheme[0].length;
+    if (start >= end)
+        return undefined;
+    if (isSensitiveName(name, kind))
+        return { rule: 'sensitive-name', start: offset + start, end: offset + end };
+    const core = value.slice(start, end);
+    if (isCredentialLikeName(name) &&
+        !/\s/.test(core) &&
+        !/^(?:[a-z][a-z0-9+.-]*:\/\/|[~.]?[/\\]|[A-Za-z]:[/\\])/i.test(core) &&
+        core.length >= HIGH_ENTROPY_MIN_LENGTH &&
+        shannonEntropy(core) >= HIGH_ENTROPY_MIN_BITS) {
+        return { rule: 'high-entropy', start: offset + start, end: offset + end };
+    }
+    return undefined;
+}
+function isWhitespaceCode(code) {
+    return code === 32 || code === 9 || code === 10 || code === 13;
+}
+/**
+ * Name matches for elements whose whole content is one CDATA section, whitespace around it
+ * allowed (`<Password><![CDATA[x]]></Password>`); the range is inside the section, so a Move keeps
+ * the wrapper. Each section is found with `indexOf`, and the start tag before it by walking back
+ * over whitespace to one `<…>`, so unclosed sections cannot make this quadratic.
+ */
+function cdataMatches(text, add) {
+    let from = 0;
+    for (;;) {
+        const open = text.indexOf(CDATA_OPEN, from);
+        if (open < 0)
+            return;
+        const valueStart = open + CDATA_OPEN.length;
+        const close = text.indexOf(CDATA_CLOSE, valueStart);
+        if (close < 0)
+            return;
+        from = close + CDATA_CLOSE.length;
+        let gt = open - 1;
+        while (gt >= 0 && isWhitespaceCode(text.charCodeAt(gt)))
+            gt--;
+        if (gt < 0 || text[gt] !== '>')
+            continue;
+        const lt = text.lastIndexOf('<', gt);
+        if (lt < 0)
+            continue;
+        XML_START_TAG_RE.lastIndex = lt;
+        const tag = XML_START_TAG_RE.exec(text);
+        if (tag === null || lt + tag[0].length !== gt + 1)
+            continue;
+        if (/PasswordDigest/.test(tag[3]))
+            continue;
+        let after = from;
+        while (after < text.length && isWhitespaceCode(text.charCodeAt(after)))
+            after++;
+        if (!text.startsWith(`</${tag[1]}>`, after))
+            continue;
+        add(nameMatch(text.slice(valueStart, close), valueStart, tag[2], 'field'));
+    }
+}
+function isFormType(contentType) {
+    return (contentType ?? '').split(';')[0].trim().toLowerCase() === 'application/x-www-form-urlencoded';
+}
+function structuredMatches(text, contentType, formNames) {
+    const out = [];
+    const add = (m) => {
+        if (m !== undefined)
+            out.push(m);
+    };
+    if (text.includes('":')) {
+        JSON_PAIR_RE.lastIndex = 0;
+        for (let m = JSON_PAIR_RE.exec(text); m !== null; m = JSON_PAIR_RE.exec(text)) {
+            const value = m[2];
+            if (value !== undefined) {
+                add(nameMatch(value, m.index + m[0].length - 1 - value.length, m[1], 'field'));
+            }
+            else if (isSensitiveName(m[1], 'field')) {
+                // A number under a sensitive key is a credential too (`"password": 123456`); its range is
+                // the digits alone, so a Move leaves a bare token that expands back to the same number.
+                // Digits alone never reach the high-entropy threshold, so only the name is checked.
+                const number = m[3];
+                add({ rule: 'sensitive-name', start: m.index + m[0].length - number.length, end: m.index + m[0].length });
+            }
+        }
+    }
+    if (text.includes('</')) {
+        XML_ELEMENT_RE.lastIndex = 0;
+        for (let m = XML_ELEMENT_RE.exec(text); m !== null; m = XML_ELEMENT_RE.exec(text)) {
+            // A WS-Security digest is a hash of the password, not the password; redaction keeps it too.
+            if (/PasswordDigest/.test(m[3]))
+                continue;
+            const value = m[4];
+            const closeLength = m[1].length + 3;
+            add(nameMatch(value, m.index + m[0].length - closeLength - value.length, m[2], 'field'));
+        }
+        if (text.includes(CDATA_OPEN))
+            cdataMatches(text, add);
+    }
+    if (isFormType(contentType)) {
+        FORM_PAIR_RE.lastIndex = 0;
+        for (let m = FORM_PAIR_RE.exec(text); m !== null; m = FORM_PAIR_RE.exec(text)) {
+            let key = m[1];
+            try {
+                key = decodeURIComponent(key.replace(/\+/g, ' '));
+            }
+            catch {
+                // keep the raw key
+            }
+            const value = m[2];
+            const match = nameMatch(value, m.index + m[0].length - value.length, key, formNames);
+            if (match !== undefined)
+                out.push({ ...match, name: key });
+        }
+    }
+    return out;
+}
+/** Drops matches inside or across an expansion, then overlaps, keeping the higher-priority rule. */
+function settle(matches, text) {
+    if (matches.length === 0)
+        return matches;
+    const expansions = text.includes('${') ? expansionRanges(text) : [];
+    const live = matches.filter((m) => m.end > m.start && !expansions.some(([s, e]) => m.start < e && s < m.end));
+    live.sort((a, b) => a.start - b.start || RULE_PRIORITY.indexOf(a.rule) - RULE_PRIORITY.indexOf(b.rule) || b.end - a.end);
+    const kept = [];
+    for (const m of live) {
+        const clash = kept.findIndex((k) => m.start < k.end && k.start < m.end);
+        if (clash < 0) {
+            kept.push(m);
+        }
+        else if (RULE_PRIORITY.indexOf(m.rule) < RULE_PRIORITY.indexOf(kept[clash].rule)) {
+            kept[clash] = m;
+        }
+    }
+    return kept.sort((a, b) => a.start - b.start);
+}
+/**
+ * Every credential in `text`. With `context.fieldName` the text is one stored value (a header, a
+ * query parameter, a form field, a property); without it, a body, where JSON keys (a string or a
+ * number value), form fields and XML element local names (text content, or one CDATA section) in
+ * `SECRET_BODY_KEYS` count as sensitive names. Only the first
+ * {@link SECRET_TEXT_SCAN_LIMIT} characters are scanned.
+ */
+export function detectInText(text, context = {}) {
+    const scanned = text.length > SECRET_TEXT_SCAN_LIMIT ? text.slice(0, SECRET_TEXT_SCAN_LIMIT) : text;
+    if (scanned.length === 0)
+        return [];
+    const matches = shapeMatches(scanned);
+    if (context.fieldName !== undefined) {
+        const named = nameMatch(scanned, 0, context.fieldName, context.nameKind);
+        if (named !== undefined && matches.length === 0)
+            matches.push(named);
+    }
+    else {
+        matches.push(...structuredMatches(scanned, context.contentType, context.nameKind ?? 'field'));
+    }
+    return settle(matches, scanned);
+}

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

@@ -0,0 +1,6 @@
+import type { Project } from '../../project/model.js';
+import type { SecretFinding } from './walk.js';
+/** Every finding in `project`. The same project always yields the same findings with the same ids. */
+export declare function scanProjectForSecrets(project: Project): SecretFinding[];
+/** The only form of a value that leaves main: its first 3 characters, `…`, and its length. */
+export declare function maskedPreview(value: string): string;

package/dist/secrets/scan/scan.js

@@ -0,0 +1,57 @@
+/**
+ * `scanProjectForSecrets`: every credential stored in plain text in a project, for the review
+ * dialog shown before a manual save or Sync commit (docs/specs/2026-09-22-secret-scanning-design.md).
+ *
+ * Pure module: no I/O.
+ */
+import { createHash } from 'node:crypto';
+import { detectInText } from './rules.js';
+import { scanTargets } from './walk.js';
+/**
+ * The id of the `occurrence`-th (from 0) match of `value` in the text at `location`. Counting equal
+ * values rather than taking the offset keeps an id when text before it is edited. The value goes
+ * last, after two NUL-ended fields (a location's JSON holds no raw NUL), so no value can be read as
+ * another value's occurrence.
+ */
+function findingId(location, value, occurrence) {
+    return createHash('sha256')
+        .update(JSON.stringify(location))
+        .update('\0')
+        .update(String(occurrence))
+        .update('\0')
+        .update(value)
+        .digest('hex')
+        .slice(0, 16);
+}
+/** Every finding in `project`. The same project always yields the same findings with the same ids. */
+export function scanProjectForSecrets(project) {
+    const findings = [];
+    for (const target of scanTargets(project)) {
+        const matches = detectInText(target.text, target.context);
+        const seen = new Map();
+        const { location } = target;
+        const inUrl = location.kind === 'rest-url' || location.kind === 'ws-url';
+        for (const match of matches) {
+            const value = target.text.slice(match.start, match.end);
+            const occurrence = seen.get(value) ?? 0;
+            seen.set(value, occurrence + 1);
+            // A URL finding under a query parameter carries its key, for the name the dialog proposes.
+            const at = inUrl && match.name !== undefined ? { ...location, name: match.name } : location;
+            findings.push({
+                id: findingId(at, value, occurrence),
+                location: at,
+                rule: match.rule,
+                label: target.label,
+                valueStart: match.start,
+                valueEnd: match.end,
+                value,
+            });
+        }
+    }
+    return findings;
+}
+/** The only form of a value that leaves main: its first 3 characters, `…`, and its length. */
+export function maskedPreview(value) {
+    const shown = value.length > 6 ? value.slice(0, 3) : '';
+    return `${shown}… (${value.length} chars)`;
+}