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

package/dist/server/serve.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import { validateFailClosedDeclaration } from "../declaration-validation.js";
 import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
@@ -1298,6 +1299,11 @@ function parseStatefulForwardingEnvelope(rawBody) {
     });
 }
 export function createServerApp(provider, options = {}) {
+    // Fail-closed validation runs here rather than only in serve(): createServerApp
+    // is a public export, so a cast-bypassed declaration would otherwise reach the
+    // request path unvalidated. serve() calls into this function, so validating
+    // here covers both entry points exactly once per app construction.
+    validateFailClosedDeclaration(provider);
     validateStatefulServerConfig(options);
     const app = new Hono();
     const logger = options.logger ?? defaultProviderServerLogger;
@@ -1626,6 +1632,8 @@ const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT"];
 const processSignalCoordinators = new Map();
 export async function serve(provider, options = {}) {
+    // Declaration validation happens inside createServerApp (the shared app
+    // construction path), so serve() does not duplicate the call here.
     const bunRuntime = getBunServeRuntime();
     if (bunRuntime === undefined) {
         throw new ProviderError("Bun runtime is required to start the provider server", {

package/dist/stealth/profiles.js

@@ -57,7 +57,7 @@ const FIREFOX_H2_SETTINGS = {
     MAX_HEADER_LIST_SIZE: 65536,
 };
 const SAFARI_H2_SETTINGS = {
-    HEADER_TABLE_SIZE: 4096,
+    // Safari 17 also sends a connection-level WINDOW_UPDATE increment of 10485760.
     ENABLE_PUSH: 0,
     INITIAL_WINDOW_SIZE: 4194304,
     MAX_CONCURRENT_STREAMS: 100,
@@ -162,8 +162,8 @@ const STEALTH_PROFILES = {
     }),
     "firefox-132": createProfile("firefox-132", {
         platform: "macos",
-        version: "132.0",
-        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:132.0) Gecko/20100101 Firefox/132.0",
+        version: "133.0",
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:133.0) Gecko/20100101 Firefox/133.0",
         tlsClientIdentifier: "firefox_132",
         ja3: FIREFOX_JA3,
         h2Settings: FIREFOX_H2_SETTINGS,
@@ -178,6 +178,15 @@ const STEALTH_PROFILES = {
         h2Settings: SAFARI_H2_SETTINGS,
         headerOrder: SAFARI_HEADER_ORDER,
     }),
+    "safari-17": createProfile("safari-17", {
+        platform: "macos",
+        version: "17.0",
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15",
+        tlsClientIdentifier: "safari_17_0",
+        ja3: SAFARI_JA3,
+        h2Settings: SAFARI_H2_SETTINGS,
+        headerOrder: SAFARI_HEADER_ORDER,
+    }),
     "safari-15": createProfile("safari-15", {
         platform: "macos",
         version: "15.6.1",
@@ -198,8 +207,8 @@ const STEALTH_PROFILES = {
     }),
     "ios-safari-18": createProfile("ios-safari-18", {
         platform: "ios",
-        version: "18.0",
-        userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
+        version: "18.1.1",
+        userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1.1 Mobile/15E148 Safari/604.1",
         tlsClientIdentifier: "safari_ios_18_0",
         ja3: SAFARI_JA3,
         h2Settings: SAFARI_H2_SETTINGS,
@@ -207,8 +216,8 @@ const STEALTH_PROFILES = {
     }),
     "ios-safari-17": createProfile("ios-safari-17", {
         platform: "ios",
-        version: "17.0",
-        userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+        version: "17.2",
+        userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
         tlsClientIdentifier: "safari_ios_17_0",
         ja3: SAFARI_JA3,
         h2Settings: SAFARI_H2_SETTINGS,

package/dist/types.d.ts

@@ -298,9 +298,27 @@ export type ProviderChallenge = {
 } | {
     readonly kind: "aws_waf";
     readonly pageUrl: string;
+    /** `window.gokuProps.key`; solver vendors require it, while `"browser"` does not. */
+    readonly siteKey?: string;
     readonly captchaScript?: string;
     readonly context?: string;
     readonly iv?: string;
+} | {
+    readonly kind: "akamai_sec_cpt";
+    readonly pageUrl: string;
+    /** The admitted challenge document, needed for tile/context extraction. */
+    readonly challengeHtml?: string;
+} | {
+    readonly kind: "akamai_sensor";
+    readonly pageUrl: string;
+    /** Upstream sensor script URL the payload must be POSTed to. */
+    readonly scriptUrl: string;
+    /** Current `_abck` cookie value, rotates each round. */
+    readonly abck?: string;
+    /** Current `bm_sz` / `ak_bmsc` value when the upstream set one. */
+    readonly bmsz?: string;
+    /** Bot Manager major version when known ("3" measured on zozo.jp). */
+    readonly version?: string;
 };
 export type ProviderChallengeKind = ProviderChallenge["kind"];
 /**
@@ -317,12 +335,21 @@ export type ChallengeSolution = {
     readonly form: "cookies";
     readonly cookies: Readonly<Record<string, string>>;
     readonly userAgent: string;
+    /** Epoch seconds copied from the upstream cookie's own expiry attribute; never a constant. */
+    readonly expires?: number;
 };
 export interface ProviderResolverConfig {
     /** Ordered vendor fallback chain, tried first to last. */
     readonly vendors: readonly ProviderResolverVendor[];
     /** Challenge kinds this provider is permitted to request. */
     readonly kinds: readonly ProviderChallengeKind[];
+    /**
+     * Client fingerprint profile the SDK must use when reaching this upstream.
+     * Measured on zozo.jp: Chrome/Firefox profiles are refused 403 before any
+     * challenge is served, while a Safari profile is admitted. Provider-declared
+     * because only the provider knows its upstream's admission rule.
+     */
+    readonly clientProfile?: string;
 }
 export type SttAudioInput = {
     kind: "base64";
@@ -534,7 +561,13 @@ export interface HealthJourneyDefinition {
     requiredSecrets?: readonly string[];
     manualTrigger?: HealthJourneyManualTriggerPolicy;
     steps: readonly [HealthJourneyStep, ...HealthJourneyStep[]];
-    run?: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
+    /**
+     * Required: a journey always declares `coversOperations`, and the health
+     * monitor reports a run-less journey as `journey_run_missing`. Declaration
+     * validation rejects a missing `run` (`health-journey-executable`), so this
+     * is typed required to fail at compile time rather than at boot.
+     */
+    run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
 }
 /**
  * Health-check authoring surface owned by `@apifuse/provider-sdk`.
@@ -1332,9 +1365,9 @@ export interface NativeProviderConfig {
 }
 export interface ProviderCacheKeyOptions {
     /**
-     * Additional field names to omit from stable key material. The SDK always
-     * omits known secret-bearing names such as serviceKey, authorization,
-     * cookie, token, password, and secret.
+     * Additional field names whose values are hashed in stable key material. The
+     * SDK always hashes values under known secret-bearing names such as serviceKey,
+     * authorization, cookie, token, password, and secret.
      */
     redactFields?: string[];
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.24",
+	"version": "2.2.0-beta.26",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -106,7 +106,6 @@
 		"acorn": "^8.17.0",
 		"ajv": "^8.17",
 		"hono": "^4.12.25",
-		"impit": "0.14.1",
 		"ioredis": "^5.11.1",
 		"ms": "^2.1.3",
 		"playwright": "^1.55.1",
@@ -116,6 +115,7 @@
 		"safe-regex": "^2.1",
 		"socks": "^2.8.9",
 		"tough-cookie": "^6.0.2",
+		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},
 	"repository": {

package/src/auth.ts

@@ -1,4 +1,9 @@
 import { AuthError, ProviderError } from "./errors.js";
+import {
+	declarationInvalidError,
+	DECLARATION_RULE_IDS,
+	type DeclarationViolation,
+} from "./declaration-validation.js";
 import type {
 	AuthAbortData,
 	AuthConfig,
@@ -656,6 +661,7 @@ export function defineCredentialsAuth<
 		string,
 		CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>
 	>;
+	validateCredentialsAuthChallenges(challenges);
 
 	return {
 		auth: {
@@ -726,3 +732,37 @@ export function defineCredentialsAuth<
 		},
 	};
 }
+
+function validateCredentialsAuthChallenges(
+	challenges: Record<
+		string,
+		CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>
+	>,
+): void {
+	const violations: DeclarationViolation[] = [];
+	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/src/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