@apifuse/provider-sdk 2.2.0-beta.24 → 2.2.0-beta.26

package/AUTHORING.md

@@ -365,7 +365,7 @@ export default defineProvider({
 ```
 <!-- @magic-end:sample -->
 
-The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the optional journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
+The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the required journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
 
 For authenticated journeys, open a fresh connection inside `run` with `ctx.gateway.connect({ input: { ... } })`, execute covered operations with the returned `connectionId`, and disconnect in a `finally` block. Do not require or store long-lived `HEALTH_MONITOR_*_CONNECTION_ID` secrets; those stale connection IDs can hide broken login ceremonies.
 
@@ -734,11 +734,12 @@ const credentialsAuth = defineCredentialsAuth({
   request's `context`.
 - Stealth/browser providers may require local runtime setup outside Provider code:
   keep access-sensitive operations on `ctx.stealth.fetch()` with an SDK stealth
-  `profile`; the TypeScript runtime uses `impit` behind that interface, so do
+  `profile`; the TypeScript runtime uses `wreq-js` behind that interface, so do
   not add per-operation JA3, HTTP/2 SETTINGS, or pseudo-header tuning. `ctx.stealth`
-  supports Chrome/Firefox-style profiles; use `browser.engine:
-  "playwright-stealth"` for Safari-specific or real browser Providers
-  (`nodriver` is Python-runtime only); install local browser assets with
+  supports Chrome, Firefox, and Safari profiles; use `ctx.browser` when a
+  Provider needs real browser execution. TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only);
+  install local browser assets with
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
@@ -786,7 +787,7 @@ its own diagnostics.
 
 Set `maxBodyBytes` on `ctx.stealth.fetch()` or `session.redirects.run()` when an
 upstream response has a known safe maximum. The limit is opt-in and counts
-decoded bytes as impit streams them. It applies to every redirect hop, uses a
+decoded bytes as `wreq-js` streams them. It applies to every redirect hop, uses a
 parseable `Content-Length` for an early rejection, and still enforces the limit
 incrementally when the header is absent or inaccurate. Exceeding the limit
 aborts the response and throws a non-retryable `TransportError` with code

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.26
+
+- Release candidate for main commit 924fe13d1101e7840d799a562a7a70174355185d.
+
+## 2.2.0-beta.25
+
+- Release candidate for main commit e6df658b95c0728b671fd221919ec2f85f82b0b7.
+
 ## 2.2.0-beta.24
 
 - Release candidate for main commit 0f21a2959dcbb9b96fe426259259d0870cfc537f.
@@ -201,7 +209,7 @@
 
 ## 2.1.0-beta.3
 
-- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by `impit` browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
+- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
 - Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
 - Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
 - Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.

package/README.md

@@ -137,7 +137,7 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
-  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
+  `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
   accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`, `profile`,
   `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
   `stealth.insecureSkipVerify`. For login
@@ -145,8 +145,8 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
   `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
-  pseudo-header order in provider code. Chrome/Firefox-style profiles are
-  supported; use `ctx.browser` when Safari-specific behavior is required.
+  pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
+  are supported; use `ctx.browser` when the provider needs browser execution.
 - **Query-parameter credentials**: when an upstream requires a credential in
   its URL query, pass it through `sensitiveParams`, not `params` and never a
   hand-built URL. It is sent as a normal query parameter while the SDK redacts

package/bin/apifuse-check.ts

@@ -11,6 +11,11 @@ import {
 	PROMPT_ASSET_SYNC_REMEDIATION,
 	verifyPromptAssets,
 } from "../src/cli/prompt-assets.js";
+import {
+	DECLARATION_INVALID_CODE,
+	validateFailClosedDeclaration,
+} from "../src/declaration-validation.js";
+import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
 import { lintProvider, type ProviderLintMode } from "../src/lint.js";
 import { safeParseSchemaSync } from "../src/schema.js";
@@ -119,14 +124,25 @@ export async function runChecks(
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
 
-	const providerModule = existsSync(indexPath)
-		? await import(pathToFileURL(indexPath).href)
-		: undefined;
+	let providerModule: Record<string, unknown> | undefined;
+	let providerImportError: unknown;
+	if (existsSync(indexPath)) {
+		try {
+			providerModule = (await import(pathToFileURL(indexPath).href)) as Record<string, unknown>;
+		} catch (error) {
+			if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+				providerImportError = error;
+			} else {
+				throw error;
+			}
+		}
+	}
 	const provider = assertProviderDefinition(providerModule?.default);
 	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
+		checkDeclaration(provider, providerImportError),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
@@ -138,6 +154,49 @@ export async function runChecks(
 	];
 }
 
+const DECLARATION_CHECK_MESSAGE = "Provider declaration passes fail-closed validation";
+
+function checkDeclaration(
+	provider: ProviderDefinition | undefined,
+	importError: unknown,
+): CheckResult {
+	if (importError !== undefined) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(importError),
+		};
+	}
+	if (!provider) return { message: DECLARATION_CHECK_MESSAGE, passed: false };
+	try {
+		validateFailClosedDeclaration(provider);
+		return { message: DECLARATION_CHECK_MESSAGE, passed: true };
+	} catch (error) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(error),
+		};
+	}
+}
+
+function formatDeclarationError(error: unknown): string[] {
+	if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+		const details = error.details;
+		if (isRecord(details) && Array.isArray(details.violations)) {
+			return details.violations.map((violation) => {
+				if (!isRecord(violation)) return String(violation);
+				const ruleId = typeof violation.ruleId === "string" ? violation.ruleId : "unknown-rule";
+				const path = typeof violation.path === "string" ? violation.path : "unknown-path";
+				const message = typeof violation.message === "string" ? `: ${violation.message}` : "";
+				const fix = typeof violation.fix === "string" ? ` Fix: ${violation.fix}` : "";
+				return `${path} [${ruleId}]${message}${fix}`;
+			});
+		}
+	}
+	return [error instanceof Error ? error.message : String(error)];
+}
+
 export const PROMPT_ASSETS_CHECK_MESSAGE =
 	"Agent prompt assets match the installed SDK version";
 

package/bin/apifuse-pack-check.ts

@@ -156,9 +156,9 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
-	if (!content.includes("impit")) {
+	if (!content.includes("wreq-js")) {
 		throw new Error(
-			`${label} must include impit stealth runtime guidance for TLS/browser bounties.`,
+			`${label} must include wreq-js stealth runtime guidance for TLS/browser bounties.`,
 		);
 	}
 
@@ -168,6 +168,12 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
+	if (!content.includes("Chrome, Firefox, and Safari")) {
+		throw new Error(
+			`${label} must document the browser families supported by the TypeScript stealth runtime.`,
+		);
+	}
+
 	if (
 		!content.includes('browser.engine: "playwright-stealth"') ||
 		!content.includes("nodriver")

package/bin/apifuse-pack-smoke.ts

@@ -73,6 +73,7 @@ try {
 		],
 		consumerDir,
 	);
+	smokePackedStealthNative(consumerDir);
 
 	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
 	if (!existsSync(cliBin)) {
@@ -216,6 +217,43 @@ function run(command: string, args: string[], cwd: string): void {
 	}
 }
 
+function smokePackedStealthNative(consumerDir: string): void {
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { createServer } from "node:http";',
+				'import { createStealthClient } from "@apifuse/provider-sdk";',
+				"const server = createServer((_request, response) => {",
+				'  response.setHeader("set-cookie", "pack_native_cookie=landed; Path=/");',
+				'  response.end("packed native stealth ok");',
+				"});",
+				"await new Promise((resolve, reject) => {",
+				'  server.once("error", reject);',
+				'  server.listen(0, "127.0.0.1", resolve);',
+				"});",
+				"const address = server.address();",
+				'if (!address || typeof address === "string") throw new Error("Local server has no TCP address");',
+				'const baseUrl = "http://127.0.0.1:" + address.port;',
+				'const session = createStealthClient(baseUrl).createSession({ profile: "safari-17" });',
+				"try {",
+				'  const response = await session.fetch("/native");',
+				'  if (response.body !== "packed native stealth ok") throw new Error("Unexpected stealth body: " + response.body);',
+				'  if (session.cookies.get("pack_native_cookie", baseUrl + "/native") !== "landed") {',
+				'    throw new Error("Packed stealth Set-Cookie did not land in the SDK jar");',
+				"  }",
+				'  console.log("packed native Safari stealth request OK");',
+				"} finally {",
+				"  session.close();",
+				"  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));",
+				"}",
+			].join("\n"),
+		],
+		consumerDir,
+	);
+}
+
 function assertGeneratedReadme(providerDir: string): void {
 	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
 	if (!readme.includes('"requestId":"req_local_ping"')) {
@@ -227,8 +265,11 @@ function assertGeneratedReadme(providerDir: string): void {
 	if (!readme.includes("bunx playwright install chromium")) {
 		throw new Error("Generated README is missing browser runtime troubleshooting guidance.");
 	}
-	if (!readme.includes("impit")) {
-		throw new Error("Generated README is missing impit stealth runtime guidance.");
+	if (!readme.includes("wreq-js")) {
+		throw new Error("Generated README is missing wreq-js stealth runtime guidance.");
+	}
+	if (!readme.includes("Chrome, Firefox, and Safari")) {
+		throw new Error("Generated README is missing supported stealth browser families.");
 	}
 	if (!readme.includes("bun run submit-check")) {
 		throw new Error("Generated README must document the submit-check pre-submission workflow.");

package/bin/apifuse-pack-types.ts

@@ -143,6 +143,51 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-aws-waf-site-key-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf siteKey must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tsiteKey: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-context-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf context must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tcontext: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-unknown-field.ts",
+		expectedCode: "TS2353",
+		description: "aws_waf rejects fields it does not declare",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tunknownField: 1,",
+			"};",
+			"",
+		].join("\n"),
+	},
 	{
 		filename: "negative-control-recaptcha-v3-action.ts",
 		expectedCode: "TS2322",
@@ -184,6 +229,19 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-resolver-runtime-adapter-factories.ts",
+		expectedCode: "TS2353",
+		description: "ResolverRuntimeOptions does not accept caller-supplied adapter factories",
+		source: [
+			'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverRuntimeOptions = {",
+			"\tadapterFactories: {},",
+			"};",
+			"",
+		].join("\n"),
+	},
 	{
 		filename: "negative-control-resolver-runtime-allowed-hosts.ts",
 		expectedCode: "TS2322",

package/bin/apifuse-submit-check.ts

@@ -1691,12 +1691,25 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+const EXCLUDED_SOURCE_DIRECTORY_SEGMENTS = new Set([
+	".git",
+	".worktree",
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+]);
+
 // `.agents`/`.apifuse` stay IN scope on purpose: managed content there is
 // markdown/JSON (never scannable), while a planted `.ts`/`.sh` under those
 // directories must not become a scan-exempt hiding place for secrets, raw
-// fetch, or vendor imports.
+// fetch, or vendor imports. Nested dependency/build output directories under
+// them use the same segment exclusions; `.worktree` is excluded because task
+// worktrees are duplicate repository checkouts, not provider source.
 function shouldScanSourceDirectory(relativePath: string): boolean {
-	return ![".git", "node_modules", "dist", "build", "coverage"].includes(relativePath);
+	return relativePath
+		.split("/")
+		.every((segment) => !EXCLUDED_SOURCE_DIRECTORY_SEGMENTS.has(segment));
 }
 
 function isExcludedTestSource(relativePath: string): boolean {

package/dist/auth.js

@@ -1,4 +1,5 @@
 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";
@@ -379,6 +380,7 @@ export function defineCredentialsAuth(options) {
     const retryTurnId = options.retryTurnId ?? "credentials.retry";
     const completeTurnId = options.completeTurnId ?? "credentials.complete";
     const challenges = (options.challenges ?? {});
+    validateCredentialsAuthChallenges(challenges);
     return {
         auth: {
             mode: "credentials",
@@ -425,3 +427,30 @@ export function defineCredentialsAuth(options) {
         },
     };
 }
+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/cli/templates/provider/README.md.tpl

@@ -114,10 +114,10 @@ Structured errors return an `error` object with `code`, `message`,
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
 - Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
-  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
-  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
-  (`nodriver` is Python-runtime only), then install local Chromium with
+  SDK stealth `profile`; the TypeScript stealth runtime uses `wreq-js` internally
+  and supports Chrome, Firefox, and Safari profiles. Use `ctx.browser` only when
+  the provider needs browser execution; TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps

package/dist/contract-serialization.d.ts

@@ -1,4 +1,23 @@
 import { type JsonValue } from "./contract-json.js";
 import type { SchemaLike } from "./types.js";
-export declare function describeSchema(schema: SchemaLike): JsonValue;
+interface DescribeSchemaOptions {
+    readonly eventName?: string;
+    readonly operationId?: string;
+    readonly outputTextTrust?: boolean;
+}
+export declare class OutputTextTrustProjectionError extends Error {
+    readonly schemaPath: string;
+    readonly operationId?: string | undefined;
+    readonly eventName?: string | undefined;
+    readonly classification: "untrusted";
+    readonly code = "output_text_trust_projection_failed";
+    constructor(schemaPath: string, cause: unknown, operationId?: string | undefined, eventName?: string | undefined);
+}
+export declare class OutputTextTrustProjectionMarkerError extends TypeError {
+    readonly schemaPath: string;
+    readonly code = "invalid_output_text_trust_projection_marker";
+    constructor(schemaPath: string);
+}
+export declare function describeSchema(schema: SchemaLike, options?: DescribeSchemaOptions): JsonValue;
 export declare function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown>;
+export {};