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

package/bin/apifuse-sync-assets.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+
+import {
+	formatPromptAssetIssues,
+	installedSdkVersion,
+	syncPromptAssets,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import { resolveProviderRoot } from "./apifuse-check.js";
+
+const HELP_TEXT = `Usage: apifuse sync-assets [path] [--check]
+Example: apifuse sync-assets .
+Default: apifuse sync-assets .
+
+Regenerates the SDK-managed agent prompt assets for the installed SDK version:
+AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and the
+.apifuse/prompt-assets.json manifest. Legacy top-level skills/ layouts are
+migrated. Idempotent.
+
+Options:
+  --check        Verify only; exit 1 with a diff list when assets are stale/missing/modified
+  --help, -h     Show this help`;
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	let checkOnly = false;
+	let inputPath: string | undefined;
+	for (const arg of args) {
+		if (arg === "--check") {
+			checkOnly = true;
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+		if (inputPath !== undefined) {
+			throw new Error(`Unexpected argument: ${arg}`);
+		}
+		inputPath = arg;
+	}
+
+	const providerRoot = resolveProviderRoot(inputPath ?? ".");
+
+	if (checkOnly) {
+		const verification = verifyPromptAssets(providerRoot);
+		if (verification.ok) {
+			console.log(
+				`Prompt assets are in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+			);
+			return;
+		}
+		console.error(`Prompt assets are out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error("\nRun `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate.");
+		process.exit(1);
+	}
+
+	const result = syncPromptAssets(providerRoot);
+
+	// Honesty gate: writes alone never imply success. sync-assets intentionally
+	// PRESERVES (does not delete) unauthorized skills and symlinks under
+	// .agents/skills, so it can return changed:false while verify still fails.
+	// Re-verify AFTER writing and let the true post-sync state drive the exit
+	// code — never claim success while the freshness gate would reject the tree.
+	const verification = verifyPromptAssets(providerRoot);
+
+	if (result.changed) {
+		for (const removed of result.removed) {
+			console.log(`removed  ${removed}`);
+		}
+		for (const wrote of result.wroteFiles) {
+			console.log(`wrote    ${wrote}`);
+		}
+		for (const link of result.createdSymlinks) {
+			console.log(`symlink  ${link}`);
+		}
+		console.log(`manifest ${result.manifestPath} (sdkVersion ${installedSdkVersion()})`);
+	}
+
+	if (!verification.ok) {
+		console.error(`\nPrompt assets are still out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error(
+			"\nsync-assets never deletes unrecognized content: resolve these by hand — remove any unauthorized skill directory or symlink under .agents/skills/, migrate a real .claude/.codex directory into .agents/ — then re-run `apifuse sync-assets .`.",
+		);
+		process.exit(1);
+	}
+
+	if (!result.changed) {
+		console.log(
+			`Prompt assets already in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+		);
+		return;
+	}
+	console.log(`\nPrompt assets synced: ${providerRoot}`);
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "sync-assets" ? argv.slice(1) : argv;
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

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-delimited-text.ts

@@ -0,0 +1,50 @@
+const MIN_RECORDED_DELIMITED_TEXT_LENGTH = 200;
+const MIN_RECORDED_DELIMITED_TEXT_LINES = 3;
+const MAX_SAMPLED_DELIMITED_TEXT_LINES = 10;
+const DELIMITER_CANDIDATES = [",", "\t", ";"] as const;
+
+// Recognizes a recorded operation value that is a substantive tabular text
+// payload. The length floor and repeated, quote-aware field structure keep
+// short strings and prose from being treated as fixture provenance.
+export function hasSubstantiveDelimitedTextStructure(value: string): boolean {
+	if (value.length < MIN_RECORDED_DELIMITED_TEXT_LENGTH) {
+		return false;
+	}
+
+	const lines = value
+		.replace(/^\uFEFF/, "")
+		.split(/\r\n?|\n/)
+		.filter((line) => line.trim().length > 0);
+	if (lines.length < MIN_RECORDED_DELIMITED_TEXT_LINES) {
+		return false;
+	}
+
+	const sampledLines = lines.slice(0, MAX_SAMPLED_DELIMITED_TEXT_LINES);
+	return DELIMITER_CANDIDATES.some((delimiter) => {
+		const fieldCounts = sampledLines.map((line) => countDelimitedFields(line, delimiter));
+		const expectedFieldCount = fieldCounts[0];
+		return (
+			expectedFieldCount !== undefined &&
+			expectedFieldCount >= 2 &&
+			fieldCounts.every((fieldCount) => fieldCount === expectedFieldCount)
+		);
+	});
+}
+
+function countDelimitedFields(line: string, delimiter: string): number | undefined {
+	let fieldCount = 1;
+	let insideQuotes = false;
+	for (let index = 0; index < line.length; index += 1) {
+		const character = line[index];
+		if (character === '"') {
+			if (insideQuotes && line[index + 1] === '"') {
+				index += 1;
+			} else {
+				insideQuotes = !insideQuotes;
+			}
+		} else if (!insideQuotes && character === delimiter) {
+			fieldCount += 1;
+		}
+	}
+	return insideQuotes ? undefined : fieldCount;
+}

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.
@@ -87,7 +87,7 @@ export declare const AUTH_TURN_SCHEMA: {
     };
     readonly $defs: {
         readonly completeTurnData: {
-            readonly title: 'Terminal payload for kind "complete"';
+            readonly title: "Terminal payload for kind \"complete\"";
             readonly description: "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.";
             readonly type: "object";
             readonly additionalProperties: true;
@@ -104,7 +104,7 @@ export declare const AUTH_TURN_SCHEMA: {
             };
         };
         readonly abortTurnData: {
-            readonly title: 'Terminal payload for kind "abort"';
+            readonly title: "Terminal payload for kind \"abort\"";
             readonly description: "data payload of an abort turn. code, when present, is the machine-readable abort reason.";
             readonly type: "object";
             readonly additionalProperties: true;

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
-import { AuthError } from "./errors";
-import type { AuthConfig, AuthFlowTerminalContext, AuthTurn, ContextDeclaration, CredentialDeclaration, FlowContext, ProviderLocaleKeyInput } from "./types";
+import { AuthError } from "./errors.js";
+import type { AuthConfig, AuthFlowTerminalContext, AuthTurn, ContextDeclaration, CredentialDeclaration, FlowContext, ProviderLocaleKeyInput } from "./types.js";
 export type CredentialsAuthFieldType = "string" | "email" | "password" | "otp";
 export interface CredentialsAuthField {
     type?: CredentialsAuthFieldType;

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { AuthError, ProviderError } from "./errors";
+import { AuthError, ProviderError } from "./errors.js";
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
 const DEFAULT_ABORT_TURN_ID = "auth.abort";
@@ -97,7 +97,7 @@ export function createAuthFlowHelpers(options = {}) {
                 },
             };
         },
-        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt, }) {
+        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt }) {
             return {
                 kind: "abort",
                 ...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
@@ -169,12 +169,8 @@ function expectedInputFromFields(fields) {
                 ...(field.type === "password" ? { format: "password" } : {}),
                 ...(field.type === "otp" ? { format: "otp" } : {}),
                 ...(field.labelKey ? { nameKey: field.labelKey } : {}),
-                ...(field.descriptionKey
-                    ? { descriptionKey: field.descriptionKey }
-                    : {}),
-                ...(field.placeholderKey
-                    ? { placeholderKey: field.placeholderKey }
-                    : {}),
+                ...(field.descriptionKey ? { descriptionKey: field.descriptionKey } : {}),
+                ...(field.placeholderKey ? { placeholderKey: field.placeholderKey } : {}),
                 ...(field.sensitive || field.type === "password" || field.type === "otp"
                     ? { sensitive: true }
                     : {}),
@@ -291,17 +287,15 @@ function completeTurn(credentialKeys, result, defaultTurnId) {
     };
 }
 function challengeTurn(definition, request) {
-    const expectedInput = definition.fields
-        ? expectedInputFromFields(definition.fields)
-        : undefined;
+    const expectedInput = definition.fields ? expectedInputFromFields(definition.fields) : undefined;
     return {
         kind: expectedInput ? "form" : "pending",
         turnId: request.turnId ?? definition.turnId ?? `credentials.${request.challengeId}`,
         ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
-        ...(request.hintKey ?? definition.hintKey
+        ...((request.hintKey ?? definition.hintKey)
             ? { hintKey: request.hintKey ?? definition.hintKey }
             : {}),
-        ...(request.timing ?? definition.timing
+        ...((request.timing ?? definition.timing)
             ? { timing: request.timing ?? definition.timing }
             : {}),
         ...(expectedInput ? { expectedInput } : {}),
@@ -378,7 +372,7 @@ async function pollPendingChallenge(ctx, credentialKeys, challenges, pending, co
 export function defineCredentialsAuth(options) {
     if (Object.keys(options.fields).length === 0) {
         throw new ProviderError("defineCredentialsAuth requires at least one field", {
-            fix: "Pass fields such as { email: { type: \"email\" }, password: { type: \"password\" } }.",
+            fix: 'Pass fields such as { email: { type: "email" }, password: { type: "password" } }.',
         });
     }
     const expectedInput = expectedInputFromFields(options.fields);
@@ -427,10 +421,7 @@ export function defineCredentialsAuth(options) {
             ...(options.justification ? { justification: options.justification } : {}),
         },
         context: {
-            keys: Array.from(new Set([
-                CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY,
-                ...(options.contextKeys ?? []),
-            ])),
+            keys: Array.from(new Set([CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, ...(options.contextKeys ?? [])])),
         },
     };
 }

package/dist/ceremonies/index.d.ts

@@ -1,5 +1,7 @@
-import type { AuthFlowDefinition, AuthTurn } from "../types";
+import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
+export declare const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export declare const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
 export declare function createOAuth2Ceremony(options: {
     authorizeUrl: string;
@@ -9,6 +11,12 @@ export declare function createOAuth2Ceremony(options: {
     scopes: string[];
     usePKCE?: boolean;
 }): AuthFlowDefinition;
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export declare function createOAuth2ProxiedStart(options: import("../types.js").ProxiedOAuthConfig): import("../types.js").AuthFlowStartHandler;
 export declare function createDeviceFlowCeremony(options: {
     deviceCodeUrl: string;
     tokenUrl: string;