@apifuse/provider-sdk 2.2.0-beta.68 → 2.2.0-beta.69

package/AUTHORING.md

@@ -345,7 +345,12 @@ a Web `Response` or `{ status, headers, body }`; an unmatched call fails with
 the operation, transport, and method named in the error. Browser handlers expose
 method-level calls such as `goto`, `evaluate`, and `locator.click`, so provide a
 canned result for each method the handler uses. Native connections similarly
-identify `connectTcp`/`connectTls` and subsequent `write` calls. Direct global
+identify `connectTcp`/`connectTls` and subsequent `write` calls. The offline
+`ctx.stealth` rejects a stealth-owned request header (`User-Agent`,
+`Sec-Fetch-*`, `sec-ch-ua*`, ...) with `STEALTH_HEADER_OVERRIDE_UNSUPPORTED`
+before calling the stub, through the same check the production transport runs,
+so a header spread from a shared constants module or read from a variable fails
+the test instead of the first production request. Direct global
 `fetch` or socket usage is outside this ProviderContext seam and should not be
 used by provider handlers.
 

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.69
+
+- Release candidate for main commit 0f4bd33ef5bd41cb6813005e923abf4324158582.
+
 ## 2.2.0-beta.68
 
 - Release candidate for main commit d630a344c18b2b192edfd09ef92bc30a482b6b8d.

package/README.md

@@ -148,8 +148,12 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
   `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
   accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`,
-  `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
-  `stealth.insecureSkipVerify`. For login
+  `maxBodyBytes`, `redirect`, `redirectPolicy`, `throwOnHttpError`, and
+  `stealth.insecureSkipVerify`. A followed redirect drops `Authorization` when
+  it leaves the origin and an explicit `Cookie` when it leaves the site (the
+  session cookie jar takes over there); set
+  `redirectPolicy: { mode: "same-origin", maxHops }` to refuse a cross-origin
+  hop with `HttpRedirectError` before any request reaches it. For login
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
@@ -157,7 +161,10 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   explicitly defaults to `macos`. The transport owns `User-Agent`,
   `Accept-Encoding`, `sec-ch-ua*`, and every `Sec-Fetch-*` header and throws
   `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` if you set one; declare
-  `stealth.requestClass: "navigation" | "xhr" | "post"` instead. Do not pin a
+  `stealth.requestClass: "navigation" | "form-post" | "xhr" | "post"` instead
+  (`form-post` for an HTML form submission). The offline
+  `ctx.stealth` in `runStandardTests` runs the same check, so a provider test
+  fails wherever production would. Do not pin a
   browser version
   or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles

package/dist/fixture-sanitization.js

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 export const REDACTED_FIXTURE_VALUE = "[REDACTED]";
 const OPAQUE_TOKEN = /^[A-Za-z0-9_+/=.:~-]+$/;
 const OPAQUE_TOKEN_RUN = /[A-Za-z0-9_+/=.:~-]{24,}/g;
@@ -6,12 +7,39 @@ const EMAIL_ADDRESS_RUN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
 const DIAGNOSTIC_URL_SENTINEL_DELIMITER = String.fromCodePoint(0);
 const DIAGNOSTIC_URL_SENTINEL_RUN = new RegExp(`${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL(\\d+)${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`, "g");
 const PEM_PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g;
+/** RFC 9110 §11.4 `token68`, the single credential token of Bearer, Basic, Negotiate and NTLM. */
+const TOKEN68 = "[A-Za-z0-9._~+/-]+=*";
+/**
+ * A credential header's value is the whole RFC 9110 `credentials` production
+ * (`auth-scheme SP token68`), so the scheme and its token are one value, not two words.
+ * The key starts at a word boundary so a long word run is scanned once, not from every offset.
+ */
+const CREDENTIALS_HEADER_ASSIGNMENT = new RegExp(String.raw `(?<![\w-])((["']?)[\w-]*authorization\2\s*[:=]\s*)[A-Za-z][\w.+-]*[ \t]+${TOKEN68}(?![^\s,;&])`, "gi");
+/**
+ * Keyless echoes of the token68 schemes whose token is always a credential. Only the scheme and
+ * its whitespace are matched, so matches never overlap a later scheme; the token is the whole
+ * opaque run that follows, so no partial redaction leaves a remainder too short for the
+ * opaque-token scan. Negotiate and NTLM match only their registered spelling so prose such as
+ * "failed to negotiate TLS" is retained.
+ */
+const TOKEN68_SCHEMES = [/\bBearer\s+/gi, /\b(?:Negotiate|NTLM)\s+/g];
+/** A keyless `Basic` token is a credential only when it decodes to `user-id:password`. */
+const BASIC_SCHEME = /\bBasic\s+/gi;
+const OPAQUE_TOKEN_CHARACTER = /[A-Za-z0-9_+/=.:~-]/;
+const BASE64_CHARACTER = /[A-Za-z0-9+/]/;
+const ASSIGNMENT_VALUE_DELIMITER = /[\s,;&]/;
+/**
+ * A key and its `:`/`=`, starting at a word boundary so a word run is scanned once. Values are
+ * never consumed, so an assignment inside another value is still found.
+ */
+const ASSIGNMENT_KEY = /(["']?)(?<![\w-])([\w-]+)\1\s*[:=]\s*/gi;
 /** Matches credential field names without treating benign prefixes such as `author` as `auth`. */
 export function isSensitiveFixtureKey(key) {
     const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
     const candidates = [normalized, normalized.replace(/(?:value|payload|header)$/, "")];
     return candidates.some((candidate) => /^(?:authorization|authentication|auth|bearer|cookie|credential|password|passwd|privatekey|secret|session|sessionid|token)$/.test(candidate) ||
-        /^(?:api|client|service|access|consumer)(?:key|secret|token)$/.test(candidate) ||
+        // Unanchored at the start so vendor-prefixed headers (`x-api-key`) match too.
+        /(?:api|client|service|access|consumer)(?:key|secret|token)$/.test(candidate) ||
         /(?:authorization|credential|password|passwd|privatekey|secret|sessionid|token)$/.test(candidate));
 }
 /**
@@ -50,7 +78,7 @@ export function sanitizeFixtureString(value) {
         const index = retainedUrls.push(isCredentialBearingUrl(url) ? sanitizeUrlForLogs(url) : url) - 1;
         return `APIFUSEURL${index}X`;
     });
-    sanitized = redactSensitiveAssignments(sanitized);
+    sanitized = redactCredentialSpans(sanitized, [credentialHeaderSpans, sensitiveAssignmentSpans]);
     sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate) => isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate);
     sanitized = sanitized.replace(/APIFUSEURL(\d+)X/g, (_match, index) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE);
     return sanitized;
@@ -135,9 +163,12 @@ export function sanitizeDiagnosticText(value) {
         const index = retainedUrls.push(sanitizeUrlForLogs(url)) - 1;
         return `${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL${index}${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`;
     })
-        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`)
         .replace(EMAIL_ADDRESS_RUN, REDACTED_FIXTURE_VALUE);
-    sanitized = redactSensitiveAssignments(sanitized);
+    sanitized = redactCredentialSpans(sanitized, [
+        credentialHeaderSpans,
+        keylessCredentialSpans,
+        sensitiveAssignmentSpans,
+    ]);
     sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate, offset, source) => {
         if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate))
             return candidate;
@@ -149,17 +180,130 @@ export function sanitizeDiagnosticText(value) {
     sanitized = sanitized.replace(DIAGNOSTIC_URL_SENTINEL_RUN, (_match, index) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE);
     return encodeDiagnosticControls(sanitized);
 }
-function redactSensitiveAssignments(value) {
-    return value.replace(/((["']?)([\w-]+)\2\s*[:=]\s*)("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;&]+)/gi, (match, prefix, _quote, key, assignmentValue) => {
-        if (!isSensitiveFixtureKey(key) && key.toLowerCase() !== "key")
-            return match;
-        const quote = assignmentValue.startsWith('"')
-            ? '"'
-            : assignmentValue.startsWith("'")
-                ? "'"
-                : "";
-        return `${prefix}${quote}${REDACTED_FIXTURE_VALUE}${quote}`;
-    });
+/**
+ * Every credential rule scans the same unmodified text and reports spans; the output redacts
+ * their union. No rule's rewrite can hide a key or a scheme word from another rule, so adding a
+ * rule can only redact more.
+ */
+function redactCredentialSpans(value, rules) {
+    const spans = rules
+        .flatMap((rule) => [...rule(value)])
+        .sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    let output = "";
+    let cursor = 0;
+    let open;
+    const close = (span) => {
+        output += value.slice(cursor, span[0]) + REDACTED_FIXTURE_VALUE;
+        cursor = span[1];
+    };
+    for (const [start, end] of spans) {
+        if (open && start <= open[1]) {
+            open[1] = Math.max(open[1], end);
+            continue;
+        }
+        if (open)
+            close(open);
+        open = [start, end];
+    }
+    if (open)
+        close(open);
+    return output + value.slice(cursor);
+}
+/** The scheme and token of a credential header value, as one span. */
+function* credentialHeaderSpans(value) {
+    for (const match of value.matchAll(CREDENTIALS_HEADER_ASSIGNMENT)) {
+        yield [match.index + match[1].length, match.index + match[0].length];
+    }
+}
+/** Tokens after keyless `Bearer`/`Negotiate`/`NTLM`, and `Basic` tokens that decode to `user-id:password`. */
+function* keylessCredentialSpans(value) {
+    const opaqueEnds = runEnds(value, OPAQUE_TOKEN_CHARACTER);
+    for (const scheme of TOKEN68_SCHEMES) {
+        for (const match of value.matchAll(scheme)) {
+            const start = match.index + match[0].length;
+            if (opaqueEnds[start] > start)
+                yield [start, opaqueEnds[start]];
+        }
+    }
+    const base64Ends = runEnds(value, BASE64_CHARACTER);
+    for (const match of value.matchAll(BASIC_SCHEME)) {
+        const start = match.index + match[0].length;
+        const payloadEnd = base64Ends[start];
+        let end = payloadEnd;
+        while (end < payloadEnd + 2 && value[end] === "=")
+            end++;
+        // The base64 token must be the whole opaque run, not the prefix of a longer token.
+        if (payloadEnd === start || end !== opaqueEnds[start])
+            continue;
+        if (Buffer.from(value.slice(start, end), "base64").includes(0x3a))
+            yield [start, end];
+    }
+}
+/**
+ * Values of credential-named keys; quotes around a quoted value are kept. Every key is visited,
+ * including keys inside another key's value (`auth: {"password": "x"}`), and each value's extent
+ * is read from precomputed tables, so the scan stays linear in the text length.
+ */
+function* sensitiveAssignmentSpans(value) {
+    let extents;
+    for (const key of value.matchAll(ASSIGNMENT_KEY)) {
+        const name = key[2];
+        if (!isSensitiveFixtureKey(name) && name.toLowerCase() !== "key")
+            continue;
+        extents ??= assignmentValueExtents(value);
+        const start = key.index + key[0].length;
+        const quote = value[start];
+        const closing = quote === '"'
+            ? extents.doubleQuoteClose[start + 1]
+            : quote === "'"
+                ? extents.singleQuoteClose[start + 1]
+                : -1;
+        if (closing !== -1) {
+            yield [start + 1, closing];
+        }
+        else if (extents.unquotedEnds[start] > start) {
+            yield [start, extents.unquotedEnds[start]];
+        }
+    }
+}
+function assignmentValueExtents(value) {
+    const unquotedEnds = new Int32Array(value.length + 1);
+    unquotedEnds[value.length] = value.length;
+    for (let index = value.length - 1; index >= 0; index--) {
+        unquotedEnds[index] = ASSIGNMENT_VALUE_DELIMITER.test(value[index])
+            ? index
+            : unquotedEnds[index + 1];
+    }
+    return {
+        unquotedEnds,
+        doubleQuoteClose: closingQuotes(value, '"'),
+        singleQuoteClose: closingQuotes(value, "'"),
+    };
+}
+/** Right-to-left: reading a quoted body from index i either closes at a quote or skips an escape pair. */
+function closingQuotes(value, quote) {
+    const closing = new Int32Array(value.length + 2).fill(-1);
+    for (let index = value.length - 1; index >= 0; index--) {
+        const character = value[index];
+        closing[index] =
+            character === quote
+                ? index
+                : character === "\\"
+                    ? /[^\n\r\u2028\u2029]/.test(value[index + 1] ?? "\n")
+                        ? closing[index + 2]
+                        : -1
+                    : closing[index + 1];
+    }
+    return closing;
+}
+/** For each index, the end of the run of `character` starting there, in one right-to-left pass. */
+function runEnds(value, character) {
+    const ends = new Int32Array(value.length + 1);
+    ends[value.length] = value.length;
+    for (let index = value.length - 1; index >= 0; index--) {
+        ends[index] = character.test(value[index]) ? ends[index + 1] : index;
+    }
+    return ends;
 }
 function isCredentialBearingUrl(value) {
     try {

package/dist/lint.js

@@ -821,6 +821,49 @@ function isStealthContextAccess(node) {
     }
     return false;
 }
+function isTupleTypeNode(type) {
+    if (!type)
+        return false;
+    const ts = getTypeScript();
+    if (ts.isTypeOperatorNode(type))
+        return isTupleTypeNode(type.type);
+    return ts.isTupleTypeNode(type);
+}
+/**
+ * True where a two-element array is consumed as a `[name, value]` header entry:
+ * inside an entries list (`new Headers([[name, value]])`,
+ * `Object.fromEntries([...])`), passed to a call such as `tuples.push(...)`, or
+ * declared with a tuple type. A two-name list is bound, iterated, or handed to
+ * a constructor instead — `const STRIP = ["sec-fetch-dest", "referer"]`,
+ * `for (const name of [...])`, `new Set([...])` — and is not an entry. The
+ * position decides because a Sec-Fetch-* value ("document", "navigate") is
+ * token-shaped exactly like a header name.
+ */
+function isHeaderEntryPosition(node) {
+    const ts = getTypeScript();
+    let child = node;
+    let parent = node.parent;
+    while (parent &&
+        (ts.isParenthesizedExpression(parent) ||
+            ts.isAsExpression(parent) ||
+            ts.isSatisfiesExpression(parent) ||
+            ts.isTypeAssertionExpression(parent))) {
+        if (!ts.isParenthesizedExpression(parent) && isTupleTypeNode(parent.type))
+            return true;
+        child = parent;
+        parent = parent.parent;
+    }
+    if (!parent)
+        return false;
+    if (ts.isArrayLiteralExpression(parent))
+        return true;
+    if (ts.isCallExpression(parent))
+        return parent.arguments.some((argument) => argument === child);
+    if (ts.isVariableDeclaration(parent)) {
+        return parent.initializer === child && isTupleTypeNode(parent.type);
+    }
+    return false;
+}
 function isStaticUndefined(node) {
     if (!node)
         return false;
@@ -842,9 +885,14 @@ function calleeName(node) {
  * runtime rejection: host, connection, and accept-encoding are left alone
  * because ctx.http callers set them legitimately in the same files, and
  * user-agent only reaches a finding through the "user-agent" kind, which
- * matches a versioned literal value rather than the name — a user-agent read
- * from a variable is rejected by the runtime and stays silent here. Widening
- * the set needs a per-file transport scope and a suppression path first.
+ * matches a versioned literal value rather than the name.
+ *
+ * This rule is the early, same-file signal only. The complete check is the
+ * offline test harness: `runStandardTests` runs every `ctx.stealth` request
+ * through the runtime's own `assertCallerHeadersSupported`, so a header spread
+ * from another module, or a user-agent read from a variable or
+ * `getStealthProfile(...)`, fails the provider's tests exactly as it would fail
+ * in production.
  */
 function isReportedOwnedHeaderName(value) {
     if (value === undefined)
@@ -928,13 +976,12 @@ function collectBrowserVersionLiteralFindings(fileName, source) {
                 : false);
         }
         if (ts.isArrayLiteralExpression(node) && node.elements[0]) {
-            // Only a `[name, value]` tuple is a header. A name list such as
-            // `new Set(["sec-ch-ua-mobile", "sec-ch-ua-platform"])` is not: it is
-            // the argument of a constructor, or its second element is itself an
-            // owned name.
+            // Only a `[name, value]` tuple is a header: a two-element array in an
+            // entry position (isHeaderEntryPosition) whose second element is not
+            // itself an owned name.
             const second = node.elements[1];
             inspectHeaderEntry(node.elements[0], staticStringText(node.elements[0]), second, node.elements.length === 2 &&
-                !ts.isNewExpression(node.parent) &&
+                isHeaderEntryPosition(node) &&
                 !isStealthOwnedHeaderName(staticStringText(second) ?? "")
                 ? "entry"
                 : false);
@@ -967,7 +1014,7 @@ function browserVersionLiteralMessage(finding) {
         case "sec-ch-ua":
             return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }. ctx.stealth also owns User-Agent, so omit that header there as well; for ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
         case "owned-header":
-            return `ctx.stealth owns the "${finding.literal}" header and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED (HTTP 500 at request time). Remove it; declare stealth: { requestClass: "navigation" | "xhr" | "post" } to drive Sec-Fetch-* and select the profile with stealth: { browser: "chrome", os: "macos" } for client hints.`;
+            return `ctx.stealth owns the "${finding.literal}" header and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED (HTTP 500 at request time). Remove it; declare stealth: { requestClass: "navigation" | "form-post" | "xhr" | "post" } to drive Sec-Fetch-* and select the profile with stealth: { browser: "chrome", os: "macos" } for client hints.`;
     }
 }
 function lintBrowserVersionLiterals(provider) {

package/dist/runtime/diagnostic-redactor.d.ts

@@ -41,7 +41,12 @@ export declare function isDiagnosticRedactionSuppressed(redact?: DiagnosticRedac
 export declare function diagnosticStructuredRedactor(redact?: DiagnosticRedactor): DiagnosticRedactor | undefined;
 export declare function redactDiagnosticAttributeKey(key: string, redact?: DiagnosticRedactor): string;
 export declare function redactCriticalDiagnosticText(text: string, redact?: DiagnosticRedactor): string;
-export declare function diagnosticAttributeRedactor(key: string, redact?: DiagnosticRedactor): DiagnosticRedactor | undefined;
+/**
+ * The redactor for one attribute value. A value its producer declares as a closed-enum literal for
+ * this key is a contract, like a typed number: exhaustion suppression skips it, while registered
+ * credentials still match. Any other value under the same key stays free text.
+ */
+export declare function diagnosticAttributeRedactor(key: string, redact?: DiagnosticRedactor, value?: unknown): DiagnosticRedactor | undefined;
 export declare function isDiagnosticBigintAttribute(attributes: object, key: string): boolean;
 export declare function copyDiagnosticAttributeTypes<T extends Record<string, unknown>>(source: Record<string, unknown>, target: T): T;
 /** Reserve existing keys so independently redacted names never drop an attribute. */

package/dist/runtime/diagnostic-redactor.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { allSensitiveValueVariants, normalizePercentEscapes, REDACTED_QUERY_VALUE, } from "./request-options.js";
+import { RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES } from "./resolver-span-attributes.js";
 export const REDACTION_FAILED = "[REDACTION_FAILED]";
 // No supported credential source needs 1–3 character secrets. Registering these
 // common tokens damages unrelated IDs and diagnostics even with token boundaries.
@@ -492,9 +493,15 @@ export function redactDiagnosticAttributeKey(key, redact) {
 export function redactCriticalDiagnosticText(text, redact) {
     return redactDiagnosticText(text, redact ? (criticalRedactors.get(redact) ?? redact) : undefined);
 }
-export function diagnosticAttributeRedactor(key, redact) {
-    if (CLOSED_ENUM_ATTRIBUTE_KEYS.has(key))
+/**
+ * The redactor for one attribute value. A value its producer declares as a closed-enum literal for
+ * this key is a contract, like a typed number: exhaustion suppression skips it, while registered
+ * credentials still match. Any other value under the same key stays free text.
+ */
+export function diagnosticAttributeRedactor(key, redact, value) {
+    if (typeof value === "string" && CLOSED_ENUM_ATTRIBUTE_VALUES.get(key)?.has(value)) {
         return diagnosticStructuredRedactor(redact);
+    }
     return CRITICAL_ATTRIBUTE_KEYS.has(key) && redact
         ? (criticalRedactors.get(redact) ?? redact)
         : redact;
@@ -512,18 +519,13 @@ const CRITICAL_ATTRIBUTE_KEYS = new Set([
     "operation",
     "http.status_code",
 ]);
-// SDK-owned closed enums are contracts, like typed numbers and booleans. This
-// exempts only exhaustion suppression; registered credentials still match.
-const CLOSED_ENUM_ATTRIBUTE_KEYS = new Set([
-    "outcome",
-    "code",
-    "errorClass",
-    "phase",
-    "cacheStatus",
-    "identitySource",
-    "taxonomy",
-    "taxonomyVersion",
-]);
+// SDK-owned closed enums are contracts, like typed numbers and booleans. The table is the
+// producers' own declaration of which span attributes are closed enums and of every literal each
+// one can carry; it exempts only exhaustion suppression, and registered credentials still match.
+const CLOSED_ENUM_ATTRIBUTE_VALUES = new Map(Object.entries(RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES).map(([key, values]) => [
+    key,
+    new Set(values),
+]));
 // Bigints normalize to strings for OTLP. Carry their type policy through internal
 // detached copies without treating arbitrary numeric-looking free text as typed.
 const bigintAttributes = new WeakMap();

package/dist/runtime/http.js

@@ -1,9 +1,9 @@
 import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, } from "../config/loader.js";
-import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
+import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
 import { httpTelemetryErrorCode, } from "./http-telemetry.js";
-import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
+import { invalidRedirectPolicy, isRedirectStatus, nextSameOriginRedirectHop, normalizeRedirectPolicy, } from "./redirects.js";
 import { normalizeHttpRequestBody, redactSensitiveError, redactSensitiveRequestError, serializeRequestUrl, } from "./request-options.js";
 import { startHttpTelemetry } from "./http-telemetry-guard.js";
 import { scopedHttpTelemetry } from "./http-telemetry-binding.js";
@@ -409,66 +409,24 @@ function resolveHttpUrl(baseUrl, url) {
     return new URL(url, baseUrl ?? DEFAULT_HTTP_BASE_URL).toString();
 }
 const MAX_HTTP_REDIRECT_HOPS = 20;
-const HTTP_REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+const HTTP_REDIRECT_POLICY_TRANSPORT = {
+    label: "ctx.http",
+    maxHops: MAX_HTTP_REDIRECT_HOPS,
+};
 const REDIRECT_BODY_HEADERS = new Set([
     "content-encoding",
     "content-language",
     "content-location",
     "content-type",
 ]);
-const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
-function invalidHttpRedirectPolicy(message, cause) {
-    return new TransportError(`Invalid ctx.http redirectPolicy: ${message}`, {
-        code: "http_redirect_policy_invalid",
-        ...(cause ? { cause } : {}),
-    });
-}
-/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
-function normalizeHttpRedirectPolicy(value) {
-    if (value === undefined)
-        return undefined;
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw invalidHttpRedirectPolicy("expected an object");
-    }
-    try {
-        const keys = Reflect.ownKeys(value);
-        for (const key of keys) {
-            if (typeof key !== "string" || !HTTP_REDIRECT_POLICY_FIELDS.has(key)) {
-                throw invalidHttpRedirectPolicy(`unknown field ${String(key)}`);
-            }
-        }
-        for (const field of HTTP_REDIRECT_POLICY_FIELDS) {
-            const descriptor = Object.getOwnPropertyDescriptor(value, field);
-            if (!descriptor || !("value" in descriptor)) {
-                throw invalidHttpRedirectPolicy(`${field} must be an own data property`);
-            }
-        }
-        const record = value;
-        if (record.mode !== "same-origin") {
-            throw invalidHttpRedirectPolicy('mode must be "same-origin"');
-        }
-        if (typeof record.maxHops !== "number" ||
-            !Number.isInteger(record.maxHops) ||
-            record.maxHops < 0 ||
-            record.maxHops > MAX_HTTP_REDIRECT_HOPS) {
-            throw invalidHttpRedirectPolicy(`maxHops must be an integer from 0 to ${MAX_HTTP_REDIRECT_HOPS}`);
-        }
-        return { mode: "same-origin", maxHops: record.maxHops };
-    }
-    catch (error) {
-        if (error instanceof TransportError)
-            throw error;
-        throw invalidHttpRedirectPolicy("could not be inspected safely", error instanceof Error ? error : undefined);
-    }
-}
 function snapshotHttpRedirectPolicy(options) {
     try {
-        return normalizeHttpRedirectPolicy(options.redirectPolicy);
+        return normalizeRedirectPolicy(options.redirectPolicy, HTTP_REDIRECT_POLICY_TRANSPORT);
     }
     catch (error) {
         if (error instanceof TransportError)
             throw error;
-        throw invalidHttpRedirectPolicy("could not be read safely", error instanceof Error ? error : undefined);
+        throw invalidRedirectPolicy(HTTP_REDIRECT_POLICY_TRANSPORT, "could not be read safely", error instanceof Error ? error : undefined);
     }
 }
 function withoutRedirectBodyHeaders(headers) {
@@ -477,21 +435,6 @@ function withoutRedirectBodyHeaders(headers) {
         nextHeaders.delete(name);
     return nextHeaders;
 }
-function redirectDiagnosticTarget(value) {
-    try {
-        const parsed = new URL(value);
-        // Origin omits URL userinfo. Keeping only origin + path makes diagnostics
-        // useful while structurally excluding every query value and fragment,
-        // including attacker-chosen keys the provider did not declare sensitive.
-        const redactedQuery = parsed.search ? "?[REDACTED]" : "";
-        return parsed.origin === "null"
-            ? `${parsed.protocol}<opaque-target>`
-            : `${parsed.origin}${parsed.pathname}${redactedQuery}`;
-    }
-    catch {
-        return MALFORMED_REDIRECT_TARGET;
-    }
-}
 function discardRedirectResponseBody(response) {
     try {
         const cancellation = response.body?.cancel();
@@ -532,47 +475,17 @@ async function fetchWithHttpRedirectPolicy(requestUrl, requestInit, policy) {
             return response;
         const location = response.headers.get("location");
         discardRedirectResponseBody(response);
-        let nextUrlString;
-        try {
-            nextUrlString = resolveRedirectUrl(location || undefined, currentUrl);
-        }
-        catch {
-            const target = MALFORMED_REDIRECT_TARGET;
-            throw new HttpRedirectError(`Redirect response has malformed Location target ${target}`, {
-                reason: "missing_location",
-                target,
-                status: response.status,
-            });
-        }
-        const decision = evaluateRedirectHop({
+        const decision = nextSameOriginRedirectHop({
+            policy,
+            initialOrigin,
+            currentUrl,
+            responseUrl: currentUrl,
             status: response.status,
             method,
-            nextUrl: nextUrlString,
-            shouldStop: nextUrlString ? new URL(nextUrlString).origin !== initialOrigin : false,
-            redirectCount: followedHops + 1,
-            maxHops: policy.maxHops,
+            location: location ?? undefined,
+            followedHops,
             visitedRequests,
         });
-        if (decision.kind === "stop") {
-            const target = decision.nextUrl ? redirectDiagnosticTarget(decision.nextUrl) : undefined;
-            const message = (() => {
-                switch (decision.reason) {
-                    case "stopped":
-                        return `Redirect policy refused cross-origin target ${target}`;
-                    case "max_hops":
-                        return `Redirect policy reached maxHops before target ${target}`;
-                    case "loop":
-                        return `Redirect loop refused target ${target}`;
-                    case "missing_location":
-                        return `Redirect response from ${redirectDiagnosticTarget(currentUrl)} is missing Location`;
-                }
-            })();
-            throw new HttpRedirectError(message, {
-                reason: decision.reason,
-                ...(target ? { target } : {}),
-                status: response.status,
-            });
-        }
         if (decision.nextMethod !== method) {
             body = undefined;
             headers = withoutRedirectBodyHeaders(headers);

package/dist/runtime/instrumentation.js

@@ -4,6 +4,7 @@ import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
 import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 const BROWSER_PAGE_METHODS = new Set([
     "goto",
     "fill",
@@ -485,7 +486,9 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
                         ? challenge.kind
                         : undefined;
                     return recorder.runSpan("resolver.solve", () => Reflect.apply(value, namespaceTarget, [args[0], args[1], recorder]), {
-                        attributes: challengeKind ? { challenge_kind: challengeKind } : undefined,
+                        attributes: challengeKind
+                            ? resolverSpanAttributes({ challenge_kind: challengeKind })
+                            : undefined,
                     });
                 };
                 wrappedMethods.set(property, wrapped);

package/dist/runtime/redirect-hop-headers.d.ts

@@ -0,0 +1,19 @@
+/** One redirect hop: the URL the headers were sent to, and the next request. */
+export interface RedirectHop {
+    readonly from: string;
+    readonly to: string;
+    readonly methodChanged: boolean;
+}
+/**
+ * The caller headers the next redirect hop carries, derived from the headers
+ * the previous hop sent. Both stealth redirect walkers compute every hop's
+ * headers here, so the rules hold on every path:
+ *
+ * - a method change drops the request-body headers;
+ * - a cross-origin hop drops `Authorization` and `Proxy-Authorization`;
+ * - a cross-site hop drops an explicit `Cookie`, after which the session
+ *   cookie jar supplies cookies by its own domain rules, as a browser does.
+ *
+ * A header dropped on one hop stays dropped for the rest of the chain.
+ */
+export declare function redirectHopHeaders<T>(hop: RedirectHop, headers: Readonly<Record<string, T>>): Record<string, T>;