@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/egress-lease.d.ts

@@ -0,0 +1,65 @@
+import type { ProxyVendorName } from "../config/loader.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export declare const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export declare const ENGINE_CEREMONY_EGRESS_LEASE: unique symbol;
+export type CeremonyEgressBinding = {
+    readonly vendor: ProxyVendorName;
+    readonly proxyUrl: string;
+    readonly poolIndex: number;
+    readonly affinityKey: string;
+    readonly refreshEpoch: number;
+    /**
+     * Vendor session lifetime the endpoint was allocated for (`proxy.session.lifetimeMinutes`,
+     * Smartproxy `life`, NodeMaven SID window). It is the upper bound of the lease, counted
+     * from the mint (the first successful attempt), so a Smartproxy lease can outlive the
+     * vendor session by the extraction-cache reuse window; expiry then drops and rebinds.
+     * The bound is not a vendor guarantee (ADR-0010: a raw Smartproxy endpoint is not a hard
+     * lease): the stealth runtime releases the binding as soon as the endpoint fails at the
+     * transport, so a dead endpoint is left before the lifetime elapses.
+     */
+    readonly lifetimeMinutes: number;
+};
+export type CeremonyEgressLeaseRuntime = {
+    /** Exact egress bound to this ceremony; undefined until the first successful attempt binds one. */
+    readonly binding: CeremonyEgressBinding | undefined;
+    /**
+     * Drops the binding once its vendor session lifetime has elapsed so the next attempt
+     * selects and binds a fresh endpoint. Returns true when a binding was dropped: the
+     * caller must also discard challenge state that was only valid for that endpoint.
+     */
+    dropExpiredBinding(): boolean;
+    /**
+     * Drops the binding unconditionally; the stealth runtime calls this when the bound
+     * endpoint fails at the transport. Same return and caller obligation as
+     * `dropExpiredBinding`.
+     */
+    dropBinding(): boolean;
+    /**
+     * Number of bindings dropped so far (expiry or release). Every stealth session created
+     * from one client shares the lease; a session compares this to what it last observed to
+     * retire endpoint-bound challenge state and replay records after another session moved
+     * the ceremony.
+     */
+    readonly generation: number;
+    bind(binding: CeremonyEgressBinding): void;
+    handle(): string | undefined;
+};
+export declare function createCeremonyEgressLeaseRuntime(options: {
+    readonly tenantId?: string;
+    readonly providerId: string;
+    readonly flowId: string;
+    readonly affinityKey: string;
+    readonly handle?: string;
+    /** Server-only registration before a handle can reach request diagnostics. */
+    readonly onHandle?: (handle: string) => void;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly now?: () => number;
+}): CeremonyEgressLeaseRuntime;

package/dist/runtime/egress-lease.js

@@ -0,0 +1,236 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { SDKError } from "../errors.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export const ENGINE_CEREMONY_EGRESS_LEASE = Symbol.for("@apifuse/provider-sdk/engine-ceremony-egress-lease");
+const HANDLE_VERSION = 1;
+const HANDLE_MAX_BYTES = 16_384;
+const AEAD_NONCE_BYTES = 12;
+const AEAD_TAG_BYTES = 16;
+const AEAD_ALGORITHM = "aes-256-gcm";
+const AEAD_KEY_DOMAIN = "apifuse:ceremony-egress-lease:v1\0";
+const LEASE_KEY_MIN_BYTES = 32;
+/** The caller presented a handle this engine cannot verify for this ceremony (409). */
+function invalidLease() {
+    throw new SDKError("The engine ceremony egress lease is invalid", {
+        code: "EGRESS_LEASE_INVALID",
+        fix: "Restart the authentication ceremony to obtain a new engine-owned egress lease.",
+    });
+}
+/** The engine violated its own binding invariant (500); never attributable to the caller. */
+function bindingFault(message) {
+    throw new SDKError(message, {
+        code: "EGRESS_LEASE_BINDING_INVALID",
+        fix: "This is an SDK or provider-runtime fault; the ceremony lease cannot bind the selected egress.",
+    });
+}
+function encryptionKey(key) {
+    return createHash("sha256").update(AEAD_KEY_DOMAIN, "utf8").update(key, "utf8").digest();
+}
+/** Fixed field order and JSON.stringify's compact form are the canonical AAD encoding. */
+function scopeAad(scope) {
+    return Buffer.from(JSON.stringify({
+        version: HANDLE_VERSION,
+        tenantId: scope.tenantId,
+        providerId: scope.providerId,
+        flowId: scope.flowId,
+        affinityKey: scope.affinityKey,
+    }), "utf8");
+}
+function encodeHandle(payload, key, scope) {
+    const nonce = randomBytes(AEAD_NONCE_BYTES);
+    const cipher = createCipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+        authTagLength: AEAD_TAG_BYTES,
+    });
+    cipher.setAAD(scopeAad(scope));
+    const ciphertext = Buffer.concat([
+        cipher.update(JSON.stringify(payload), "utf8"),
+        cipher.final(),
+    ]);
+    return [
+        `v${HANDLE_VERSION}`,
+        nonce.toString("base64url"),
+        ciphertext.toString("base64url"),
+        cipher.getAuthTag().toString("base64url"),
+    ].join(".");
+}
+function isFiniteInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function decodeHandle(handle, key, scope) {
+    if (Buffer.byteLength(handle, "utf8") > HANDLE_MAX_BYTES)
+        return invalidLease();
+    const parts = handle.split(".");
+    if (parts.length !== 4 ||
+        parts[0] !== `v${HANDLE_VERSION}` ||
+        parts.slice(1).some((part) => !/^[A-Za-z0-9_-]+$/u.test(part))) {
+        return invalidLease();
+    }
+    let parsed;
+    try {
+        const nonce = Buffer.from(parts[1], "base64url");
+        const ciphertext = Buffer.from(parts[2], "base64url");
+        const tag = Buffer.from(parts[3], "base64url");
+        if (nonce.byteLength !== AEAD_NONCE_BYTES ||
+            tag.byteLength !== AEAD_TAG_BYTES ||
+            ciphertext.byteLength === 0) {
+            return invalidLease();
+        }
+        const decipher = createDecipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+            authTagLength: AEAD_TAG_BYTES,
+        });
+        decipher.setAAD(scopeAad(scope));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        parsed = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        return invalidLease();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return invalidLease();
+    const candidate = parsed;
+    if (candidate.version !== HANDLE_VERSION ||
+        (candidate.vendor !== "smartproxy" && candidate.vendor !== "nodemaven") ||
+        typeof candidate.proxyUrl !== "string" ||
+        !candidate.proxyUrl ||
+        !isFiniteInteger(candidate.poolIndex) ||
+        typeof candidate.affinityKey !== "string" ||
+        !candidate.affinityKey ||
+        !isFiniteInteger(candidate.refreshEpoch) ||
+        typeof candidate.tenantId !== "string" ||
+        !candidate.tenantId ||
+        typeof candidate.providerId !== "string" ||
+        !candidate.providerId ||
+        typeof candidate.flowId !== "string" ||
+        !candidate.flowId ||
+        !isFiniteInteger(candidate.mintedAtMs) ||
+        !isFiniteInteger(candidate.expiresAtMs) ||
+        candidate.expiresAtMs <= candidate.mintedAtMs ||
+        !isPositiveFinite(candidate.lifetimeMinutes)) {
+        return invalidLease();
+    }
+    try {
+        const proxy = new URL(candidate.proxyUrl);
+        if (proxy.protocol !== "http:" && proxy.protocol !== "socks5:")
+            return invalidLease();
+    }
+    catch {
+        return invalidLease();
+    }
+    return candidate;
+}
+function bindingOf(payload) {
+    return {
+        vendor: payload.vendor,
+        proxyUrl: payload.proxyUrl,
+        poolIndex: payload.poolIndex,
+        affinityKey: payload.affinityKey,
+        refreshEpoch: payload.refreshEpoch,
+        lifetimeMinutes: payload.lifetimeMinutes,
+    };
+}
+export function createCeremonyEgressLeaseRuntime(options) {
+    const environment = options.environment ?? process.env;
+    const now = options.now ?? Date.now;
+    if (typeof options.tenantId !== "string" || !options.tenantId.trim()) {
+        throw new SDKError("A tenant is required for an engine ceremony egress lease", {
+            code: "EGRESS_LEASE_INVALID",
+            fix: "Restart the authentication ceremony with its tenant identity.",
+        });
+    }
+    const scope = {
+        tenantId: options.tenantId,
+        providerId: options.providerId,
+        flowId: options.flowId,
+        affinityKey: options.affinityKey,
+    };
+    const key = readDiagnosticEnv(APIFUSE__ENGINE__CEREMONY_LEASE_KEY, environment)?.trim();
+    if (!key) {
+        throw new SDKError("The engine ceremony egress lease key is not configured", {
+            code: "EGRESS_LEASE_KEY_MISSING",
+            fix: `Configure ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} in the engine host.`,
+        });
+    }
+    // The key is the whole authenticity boundary of a handle (a verified handle's proxyUrl
+    // becomes the ceremony egress), so the documented minimum is enforced, not advisory.
+    if (Buffer.byteLength(key, "utf8") < LEASE_KEY_MIN_BYTES) {
+        throw new SDKError(`The engine ceremony egress lease key is shorter than ${LEASE_KEY_MIN_BYTES} bytes`, {
+            code: "EGRESS_LEASE_KEY_WEAK",
+            fix: `Set ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} to at least ${LEASE_KEY_MIN_BYTES} random bytes (for example \`openssl rand -base64 32\`).`,
+        });
+    }
+    let payload;
+    let currentHandle;
+    let generation = 0;
+    const dropBinding = () => {
+        if (!payload)
+            return false;
+        payload = undefined;
+        currentHandle = undefined;
+        generation += 1;
+        return true;
+    };
+    const dropExpiredBinding = () => payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
+    if (options.handle !== undefined) {
+        options.onHandle?.(options.handle);
+        // Scope mismatch fails GCM authentication because scope is AAD; there is
+        // deliberately no post-decrypt scope comparison fallback.
+        payload = decodeHandle(options.handle, key, scope);
+        currentHandle = options.handle;
+        // An expired but authentic handle is not a fault: the ceremony continues on a
+        // freshly selected endpoint and the next turn receives the new handle.
+        dropExpiredBinding();
+    }
+    return {
+        get binding() {
+            return payload ? bindingOf(payload) : undefined;
+        },
+        dropExpiredBinding,
+        dropBinding,
+        get generation() {
+            return generation;
+        },
+        bind(binding) {
+            if (payload) {
+                // The stealth runtime reuses the bound endpoint while a binding exists and
+                // never rebinds it; a second bind is an engine invariant break.
+                return bindingFault("The ceremony egress lease is already bound");
+            }
+            if (binding.affinityKey !== options.affinityKey ||
+                !binding.proxyUrl ||
+                (binding.vendor !== "smartproxy" && binding.vendor !== "nodemaven") ||
+                !isFiniteInteger(binding.poolIndex) ||
+                !isPositiveFinite(binding.lifetimeMinutes)) {
+                return bindingFault("The selected egress cannot be bound to the ceremony lease");
+            }
+            const mintedAtMs = now();
+            payload = {
+                version: HANDLE_VERSION,
+                tenantId: scope.tenantId,
+                providerId: options.providerId,
+                flowId: options.flowId,
+                ...binding,
+                mintedAtMs,
+                expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
+            };
+            currentHandle = encodeHandle(payload, key, scope);
+            options.onHandle?.(currentHandle);
+        },
+        handle() {
+            return currentHandle;
+        },
+    };
+}

package/dist/runtime/engine-mode.d.ts

@@ -0,0 +1,74 @@
+import { type ProviderEngine, type ProviderEngineMode } from "../engine.js";
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export declare const DEFAULT_PROVIDER_ENGINE_MODE = "in-process";
+/** Remote engine client endpoint; engine-owned, so never declarable as a provider secret. */
+export declare const REMOTE_ENGINE_CLIENT_URL_ENV = "APIFUSE__ENGINE__URL";
+/** Remote engine client credential; registered with the diagnostic redactor by sensitive-values. */
+export declare const REMOTE_ENGINE_CLIENT_API_KEY_ENV = "APIFUSE__ENGINE__API_KEY";
+/** Where the resolved mode came from, in precedence order. */
+export type ProviderEngineModeSource = "engine" | "env" | "option" | "default";
+/**
+ * Non-fatal conditions worth reporting at boot:
+ * - `invalid_env_value`: `APIFUSE__ENGINE__MODE` held an unrecognized value.
+ * - `env_overrode_option`: the manifest and the host code disagreed; the manifest won.
+ * - `engine_object_overrode_requested_mode`: an explicit engine object cannot honour the requested mode.
+ * - `engine_env_ignored`: remote-only engine env is projected but the mode is not
+ *   remote (not reported for a host-supplied engine, which may consume it itself).
+ */
+export type ProviderEngineModeWarning = "invalid_env_value" | "env_overrode_option" | "engine_object_overrode_requested_mode" | "engine_env_ignored";
+export interface ProviderEngineModeResolution {
+    readonly mode: ProviderEngineMode | "custom";
+    readonly source: ProviderEngineModeSource;
+    /** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+    readonly deprecated: boolean;
+    readonly warnings: readonly ProviderEngineModeWarning[];
+}
+export interface ProviderEngineModeResolutionInput {
+    /** Explicit `engineMode` option passed by the host process. */
+    readonly option?: ProviderEngineMode;
+    /** Explicit engine object passed by the host; used as given when present. */
+    readonly engine?: Pick<ProviderEngine, "kind">;
+    /** Environment to read the engine env from; defaults to `process.env`. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolve the engine attachment mode once at boot.
+ *
+ * Precedence: an explicit `engine` object, then `APIFUSE__ENGINE__MODE`, then the
+ * `engineMode` option, then the default. The manifest outranks the option so
+ * provider code cannot silently downgrade what the deployment asked for; every
+ * disagreement is reported in `warnings` with a truthful `source` rather than
+ * being dropped.
+ *
+ * Deployment-authored input is never fatal (an unrecognized env value is warned
+ * about and ignored). A malformed `engineMode` option is a fault in the calling
+ * code, which no manifest can reach, so it throws.
+ */
+export declare function resolveProviderEngineMode(input?: ProviderEngineModeResolutionInput): ProviderEngineModeResolution;
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export declare function isUnavailableProviderEngine(engine: ProviderEngine): boolean;
+/**
+ * Engine that refuses every attachment with `reason`.
+ *
+ * Requesting a mode this release cannot serve must not crash the process: the SDK
+ * answers a structured error per request and reports the process unready, the same
+ * trade-off `provider_secrets_missing` already makes at boot. Non-retryable, so a
+ * caller-side retry loop cannot turn a configuration fault into load.
+ */
+export declare function createUnavailableProviderEngine(kind: ProviderEngineMode, reason: {
+    message: string;
+    code: string;
+    fix: string;
+}): ProviderEngine;
+/**
+ * Engine for a resolved mode. `remote` has no client in this release, so it
+ * resolves to an engine that fails every request instead of falling back to
+ * in-process (ADR-0011 Pitfall 2: in-process is never a fallback).
+ */
+export declare function createEngineForMode(mode: ProviderEngineMode | "custom"): ProviderEngine;
+/**
+ * Fail fast for the CLIs (`apifuse dev`, `apifuse record`). They are developer
+ * tools, not pods: an unusable mode should stop the command rather than start a
+ * server that refuses every request.
+ */
+export declare function assertProcessEngineModeSupported(environment?: Readonly<Record<string, string | undefined>>): ProviderEngineModeResolution;

package/dist/runtime/engine-mode.js

@@ -0,0 +1,152 @@
+import { createInProcessProviderEngine, PROVIDER_ENGINE_MODE_ENV, } from "../engine.js";
+import { ProviderError, ValidationError } from "../errors.js";
+/**
+ * Engine attachment selection. Internal on purpose: ADR-0011 removes the
+ * in-process lane, so every symbol exported here would become a breaking removal
+ * later. The server surfaces the outcome on the `provider_engine_mode` boot
+ * event instead.
+ */
+const KNOWN_PROVIDER_ENGINE_MODES = ["in-process", "remote"];
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export const DEFAULT_PROVIDER_ENGINE_MODE = "in-process";
+/** Remote engine client endpoint; engine-owned, so never declarable as a provider secret. */
+export const REMOTE_ENGINE_CLIENT_URL_ENV = "APIFUSE__ENGINE__URL";
+/** Remote engine client credential; registered with the diagnostic redactor by sensitive-values. */
+export const REMOTE_ENGINE_CLIENT_API_KEY_ENV = "APIFUSE__ENGINE__API_KEY";
+/** Engine env names that only mean something in remote mode. */
+const REMOTE_ONLY_ENGINE_ENV_NAMES = [
+    REMOTE_ENGINE_CLIENT_URL_ENV,
+    REMOTE_ENGINE_CLIENT_API_KEY_ENV,
+];
+function isKnownMode(value) {
+    return KNOWN_PROVIDER_ENGINE_MODES.includes(value);
+}
+function normalize(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim().toLowerCase();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * Resolve the engine attachment mode once at boot.
+ *
+ * Precedence: an explicit `engine` object, then `APIFUSE__ENGINE__MODE`, then the
+ * `engineMode` option, then the default. The manifest outranks the option so
+ * provider code cannot silently downgrade what the deployment asked for; every
+ * disagreement is reported in `warnings` with a truthful `source` rather than
+ * being dropped.
+ *
+ * Deployment-authored input is never fatal (an unrecognized env value is warned
+ * about and ignored). A malformed `engineMode` option is a fault in the calling
+ * code, which no manifest can reach, so it throws.
+ */
+export function resolveProviderEngineMode(input = {}) {
+    const environment = input.environment ?? process.env;
+    const warnings = [];
+    // Read directly: this is a mode name, not a credential, so it must not be
+    // registered with the diagnostic redactor the way readDiagnosticEnv is.
+    const rawEnv = normalize(environment[PROVIDER_ENGINE_MODE_ENV]);
+    let envMode;
+    if (rawEnv !== undefined) {
+        if (isKnownMode(rawEnv))
+            envMode = rawEnv;
+        else
+            warnings.push("invalid_env_value");
+    }
+    const optionMode = normalize(input.option);
+    if (input.option !== undefined && (optionMode === undefined || !isKnownMode(optionMode))) {
+        throw new ValidationError(`Invalid engineMode option "${String(input.option)}"; expected ${KNOWN_PROVIDER_ENGINE_MODES.join(" or ")}`, { fix: 'Pass engineMode: "in-process" | "remote", or omit it to use the default.' });
+    }
+    if (optionMode !== undefined && envMode !== undefined && optionMode !== envMode) {
+        warnings.push("env_overrode_option");
+    }
+    const requested = envMode ?? optionMode;
+    const requestedSource = envMode !== undefined ? "env" : optionMode !== undefined ? "option" : undefined;
+    // Normalized like every other mode input: an un-normalized host `kind` would
+    // reach the boot event and /readyz verbatim and mis-score the fleet audit.
+    const engineKind = input.engine === undefined ? undefined : (normalize(input.engine.kind) ?? "custom");
+    if (engineKind !== undefined) {
+        if (requested !== undefined && engineKind !== requested) {
+            warnings.push("engine_object_overrode_requested_mode");
+        }
+        return finalize(engineKind, "engine", environment, warnings);
+    }
+    return finalize(requested ?? DEFAULT_PROVIDER_ENGINE_MODE, requestedSource ?? "default", environment, warnings);
+}
+function finalize(mode, source, environment, warnings) {
+    // Presence of the remote engine env never selects a mode (the manifest
+    // generator projects it fleet-wide before the SDK can use it), but staying
+    // silent about it would hide a half-applied cutover. Skipped for a host-supplied
+    // engine: that object may be a remote client that consumes the env itself, so
+    // claiming the env is unused would be a false report.
+    if (mode !== "remote" &&
+        source !== "engine" &&
+        REMOTE_ONLY_ENGINE_ENV_NAMES.some((name) => normalize(environment[name]) !== undefined)) {
+        warnings.push("engine_env_ignored");
+    }
+    // Fail-closed for the ADR-0011 audit: everything that is not the remote lane
+    // still attaches capabilities inside the pod process and is scheduled for
+    // removal, including an opaque host engine that declares no kind.
+    return { mode, source, deprecated: mode !== "remote", warnings };
+}
+const UNAVAILABLE_ENGINES = new WeakSet();
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export function isUnavailableProviderEngine(engine) {
+    return UNAVAILABLE_ENGINES.has(engine);
+}
+/**
+ * Engine that refuses every attachment with `reason`.
+ *
+ * Requesting a mode this release cannot serve must not crash the process: the SDK
+ * answers a structured error per request and reports the process unready, the same
+ * trade-off `provider_secrets_missing` already makes at boot. Non-retryable, so a
+ * caller-side retry loop cannot turn a configuration fault into load.
+ */
+export function createUnavailableProviderEngine(kind, reason) {
+    const engine = {
+        kind,
+        attach: () => {
+            throw new ProviderError(reason.message, {
+                code: reason.code,
+                retryable: false,
+                fix: reason.fix,
+            });
+        },
+    };
+    UNAVAILABLE_ENGINES.add(engine);
+    return engine;
+}
+/**
+ * Engine for a resolved mode. `remote` has no client in this release, so it
+ * resolves to an engine that fails every request instead of falling back to
+ * in-process (ADR-0011 Pitfall 2: in-process is never a fallback).
+ */
+export function createEngineForMode(mode) {
+    // Default-deny on the mode name, not just on "remote": the mode union is open
+    // so a later lane can be named, and falling through to in-process for an
+    // unserved lane is the silent downgrade ADR-0011 Pitfall 2 forbids.
+    if (mode === DEFAULT_PROVIDER_ENGINE_MODE)
+        return createInProcessProviderEngine();
+    return createUnavailableProviderEngine(mode, {
+        message: `Provider engine mode "${mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`,
+        code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+        fix: `Unset ${PROVIDER_ENGINE_MODE_ENV} (or the engineMode option), or upgrade to a release that serves this mode.`,
+    });
+}
+/**
+ * Fail fast for the CLIs (`apifuse dev`, `apifuse record`). They are developer
+ * tools, not pods: an unusable mode should stop the command rather than start a
+ * server that refuses every request.
+ */
+export function assertProcessEngineModeSupported(environment = process.env) {
+    const resolution = resolveProviderEngineMode({ environment });
+    if (resolution.mode !== DEFAULT_PROVIDER_ENGINE_MODE) {
+        throw new ProviderError(`Provider engine mode "${resolution.mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`, {
+            code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+            retryable: false,
+            details: { mode: resolution.mode, source: resolution.source },
+            fix: `Unset ${PROVIDER_ENGINE_MODE_ENV}, or upgrade to a release that serves this mode.`,
+        });
+    }
+    return resolution;
+}

package/dist/runtime/env.js

@@ -1,10 +1,23 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { isEngineOwnedEnvName } from "../engine.js";
+/**
+ * A mixed-case spelling of an engine-owned name is an alias: on Windows it resolves to the
+ * engine's variable while evading an exact-name allowlist. Only the exact (upper-case) name,
+ * which engine-internal contexts allowlist explicitly, may read those values.
+ */
+function isEngineOwnedEnvAlias(key) {
+    return isEngineOwnedEnvName(key) && key !== key.toUpperCase();
+}
 export function createEnvContext(allowedKeys) {
     return {
         get(key) {
             if (allowedKeys && !allowedKeys.includes(key)) {
                 return undefined;
             }
-            return process.env[key];
+            if (isEngineOwnedEnvAlias(key)) {
+                return undefined;
+            }
+            return readDiagnosticEnv(key);
         },
     };
 }

package/dist/runtime/executor.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderContext, ProviderDefinition } from "../types.js";
+import type { EnvContext, ProviderDefinition } from "../types.js";
 export declare function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean;
 /**
  * Execute a provider operation by calling its handler.
@@ -11,6 +11,7 @@ export declare function isStreamingOperation(provider: ProviderDefinition, opera
  *
  * @see openspec/provider-sdk/03-sdk-core.md §3.6
  */
-export declare function executeOperation(provider: ProviderDefinition, operationId: string, ctx: ProviderContext, input: unknown, _options?: {
+export declare function executeOperation<const TProvider extends ProviderDefinition, const TOperationId extends keyof TProvider["operations"] & string>(provider: TProvider, operationId: TOperationId, ctx: NoInfer<Parameters<TProvider["operations"][TOperationId]["handler"]>[0]>, input: unknown, _options?: {
     skipAuth?: boolean;
+    env?: EnvContext;
 }): Promise<unknown>;

package/dist/runtime/executor.js

@@ -1,4 +1,5 @@
-import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import { isValidationError, ProviderError, ValidationError, } from "../errors.js";
+import { z } from "zod";
 import { parseSchema } from "../schema.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
@@ -21,6 +22,9 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (!operation) {
         throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
             code: "NOT_FOUND",
+            // No upstream was asked: keep the registered NOT_FOUND code from
+            // attributing this to one.
+            category: "provider_error",
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
@@ -29,35 +33,28 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     // handler, so every invocation path (serve /v1, self-test probes, perf,
     // record) fails with the same structured MISSING_SECRET error instead of a
     // handler-specific crash. Providers must not re-check presence locally.
-    assertRequiredSecretsPresent(provider, ctx.env);
+    if (provider.secrets?.some((secret) => secret.required === true)) {
+        assertRequiredSecretsPresent(provider, _options?.env ?? ("env" in ctx ? ctx.env : { get: () => undefined }));
+    }
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
-    let result;
+    const result = await execute();
+    if (isStreamingOperation(provider, operationId)) {
+        return result;
+    }
     try {
-        result = await execute();
+        return await parseSchema(operation.output, result, `operations.${operationId}.output`);
     }
-    catch (error) {
-        // Session expiry is renewed by Credential Service via the /auth/refresh
-        // route, NOT in-process here: this executor cannot mutate ctx.credential,
-        // so an in-process retry would just repeat the call with the same stale
-        // credential (and risk repeating partial side-effects). Instead we surface
-        // the expiry so Credential Service refreshes and re-drives the operation
-        // with a fresh credential. `retryOnAuthRefresh` declares that this
-        // operation is safe to re-drive after refresh, which we signal by marking
-        // the surfaced error retryable; non-idempotent operations (the default)
-        // stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-        // Use the branded guard, not `instanceof`: a handler loaded through a
-        // duplicate/published SDK module can throw a correctly branded
-        // SessionExpiredError whose constructor identity differs from this
-        // executor's, which `instanceof` would miss — dropping the retryable
-        // upgrade and stranding an operation that opted into auth refresh.
-        if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
-            throw new SessionExpiredError(error.message, { retryable: true });
+    catch (cause) {
+        if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+            throw cause;
         }
-        throw error;
-    }
-    if (isStreamingOperation(provider, operationId)) {
-        return result;
+        throw new ValidationError(`Operation handler output failed schema validation.`, {
+            code: "OUTPUT_VALIDATION_FAILED",
+            category: "output_validation",
+            retryable: false,
+            zodError: isValidationError(cause) ? cause.zodError : cause,
+            ...(cause instanceof Error ? { cause } : {}),
+        });
     }
-    return parseSchema(operation.output, result, `operations.${operationId}.output`);
 }