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

package/src/error-resolution.ts

@@ -1,3 +1,4 @@
+import type { ProviderErrorCategory } from "./observability.js";
 import type { ProviderErrorStatus } from "./types.js";
 
 // This set suppresses the unregistered-provider-error-code signal for codes
@@ -120,11 +121,89 @@ export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
 	"not_found",
 ]);
 
+/** One registered upstream code: the status the SDK serves and who failed. */
+export type SdkUpstreamErrorCodeRegistration = {
+	readonly status: ProviderErrorStatus;
+	readonly category: ProviderErrorCategory;
+};
+
+// Registered codes that name an upstream outcome. A row states the status the
+// SDK serves and the observability category together, so an upstream code
+// cannot be registered without saying who failed. Serve reads the category
+// for a `ProviderError` that carries one of these codes and no explicit
+// `category`, and the public `source` follows from it (`sourceForCategory`).
+// Without a row the category defaults to `provider_error` → `source:
+// "apifuse"`, and the health monitor cannot tie a real upstream failure to the
+// upstream: it publishes `monitoring_unavailable` instead of `down`.
+//
+// The category is `categoryForStatus(status)` unless the code names a
+// narrower class than its status can: a schema change, a bot wall, an
+// upstream refusal of the platform-managed key (served 400, see below).
+// Every row is a code the fleet throws for something the upstream did or
+// said; caller-side and SDK-internal codes stay in the table below.
+export const SDK_UPSTREAM_ERROR_CODE_REGISTRY: ReadonlyMap<
+	string,
+	SdkUpstreamErrorCodeRegistration
+> = new Map<string, SdkUpstreamErrorCodeRegistration>([
+	// The SDK's own unknown-operation and unknown-route throws reuse the
+	// not-found spellings; they set an explicit category and stay APIFuse's.
+	["NOT_FOUND", { status: 404, category: "upstream_http" }],
+	["not_found", { status: 404, category: "upstream_http" }],
+	["NO_DATA", { status: 404, category: "upstream_http" }],
+	["RATE_LIMITED", { status: 429, category: "upstream_rate_limited" }],
+	["UPSTREAM_RATE_LIMIT", { status: 429, category: "upstream_rate_limited" }],
+	[
+		"LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR",
+		{ status: 429, category: "upstream_rate_limited" },
+	],
+	// Deterministic upstream business refusal (honest-provider-error-
+	// contract): the upstream evaluated the request and said no under its
+	// own rules — a conflict with upstream state, never a 5xx.
+	["UPSTREAM_REJECTED", { status: 409, category: "upstream_rejected" }],
+	["UPSTREAM_ERROR", { status: 502, category: "upstream_http" }],
+	// The upstream's bot wall or request protection refused the request. The
+	// status says only "upstream"; the code says which kind.
+	["BLOCKED", { status: 502, category: "anti_bot_blocked" }],
+	// Fleet-consensus provider codes. These are thrown by provider code, not
+	// by the SDK, so they are registered here (status mapping) and not in
+	// SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+	// exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+	// them stops the fleet from re-declaring the same rows on every
+	// operation, and stops an undeclared throw from being served as 500.
+	//
+	// A platform-managed upstream service key the upstream refuses. With
+	// `auth.mode: "platform-managed"` the caller holds no credential, so 401
+	// ("re-authenticate") tells the caller to do something it cannot do, and
+	// 502 ("upstream is sick") promises a recovery that will never come. It is
+	// a deployment/config defect — the same class as MISSING_SECRET below,
+	// which is already an explicit 400 for that reason. The upstream is still
+	// the one refusing, so the category is `upstream_auth`; the gateway
+	// records it as `provider_error` for every non-`required` connection mode
+	// so the refusal stays provider-alertable.
+	["UPSTREAM_AUTH_ERROR", { status: 400, category: "upstream_auth" }],
+	// The upstream changed its response shape and the provider cannot
+	// normalize it. 502 because the fault is upstream of us, non-retryable
+	// because a retry returns the same broken payload.
+	["UPSTREAM_SCHEMA_ERROR", { status: 502, category: "upstream_schema_drift" }],
+]);
+
+/**
+ * The category a registered upstream code carries when its `ProviderError`
+ * sets none. `undefined` for every other code, which keeps its existing
+ * default.
+ */
+export function registeredUpstreamErrorCategory(
+	code: string | undefined,
+): ProviderErrorCategory | undefined {
+	return code === undefined ? undefined : SDK_UPSTREAM_ERROR_CODE_REGISTRY.get(code)?.category;
+}
+
 // Canonical SDK status mapping for recognized provider-thrown error codes.
 // serve.ts toStatusCode consults this map (after operation-declared overrides
 // for non-SDK-owned codes), and the authoring lint treats these codes as
 // SDK-registered. Add new codes here instead of duplicating literals in
-// either consumer.
+// either consumer — an upstream-attributed code goes in
+// SDK_UPSTREAM_ERROR_CODE_REGISTRY above, which feeds this map.
 export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus> =
 	new Map<string, ProviderErrorStatus>([
 		["AUTH_REQUIRED", 401],
@@ -132,16 +211,6 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		// Unprovisioned declared secret: a deployment/config defect, never an
 		// upstream failure — explicit 400.
 		["MISSING_SECRET", 400],
-		["NOT_FOUND", 404],
-		["not_found", 404],
-		["NO_DATA", 404],
-		["RATE_LIMITED", 429],
-		["UPSTREAM_RATE_LIMIT", 429],
-		["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 429],
-		// Deterministic upstream business refusal (honest-provider-error-
-		// contract): the upstream evaluated the request and said no under its
-		// own rules — a conflict with upstream state, never a 5xx.
-		["UPSTREAM_REJECTED", 409],
 		// Only an unverifiable or foreign handle is the caller's: key and binding
 		// faults stay unmapped (500) because the engine host, not the caller, owns them.
 		["EGRESS_LEASE_INVALID", 409],
@@ -157,30 +226,11 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		["HANDLE_EXPIRED", 410],
 		["HANDLE_COMMITTED", 409],
 		["HANDLE_BUSY", 409],
-		["UPSTREAM_ERROR", 502],
-		["BLOCKED", 502],
-		// Fleet-consensus provider codes. These are thrown by provider code, not
-		// by the SDK, so they are registered here (status mapping) and not in
-		// SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
-		// exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
-		// them stops the fleet from re-declaring the same three rows on every
-		// operation, and stops an undeclared throw from being served as 500.
-		//
-		// A platform-managed upstream service key the upstream refuses. With
-		// `auth.mode: "platform-managed"` the caller holds no credential, so 401
-		// ("re-authenticate") tells the caller to do something it cannot do, and
-		// 502 ("upstream is sick") promises a recovery that will never come. It is
-		// a deployment/config defect — the same class as MISSING_SECRET above,
-		// which is already an explicit 400 for that reason.
-		["UPSTREAM_AUTH_ERROR", 400],
-		// The upstream changed its response shape and the provider cannot
-		// normalize it. 502 because the fault is upstream of us, non-retryable
-		// because a retry returns the same broken payload.
-		["UPSTREAM_SCHEMA_ERROR", 502],
-		// Caller-side bad input rejected by the provider. The minority spellings
-		// (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are deliberately not
-		// registered: they migrate to this spelling on the contract track, and
-		// registering them here would freeze the divergence.
+		// Caller-side bad input rejected by the provider (fleet consensus, like
+		// UPSTREAM_AUTH_ERROR and UPSTREAM_SCHEMA_ERROR above). The minority
+		// spellings (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are
+		// deliberately not registered: they migrate to this spelling on the
+		// contract track, and registering them here would freeze the divergence.
 		["INVALID_REQUEST", 400],
 		["OCR_UNAVAILABLE", 503],
 		["UNSUPPORTED_OCR_BACKEND", 503],
@@ -194,6 +244,10 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		// retry can clear, and a retryable 5xx there would turn one bad rollout
 		// into gateway-driven load.
 		["PROVIDER_ENGINE_UNAVAILABLE", 503],
+		...Array.from(
+			SDK_UPSTREAM_ERROR_CODE_REGISTRY,
+			([code, registration]) => [code, registration.status] as const,
+		),
 	]);
 
 // Canonical retryability for the fleet-consensus codes registered above.

package/src/fixture-sanitization.ts

@@ -1,3 +1,5 @@
+import { Buffer } from "node:buffer";
+
 import type { JsonValue } from "./contract-json.js";
 
 export const REDACTED_FIXTURE_VALUE = "[REDACTED]";
@@ -13,6 +15,35 @@ const DIAGNOSTIC_URL_SENTINEL_RUN = new RegExp(
 );
 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] as const;
+/** 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: string): boolean {
@@ -23,7 +54,8 @@ export function isSensitiveFixtureKey(key: string): boolean {
 			/^(?: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,
 			),
@@ -71,7 +103,7 @@ export function sanitizeFixtureString(value: string): string {
 			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,
 	);
@@ -162,9 +194,12 @@ export function sanitizeDiagnosticText(value: string): string {
 			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: number, source: string) => {
 		if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate)) return candidate;
 		const prefix = source.slice(Math.max(0, offset - 32), offset);
@@ -178,19 +213,142 @@ export function sanitizeDiagnosticText(value: string): string {
 	return encodeDiagnosticControls(sanitized);
 }
 
-function redactSensitiveAssignments(value: string): string {
-	return value.replace(
-		/((["']?)([\w-]+)\2\s*[:=]\s*)("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;&]+)/gi,
-		(match, prefix: string, _quote: string, key: string, assignmentValue: string) => {
-			if (!isSensitiveFixtureKey(key) && key.toLowerCase() !== "key") return match;
-			const quote = assignmentValue.startsWith('"')
-				? '"'
-				: assignmentValue.startsWith("'")
-					? "'"
-					: "";
-			return `${prefix}${quote}${REDACTED_FIXTURE_VALUE}${quote}`;
-		},
-	);
+type CredentialSpan = readonly [start: number, end: number];
+
+/**
+ * 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: string,
+	rules: readonly ((value: string) => Iterable<CredentialSpan>)[],
+): string {
+	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: [number, number] | undefined;
+	const close = (span: [number, number]) => {
+		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: string): Iterable<CredentialSpan> {
+	for (const match of value.matchAll(CREDENTIALS_HEADER_ASSIGNMENT)) {
+		yield [match.index + (match[1] as string).length, match.index + match[0].length];
+	}
+}
+
+/** Tokens after keyless `Bearer`/`Negotiate`/`NTLM`, and `Basic` tokens that decode to `user-id:password`. */
+function* keylessCredentialSpans(value: string): Iterable<CredentialSpan> {
+	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: string): Iterable<CredentialSpan> {
+	let extents: AssignmentValueExtents | undefined;
+	for (const key of value.matchAll(ASSIGNMENT_KEY)) {
+		const name = key[2] as string;
+		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]];
+		}
+	}
+}
+
+type AssignmentValueExtents = {
+	/** End of the unquoted value (`[^\s,;&]+`) starting at each index. */
+	readonly unquotedEnds: Int32Array;
+	/** Index of the closing `"` when a `"(?:\\.|[^"\\])*"` body is read from each index, or -1. */
+	readonly doubleQuoteClose: Int32Array;
+	readonly singleQuoteClose: Int32Array;
+};
+
+function assignmentValueExtents(value: string): AssignmentValueExtents {
+	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] as string)
+			? 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: string, quote: string): Int32Array {
+	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] as number)
+						: -1
+					: (closing[index + 1] as number);
+	}
+	return closing;
+}
+
+/** For each index, the end of the run of `character` starting there, in one right-to-left pass. */
+function runEnds(value: string, character: RegExp): Int32Array {
+	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] as string) ? (ends[index + 1] as number) : index;
+	}
+	return ends;
 }
 
 function isCredentialBearingUrl(value: string): boolean {