@zackbart/connecta 0.32.0 → 0.33.0

package/dist/providers/_shared/rest/value-safety.js

@@ -1,3 +1,40 @@
+// Value safety for every REST vendor (decision 0005): no tool response,
+// success or error, returns a credential (API, service, or bypass tokens,
+// signing secrets, bearer URLs, private keys, temporary credentials, auth
+// headers, authorization verifiers) or a stored secret value (environment
+// variables, secret items), unless a reviewed named tool exists to return it.
+//
+// One mechanism, strongest layer first:
+//
+// 1. Refuse by operation. `scripts/value-safety.mjs` flags every operation in
+//    a vendor's pinned spec whose response may carry one; `providers:spec`
+//    commits the result as `value-safety.candidates.json`. Each needs a
+//    reviewed verdict in the vendor's `value-safety.ts` table, and the shared
+//    harness (`test/fixtures/value-safety.ts`) fails on any flagged operation
+//    without one, a stale pin, a verdict for an operation the index lacks, a
+//    flagged field no verdict accounts for, or a refusal that reaches
+//    transport.
+// 2. Reviewed field paths for `redact` verdicts, on every success body the
+//    vendor returns (generic tools, HEAD data, named tools, uploads, logs),
+//    after any envelope unwrap and before cursors or `select` read it; then
+//    resource rules on every object whose type discriminator they name,
+//    wherever an expansion, list, or event embeds it.
+// 3. A key-name heuristic, defense in depth only, over every body: any
+//    subtree under a credential-named key, labelled or typed secret records,
+//    environment containers, header rules, and URLs with userinfo or
+//    credential query parameters.
+// 4. Errors: an operation with a verdict, or whose request accepts a
+//    credential-named field, answers failures with the vendor's codes and
+//    statuses but never its text (`withholdsErrors`), unless its review
+//    found its errors cannot echo a stored secret (`vendorErrors`).
+//
+// Residual risk, as with Infisical: a secret a person typed into a free-text
+// name, description, log line, or identifier is out of scope.
+//
+// The key-name rules combine Cloudflare's and Vercel's former engines.
+// URL policy and exemptions are reviewed per vendor in its table (`keep`,
+// `fields`, `scopeMaps`, `envBodies`, `embeddedUrls`).
+import { ConnectorCallError } from "../../../errors.js";
 /** What a removed secret reads as. */
 export const REDACTED = "[redacted]";
 /** Credential vocabulary over normalized names, matched anywhere; mirrors `scripts/value-safety.mjs`. */
@@ -159,7 +196,7 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** A URL without userinfo, credential query parameters, or a credential-looking fragment; anything unparseable is withheld. */
-function sanitizeUrl(value) {
+function sanitizeUrl(value, credentials = true) {
     let url;
     try {
         url = new URL(value);
@@ -174,19 +211,624 @@ function sanitizeUrl(value) {
         changed = true;
     }
     // A snapshot of the names: setting a parameter while iterating the live list is unsafe.
-    for (const name of Array.from(url.searchParams.keys())) {
+    for (const name of credentials ? Array.from(url.searchParams.keys()) : []) {
         if (URL_PARAM_CONTAINS.test(name) || URL_PARAM_SUFFIX.test(name.toLowerCase().replace(/[_-]/g, ""))) {
             url.searchParams.set(name, REDACTED);
             changed = true;
         }
     }
-    if (url.hash && /token|secret|key|code|auth/i.test(url.hash)) {
+    if (credentials && url.hash && /token|secret|key|code|auth/i.test(url.hash)) {
         url.hash = "";
         changed = true;
     }
     // An ordinary URL comes back exactly as the vendor sent it.
     return changed ? url.toString() : value;
 }
+/** Signing parameters that are a credential in any URL, with their `=` plain or encoded. */
+const SIGNING_PARAM = /x-(?:amz|goog)-(?:signature|credential|security-token)(?:=|%(?:25)*3d|&#0*61;?|&#x0*3d;?|=?|\\u003d)/gi;
+/**
+ * One encoded character at the start of link text: a percent escape, an HTML
+ * character reference, a `\u` or `\x` escape, or a Markdown backslash escape.
+ */
+const LEADING_ESCAPE = /^(?:%([0-9a-f]{2})|&(?:#(\d{1,7})|#x([0-9a-f]{1,6})|(amp|quot|apos|lt|gt|quest|num|semi|equals|sol|percnt|bsol));?|\\u([0-9a-f]{4})|\\x([0-9a-f]{2})|\\)/i;
+/** One encoded character just before a host: the same escapes, read backwards over a few characters. */
+const TRAILING_ESCAPE = /(?:%(?:25){0,4}([0-9a-f]{2})|&(?:#0{0,6}(\d{1,7})|#x0{0,6}([0-9a-f]{1,6})|([a-z]{2,6}));?|\\u([0-9a-f]{4})|\\x([0-9a-f]{2})|\\)$/i;
+/** Every escape in link text, decoded together; an unknown entity name stays as written. */
+const ESCAPES = /%([0-9a-f]{2})|&(?:#(\d{1,7})|#x([0-9a-f]{1,6})|([a-z]{2,8}));?|\\u([0-9a-f]{4})|\\x([0-9a-f]{2})|\\(?=[^a-z0-9])/gi;
+/** One slash however it is spelled, read forwards. */
+const SLASH = /\/|\\\/|%(?:25){0,4}2f|&#0{0,6}47;?|&#x0{0,6}2f;?|/?|\\u002f|\\x2f/iy;
+/** An S3 endpoint host: global, regional, dual-stack, or accelerated. */
+const S3_ENDPOINT = String.raw `s3(?:[.-](?:dualstack|accelerate|external-1|[a-z]{2}(?:-[a-z]{1,12}){1,3}-\d{1,2})){0,2}\.amazonaws\.com`;
+const NAMED = {
+    amp: "&",
+    colon: ":",
+    quot: '"',
+    apos: "'",
+    lt: "<",
+    gt: ">",
+    quest: "?",
+    num: "#",
+    semi: ";",
+    equals: "=",
+    sol: "/",
+    percnt: "%",
+    bsol: "\\",
+    lbrack: "[",
+    rbrack: "]",
+    lsqb: "[",
+    rsqb: "]",
+    period: ".",
+};
+/** A host name's label character: the subdomain labels before a reviewed name are these alone. */
+const LABEL = /[a-z0-9.-]/i;
+/** The longest host name DNS allows: the bound on authority inspection. */
+const MAX_HOST = 253;
+/** The longest scheme read back from its `:`. */
+const MAX_SCHEME = 32;
+const SCHEME_CHAR = /[a-z0-9+.-]/i;
+/** What may open a scheme-less `//host`: whitespace or punctuation that opens a link, value, or attribute. */
+const OPENS_LINK = /[\s"'`(<[{=,;|]/;
+/** Punctuation that may close the syntax around a link; it carries no secret, so it comes back. */
+const TRAILING = /[)\]}.,;:!*_~`\\]/;
+/** Code points past Unicode's range decode to nothing rather than throw. */
+function codePoint(value) {
+    return value <= 0x10ffff ? String.fromCodePoint(value) : "";
+}
+/** The character an escape's groups spell: percent, decimal, hex, name, `\u`, `\x`; a bare backslash spells nothing. */
+function unescaped(groups) {
+    const [percent, decimal, hex, name, unicode, byte] = groups;
+    if (percent !== undefined)
+        return String.fromCharCode(Number.parseInt(percent, 16));
+    if (decimal !== undefined)
+        return codePoint(Number(decimal));
+    if (hex !== undefined)
+        return codePoint(Number.parseInt(hex, 16));
+    if (name !== undefined)
+        return NAMED[name.toLowerCase()];
+    if (unicode !== undefined || byte !== undefined)
+        return String.fromCharCode(Number.parseInt((unicode ?? byte), 16));
+    return "";
+}
+/**
+ * Whether link text opens its query or fragment here once decoded as a
+ * browser, a Markdown renderer, or a JSON parser would: `%3F`, `%253F`,
+ * `&#63;`, `&amp;#35;`, `?`. Only the leading character matters, so
+ * each round decodes one escape there: constant work.
+ */
+function opener(text, at) {
+    let current = text.slice(at, at + 32);
+    for (let round = 0; round < 4; round++) {
+        if (current[0] === "?" || current[0] === "#")
+            return current[0];
+        const escape = LEADING_ESCAPE.exec(current);
+        if (!escape)
+            return undefined;
+        current = (unescaped(escape.slice(1)) ?? "") + current.slice(escape[0].length);
+    }
+    return current[0] === "?" || current[0] === "#" ? current[0] : undefined;
+}
+/** The character ending just before `at`, decoded if it is escaped, and how many characters spell it. */
+function charBefore(text, at) {
+    const escape = TRAILING_ESCAPE.exec(text.slice(Math.max(0, at - 16), at));
+    const char = escape ? unescaped(escape.slice(1)) : undefined;
+    if (escape && char)
+        return { char, length: escape[0].length };
+    // A JSON-escaped slash, `\/`, is one slash.
+    if (text[at - 1] === "/" && text[at - 2] === "\\")
+        return { char: "/", length: 2 };
+    return { char: text[at - 1], length: 1 };
+}
+/**
+ * Where the link whose authority opens at `at` starts, or `-1` when no
+ * authority opens there: `//` however spelled, after a scheme's `:`
+ * (`https:`, `https%3A`), the text's start, or what opens a scheme-less
+ * link (`src=//`, ` //`). A `//` after anything else (`example.com//`) is
+ * part of a path.
+ */
+function authorityAt(text, at) {
+    if (at === 0)
+        return -1;
+    const second = charBefore(text, at);
+    const between = at - second.length;
+    if (second.char !== "/" || between <= 0)
+        return -1;
+    const first = charBefore(text, between);
+    const slashes = between - first.length;
+    if (first.char !== "/" || slashes < 0)
+        return -1;
+    if (slashes === 0)
+        return 0;
+    const before = charBefore(text, slashes);
+    if (before.char !== ":")
+        return OPENS_LINK.test(before.char) ? slashes : -1;
+    const colon = slashes - before.length;
+    let start = colon;
+    while (start > 0 && colon - start < MAX_SCHEME && SCHEME_CHAR.test(text[start - 1]))
+        start--;
+    return start < colon && (start === 0 || OPENS_LINK.test(text[start - 1])) ? start : -1;
+}
+/** Where a host's optional trailing dot and port end after `at`, or `-1` when a `:` holds no port (userinfo's password). */
+function afterPort(text, at) {
+    if (text[at] === ".")
+        at++;
+    if (text[at] !== ":")
+        return at;
+    let digits = at + 1;
+    while (digits - at <= 5 && /\d/.test(text[digits] ?? ""))
+        digits++;
+    return digits > at + 1 ? digits : -1;
+}
+/**
+ * Whether a host or path segment ends at `at`: a slash, query, or fragment
+ * however spelled, or the link's end. Never another
+ * name character or an `@`: `file.notion.so@evil.com` names userinfo, and
+ * `prod-files-secure@other` and `prod-files-securex` are other segments.
+ */
+function boundary(text, at) {
+    if (at < 0)
+        return false;
+    if (at >= text.length)
+        return true;
+    if (endsLink(text.charCodeAt(at), text[at]))
+        return true;
+    SLASH.lastIndex = at;
+    return SLASH.test(text) || opener(text, at) !== undefined;
+}
+/** Whether the `#` at `at` belongs to a numeric character reference (`&#38;`) rather than opening a fragment. */
+function reference(text, at) {
+    return text.charCodeAt(at - 1) === 0x26 && /[0-9x]/i.test(text[at + 1] ?? "");
+}
+/** Whitespace, a quote, or an angle bracket: where a link in text ends, read fail-closed. */
+function endsLink(code, char) {
+    if (code <= 0x20 || code === 0x22 || code === 0x27 || code === 0x3c || code === 0x3e)
+        return true;
+    return code > 0x7f && /\s/.test(char);
+}
+/** Where a signing parameter's value ends: its link's end, or the next parameter or closing bracket. */
+function endsValue(text, at) {
+    const code = text.charCodeAt(at);
+    if (endsLink(code, text[at]))
+        return true;
+    if (code === 0x26 || code === 0x23 || code === 0x29 || code === 0x5d || code === 0x60)
+        return true;
+    // `\/` is a JSON-escaped slash inside the value; any other backslash escapes what follows it.
+    return code === 0x5c && text.charCodeAt(at + 1) !== 0x2f;
+}
+const HOST_MATCHERS = new WeakMap();
+function hostMatcher(hosts) {
+    let matcher = HOST_MATCHERS.get(hosts);
+    if (!matcher) {
+        matcher = {
+            endpoint: new RegExp(`^${S3_ENDPOINT}$`, "i"),
+            domains: hosts.domains.map((host) => host.toLowerCase()),
+            buckets: hosts.buckets.map((bucket) => bucket.toLowerCase()),
+        };
+        HOST_MATCHERS.set(hosts, matcher);
+    }
+    return matcher;
+}
+/** The end of a reviewed file authority, read only at the current URL's host. */
+function fileHost(text, start, matcher) {
+    let end = start;
+    while (end < text.length && end - start <= MAX_HOST && LABEL.test(text[end]))
+        end++;
+    if (end === start || end - start > MAX_HOST)
+        return undefined;
+    const port = afterPort(text, end);
+    if (!boundary(text, port))
+        return undefined;
+    const name = text.slice(start, end).toLowerCase().replace(/\.$/, "");
+    if (matcher.domains.some((domain) => name === domain || name.endsWith(`.${domain}`)))
+        return end;
+    if (matcher.buckets.some((bucket) => name.startsWith(`${bucket}.`) && matcher.endpoint.test(name.slice(bucket.length + 1)))) {
+        return end;
+    }
+    if (!matcher.endpoint.test(name))
+        return undefined;
+    SLASH.lastIndex = port;
+    if (!SLASH.test(text))
+        return undefined;
+    const segment = SLASH.lastIndex;
+    for (const bucket of matcher.buckets) {
+        const after = segment + bucket.length;
+        if (text.slice(segment, after).toLowerCase() === bucket && boundary(text, after))
+            return after;
+    }
+    return undefined;
+}
+/** The authority immediately after a destination's scheme and slashes, however escaped. */
+function destinationHost(text, start) {
+    // A scheme and three escaped characters (colon and slashes), each bounded
+    // as in charBefore. Never search a destination's path or query for another.
+    for (let at = start; at < Math.min(text.length, start + MAX_SCHEME + 48); at++) {
+        SLASH.lastIndex = at;
+        if (!SLASH.test(text))
+            continue;
+        const next = SLASH.lastIndex;
+        SLASH.lastIndex = next;
+        if (!SLASH.test(text))
+            return undefined;
+        const host = SLASH.lastIndex;
+        return authorityAt(text, host) === start ? host : undefined;
+    }
+    return undefined;
+}
+/** CommonMark permits spaces/tabs and at most one line ending before a destination. */
+function markdownStart(text, at) {
+    let line = false;
+    for (; at < text.length; at++) {
+        const char = text[at];
+        if (char === " " || char === "\t")
+            continue;
+        if (char !== "\r" && char !== "\n")
+            return at;
+        if (line)
+            return undefined;
+        line = true;
+        if (char === "\r" && text[at + 1] === "\n")
+            at++;
+    }
+    return at;
+}
+/**
+ * Read a destination once. Admission ends at its actual CommonMark close,
+ * counting balanced and escaped parentheses. Redaction with a query keeps
+ * its separate fail-closed span through whitespace, a quote, or an angle
+ * bracket, since parentheses can also be part of a signed value.
+ */
+function linkSpan(text, start, host, inline, redact) {
+    let depth = 0;
+    let escaped = false;
+    let cut = -1;
+    let open = "?";
+    let end = start;
+    for (; end < text.length; end++) {
+        const code = text.charCodeAt(end);
+        if (endsLink(code, text[end]))
+            break;
+        if (inline) {
+            if (escaped)
+                escaped = false;
+            else if (code === 0x5c)
+                escaped = true;
+            else if (code === 0x28)
+                depth++;
+            else if (code === 0x29 && depth-- === 0)
+                break;
+        }
+        if (host === undefined || end < host || cut >= 0)
+            continue;
+        if (code === 0x3f || (code === 0x23 && !reference(text, end))) {
+            cut = end;
+            open = text[end];
+        }
+        else if (code === 0x25 || code === 0x26 || code === 0x5c) {
+            const opens = opener(text, end);
+            if (opens) {
+                cut = end;
+                open = opens;
+            }
+        }
+    }
+    if (redact && cut >= 0) {
+        while (end < text.length && !endsLink(text.charCodeAt(end), text[end]))
+            end++;
+    }
+    return { cut, open, end };
+}
+/**
+ * Scan destinations, including ones at other hosts, so an outer URL owns
+ * every byte of its path and query. A nested scheme or // cannot re-anchor
+ * file-host matching. Each consumed span is skipped in full; admission and
+ * redaction choose their own span boundary, and both stay linear.
+ */
+function* hostLinks(text, hosts, redact) {
+    const matcher = hosts ? hostMatcher(hosts) : undefined;
+    // The first URL delimiter in the current text run also protects relative
+    // paths/queries such as /proxy/https://… and image?url=//… .
+    let firstReference = -1;
+    for (let at = 0; at < text.length; at++) {
+        const char = text[at];
+        if (endsLink(text.charCodeAt(at), char)) {
+            firstReference = -1;
+            continue;
+        }
+        if (char === "]" && text[at + 1] === "(") {
+            const destination = markdownStart(text, at + 2);
+            if (destination !== undefined) {
+                const angle = text[destination] === "<";
+                const start = destination + (angle ? 1 : 0);
+                const authority = destinationHost(text, start);
+                // Generic policy inspects a relative destination's own query/fragment.
+                // Host policy must still attribute the leading authority to the vendor.
+                const host = matcher
+                    ? authority === undefined
+                        ? undefined
+                        : fileHost(text, authority, matcher)
+                    : (authority ?? start);
+                const span = linkSpan(text, start, host, !angle, redact);
+                at = Math.max(destination, span.end) - 1;
+                firstReference = -1;
+                if (host !== undefined)
+                    yield span;
+                continue;
+            }
+        }
+        if (char === "/" || char === "\\" || char === "%" || char === "&") {
+            SLASH.lastIndex = at;
+            if (SLASH.test(text)) {
+                const next = SLASH.lastIndex;
+                SLASH.lastIndex = next;
+                if (SLASH.test(text)) {
+                    const authority = SLASH.lastIndex;
+                    const start = authorityAt(text, authority);
+                    // Global parameter scanning needs no host attribution. This also
+                    // catches a URL after a log label such as `download:https://…`.
+                    // File-host policy keeps the stricter authority/proxy boundary.
+                    if (!matcher || (start >= 0 && (firstReference < 0 || firstReference >= start))) {
+                        const host = matcher ? fileHost(text, authority, matcher) : authority;
+                        const span = linkSpan(text, authority, host, false, redact);
+                        at = span.end - 1;
+                        firstReference = -1;
+                        if (host !== undefined)
+                            yield span;
+                        continue;
+                    }
+                }
+                if (firstReference < 0)
+                    firstReference = at;
+            }
+        }
+        if (firstReference < 0 && (char === ":" || char === "?" || (char === "#" && !reference(text, at)))) {
+            firstReference = at;
+        }
+    }
+}
+/**
+ * `text` with every pre-signed link withheld: at one of `hosts` (Notion's
+ * file storage, say), its whole query and fragment; anywhere, a signing
+ * parameter's value. Everything else comes back byte for byte.
+ */
+export function withholdSignedLinks(text, hosts) {
+    return withholdSigningParams(withholdLinkQueries(text, hosts));
+}
+/** A credential-named parameter in a URL, rather than an assignment in prose. */
+function credentialQuery(text) {
+    let decoded = decodeLinkText(text, false);
+    // Decode the destination's enclosing percent layers only until its own
+    // opener is visible. Encoded &/# inside a proxy parameter remain data,
+    // rather than becoming parameters or a fragment of the outer URL.
+    for (let round = 0; round < 4 && decoded[0] !== "?" && decoded[0] !== "#"; round++) {
+        const next = decoded.replace(/%([0-9a-f]{2})/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+        if (next === decoded)
+            break;
+        decoded = next;
+    }
+    const fragment = decoded.indexOf("#");
+    if (fragment >= 0 && /token|secret|key|code|auth/i.test(decodeLinkText(decoded.slice(fragment + 1))))
+        return true;
+    const query = fragment < 0 ? decoded : decoded.slice(0, fragment);
+    for (let at = query[0] === "?" ? 1 : 0; at < query.length;) {
+        const next = query.indexOf("&", at);
+        const end = next < 0 ? query.length : next;
+        const pair = decodeLinkText(query.slice(at, end));
+        const equals = pair.indexOf("=");
+        at = end + 1;
+        if (equals < 0)
+            continue;
+        const name = pair.slice(0, equals);
+        if (!URL_PARAM_CONTAINS.test(name) && !URL_PARAM_SUFFIX.test(normalizedName(name)))
+            continue;
+        if (pair.slice(equals + 1) !== REDACTED)
+            return true;
+    }
+    return false;
+}
+/** Remove a link's entire query/fragment, keeping its surrounding syntax. */
+function withholdLinkQueries(text, hosts) {
+    let out = "";
+    let copied = 0;
+    for (const { cut, open, end } of hostLinks(text, hosts, hosts !== undefined)) {
+        if (cut < 0)
+            continue;
+        if (!hosts && !credentialQuery(text.slice(cut, end)))
+            continue;
+        let keep = end;
+        while (keep > cut + 1 && TRAILING.test(text[keep - 1])) {
+            // A signing pass may already have replaced the final parameter. Its
+            // closing bracket belongs to the value, not the surrounding Markdown.
+            if (text.endsWith(REDACTED, keep))
+                break;
+            keep--;
+        }
+        // A query with nothing in it.
+        if (keep <= cut + 1)
+            continue;
+        out += `${text.slice(copied, cut)}${open}${REDACTED}`;
+        copied = keep;
+    }
+    return copied === 0 ? text : out + text.slice(copied);
+}
+function withholdSigningParams(anchored) {
+    let out = "";
+    let copied = 0;
+    SIGNING_PARAM.lastIndex = 0;
+    for (let match = SIGNING_PARAM.exec(anchored); match; match = SIGNING_PARAM.exec(anchored)) {
+        const start = match.index + match[0].length;
+        // Skip an existing complete placeholder, but still remove any suffix.
+        const already = anchored.startsWith(REDACTED, start);
+        let end = already ? start + REDACTED.length : start;
+        while (end < anchored.length && !endsValue(anchored, end))
+            end++;
+        SIGNING_PARAM.lastIndex = end;
+        if (end === start || (already && end === start + REDACTED.length))
+            continue;
+        out += `${anchored.slice(copied, start)}${REDACTED}`;
+        copied = end;
+    }
+    return copied === 0 ? anchored : out + anchored.slice(copied);
+}
+/**
+ * Reviewed REST text policy: only credential-bearing URL queries/fragments
+ * change. Ordinary links, including external proxies, retain their bytes.
+ * Literal AWS/Google signing names are withheld anywhere, as in #818.
+ */
+export function withholdEmbeddedUrls(text) {
+    return withholdSigningParams(withholdLinkQueries(text));
+}
+/** Every string inside a JSON value through `withholdSignedLinks`; unchanged values keep their identity. */
+export function withholdSignedLinksIn(value, hosts, depth = 0) {
+    return mapStrings(value, (text) => withholdSignedLinks(text, hosts), depth);
+}
+/** Apply the reviewed text policy to a selected value or vendor error body. */
+export function withholdEmbeddedUrlsIn(value) {
+    return mapStrings(value, withholdEmbeddedUrls, 0);
+}
+function mapStrings(value, cleanText, depth) {
+    if (typeof value === "string")
+        return cleanText(value);
+    if (typeof value !== "object" || value === null)
+        return value;
+    // Deeper than any vendor's shape: withheld, as the heuristic does.
+    if (depth > MAX_DEPTH)
+        return REDACTED;
+    if (Array.isArray(value)) {
+        let changed = false;
+        const items = value.map((item) => {
+            const clean = mapStrings(item, cleanText, depth + 1);
+            if (clean !== item)
+                changed = true;
+            return clean;
+        });
+        return changed ? items : value;
+    }
+    let changed = false;
+    const entries = Object.entries(value).map(([key, item]) => {
+        const clean = mapStrings(item, cleanText, depth + 1);
+        if (clean !== item)
+            changed = true;
+        return [key, clean];
+    });
+    return changed ? Object.fromEntries(entries) : value;
+}
+/**
+ * Link text decoded as a browser, a Markdown renderer, or a JSON parser
+ * would, through up to four layers of escaping (`%255B`, `&amp;#91;`). Each
+ * round is one linear pass.
+ */
+function decodeLinkText(text, percent = true) {
+    for (let round = 0; round < 4; round++) {
+        const next = text.replace(ESCAPES, (token, ...groups) => !percent && groups[0] !== undefined ? token : token === "\\" ? "" : (unescaped(groups.slice(0, 6)) ?? token));
+        if (next === text)
+            break;
+        text = next;
+    }
+    return text;
+}
+/**
+ * Whether a request value carries a link whose query or
+ * fragment holds the exact `[redacted]` placeholder, plain or encoded: a
+ * withheld read copied into a write, which would store the placeholder.
+ * Only the link's own destination is read: a Markdown link ends at its
+ * closing `)`, so `[f](…?a=1)[redacted]` is ordinary text after it.
+ * The word alone (`unredacted`) or the placeholder away from a file link is
+ * a person's text. When `hosts` is supplied, require its actual authority
+ * to match that policy, preserving Notion's external-proxy boundary.
+ */
+export function carriesWithheldLink(value, hosts) {
+    const pending = [{ value }];
+    const ancestors = new WeakSet();
+    const inspect = (text) => {
+        for (const { cut, end } of hostLinks(text, hosts, false)) {
+            if (cut >= 0 && decodeLinkText(text.slice(cut, end)).includes(REDACTED))
+                return true;
+        }
+        return false;
+    };
+    // JSON structure is bounded by the admitted request's bytes. Visit every key
+    // and value iteratively, without imposing a smaller node/depth limit. Reject
+    // cycles from direct callers; repeated non-cyclic references remain valid.
+    while (pending.length > 0) {
+        const { value: item, leave } = pending.pop();
+        if (typeof item === "string") {
+            if (inspect(item))
+                return true;
+        }
+        else if (typeof item === "object" && item !== null) {
+            if (leave) {
+                ancestors.delete(item);
+                continue;
+            }
+            if (ancestors.has(item)) {
+                throw new ConnectorCallError("invalid_args", "Not sent: URL admission cannot inspect cyclic JSON.");
+            }
+            ancestors.add(item);
+            pending.push({ value: item, leave: true });
+            if (Array.isArray(item)) {
+                for (const child of item)
+                    pending.push({ value: child });
+            }
+            else {
+                for (const [key, child] of Object.entries(item)) {
+                    if (inspect(key))
+                        return true;
+                    pending.push({ value: child });
+                }
+            }
+        }
+    }
+    return false;
+}
+/** Refuse a withheld destination copied into customer data, before any dispatch. */
+export function refuseWithheldLinks(value, title) {
+    if (!carriesWithheldLink(value))
+        return;
+    throw new ConnectorCallError("invalid_args", `This write carries a URL whose query or fragment Connecta withheld ([redacted]), so ${title} would store the placeholder. Do not write withheld URLs back; obtain the original link or omit the field.`);
+}
+/** Upload admission inspects actual bytes, including base64-decoded files and multipart blobs. */
+export async function refuseWithheldUpload(body, title) {
+    if (body instanceof FormData) {
+        for (const [name, part] of body) {
+            refuseWithheldLinks(name, title);
+            if (typeof part === "string")
+                refuseWithheldLinks(part, title);
+            else {
+                refuseWithheldLinks(part.name, title);
+                refuseWithheldLinks(await part.text(), title);
+            }
+        }
+    }
+    else if (body instanceof Blob)
+        refuseWithheldLinks(await body.text(), title);
+    else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+        refuseWithheldLinks(new TextDecoder().decode(body), title);
+    }
+    else
+        refuseWithheldLinks(body instanceof URLSearchParams ? body.toString() : body, title);
+}
+/** Only for documented JSON fields the vendor decodes as base64, never arbitrary strings. */
+export async function refuseWithheldBase64(value, title, maxDecodedBytes) {
+    if (typeof value !== "string") {
+        throw new ConnectorCallError("invalid_args", "Not sent: a base64 field must be a string.");
+    }
+    // One decode, bounded by this field's own encoded length (at most 3/4 as
+    // many bytes), itself bounded by the host's request limit. Operation-specific
+    // value limits are independent of response caps and raw-upload caps.
+    let decoded;
+    try {
+        decoded = atob(value);
+    }
+    catch {
+        throw new ConnectorCallError("invalid_args", "Not sent: a base64 field must be valid base64.");
+    }
+    if (maxDecodedBytes !== undefined && decoded.length > maxDecodedBytes) {
+        throw new ConnectorCallError("invalid_args", `Not sent: a base64 field must encode at most ${maxDecodedBytes} bytes.`);
+    }
+    const bytes = new Uint8Array(decoded.length);
+    for (let i = 0; i < decoded.length; i++)
+        bytes[i] = decoded.charCodeAt(i);
+    await refuseWithheldUpload(bytes, title);
+}
 /**
  * A destination URL reduced to its origin: webhook, drain, and bearer URLs
  * can carry a secret in the path itself (`hooks.slack.com/services/…`), so
@@ -298,10 +940,12 @@ export function validPath(raw) {
     return segments.length > 0 && segments.every((segment) => SEGMENT.test(segment));
 }
 /** Apply one reviewed path to a body in place of its value. */
-function applyPath(body, raw) {
+function applyPath(body, raw, transform) {
     const { mode, segments } = parsePath(raw);
     const step = (current, index) => {
         if (index === segments.length) {
+            if (transform)
+                return transform(current);
             if (current === undefined || current === null)
                 return current;
             if (mode === "url")
@@ -450,8 +1094,16 @@ function heuristic(value, exempt) {
     const walk = (current, trail, parent, depth) => {
         if (depth > MAX_DEPTH)
             return REDACTED;
-        if (typeof current === "string")
-            return URL_SHAPE.test(current) ? sanitizeUrl(current) : current;
+        if (typeof current === "string") {
+            // Scan original escaped text before URL parsing. A string containing
+            // HTML, Markdown or escapes is text, even when it has no whitespace.
+            // Reviewed vendors already scanned signing names and selected text;
+            // generic names in customer data must retain their original bytes.
+            if (!exempt.reviewedUrls)
+                return URL_SHAPE.test(current) ? sanitizeUrl(current) : current;
+            const whole = URL_SHAPE.test(current) && !/[\s<>"'`\\]|&(?:#|[a-z]+;)|\]\(/i.test(current);
+            return whole ? sanitizeUrl(current, false) : current;
+        }
         if (Array.isArray(current))
             return current.map((item) => walk(item, trail, parent, depth + 1));
         if (!isRecord(current))
@@ -548,6 +1200,40 @@ export function valueSafety(table, index) {
         redact(data, method, template) {
             const reviewed = verdict(method, template);
             let out = data;
+            if (table.embeddedUrls) {
+                // Do this before any reviewed URL rule parses/serializes the text.
+                out = mapStrings(out, withholdSigningParams, 0);
+                for (const path of table.embeddedUrls.operations?.[`${method} ${template}`] ?? []) {
+                    out = applyPath(out, path, withholdEmbeddedUrlsIn);
+                }
+                const resources = table.embeddedUrls.resources;
+                if (resources) {
+                    const scan = (value, depth) => {
+                        if (depth > MAX_DEPTH || value === null || typeof value !== "object")
+                            return value;
+                        if (Array.isArray(value))
+                            return value.map((item) => scan(item, depth + 1));
+                        let clean = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scan(item, depth + 1)]));
+                        const inner = clean[resources.key];
+                        const innerType = isRecord(inner) ? inner[resources.key] : undefined;
+                        if (typeof innerType === "string" && Object.hasOwn(resources.paths, innerType)) {
+                            for (const partial of resources.partials ?? []) {
+                                if (!Object.hasOwn(clean, partial))
+                                    continue;
+                                for (const path of resources.paths[innerType])
+                                    clean[partial] = applyPath(clean[partial], path, withholdEmbeddedUrlsIn);
+                            }
+                        }
+                        const type = clean[resources.key];
+                        if (typeof type === "string" && Object.hasOwn(resources.paths, type)) {
+                            for (const path of resources.paths[type])
+                                clean = applyPath(clean, path, withholdEmbeddedUrlsIn);
+                        }
+                        return clean;
+                    };
+                    out = scan(out, 0);
+                }
+            }
             if (reviewed?.verdict === "redact")
                 for (const path of reviewed.paths)
                     out = applyPath(out, path);
@@ -557,7 +1243,13 @@ export function valueSafety(table, index) {
             if (table.resources)
                 out = resourcePass(out, table.resources, verbatim, 0);
             const keep = reviewed && reviewed.verdict !== "refuse" ? (reviewed.keep ?? []) : [];
-            return heuristic(out, { keep: keep.map(trailOf), verbatim, fields, scopeMaps });
+            return heuristic(out, {
+                keep: keep.map(trailOf),
+                verbatim,
+                fields,
+                scopeMaps,
+                reviewedUrls: table.embeddedUrls !== undefined,
+            });
         },
         withholdsErrors(op) {
             const reviewed = verdict(op.method, op.path);