@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/src/cli/migrate-provider-shape.ts

@@ -40,7 +40,11 @@ export type ProviderShapeKind =
 	| "single-phase-default-export"
 	/** `const p = defineProvider({ ..., operations }); export default p;` */
 	| "single-phase-variable-export"
-	/** `const p = defineProvider({ ..., operations }); export default { ...p, deployment };` */
+	/**
+	 * `const p = defineProvider({ ..., operations }); export default { ...p, extra };`
+	 * — extras stay on the spread export; a `deployment` extra is a legacy
+	 * surface that `apifuse migrate-deployment` hoists into the declaration.
+	 */
 	| "single-phase-variable-spread-export"
 	/** Already `const b = defineProvider(...); export default b({ operations })` */
 	| "two-phase";
@@ -221,7 +225,7 @@ type ShapeClassification =
 			/** Variable the declaration is currently bound to, when it is bound. */
 			readonly variableName?: string;
 			readonly variableStatement?: TS.VariableStatement;
-			/** Extra properties on a `{ ...provider, deployment }` default export. */
+			/** Extra properties on a `{ ...provider, ...extras }` default export. */
 			readonly spreadExportExtras?: string;
 	  }
 	| { readonly status: "skipped"; readonly reason: string };
@@ -360,7 +364,7 @@ function defaultExportCallsBuilder(
  * resolves to a builder-call result. Covers the three migrated layouts —
  * `export default buildProvider({...})`, an intermediate
  * `const provider = buildProvider({...}); export default provider;`, and the
- * spread export `export default { ...provider, deployment }` over such a
+ * spread export `export default { ...provider, ...extras }` over such a
  * binding. Without the latter two, re-running the transform on its own
  * spread-shape output reports "ambiguous" instead of "unchanged", which
  * breaks idempotency for repeated fan-out runs.
@@ -549,7 +553,9 @@ function rewriteDefaultExport(
 	}
 
 	// Spread export: re-introduce the provider binding so the extra properties
-	// (currently `deployment`) still spread over a built provider.
+	// (e.g. `healthAccountSeedInputs`, or a legacy `deployment` that
+	// `apifuse migrate-deployment` later hoists) still spread over a built
+	// provider.
 	const providerName = shape.variableName ?? "provider";
 	const extras = shape.spreadExportExtras ?? "";
 	const rebuilt =

package/src/cli/resolver-runtime.ts

@@ -0,0 +1,72 @@
+import {
+	compileProcessDiagnosticSensitiveValues,
+	createDiagnosticRedactor,
+} from "../runtime/diagnostic-redactor.js";
+import {
+	createResolverClientFromEnv,
+	createUnsupportedResolverClient,
+} from "../runtime/resolver.js";
+import {
+	createResolverRuntimeOptions,
+	resolveNativeProxyPolicy,
+} from "../runtime/resolver-runtime-options.js";
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import { collectStaticDiagnosticSensitiveValues } from "../server/sensitive-values.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+import type { ProviderCache, ProviderDefinition, ResolverContext } from "../types.js";
+
+export interface CliResolverRuntime {
+	readonly resolver: ResolverContext;
+	/** Per-context sink; `toLogPayload()` is the `resolver` sibling of the server request log. */
+	readonly resolverTelemetry: ResolverTelemetryCollector;
+	/**
+	 * Extend the collector's redaction with values learned after construction (request-scoped
+	 * `sensitiveParams` the recorder captures); the collector redacts at record time, before it
+	 * truncates, so values must be registered before the vendor call that may echo them.
+	 */
+	readonly registerSensitiveValues: (values: readonly string[]) => void;
+}
+
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export function createCliResolverRuntime(
+	provider: ProviderDefinition,
+	cache: ProviderCache,
+): CliResolverRuntime {
+	const sensitiveValues = createDiagnosticRedactor(
+		[],
+		compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider)),
+	);
+	const resolverTelemetry = new ResolverTelemetryCollector({ redact: sensitiveValues.redact });
+	const registerSensitiveValues = (values: readonly string[]) => sensitiveValues.add(values);
+	if (!provider.resolver) {
+		return {
+			resolver: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+			resolverTelemetry,
+			registerSensitiveValues,
+		};
+	}
+	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+	return {
+		resolver: createResolverClientFromEnv(
+			provider.resolver,
+			process.env,
+			createResolverRuntimeOptions(
+				provider,
+				cache,
+				undefined,
+				resolveNativeProxyPolicy(provider),
+				{ upstream: { proxy: provider.proxy } },
+				stealthProfile,
+				resolverTelemetry,
+			),
+		),
+		resolverTelemetry,
+		registerSensitiveValues,
+	};
+}

package/src/define.ts

@@ -587,6 +587,9 @@ export interface ProviderDeclaration {
 	 * provider definition. The SDK types this field but does not deep-validate
 	 * it — the APIFuse registry builder owns deployment validation and
 	 * resolves omitted fields against the runtime deployment profiles.
+	 *
+	 * This is the only authored deployment surface (no standalone
+	 * `deploy.ts`); declare only the fields that differ from the profile.
 	 */
 	deployment?: ProviderDeploymentOverrides;
 	/** Declares the HTTP capability binding. A bare object states use without configuration. */
@@ -949,6 +952,16 @@ function validateProviderProxy(config: {
 	secrets?: ProviderSecretDeclaration[];
 }): void {
 	for (const secret of config.secrets ?? []) {
+		if (
+			secret.issuer !== undefined &&
+			secret.issuer !== "apifuse" &&
+			secret.issuer !== "contributor"
+		) {
+			throw new ValidationError(
+				`Provider "${config.id}" secret "${secret.name}" has invalid issuer "${String(secret.issuer)}"`,
+				{ fix: `Set issuer to "apifuse" or "contributor", or omit it.` },
+			);
+		}
 		const engineName = engineOwnedResolverCredentialTarget(secret.name);
 		if (engineName !== undefined) {
 			throw new ValidationError(

package/src/dev.ts

@@ -1,5 +1,5 @@
 import { serve } from "./server/serve.js";
-import type { ProviderEngine } from "./engine.js";
+import type { ProviderEngine, ProviderEngineMode } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 
 export interface DevServerOptions {
@@ -7,6 +7,8 @@ export interface DevServerOptions {
 	sessionDbPath?: string;
 	/** Override the default in-process engine attachment. */
 	engine?: ProviderEngine;
+	/** Explicit engine mode; `APIFUSE__ENGINE__MODE` outranks it when both are set. */
+	engineMode?: ProviderEngineMode;
 }
 
 export function createDevServer(
@@ -19,7 +21,12 @@ export function createDevServer(
 		start: () => {
 			// Local development has no Redis by default; handles (ADR-0012) need a
 			// state backend, so fall back to memory state when none is configured.
-			void serve(provider, { port, engine: options?.engine, allowMemoryStateFallback: true });
+			void serve(provider, {
+				port,
+				engine: options?.engine,
+				engineMode: options?.engineMode,
+				allowMemoryStateFallback: true,
+			});
 			console.log(
 				`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`,
 			);

package/src/engine.ts

@@ -38,6 +38,27 @@ import type {
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1" as const;
 
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
+
+/**
+ * How a provider process attaches its capability bindings: `"in-process"` today,
+ * `"remote"` for the authenticated engine (ADR-0011).
+ *
+ * The union is intentionally open so further lanes (for example a provider hosted
+ * inside the engine) can be named without a breaking change. Unknown values are
+ * rejected at runtime, not by the type.
+ */
+export type ProviderEngineMode = "in-process" | "remote" | (string & {});
+
 /** Credential names owned by the engine and forbidden in provider declarations. */
 export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
 	"APIFUSE__PROXY__SMARTPROXY_APP_KEY",
@@ -262,6 +283,12 @@ export interface ProviderEngineAttachmentInput {
 
 /** Attachment boundary shared by in-process development and remote RPC bridges. */
 export interface ProviderEngine {
+	/**
+	 * Which attachment this engine performs. Lets the server report a truthful
+	 * mode at boot and compare an explicit engine object against a requested
+	 * `engineMode`; omit for opaque host engines (reported as `custom`).
+	 */
+	readonly kind?: ProviderEngineMode;
 	attach<TDeclaration extends object = Record<string, unknown>>(
 		input: ProviderEngineAttachmentInput,
 	): ProviderContext<TDeclaration>;
@@ -348,7 +375,16 @@ function attachInProcess<TDeclaration extends object>(
 	}) as ProviderContext<TDeclaration>;
 }
 
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
 export function createInProcessProviderEngine(): ProviderEngine {
-	return { attach: attachInProcess };
+	return { kind: "in-process", attach: attachInProcess };
 }

package/src/error-resolution.ts

@@ -20,6 +20,14 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"refresh_not_supported",
 	"RUNTIME_UNSUPPORTED",
 	"PROVIDER_STATE_UNSUPPORTED",
+	// Engine attachment (ADR-0011). Registered here so an engine failure is served
+	// as a known SDK code instead of raising a false
+	// `unregistered_provider_error_code` signal on a 500.
+	"PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+	"PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+	"PROVIDER_ENGINE_UNAVAILABLE",
+	"PROVIDER_ENGINE_MODE_UNSUPPORTED",
+	"PROVIDER_EGRESS_DENIED",
 	"HANDLE_INVALID",
 	"HANDLE_NOT_FOUND",
 	"HANDLE_EXPIRED",
@@ -59,6 +67,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"http_redirect_missing_location",
 	"http_redirect_loop",
 	"transport_invalid_url",
+	"http_header_factory_failed",
 	"EGRESS_LEASE_INVALID",
 	"EGRESS_LEASE_BINDING_INVALID",
 	"EGRESS_LEASE_KEY_MISSING",
@@ -86,6 +95,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
 	"STATEFUL_FORWARDING_REQUEST_FAILED",
 	"STATEFUL_FORWARDING_CONTEXT_MISSING",
+	"STATEFUL_FORWARDING_CONTEXT_INVALID",
 	"STATEFUL_FORWARDING_BAD_RESPONSE",
 	"STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
 	"STATEFUL_FILE_FORWARDING_UNSUPPORTED",
@@ -149,9 +159,57 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		["HANDLE_BUSY", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
+		// Fleet-consensus provider codes. These are thrown by provider code, not
+		// by the SDK, so they are registered here (status mapping) and not in
+		// SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+		// exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+		// them stops the fleet from re-declaring the same three rows on every
+		// operation, and stops an undeclared throw from being served as 500.
+		//
+		// A platform-managed upstream service key the upstream refuses. With
+		// `auth.mode: "platform-managed"` the caller holds no credential, so 401
+		// ("re-authenticate") tells the caller to do something it cannot do, and
+		// 502 ("upstream is sick") promises a recovery that will never come. It is
+		// a deployment/config defect — the same class as MISSING_SECRET above,
+		// which is already an explicit 400 for that reason.
+		["UPSTREAM_AUTH_ERROR", 400],
+		// The upstream changed its response shape and the provider cannot
+		// normalize it. 502 because the fault is upstream of us, non-retryable
+		// because a retry returns the same broken payload.
+		["UPSTREAM_SCHEMA_ERROR", 502],
+		// Caller-side bad input rejected by the provider. The minority spellings
+		// (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are deliberately not
+		// registered: they migrate to this spelling on the contract track, and
+		// registering them here would freeze the divergence.
+		["INVALID_REQUEST", 400],
 		["OCR_UNAVAILABLE", 503],
 		["UNSUPPORTED_OCR_BACKEND", 503],
 		["STT_UNAVAILABLE", 503],
 		["UNSUPPORTED_STT_BACKEND", 503],
 		["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+		// The engine is reachable-in-principle but not now: retryable, so the
+		// caller may retry once the engine recovers. Authentication, protocol
+		// mismatch, an unsupported mode and denied egress stay unmapped (500) and
+		// non-retryable: they are deployment or provider faults that no caller
+		// retry can clear, and a retryable 5xx there would turn one bad rollout
+		// into gateway-driven load.
+		["PROVIDER_ENGINE_UNAVAILABLE", 503],
 	]);
+
+// Canonical retryability for the fleet-consensus codes registered above.
+//
+// Runtime retryability still resolves as `instance option ?? declared ??
+// false`, so this map changes no served response: an undeclared throw already
+// defaults to false, which is what every entry here says. It exists so the
+// authoring lint can tell a provider that its declared `retryable` contradicts
+// the registered meaning of the code, instead of the fleet quietly shipping two
+// answers for the same code. Only codes whose retryability was fixed as part of
+// registration belong here — do not backfill opinions the SDK never made.
+export const SDK_CANONICAL_ERROR_CODE_RETRYABILITY: ReadonlyMap<string, boolean> = new Map<
+	string,
+	boolean
+>([
+	["UPSTREAM_AUTH_ERROR", false],
+	["UPSTREAM_SCHEMA_ERROR", false],
+	["INVALID_REQUEST", false],
+]);

package/src/errors.ts

@@ -1,5 +1,6 @@
+import type { ProviderErrorMessageParams } from "./i18n/error-messages.js";
 import type { ProviderErrorCategory } from "./observability.js";
-import type { HttpRedirectFailureReason } from "./types.js";
+import type { HttpRedirectFailureReason, ProviderLocaleKeyInput } from "./types.js";
 
 // Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
 // any copy/entrypoint of this SDK major version, so an error created by a
@@ -49,6 +50,25 @@ export type ProviderErrorOptions = {
 	retryable?: boolean;
 	/** Provider-authored, bounded metadata safe for operational logs and error headers. */
 	observability?: ProviderErrorObservability;
+	/**
+	 * Locale catalog key for the client-facing `message`, e.g.
+	 * `"errors.upstreamSchema.message"`. Resolved at serve time against the
+	 * provider's `locales/{en,ko,ja}.json` with the caller's `Accept-Language`,
+	 * falling back to `en` and then to the positional `message`.
+	 *
+	 * The positional `message` stays English: it is what `error.message`, cause
+	 * frames, logs and OTLP attributes carry. Only the response envelope is
+	 * localized.
+	 */
+	messageKey?: ProviderLocaleKeyInput;
+	/** Locale catalog key for the client-facing `fix`. Same resolution as {@link ProviderErrorOptions.messageKey}. */
+	fixKey?: ProviderLocaleKeyInput;
+	/**
+	 * Values substituted into `{name}` placeholders of the resolved text.
+	 * Strings and finite numbers only; string values are scrubbed and length
+	 * capped before substitution because upstream text routinely lands here.
+	 */
+	params?: ProviderErrorMessageParams;
 };
 
 /**
@@ -98,6 +118,62 @@ export class SDKError extends ProviderError {
 	}
 }
 
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export class ProviderEngineProtocolVersionError extends SDKError {
+	constructor(
+		public readonly receivedVersion: unknown,
+		public readonly expectedVersion: string,
+	) {
+		super(
+			`Provider engine protocol version mismatch: expected ${expectedVersion}, received ${String(receivedVersion)}`,
+			{
+				code: "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+				details: { receivedVersion, expectedVersion },
+				fix: "Update @apifuse/provider-sdk or use a compatible APIFuse provider engine.",
+			},
+		);
+		this.name = "ProviderEngineProtocolVersionError";
+	}
+}
+
+/** Raised when the remote provider engine rejects a workspace API key. */
+export class ProviderEngineAuthenticationError extends SDKError {
+	constructor(message = "Provider engine authentication failed", options?: ProviderErrorOptions) {
+		super(message, {
+			code: "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+			fix: "Set APIFUSE__ENGINE__API_KEY to the workspace API key from your APIFuse bounty dashboard.",
+			...options,
+		});
+		this.name = "ProviderEngineAuthenticationError";
+	}
+}
+
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export class ProviderEngineUnavailableError extends SDKError {
+	constructor(message = "The remote APIFuse provider engine is unavailable", cause?: Error) {
+		super(message, {
+			code: "PROVIDER_ENGINE_UNAVAILABLE",
+			retryable: true,
+			fix: "Check network access and the provider engine endpoint, then retry.",
+			...(cause ? { cause } : {}),
+		});
+		this.name = "ProviderEngineUnavailableError";
+	}
+}
+
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export class ProviderEgressDeniedError extends ProviderError {
+	constructor(message: string, details?: unknown) {
+		super(message, {
+			code: "PROVIDER_EGRESS_DENIED",
+			retryable: false,
+			details,
+			fix: "Use a host in the provider's pinned allowedHosts declaration, or request a trusted pin update.",
+		});
+		this.name = "ProviderEgressDeniedError";
+	}
+}
+
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export class StealthCookieStoreVersionError extends SDKError {
 	constructor(public readonly version: unknown) {

package/src/handle-meta.ts

@@ -12,12 +12,19 @@ export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle" as const;
 export type HandleKindType = "cursor" | "draft";
 export type HandleAccess = "bound" | "public";
 
+/**
+ * Operation key(s) that issue a handle. A single string is the common case; a
+ * list names every operation whose output carries the field (for example
+ * `search-address` and `reverse-geocode` both issuing `location_token`).
+ */
+export type HandleIssuedBy = string | readonly string[];
+
 /** Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field. */
 export interface HandleFieldMeta {
 	readonly kind: string;
 	readonly type: HandleKindType;
 	readonly fieldName: string;
-	readonly issuedBy?: string;
+	readonly issuedBy?: HandleIssuedBy;
 }
 
 /**
@@ -30,12 +37,39 @@ export interface HandleKindDeclaration {
 	readonly type: HandleKindType;
 	readonly fieldName: string;
 	readonly access: HandleAccess;
-	readonly issuedBy?: string;
+	readonly issuedBy?: HandleIssuedBy;
 }
 
 /** Kind names are lowercase letters only so they never fuse with the word body. */
 export const HANDLE_KIND_NAME_PATTERN = /^[a-z]{2,12}$/;
 
+/** True for a single operation key or a non-empty list of operation keys. */
+export function isHandleIssuedBy(value: unknown): value is HandleIssuedBy {
+	if (typeof value === "string") return true;
+	return (
+		Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string")
+	);
+}
+
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export function handleIssuerList(issuedBy: HandleIssuedBy | undefined): readonly string[] {
+	if (issuedBy === undefined) return [];
+	return typeof issuedBy === "string" ? [issuedBy] : issuedBy;
+}
+
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export function formatHandleIssuers(issuedBy: HandleIssuedBy | undefined): string | undefined {
+	const issuers = handleIssuerList(issuedBy).map((operation) => `\`${operation}\``);
+	if (issuers.length === 0) return undefined;
+	if (issuers.length === 1) return issuers[0];
+	if (issuers.length === 2) return `${issuers[0]} or ${issuers[1]}`;
+	return `${issuers.slice(0, -1).join(", ")}, or ${issuers[issuers.length - 1]}`;
+}
+
 export function isHandleFieldMeta(value: unknown): value is HandleFieldMeta {
 	if (typeof value !== "object" || value === null) return false;
 	const record = value as Record<string, unknown>;
@@ -43,7 +77,7 @@ export function isHandleFieldMeta(value: unknown): value is HandleFieldMeta {
 		typeof record.kind === "string" &&
 		(record.type === "cursor" || record.type === "draft") &&
 		typeof record.fieldName === "string" &&
-		(record.issuedBy === undefined || typeof record.issuedBy === "string")
+		(record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy))
 	);
 }
 
@@ -53,6 +87,7 @@ export function isHandleFieldMeta(value: unknown): value is HandleFieldMeta {
  * provider override re-enters the localization rules.
  */
 export function handleFieldDescription(meta: Pick<HandleFieldMeta, "issuedBy">): string {
-	const origin = meta.issuedBy ? ` issued by \`${meta.issuedBy}\`` : "";
+	const issuers = formatHandleIssuers(meta.issuedBy);
+	const origin = issuers ? ` issued by ${issuers}` : "";
 	return `Opaque handle${origin}. Copy it exactly as returned; do not edit or shorten it.`;
 }