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

package/bin/apifuse-record.ts

@@ -20,8 +20,8 @@ import {
 	type StealthClient,
 	TransportError,
 	ValidationError,
-} from "../src";
-import { createMemoryProviderRuntimeState } from "../src/runtime/state";
+} from "../src/index.js";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
 
 type CliArgs = {
 	append: boolean;
@@ -64,31 +64,18 @@ export async function main() {
 			resolveOperationBaseUrl(provider, operationName),
 		);
 
-		console.log(
-			`[apifuse record] Calling ${operationName} on ${provider.id}...`,
-		);
+		console.log(`[apifuse record] Calling ${operationName} on ${provider.id}...`);
 
-		const result = await executeOperation(
-			provider,
-			operationName,
-			capture.ctx,
-			parsedParams,
-		);
+		const result = await executeOperation(provider, operationName, capture.ctx, parsedParams);
 		const captured = capture.getCapturedRaw();
 
 		if (captured === undefined) {
-			throw new Error(
-				`No upstream response was captured for ${provider.id}.${operationName}.`,
-			);
+			throw new Error(`No upstream response was captured for ${provider.id}.${operationName}.`);
 		}
 
 		const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
 		const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
-		const nextPayload = await prepareFixturePayload(
-			fixturePath,
-			rawPayload,
-			args.append,
-		);
+		const nextPayload = await prepareFixturePayload(fixturePath, rawPayload, args.append);
 
 		await mkdir(dirname(fixturePath), { recursive: true });
 		await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
@@ -98,9 +85,7 @@ export async function main() {
 				Buffer.byteLength(JSON.stringify(rawPayload)),
 			)})`,
 		);
-		console.log(
-			`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`,
-		);
+		console.log(`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`);
 
 		void result;
 	} catch (error) {
@@ -210,11 +195,7 @@ function formatCliError(error: unknown): string {
 	}
 
 	if (error instanceof ProviderError || error instanceof ValidationError) {
-		return [
-			error.message,
-			error.code ? `code=${error.code}` : undefined,
-			error.fix,
-		]
+		return [error.message, error.code ? `code=${error.code}` : undefined, error.fix]
 			.filter(Boolean)
 			.join(" ");
 	}
@@ -269,8 +250,7 @@ function findProviderRoot(startDirectory: string): string | undefined {
 
 function looksLikeProviderRoot(directory: string): boolean {
 	return (
-		existsSync(resolve(directory, "index.ts")) &&
-		existsSync(resolve(directory, "package.json"))
+		existsSync(resolve(directory, "index.ts")) && existsSync(resolve(directory, "package.json"))
 	);
 }
 
@@ -287,15 +267,10 @@ async function loadProvider(rootDir: string): Promise<ProviderRuntime> {
 	return module.default;
 }
 
-function resolveOperationName(
-	provider: ProviderRuntime,
-	operationName?: string,
-): string {
+function resolveOperationName(provider: ProviderRuntime, operationName?: string): string {
 	if (operationName) {
 		if (!(operationName in provider.operations)) {
-			throw new Error(
-				`Unknown operation "${operationName}" for provider "${provider.id}".`,
-			);
+			throw new Error(`Unknown operation "${operationName}" for provider "${provider.id}".`);
 		}
 
 		return operationName;
@@ -309,10 +284,7 @@ function resolveOperationName(
 	return firstOperation;
 }
 
-function parseParams(
-	operation: ProviderRuntime["operations"][string],
-	value: string,
-): unknown {
+function parseParams(operation: ProviderRuntime["operations"][string], value: string): unknown {
 	let parsed: unknown;
 
 	try {
@@ -326,10 +298,7 @@ function parseParams(
 	return operation.input ? operation.input.parse(parsed) : parsed;
 }
 
-function resolveOperationBaseUrl(
-	provider: ProviderRuntime,
-	operationName: string,
-): string {
+function resolveOperationBaseUrl(provider: ProviderRuntime, operationName: string): string {
 	const baseUrl = provider.operations[operationName]?.upstream?.baseUrl;
 	if (!baseUrl) {
 		throw new Error(
@@ -346,12 +315,9 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 	const http = proxyHttpClient(createHttpClient(baseUrl), (response) => {
 		capturedRaw = response.data;
 	});
-	const stealth = proxyStealthClient(
-		createStealthClient(baseUrl),
-		(response) => {
-			capturedRaw = normalizeCapturedStealthResponse(response);
-		},
-	);
+	const stealth = proxyStealthClient(createStealthClient(baseUrl), (response) => {
+		capturedRaw = normalizeCapturedStealthResponse(response);
+	});
 
 	const env = {
 		get: (key: string) => process.env[key],
@@ -464,9 +430,7 @@ function proxyStealthSession(
 	};
 }
 
-function normalizeCapturedStealthResponse(
-	response: Awaited<ReturnType<StealthClient["fetch"]>>,
-) {
+function normalizeCapturedStealthResponse(response: Awaited<ReturnType<StealthClient["fetch"]>>) {
 	try {
 		return JSON.parse(response.body);
 	} catch {
@@ -483,15 +447,13 @@ function sanitizeFixture(value: unknown): unknown {
 		return value;
 	}
 
-	const entries = Object.entries(value as MutableRecord).map(
-		([key, entryValue]) => {
-			if (isSensitiveKey(key)) {
-				return [key, "[REDACTED]"] as const;
-			}
+	const entries = Object.entries(value as MutableRecord).map(([key, entryValue]) => {
+		if (isSensitiveKey(key)) {
+			return [key, "[REDACTED]"] as const;
+		}
 
-			return [key, sanitizeFixture(entryValue)] as const;
-		},
-	);
+		return [key, sanitizeFixture(entryValue)] as const;
+	});
 
 	return Object.fromEntries(entries);
 }

package/bin/apifuse-submit-check.ts

@@ -11,15 +11,16 @@ import * as acorn from "acorn";
 import { z } from "zod";
 
 import packageJson from "../package.json";
-import type { ProviderDefinition } from "../src";
+import type { ProviderDefinition } from "../src/index.js";
 import {
 	loadProviderLocaleCatalogs,
 	type ProviderLocale,
 	validateProviderLocaleCatalogs,
-} from "../src/i18n";
-import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema";
-import { safeParseSchemaSync } from "../src/schema";
-import { type CheckResult, runChecks } from "./apifuse-check";
+} from "../src/i18n/index.js";
+import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema.js";
+import { safeParseSchemaSync } from "../src/schema.js";
+import { type CheckResult, runChecks } from "./apifuse-check.js";
+import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
 const TIER_VALUES: ReadonlySet<string> = new Set(TIERS);
@@ -1979,10 +1980,7 @@ function scoreFixtureCoverage(provider: ProviderDefinition): SubmitCheck {
 
 const GENERATED_LOCAL_ONLY_SCAFFOLD_REASON = /generated local-only scaffold/i;
 
-function scoreFixtureProvenance(
-	providerRoot: string,
-	provider: ProviderDefinition,
-): SubmitCheck {
+function scoreFixtureProvenance(providerRoot: string, provider: ProviderDefinition): SubmitCheck {
 	const rawPath = resolve(providerRoot, "__fixtures__", "raw.json");
 	let hasRecordedEvidence = false;
 	if (existsSync(rawPath)) {
@@ -2066,8 +2064,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 };
 }
@@ -2083,12 +2087,17 @@ function allOperationsAreGeneratedLocalScaffold(provider: ProviderDefinition): b
 }
 
 function scoreVendorKeyLeak(providerRoot: string): SubmitCheck {
-	return escapeHatchResult(providerRoot, "vendor-key-leak", findVendorKeyLeakFindings(providerRoot), {
-		blockerMessage: "Public schema keys leak raw vendor field names.",
-		remediation:
-			"Normalize public request/response fields to APIFuse-standard lowerCamelCase names (e.g. isOpen24h, latitude); keep raw vendor keys only in upstream-parsing schemas (const upstream... = z.object(...)). Add `// @apifuse-allow vendor-key-leak` only with a comment explaining why the vendor name is genuinely canonical.",
-		passMessage: "No vendor field-name leaks detected in public schemas.",
-	});
+	return escapeHatchResult(
+		providerRoot,
+		"vendor-key-leak",
+		findVendorKeyLeakFindings(providerRoot),
+		{
+			blockerMessage: "Public schema keys leak raw vendor field names.",
+			remediation:
+				"Normalize public request/response fields to APIFuse-standard lowerCamelCase names (e.g. isOpen24h, latitude); keep raw vendor keys only in upstream-parsing schemas (const upstream... = z.object(...)). Add `// @apifuse-allow vendor-key-leak` only with a comment explaining why the vendor name is genuinely canonical.",
+			passMessage: "No vendor field-name leaks detected in public schemas.",
+		},
+	);
 }
 
 function scoreVendorTimestampLeak(providerRoot: string): SubmitCheck {
@@ -2191,26 +2200,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,
@@ -2244,9 +2284,7 @@ function collectTopLevelObjectKeys(
 			if (computedQuote === '"' || computedQuote === "'") {
 				const literalEnd = findStringEnd(source, literalStart);
 				const afterLiteral =
-					literalEnd === -1
-						? -1
-						: skipWhitespaceAndComments(masked, literalEnd + 1, computedEnd);
+					literalEnd === -1 ? -1 : skipWhitespaceAndComments(masked, literalEnd + 1, computedEnd);
 				if (literalEnd !== -1 && afterLiteral === computedEnd) {
 					key = source.slice(literalStart + 1, literalEnd);
 				}
@@ -2364,8 +2402,13 @@ function findNamedConstValueRanges(source: string): NamedObjectRange[] {
 	return ranges;
 }
 
-function findConstValueRangeContaining(source: string, offset: number): NamedObjectRange | undefined {
-	return findNamedConstValueRanges(source).find((range) => offset >= range.start && offset <= range.end);
+function findConstValueRangeContaining(
+	source: string,
+	offset: number,
+): NamedObjectRange | undefined {
+	return findNamedConstValueRanges(source).find(
+		(range) => offset >= range.start && offset <= range.end,
+	);
 }
 
 function findStringLiteralsInRange(

package/bin/apifuse.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import packageJson from "../package.json";
-import { COMMAND_MANIFEST, COMMAND_ORDER } from "../src/cli/commands";
+import { COMMAND_MANIFEST, COMMAND_ORDER } from "../src/cli/commands.js";
 
 const command = process.argv[2];
 

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.js";
+
+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/auth-turn/index.d.ts

@@ -1,4 +1,4 @@
-import type { AuthTurn } from "../types";
+import type { AuthTurn } from "../types.js";
 export type { AuthTurn };
 /**
  * Major version of the AuthTurn envelope contract.