@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.3
+
+- Release candidate for main commit 74e8e18b502dd9b02dbf0d3e702f917570312fc0.
+
 ## 2.2.0-beta.2
 
 - Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.

package/bin/apifuse-submit-check.ts

@@ -20,6 +20,7 @@ import {
 import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema";
 import { safeParseSchemaSync } from "../src/schema";
 import { type CheckResult, runChecks } from "./apifuse-check";
+import { hasSubstantiveXmlStructure } from "./submit-check-xml";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
 const TIER_VALUES: ReadonlySet<string> = new Set(TIERS);
@@ -2066,8 +2067,14 @@ function recordedFixtureStats(
 			leafValues,
 		};
 	}
-	if (typeof value === "string" && value.length === 0) {
-		return { hasNestedSubstance: false, leafValues: 0 };
+	if (typeof value === "string") {
+		if (value.length === 0) {
+			return { hasNestedSubstance: false, leafValues: 0 };
+		}
+		// A recorded operation value may be a raw XML success payload; treat a
+		// substantive, well-formed one as nested evidence while still counting the
+		// string as a leaf so existing JSON provenance heuristics are unchanged.
+		return { hasNestedSubstance: hasSubstantiveXmlStructure(value), leafValues: 1 };
 	}
 	return { hasNestedSubstance: false, leafValues: 1 };
 }
@@ -2191,26 +2198,57 @@ function vendorKeyFindingsForObject(
 	const keys = collectTopLevelObjectKeys(source, zObject.objectStart, zObject.objectEnd);
 	const digitFamilies = new Map<string, Set<string>>();
 	for (const key of keys) {
-		const digitMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(key.name);
-		if (!digitMatch?.[1] || !digitMatch[2]) {
+		const member = numberedFamilyMember(key.name);
+		if (!member) {
 			continue;
 		}
-		const digits = digitFamilies.get(digitMatch[1]) ?? new Set<string>();
-		digits.add(digitMatch[2]);
-		digitFamilies.set(digitMatch[1], digits);
+		const positions = digitFamilies.get(member.base) ?? new Set<string>();
+		positions.add(member.position);
+		digitFamilies.set(member.base, positions);
 	}
 
 	return keys
 		.filter((key) => {
-			if (!/^[a-z][a-zA-Z0-9]*$/.test(key.name)) {
+			if (!isAllowedPublicOutputKeyName(key.name)) {
 				return true;
 			}
-			const digitMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(key.name);
-			return digitMatch?.[1] !== undefined && (digitFamilies.get(digitMatch[1])?.size ?? 0) >= 3;
+			const member = numberedFamilyMember(key.name);
+			return member !== null && (digitFamilies.get(member.base)?.size ?? 0) >= 3;
 		})
 		.map((key) => ({ key: key.name, line: offsetToLine(source, key.offset) }));
 }
 
+// A numbered vendor family is a base name plus a numeric position and an
+// optional trailing letter suffix, in either compact/camel form (sensor1,
+// duty1s) or semantic snake_case form (sensor_1, duty_time_1s). Both styles
+// normalize to the same { base, position } so a family of >=3 distinct
+// positions is caught regardless of which naming style the vendor leaked
+// through. Returns null for names that carry no numeric position.
+function numberedFamilyMember(name: string): { base: string; position: string } | null {
+	const camelMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(name);
+	if (camelMatch?.[1] && camelMatch[2]) {
+		return { base: camelMatch[1], position: camelMatch[2] };
+	}
+	const snakeMatch = /^([a-z][a-z0-9]*(?:_[a-z0-9]+)*?)_(\d+)[a-z]*$/.exec(name);
+	if (snakeMatch?.[1] && snakeMatch[2]) {
+		return { base: snakeMatch[1], position: snakeMatch[2] };
+	}
+	return null;
+}
+
+// Public output keys may use APIFuse lowerCamelCase (isOpen24h, latitude) or
+// semantic snake_case (pharmacy_id, weekly_hours, total_count, scan_exhausted).
+// Both are normalized, human-authored names. Raw vendor keys leak through mixed
+// case or uppercase acronyms (MKioskTy) and match neither, so they stay flagged.
+// Numbered vendor families still pass this name gate in either style
+// (sensor1/2/3 or sensor_1/sensor_2/sensor_3), so they are caught separately by
+// the >=3-member numberedFamilyMember check in vendorKeyFindingsForObject.
+function isAllowedPublicOutputKeyName(name: string): boolean {
+	const isLowerCamelCase = /^[a-z][a-zA-Z0-9]*$/.test(name);
+	const isSemanticSnakeCase = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/.test(name);
+	return isLowerCamelCase || isSemanticSnakeCase;
+}
+
 function collectTopLevelObjectKeys(
 	source: string,
 	objectStart: number,

package/bin/submit-check-xml-semantics.ts

@@ -0,0 +1,204 @@
+import type { XmlElement } from "@rgrove/parse-xml";
+
+const FAILURE_TEXT_PATTERN =
+	/\b(?:access denied|denied|error|exception|failed|failure|fault|forbidden|invalid|maintenance|not authorized|temporarily unavailable|unauthorized|unavailable)\b/i;
+const KOREAN_FAILURE_TEXT_PATTERN =
+	/(?:오류|에러|실패|장애|점검|서비스\s*(?:중단|불가)|(?:일시적(?:으로)?\s*)?(?:이용|사용)\s*(?:이|가)?\s*(?:불가|어렵|할\s*수\s*없))/u;
+const SUCCESS_CODE_PATTERN = /^(?:0+|2\d\d|2xx|ok|success|successful|normalservice)$/;
+const SUCCESS_VALUE_PATTERN = /^(?:1|true|y|yes|ok|success|successful)$/;
+const SUCCESS_TEXT_PATTERN = /^(?:normalserviceresponse|successfulresponse)$/;
+const LOCALIZED_SUCCESS_TEXT_PATTERN =
+	/^(?:成功|正常|処理完了|正常終了|処理が完了しました|성공|정상|처리완료|처리가완료되었습니다|处理完成|處理完成|操作成功)$/u;
+const CODE_SHAPED_VALUE_PATTERN = /^(?:\d+|[1-5]xx)$/;
+const CODE_CONTROL_FIELDS: ReadonlySet<string> = new Set([
+	"httpstatus",
+	"resultcode",
+	"returnreasoncode",
+	"statuscode",
+]);
+const TEXT_CONTROL_FIELDS: ReadonlySet<string> = new Set([
+	"message",
+	"msg",
+	"reason",
+	"resultmessage",
+	"resultmsg",
+	"state",
+	"status",
+	"statustext",
+]);
+const SUCCESS_CONTROL_FIELDS: ReadonlySet<string> = new Set([
+	"issuccess",
+	"ok",
+	"success",
+	"successful",
+]);
+const ERROR_CODE_FIELD_PATTERN = /^(?:(?:error|exception|fault)(?:code|status)s?|errcode)$/;
+const ERROR_TEXT_FIELD_PATTERN =
+	/^(?:(?:error|exception|fault)(?:description|detail|details|info|message|reason|string|type)?s?|errmsg|returnauthmsg)$/;
+const STRONG_CONTROL_CONTEXT_NAMES: ReadonlySet<string> = new Set([
+	"cmmmsgheader",
+	"control",
+	"error",
+	"exception",
+	"fault",
+	"header",
+	"meta",
+	"result",
+	"status",
+]);
+const ORDINARY_ENVELOPE_NAMES: ReadonlySet<string> = new Set(["body", "envelope", "response"]);
+const ERROR_ROOT_NAMES: ReadonlySet<string> = new Set([
+	"error",
+	"errorresponse",
+	"exception",
+	"exceptionresponse",
+	"fault",
+	"faultresponse",
+]);
+const DOMAIN_BOUNDARY_NAMES: ReadonlySet<string> = new Set([
+	"entry",
+	"item",
+	"measurement",
+	"record",
+	"row",
+]);
+
+export type XmlSemanticBranch = "control" | "domain" | "envelope" | "error" | "neutral";
+
+// A control failure is only meaningful in a control/error/envelope context.
+// Inside a domain boundary (item/record/row/…) the same field names are ordinary
+// data — e.g. `faultCode` describing a charger's fault is not a service failure.
+export function hasSemanticXmlFailure(element: XmlElement, branch: XmlSemanticBranch): boolean {
+	if (branch === "domain") return false;
+	const insideError = branch === "error";
+	const strongControl = insideError || branch === "control";
+	const insideControl = strongControl || branch === "envelope";
+	const fieldName = normalizedXmlName(element.name);
+	const value = element.text.trim();
+	if (
+		hasControlValueFailure({
+			fieldName,
+			value,
+			insideControl: insideControl || isSemanticControlField(fieldName),
+			strongControl,
+		})
+	) {
+		return true;
+	}
+	return Object.entries(element.attributes).some(([name, attributeValue]) =>
+		hasControlValueFailure({
+			fieldName: normalizedXmlName(name),
+			value: attributeValue.trim(),
+			insideControl: true,
+			strongControl: true,
+		}),
+	);
+}
+
+export function rootXmlContext(name: string): XmlSemanticBranch {
+	if (DOMAIN_BOUNDARY_NAMES.has(name)) return "domain";
+	if (isXmlErrorWrapperName(name)) return "error";
+	if (isStrongControlContextName(name)) return "control";
+	return ORDINARY_ENVELOPE_NAMES.has(name) ? "envelope" : "neutral";
+}
+
+export function childXmlContext(parent: XmlSemanticBranch, name: string): XmlSemanticBranch {
+	if (parent === "control" || parent === "domain" || parent === "error") return parent;
+	if (isXmlErrorWrapperName(name)) return "error";
+	if (isStrongControlContextName(name)) return "control";
+	if (DOMAIN_BOUNDARY_NAMES.has(name)) return "domain";
+	return parent === "envelope" || ORDINARY_ENVELOPE_NAMES.has(name) ? "envelope" : "neutral";
+}
+
+export function isXmlErrorRootName(name: string): boolean {
+	return ERROR_ROOT_NAMES.has(name) || isXmlErrorWrapperName(name);
+}
+
+export function normalizedXmlName(name: string): string {
+	const compatibleName = name.normalize("NFKC");
+	const localName = compatibleName.slice(compatibleName.lastIndexOf(":") + 1);
+	return localName.replace(/[^\p{L}\p{N}]/gu, "").toLowerCase();
+}
+
+function hasControlValueFailure(input: {
+	readonly fieldName: string;
+	readonly value: string;
+	readonly insideControl: boolean;
+	readonly strongControl: boolean;
+}): boolean {
+	const { fieldName, value, insideControl, strongControl } = input;
+	const normalizedValue = normalizedXmlValue(value);
+	if (ERROR_CODE_FIELD_PATTERN.test(fieldName)) {
+		return !SUCCESS_CODE_PATTERN.test(normalizedValue);
+	}
+	if (ERROR_TEXT_FIELD_PATTERN.test(fieldName)) {
+		return normalizedValue.length > 0 && !SUCCESS_CODE_PATTERN.test(normalizedValue);
+	}
+	if (
+		strongControl &&
+		TEXT_CONTROL_FIELDS.has(fieldName) &&
+		normalizedValue.length > 0 &&
+		!isExplicitSuccess(normalizedValue)
+	) {
+		return true;
+	}
+	const isCodeControl =
+		CODE_CONTROL_FIELDS.has(fieldName) ||
+		(fieldName === "code" && insideControl) ||
+		(fieldName === "status" && insideControl && CODE_SHAPED_VALUE_PATTERN.test(normalizedValue));
+	if (isCodeControl && !SUCCESS_CODE_PATTERN.test(normalizedValue)) return true;
+	if (
+		insideControl &&
+		SUCCESS_CONTROL_FIELDS.has(fieldName) &&
+		!SUCCESS_VALUE_PATTERN.test(normalizedValue)
+	) {
+		return true;
+	}
+	return insideControl && TEXT_CONTROL_FIELDS.has(fieldName) && hasFailureText(value);
+}
+
+function isSemanticControlField(fieldName: string): boolean {
+	return (
+		CODE_CONTROL_FIELDS.has(fieldName) ||
+		TEXT_CONTROL_FIELDS.has(fieldName) ||
+		SUCCESS_CONTROL_FIELDS.has(fieldName) ||
+		ERROR_CODE_FIELD_PATTERN.test(fieldName) ||
+		ERROR_TEXT_FIELD_PATTERN.test(fieldName) ||
+		fieldName === "code"
+	);
+}
+
+function isExplicitSuccess(value: string): boolean {
+	return (
+		SUCCESS_CODE_PATTERN.test(value) ||
+		SUCCESS_VALUE_PATTERN.test(value) ||
+		SUCCESS_TEXT_PATTERN.test(value) ||
+		LOCALIZED_SUCCESS_TEXT_PATTERN.test(value)
+	);
+}
+
+function isStrongControlContextName(name: string): boolean {
+	return STRONG_CONTROL_CONTEXT_NAMES.has(name) || name.endsWith("control");
+}
+
+function isXmlErrorWrapperName(name: string): boolean {
+	return /(?:error|exception|fault)(?:response)?$/.test(name);
+}
+
+function hasFailureText(value: string): boolean {
+	const normalized = value.normalize("NFKC");
+	return [normalized, normalized.replace(/\p{Cf}/gu, "")].some((candidate) => {
+		if (KOREAN_FAILURE_TEXT_PATTERN.test(candidate)) return true;
+		const tokenized = candidate
+			.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+			.replace(/[^A-Za-z0-9]+/g, " ");
+		return FAILURE_TEXT_PATTERN.test(tokenized);
+	});
+}
+
+function normalizedXmlValue(value: string): string {
+	return value
+		.normalize("NFKC")
+		.replace(/[^\p{L}\p{N}]/gu, "")
+		.toLowerCase();
+}

package/bin/submit-check-xml.ts

@@ -0,0 +1,134 @@
+import {
+	parseXml,
+	XmlDocumentType,
+	XmlElement,
+	XmlError,
+	XmlProcessingInstruction,
+} from "@rgrove/parse-xml";
+import { Buffer } from "node:buffer";
+
+import {
+	childXmlContext,
+	hasSemanticXmlFailure,
+	isXmlErrorRootName,
+	normalizedXmlName,
+	rootXmlContext,
+	type XmlSemanticBranch,
+} from "./submit-check-xml-semantics";
+
+const MIN_RECORDED_XML_LENGTH = 128;
+// Recorded fixtures must remain reviewable; this pre-allocation cap also bounds the parser tree.
+export const MAX_RECORDED_XML_BYTES = 4 * 1024 * 1024;
+const MAX_RECORDED_XML_DEPTH = 64;
+const MAX_RECORDED_XML_ELEMENTS = 50_000;
+const XML_DOCTYPE_PATTERN = /<!DOCTYPE\b/i;
+const REJECTED_RECORDED_XML_ROOT_NAMES: ReadonlySet<string> = new Set(["body", "html", "head"]);
+
+// Recognizes a recorded operation value that is a substantive, well-formed XML
+// success payload — the shape captured by `apifuse record` against upstreams
+// that return XML (e.g. Korean public-data APIs). Fails closed on malformed XML,
+// HTML, DTD/processing-instruction payloads, oversized/deep/wide trees, error
+// roots, and failure/control-only envelopes. Uses a maintained parser rather
+// than regex so entity/namespace/CDATA handling is correct.
+export function hasSubstantiveXmlStructure(
+	value: string,
+	parser: typeof parseXml = parseXml,
+): boolean {
+	if (Buffer.byteLength(value, "utf8") > MAX_RECORDED_XML_BYTES) {
+		return false;
+	}
+	const xml = value.trim();
+	if (xml.length < MIN_RECORDED_XML_LENGTH || XML_DOCTYPE_PATTERN.test(xml)) {
+		return false;
+	}
+
+	let document: ReturnType<typeof parseXml>;
+	try {
+		document = parser(xml, { preserveDocumentType: true });
+	} catch (error) {
+		if (error instanceof XmlError || error instanceof RangeError) {
+			return false;
+		}
+		throw error;
+	}
+	if (
+		document.children.some(
+			(child) => child instanceof XmlDocumentType || child instanceof XmlProcessingInstruction,
+		)
+	) {
+		return false;
+	}
+
+	const root = document.root;
+	if (root === null) {
+		return false;
+	}
+	const rootName = normalizedXmlName(root.name);
+	if (REJECTED_RECORDED_XML_ROOT_NAMES.has(rootName) || isXmlErrorRootName(rootName)) {
+		return false;
+	}
+
+	const pending: Array<{
+		readonly branch: XmlSemanticBranch;
+		readonly element: XmlElement;
+		readonly depth: number;
+	}> = [
+		{
+			element: root,
+			depth: 1,
+			branch: rootXmlContext(rootName),
+		},
+	];
+	const leafNames = new Set<string>();
+	let leafTextLength = 0;
+	let elementCount = 0;
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (current === undefined) {
+			break;
+		}
+		elementCount += 1;
+		if (
+			elementCount > MAX_RECORDED_XML_ELEMENTS ||
+			current.depth > MAX_RECORDED_XML_DEPTH ||
+			hasSemanticXmlFailure(current.element, current.branch)
+		) {
+			return false;
+		}
+
+		const childElements: XmlElement[] = [];
+		for (const child of current.element.children) {
+			if (child instanceof XmlProcessingInstruction) {
+				return false;
+			}
+			if (child instanceof XmlElement) {
+				childElements.push(child);
+			}
+		}
+		if (childElements.length === 0) {
+			const leafText = current.element.text.trim();
+			// Only substantive *domain* leaves count as evidence. Control/error
+			// leaves (resultCode, resultMsg, header status, …) are not payload data,
+			// so a control-only success envelope with no real records is rejected.
+			if (
+				leafText.length > 0 &&
+				current.depth >= 3 &&
+				current.branch !== "control" &&
+				current.branch !== "error"
+			) {
+				leafNames.add(normalizedXmlName(current.element.name));
+				leafTextLength += leafText.length;
+			}
+			continue;
+		}
+		for (const child of childElements) {
+			const childName = normalizedXmlName(child.name);
+			pending.push({
+				element: child,
+				depth: current.depth + 1,
+				branch: childXmlContext(current.branch, childName),
+			});
+		}
+	}
+	return leafNames.size >= 2 && leafTextLength >= 16;
+}

package/dist/errors.d.ts

@@ -39,6 +39,9 @@ export declare class TransportError extends ProviderError {
     readonly upstreamStatus?: number;
     constructor(message: string, options?: TransportErrorOptions);
 }
+export declare function isProviderError(value: unknown): value is ProviderError;
+export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
+export declare function isTransportError(value: unknown): value is TransportError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }

package/dist/errors.js

@@ -1,3 +1,37 @@
+// Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
+// any copy/entrypoint of this SDK major version, so an error created by a
+// duplicate module instance (e.g. the packaged CLI's src/* server vs a
+// provider's dist/* import) still carries a brand the server can recognize even
+// though `instanceof` splits across the two constructors. The `@1` suffix lets a
+// future breaking change to this contract mint a distinct key.
+const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
+const PROVIDER_ERROR_BRAND_VALUE = 1;
+const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
+const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+// Defines a non-enumerable, non-writable, non-configurable own data property.
+// Immutable + own means a guard can trust it via a single descriptor read
+// without invoking attacker-controlled getters or accepting inherited brands.
+function defineErrorBrand(target, brand, value) {
+    Object.defineProperty(target, brand, {
+        value,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+}
+// Recognizes an own data-property brand with the expected value. Rejects
+// missing brands (unbranded lookalikes), accessor brands (no own `value`
+// slot — the getter is never called), and inherited brands (own-descriptor
+// lookup returns undefined on the child).
+function hasOwnBrand(value, brand, expected) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+        return false;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, brand);
+    return (descriptor !== undefined &&
+        Object.hasOwn(descriptor, "value") &&
+        descriptor.value === expected);
+}
 export class ProviderError extends Error {
     options;
     constructor(message, options) {
@@ -7,6 +41,7 @@ export class ProviderError extends Error {
         if (options?.cause) {
             this.cause = options.cause;
         }
+        defineErrorBrand(this, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
     }
     get fix() {
         return this.options?.fix;
@@ -39,6 +74,7 @@ export class SessionExpiredError extends AuthError {
             ...options,
         });
         this.name = "SessionExpiredError";
+        defineErrorBrand(this, SESSION_EXPIRED_BRAND, true);
     }
 }
 export class ValidationError extends ProviderError {
@@ -57,8 +93,22 @@ export class TransportError extends ProviderError {
         this.name = "TransportError";
         this.status = options?.status;
         this.upstreamStatus = options?.upstreamStatus ?? options?.status;
+        defineErrorBrand(this, TRANSPORT_BRAND, true);
     }
 }
+// Cross-module type guards. Prefer these over `instanceof` at any boundary that
+// may receive an error from a different copy/entrypoint of the SDK (see the HTTP
+// server error boundary). They recognize branded errors regardless of which
+// module instance constructed them, while rejecting unbranded lookalikes.
+export function isProviderError(value) {
+    return hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
+}
+export function isSessionExpiredError(value) {
+    return isProviderError(value) && hasOwnBrand(value, SESSION_EXPIRED_BRAND, true);
+}
+export function isTransportError(value) {
+    return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
+}
 export class ProviderSecretError extends ProviderError {
     constructor(message, options) {
         super(message, { code: "provider_secret_error", ...options });

package/dist/provider.d.ts

@@ -3,7 +3,7 @@ export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeReques
 export { createFormCeremony } from "./ceremonies";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
-export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
+export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema";

package/dist/provider.js

@@ -2,7 +2,7 @@ export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, define
 export { createFormCeremony } from "./ceremonies";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
-export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
+export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema";

package/dist/runtime/executor.js

@@ -1,4 +1,4 @@
-import { ProviderError, SessionExpiredError } from "../errors";
+import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors";
 import { parseSchema } from "../schema";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
@@ -39,7 +39,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
         // operation is safe to re-drive after refresh, which we signal by marking
         // the surfaced error retryable; non-idempotent operations (the default)
         // stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-        if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+        // Use the branded guard, not `instanceof`: a handler loaded through a
+        // duplicate/published SDK module can throw a correctly branded
+        // SessionExpiredError whose constructor identity differs from this
+        // executor's, which `instanceof` would miss — dropping the retryable
+        // upgrade and stranding an operation that opted into auth refresh.
+        if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
             throw new SessionExpiredError(error.message, { retryable: true });
         }
         throw error;

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth";
-import { AuthError, ProviderError, SessionExpiredError, TransportError, } from "../errors";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, } from "../errors";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability";
 import { createScratchpad } from "../runtime/auth-flow";
@@ -293,7 +293,7 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         const details = publicProviderErrorDetails(error);
         return {
             error: {
@@ -343,20 +343,25 @@ function publicProviderErrorDetails(error) {
 function isPlainRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+// Accepts `unknown` so the branded guards narrow cleanly from the top: the
+// subtype error classes are structurally compatible with ProviderError, so
+// narrowing from a ProviderError-typed value would collapse the negative branch
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
 function providerObservabilityDetails(error) {
     // Session-expiry surfaces the credential_expired category + the opt-in
     // retryable signal so Gateway/Credential Service can refresh and re-drive the
     // operation (see design.md §4.3 D3). Without this branch the auth error would
     // serialize as a bare 401 with no retryable/category, losing the refresh
     // signal for exactly the retryOnAuthRefresh operations it is meant to enable.
-    if (error instanceof SessionExpiredError) {
+    if (isSessionExpiredError(error)) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: error.options?.retryable ?? false,
         };
     }
-    if (!(error instanceof TransportError)) {
+    if (!isTransportError(error)) {
         return undefined;
     }
     const isProxyPoolCode = error.code === PROXY_POOL_EXHAUSTED_CODE ||
@@ -385,7 +390,7 @@ function providerObservabilityDetails(error) {
     };
 }
 function publicProviderErrorMessage(error) {
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
             return error.message;
         }
@@ -413,10 +418,10 @@ function toStatusCode(error) {
     if (error instanceof z.ZodError) {
         return 400;
     }
-    if (error instanceof TransportError) {
+    if (isTransportError(error)) {
         return error.code === "transport_timeout" ? 504 : 502;
     }
-    if (error instanceof ProviderError) {
+    if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -448,14 +453,14 @@ function extractRequestId(raw) {
     return typeof value === "string" ? value : undefined;
 }
 function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
-    const code = error instanceof ProviderError
+    const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
             ? "invalid_request"
             : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = error instanceof ProviderError
+    const details = isProviderError(error)
         ? providerObservabilityDetails(error)
         : undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
@@ -471,7 +476,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(error instanceof TransportError && error.upstreamStatus
+        ...(isTransportError(error) && error.upstreamStatus
             ? { upstreamStatus: error.upstreamStatus }
             : {}),
         ...(details

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.2",
+	"version": "2.2.0-beta.3",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -93,6 +93,7 @@
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
+		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
 		"ajv": "^8.17",

package/src/errors.ts

@@ -1,5 +1,46 @@
 import type { ProviderErrorCategory } from "./observability";
 
+// Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
+// any copy/entrypoint of this SDK major version, so an error created by a
+// duplicate module instance (e.g. the packaged CLI's src/* server vs a
+// provider's dist/* import) still carries a brand the server can recognize even
+// though `instanceof` splits across the two constructors. The `@1` suffix lets a
+// future breaking change to this contract mint a distinct key.
+const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
+const PROVIDER_ERROR_BRAND_VALUE = 1;
+const SESSION_EXPIRED_BRAND = Symbol.for(
+	"@apifuse/provider-sdk/error-kind/session-expired@1",
+);
+const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+
+// Defines a non-enumerable, non-writable, non-configurable own data property.
+// Immutable + own means a guard can trust it via a single descriptor read
+// without invoking attacker-controlled getters or accepting inherited brands.
+function defineErrorBrand(target: object, brand: symbol, value: number | true): void {
+	Object.defineProperty(target, brand, {
+		value,
+		enumerable: false,
+		writable: false,
+		configurable: false,
+	});
+}
+
+// Recognizes an own data-property brand with the expected value. Rejects
+// missing brands (unbranded lookalikes), accessor brands (no own `value`
+// slot — the getter is never called), and inherited brands (own-descriptor
+// lookup returns undefined on the child).
+function hasOwnBrand(value: unknown, brand: symbol, expected: number | true): boolean {
+	if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+		return false;
+	}
+	const descriptor = Object.getOwnPropertyDescriptor(value, brand);
+	return (
+		descriptor !== undefined &&
+		Object.hasOwn(descriptor, "value") &&
+		descriptor.value === expected
+	);
+}
+
 export type ProviderErrorOptions = {
 	fix?: string;
 	code?: string;
@@ -19,6 +60,7 @@ export class ProviderError extends Error {
 		if (options?.cause) {
 			this.cause = options.cause;
 		}
+		defineErrorBrand(this, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
 	}
 
 	get fix(): string | undefined {
@@ -60,6 +102,7 @@ export class SessionExpiredError extends AuthError {
 			...options,
 		});
 		this.name = "SessionExpiredError";
+		defineErrorBrand(this, SESSION_EXPIRED_BRAND, true);
 	}
 }
 
@@ -91,9 +134,26 @@ export class TransportError extends ProviderError {
 		this.name = "TransportError";
 		this.status = options?.status;
 		this.upstreamStatus = options?.upstreamStatus ?? options?.status;
+		defineErrorBrand(this, TRANSPORT_BRAND, true);
 	}
 }
 
+// Cross-module type guards. Prefer these over `instanceof` at any boundary that
+// may receive an error from a different copy/entrypoint of the SDK (see the HTTP
+// server error boundary). They recognize branded errors regardless of which
+// module instance constructed them, while rejecting unbranded lookalikes.
+export function isProviderError(value: unknown): value is ProviderError {
+	return hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE);
+}
+
+export function isSessionExpiredError(value: unknown): value is SessionExpiredError {
+	return isProviderError(value) && hasOwnBrand(value, SESSION_EXPIRED_BRAND, true);
+}
+
+export function isTransportError(value: unknown): value is TransportError {
+	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
+}
+
 export class ProviderSecretError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, { code: "provider_secret_error", ...options });

package/src/provider.ts

@@ -37,6 +37,9 @@ export {
 } from "./define";
 export {
 	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
 	ProviderError,
 	SessionExpiredError,
 	TransportError,

package/src/runtime/executor.ts

@@ -1,4 +1,4 @@
-import { ProviderError, SessionExpiredError } from "../errors";
+import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors";
 import { parseSchema } from "../schema";
 import type { ProviderContext, ProviderDefinition } from "../types";
 
@@ -64,7 +64,12 @@ export async function executeOperation(
 		// operation is safe to re-drive after refresh, which we signal by marking
 		// the surfaced error retryable; non-idempotent operations (the default)
 		// stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-		if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+		// Use the branded guard, not `instanceof`: a handler loaded through a
+		// duplicate/published SDK module can throw a correctly branded
+		// SessionExpiredError whose constructor identity differs from this
+		// executor's, which `instanceof` would miss — dropping the retryable
+		// upgrade and stranding an operation that opted into auth refresh.
+		if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
 			throw new SessionExpiredError(error.message, { retryable: true });
 		}
 		throw error;

package/src/server/serve.ts

@@ -6,9 +6,10 @@ import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth";
 import {
 	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
 	ProviderError,
-	SessionExpiredError,
-	TransportError,
 } from "../errors";
 import {
 	loadProviderLocaleCatalogs,
@@ -507,7 +508,7 @@ function toErrorResponse(
 	error: unknown,
 	requestId?: string,
 ): OperationErrorResponse {
-	if (error instanceof ProviderError) {
+	if (isProviderError(error)) {
 		const details = publicProviderErrorDetails(error);
 		return {
 			error: {
@@ -563,7 +564,12 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function providerObservabilityDetails(error: ProviderError):
+// Accepts `unknown` so the branded guards narrow cleanly from the top: the
+// subtype error classes are structurally compatible with ProviderError, so
+// narrowing from a ProviderError-typed value would collapse the negative branch
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
+function providerObservabilityDetails(error: unknown):
 	| {
 			category: ProviderErrorCategory;
 			taxonomyVersion: string;
@@ -576,14 +582,14 @@ function providerObservabilityDetails(error: ProviderError):
 	// operation (see design.md §4.3 D3). Without this branch the auth error would
 	// serialize as a bare 401 with no retryable/category, losing the refresh
 	// signal for exactly the retryOnAuthRefresh operations it is meant to enable.
-	if (error instanceof SessionExpiredError) {
+	if (isSessionExpiredError(error)) {
 		return {
 			category: error.options?.category ?? "credential_expired",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: error.options?.retryable ?? false,
 		};
 	}
-	if (!(error instanceof TransportError)) {
+	if (!isTransportError(error)) {
 		return undefined;
 	}
 	const isProxyPoolCode =
@@ -616,7 +622,7 @@ function providerObservabilityDetails(error: ProviderError):
 }
 
 function publicProviderErrorMessage(error: ProviderError): string {
-	if (error instanceof TransportError) {
+	if (isTransportError(error)) {
 		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
 			return error.message;
 		}
@@ -646,11 +652,11 @@ function toStatusCode(
 		return 400;
 	}
 
-	if (error instanceof TransportError) {
+	if (isTransportError(error)) {
 		return error.code === "transport_timeout" ? 504 : 502;
 	}
 
-	if (error instanceof ProviderError) {
+	if (isProviderError(error)) {
 		switch (error.code) {
 			case "AUTH_REQUIRED":
 			case "reauth_required":
@@ -697,7 +703,7 @@ function logProviderError(
 	cost: ProviderRequestCost,
 ): void {
 	const code =
-		error instanceof ProviderError
+		isProviderError(error)
 			? (error.code ?? "provider_error")
 			: error instanceof z.ZodError
 				? "invalid_request"
@@ -705,7 +711,7 @@ function logProviderError(
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
 	const details =
-		error instanceof ProviderError
+		isProviderError(error)
 			? providerObservabilityDetails(error)
 			: undefined;
 	const emit =
@@ -722,7 +728,7 @@ function logProviderError(
 		code,
 		errorClass,
 		message,
-		...(error instanceof TransportError && error.upstreamStatus
+		...(isTransportError(error) && error.upstreamStatus
 			? { upstreamStatus: error.upstreamStatus }
 			: {}),
 		...(details