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

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

@@ -14,7 +14,7 @@ import {
 	normalizedXmlName,
 	rootXmlContext,
 	type XmlSemanticBranch,
-} from "./submit-check-xml-semantics";
+} 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.

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.
@@ -20,7 +20,7 @@ export declare const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped
@@ -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-turn/index.js

@@ -18,7 +18,7 @@ export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schem
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped

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;
@@ -66,6 +66,20 @@ export interface DefineCredentialsAuthOptions<TFields extends CredentialsAuthFie
     /** Extra auth-flow context keys used by custom login/challenge code. */
     contextKeys?: readonly string[];
     login(ctx: FlowContext, input: CredentialsAuthInput<TFields>): CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string> | Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+    /**
+     * Optional re-mint of an expired session from the stored credential, wired
+     * to `auth.flow.refresh`.
+     *
+     * Credential-auth upstreams routinely invalidate a session well before the
+     * `expiresAt` the provider advertised, which leaves every operation failing
+     * with a reauth error until a human repeats the whole interactive login.
+     * Implement this to re-establish the session from what is already stored on
+     * the connection; the result is resolved exactly like `login`, so it may
+     * also raise a challenge when the upstream demands one. Omit it when the
+     * upstream has no non-interactive path and re-authentication genuinely
+     * requires the user.
+     */
+    refresh?(ctx: FlowContext, input: Partial<CredentialsAuthInput<TFields>>): CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string> | Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 export interface DefinedCredentialsAuth {
     auth: AuthConfig;

package/dist/auth.js

@@ -1,4 +1,5 @@
-import { AuthError, ProviderError } from "./errors";
+import { AuthError, ProviderError } from "./errors.js";
+import { declarationInvalidError, DECLARATION_RULE_IDS, } from "./declaration-validation.js";
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
 const DEFAULT_ABORT_TURN_ID = "auth.abort";
@@ -97,7 +98,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 +170,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 }
                     : {}),
@@ -202,6 +199,23 @@ function normalizeInput(fields, input) {
     }
     return result;
 }
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput(fields, input) {
+    const result = {};
+    for (const name of Object.keys(fields)) {
+        const value = input?.[name];
+        if (typeof value === "string") {
+            result[name] = value;
+        }
+    }
+    return result;
+}
 function assertCredentialKeys(credentialKeys, credential) {
     const missing = credentialKeys.filter((key) => {
         const value = credential[key];
@@ -291,17 +305,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,13 +390,14 @@ 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);
     const retryTurnId = options.retryTurnId ?? "credentials.retry";
     const completeTurnId = options.completeTurnId ?? "credentials.complete";
     const challenges = (options.challenges ?? {});
+    validateCredentialsAuthChallenges(challenges);
     return {
         auth: {
             mode: "credentials",
@@ -417,6 +430,27 @@ export function defineCredentialsAuth(options) {
                     }
                     return await pollPendingChallenge(ctx, options.credentialKeys, challenges, pending, completeTurnId);
                 },
+                // Only advertise refresh when the provider implements it: the
+                // protocol treats the hook's presence as "this connection can be
+                // re-established without the user", and exposing a stub that
+                // cannot actually re-mint would turn a recoverable expiry into a
+                // silent failure.
+                ...(options.refresh
+                    ? {
+                        refresh: async (ctx, rawInput) => {
+                            // A pending challenge belongs to the interactive flow that
+                            // raised it; finish it there rather than restarting.
+                            const pending = getPendingChallenge(ctx);
+                            if (pending) {
+                                return await continuePendingChallenge(ctx, options.credentialKeys, challenges, pending, rawInput, completeTurnId);
+                            }
+                            // Refresh runs without user input, so fields are optional
+                            // here — unlike `continue`, missing ones are not a retry.
+                            const result = await options.refresh(ctx, normalizePartialInput(options.fields, rawInput));
+                            return await resolveAuthResult(ctx, options.credentialKeys, challenges, result, completeTurnId);
+                        },
+                    }
+                    : {}),
             },
         },
         credential: {
@@ -427,10 +461,34 @@ 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 ?? [])])),
         },
     };
 }
+function validateCredentialsAuthChallenges(challenges) {
+    const violations = [];
+    for (const [challengeId, challenge] of Object.entries(challenges)) {
+        const fieldCount = challenge.fields && typeof challenge.fields === "object"
+            ? Object.keys(challenge.fields).length
+            : 0;
+        const fieldsDeclared = challenge.fields !== undefined && challenge.fields !== null;
+        const hasFields = fieldCount > 0;
+        const hasVerify = typeof challenge.verify === "function";
+        const hasPoll = typeof challenge.poll === "function";
+        const isInteractive = hasFields && hasVerify && !hasPoll;
+        const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+        const isHybrid = hasFields && hasVerify && hasPoll;
+        const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+        if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid))
+            continue;
+        const path = `challenges.${challengeId}`;
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.challengeShape,
+            path,
+            message: "challenge must be interactive, polling, or an explicit hybrid.",
+            fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+        });
+    }
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}

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;

package/dist/ceremonies/index.js

@@ -1,14 +1,17 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import Ajv2020 from "ajv/dist/2020.js";
-import { AUTH_TURN_SCHEMA } from "../auth-turn";
-import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors";
-const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
-// Runtime ceremony-output validation derives from the exported versioned
-// contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
-// dist/auth-turn/auth-turn.v1.schema.json, so the two cannot drift.
-const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
+import { AUTH_TURN_SCHEMA } from "../auth-turn/index.js";
+import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors.js";
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+export const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
+const OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS = new Set([
+    "client_id",
+    "response_type",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+]);
 const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
@@ -17,6 +20,50 @@ const FORM_FIELD_ORDER_EXTENSION = "x-apifuse-field-order";
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function validateSchemaNode(value, schema, path, errors) {
+    if (schema.type === "object") {
+        if (!isRecord(value)) {
+            errors.push(`${path} must be object`);
+            return;
+        }
+        const properties = schema.properties ?? {};
+        for (const required of schema.required ?? []) {
+            if (!Object.hasOwn(value, required) || value[required] === undefined) {
+                errors.push(`${path} must have required property '${required}'`);
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!Object.hasOwn(properties, key)) {
+                    errors.push(`${path} must NOT have additional property '${key}'`);
+                }
+            }
+        }
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (Object.hasOwn(value, key) && value[key] !== undefined) {
+                validateSchemaNode(value[key], childSchema, `${path}/${key}`, errors);
+            }
+        }
+        return;
+    }
+    if (schema.type === "string") {
+        if (typeof value !== "string") {
+            errors.push(`${path} must be string`);
+        }
+        else if (schema.minLength !== undefined && value.length < schema.minLength) {
+            errors.push(`${path} must NOT have fewer than ${schema.minLength} characters`);
+        }
+        return;
+    }
+    if (schema.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            errors.push(`${path} must be number`);
+        }
+        else if (schema.minimum !== undefined && value < schema.minimum) {
+            errors.push(`${path} must be >= ${schema.minimum}`);
+        }
+    }
+}
 function ensureRecord(value) {
     return isRecord(value) ? value : {};
 }
@@ -38,11 +85,7 @@ function getRequiredEnv(ctx, key) {
     return value;
 }
 function toBase64Url(input) {
-    return input
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/g, "");
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 function createCodeVerifier() {
     return toBase64Url(randomBytes(32));
@@ -100,8 +143,7 @@ function withDeclaredFormFieldOrder(expectedInput) {
         return expectedInput;
     }
     const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
-    if (Array.isArray(existingOrder) &&
-        existingOrder.every((value) => typeof value === "string")) {
+    if (Array.isArray(existingOrder) && existingOrder.every((value) => typeof value === "string")) {
         return expectedInput;
     }
     return {
@@ -110,11 +152,14 @@ function withDeclaredFormFieldOrder(expectedInput) {
     };
 }
 export function validateCeremonyOutput(turn) {
-    if (!validateAuthTurn(turn)) {
-        const detail = validateAuthTurn.errors
-            ?.map((error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`)
-            .join("; ");
-        throw new TurnValidationError(detail || "Invalid AuthTurn output");
+    // Evaluate the exact exported versioned schema without eagerly initializing
+    // a general-purpose JSON Schema compiler in every provider process. Contract
+    // parity tests compare this focused evaluator with AJV over all fixtures and
+    // edge probes, so the runtime and shipped document remain locked together.
+    const errors = [];
+    validateSchemaNode(turn, AUTH_TURN_SCHEMA, "", errors);
+    if (errors.length > 0) {
+        throw new TurnValidationError(errors.join("; "));
     }
     return turn;
 }
@@ -178,6 +223,54 @@ export function createOAuth2Ceremony(options) {
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
     };
 }
+/**
+ * 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 function createOAuth2ProxiedStart(options) {
+    const pkce = options.pkce ?? "S256";
+    return (ctx) => runCeremonyHandler(async () => {
+        for (const key of Object.keys(options.authorizeParams ?? {})) {
+            if (OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+                throw new ValidationError(`OAuth2 proxied authorizeParams cannot override reserved parameter "${key}".`);
+            }
+        }
+        const proxyOrigin = ctx.env.get(OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY);
+        if (!proxyOrigin) {
+            throw new ProviderSecretError(`Missing required platform environment: ${OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY}`);
+        }
+        const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+        if (!ctx.flowId) {
+            throw new ValidationError("OAuth2 proxied start requires the gateway flow id.");
+        }
+        const authorizePath = new URL(options.authorizeUrl).pathname;
+        const url = new URL(`/p/${encodeURIComponent(ctx.providerId)}/f/${encodeURIComponent(ctx.flowId)}${authorizePath}`, proxyOrigin);
+        url.searchParams.set("client_id", clientId);
+        url.searchParams.set("response_type", "code");
+        if (pkce === "S256") {
+            const verifier = createCodeVerifier();
+            ctx.context.set(OAUTH2_PROXIED_PKCE_VERIFIER_KEY, verifier);
+            url.searchParams.set("code_challenge", createCodeChallenge(verifier));
+            url.searchParams.set("code_challenge_method", "S256");
+        }
+        for (const [key, value] of Object.entries(options.authorizeParams ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        return createTurn("redirect", {
+            data: { url: url.toString() },
+            hint: "Open the provider authorization page to continue.",
+            expectedInput: {
+                type: "object",
+                required: ["code", "state"],
+                properties: {
+                    code: { type: "string" },
+                    state: { type: "string" },
+                },
+            },
+        });
+    }, "OAuth2 proxied start failed", ctx);
+}
 export function createDeviceFlowCeremony(options) {
     return {
         start: (ctx) => runCeremonyHandler(async () => {
@@ -218,8 +311,7 @@ export function createDeviceFlowCeremony(options) {
             });
             const data = ensureRecord(response.data);
             const errorCode = getString(data, "error");
-            if (errorCode === "authorization_pending" ||
-                errorCode === "slow_down") {
+            if (errorCode === "authorization_pending" || errorCode === "slow_down") {
                 return createTurn("poll", {
                     data,
                     hint: "Authorization pending.",
@@ -345,7 +437,7 @@ export function createFormCeremony(options) {
     return {
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
-            const { prevalidate } = await import("../runtime/prevalidate");
+            const { prevalidate } = await import("../runtime/prevalidate.js");
             const result = prevalidate(options.schema, input);
             if (!result.valid) {
                 throw new ValidationError("Form input failed validation.", {
@@ -354,9 +446,7 @@ export function createFormCeremony(options) {
             }
             return createTurn("complete", {
                 data: {
-                    credential: options.mapCredential
-                        ? options.mapCredential(input)
-                        : input,
+                    credential: options.mapCredential ? options.mapCredential(input) : input,
                 },
                 hint: "Form completed.",
             });
@@ -428,9 +518,7 @@ export function createSwitchCeremony(options) {
         })),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
-            const choice = typeof storedChoice === "string"
-                ? storedChoice
-                : getString(input, "choice");
+            const choice = typeof storedChoice === "string" ? storedChoice : getString(input, "choice");
             if (!choice || !options.choices[choice]) {
                 throw new ValidationError("A valid choice is required.");
             }

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;