@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.1

package/src/runtime/credential.ts

@@ -0,0 +1,95 @@
+import { CredentialModeError } from "../errors";
+import type { AuthMode, CredentialContext } from "../types";
+
+export interface CreateCredentialContextOptions {
+	allowedKeys?: string[];
+	mode?: AuthMode;
+	scopes?: string[];
+	values?: Record<string, string>;
+}
+
+function getAllowedKeys(
+	allowedKeys: string[] | undefined,
+	values: Record<string, string>,
+): string[] {
+	if (allowedKeys) {
+		return allowedKeys;
+	}
+
+	return Object.keys(values);
+}
+
+function normalizeScopes(
+	mode: AuthMode,
+	values: Record<string, string>,
+	scopes?: string[],
+): string[] {
+	if (mode !== "oauth2") {
+		return [];
+	}
+
+	if (scopes) {
+		return [...scopes];
+	}
+
+	const rawScopes = values.scope ?? values.scopes;
+	if (!rawScopes) {
+		return [];
+	}
+
+	return rawScopes
+		.split(/[\s,]+/)
+		.map((scope) => scope.trim())
+		.filter((scope) => scope.length > 0);
+}
+
+export function createCredentialContext(
+	options: CreateCredentialContextOptions = {},
+): CredentialContext {
+	const mode = options.mode ?? "none";
+	const values = options.values ?? {};
+	const allowedKeys = getAllowedKeys(options.allowedKeys, values);
+	const allowedKeySet = new Set(allowedKeys);
+	const normalizedScopes = normalizeScopes(mode, values, options.scopes);
+
+	return {
+		mode,
+		get(key: string): string | undefined {
+			if (!allowedKeySet.has(key)) {
+				return undefined;
+			}
+
+			return values[key];
+		},
+		getAll(): Record<string, string> {
+			const result: Record<string, string> = {};
+
+			for (const key of allowedKeys) {
+				const value = values[key];
+				if (value !== undefined) {
+					result[key] = value;
+				}
+			}
+
+			return result;
+		},
+		getAccessToken(): string | undefined {
+			if (mode !== "oauth2") {
+				throw new CredentialModeError(
+					"Access tokens are only available for oauth2 credential mode.",
+				);
+			}
+
+			return values.access_token;
+		},
+		getScopes(): string[] {
+			if (mode !== "oauth2") {
+				throw new CredentialModeError(
+					"OAuth scopes are only available for oauth2 credential mode.",
+				);
+			}
+
+			return [...normalizedScopes];
+		},
+	};
+}

package/src/runtime/env.ts

@@ -0,0 +1,13 @@
+import type { EnvContext } from "../types";
+
+export function createEnvContext(allowedKeys?: string[]): EnvContext {
+	return {
+		get(key: string): string | undefined {
+			if (allowedKeys && !allowedKeys.includes(key)) {
+				return undefined;
+			}
+
+			return process.env[key];
+		},
+	};
+}

package/src/runtime/executor.ts

@@ -1,8 +1,7 @@
 import { ProviderError } from "../errors";
+import { parseSchema } from "../schema";
 import type { ProviderContext, ProviderDefinition } from "../types";
 
-import { createAuthManager } from "./auth";
-
 /**
  * Execute a provider operation by calling its handler.
  *
@@ -19,7 +18,7 @@ export async function executeOperation(
 	operationId: string,
 	ctx: ProviderContext,
 	input: unknown,
-	options?: { skipAuth?: boolean },
+	_options?: { skipAuth?: boolean },
 ): Promise<unknown> {
 	const operation = provider.operations[operationId];
 
@@ -33,22 +32,22 @@ export async function executeOperation(
 		);
 	}
 
-	const validatedInput = operation.input.parse(input);
+	const validatedInput = await parseSchema(
+		operation.input,
+		input,
+		`operations.${operationId}.input`,
+	);
 
 	const execute = () =>
 		ctx.trace.span(`handler:${operationId}`, () =>
 			operation.handler(ctx, validatedInput),
 		);
 
-	const useAuth =
-		!options?.skipAuth && provider.auth && provider.auth.mode !== "none";
-
-	const result = useAuth
-		? await createAuthManager(provider.auth, ctx.session).wrapWithAutoRefresh(
-				ctx,
-				execute,
-			)
-		: await execute();
+	const result = await execute();
 
-	return operation.output.parse(result);
+	return parseSchema(
+		operation.output,
+		result,
+		`operations.${operationId}.output`,
+	);
 }

package/src/runtime/http.ts

@@ -17,6 +17,8 @@ const require = createRequire(import.meta.url);
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
 type FetchProxyInit = RequestInit & {
 	dispatcher?: unknown;
 	proxy?: string;
@@ -56,7 +58,8 @@ async function doRequest(
 	proxy: string | undefined,
 	options: RequestOptions & { body?: unknown } = {},
 ): Promise<HttpResponse> {
-	const { headers, params, timeout, body } = options;
+	const { headers, params, body } = options;
+	const timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
 	const controller = new AbortController();
 	let timeoutId: ReturnType<typeof setTimeout> | undefined;
@@ -80,12 +83,12 @@ async function doRequest(
 		});
 
 		if (!response.ok) {
-			const text = await response.text().catch(() => "");
+			await drainFetchResponse(response);
 			throw new TransportError(
-				`HTTP ${response.status} ${response.statusText}: ${requestUrl}`,
+				`Upstream request failed with status ${response.status}`,
 				{
+					code: "upstream_http_error",
 					status: response.status,
-					fix: `Check the endpoint URL and request parameters. Response: ${text.slice(0, 200)}`,
 				},
 			);
 		}
@@ -117,15 +120,13 @@ async function doRequest(
 		}
 
 		if (error instanceof Error && error.name === "AbortError") {
-			throw new TransportError(
-				`Request timed out: ${resolveUrl(baseUrl, url)}`,
-				{
-					fix: `Increase timeout option (current: ${timeout}ms)`,
-				},
-			);
+			throw new TransportError("Request timed out", {
+				code: "transport_timeout",
+			});
 		}
 
-		throw new TransportError(`Network error: ${String(error)}`, {
+		throw new TransportError("Network error", {
+			code: "transport_network_error",
 			cause: error instanceof Error ? error : undefined,
 		});
 	} finally {
@@ -135,6 +136,27 @@ async function doRequest(
 	}
 }
 
+async function drainFetchResponse(response: Response): Promise<void> {
+	const reader = response.body?.getReader();
+	if (!reader) {
+		return;
+	}
+
+	try {
+		while (true) {
+			const { done } = await reader.read();
+			if (done) {
+				return;
+			}
+		}
+	} catch {
+		// Best-effort drain for transport reuse only; callers still receive the
+		// sanitized upstream error below.
+	} finally {
+		reader.releaseLock();
+	}
+}
+
 function createProxyInit(
 	proxy?: string,
 ): Pick<FetchProxyInit, "dispatcher" | "proxy"> {
@@ -142,7 +164,9 @@ function createProxyInit(
 		return {};
 	}
 
-	if (typeof Bun !== "undefined") {
+	const bunRuntime = Object.getOwnPropertyDescriptor(globalThis, "Bun")?.value;
+
+	if (bunRuntime !== undefined) {
 		return { proxy };
 	}
 

package/src/runtime/insights.ts

@@ -27,7 +27,7 @@ const DNS_WARN_MS = 5;
 const BROWSER_IDLE_MS = 5_000;
 const REFRESH_WARN_RATE = 0.1;
 
-const TLS_REUSE_FIX = `const session = ctx.tls.createSession({ profile: 'chrome-131' });
+const TLS_REUSE_FIX = `const session = ctx.tls.createSession({ profile: 'chrome-146' });
 const resp = await session.fetch(url, opts);`;
 
 const TRANSFORM_FIX = `transformResponse: (raw) => {
@@ -39,7 +39,7 @@ const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
 });`;
 
 const DNS_FIX = `// Enable DNS caching or reuse a long-lived session per host.
-const session = ctx.tls.createSession({ profile: 'chrome-131' });
+const session = ctx.tls.createSession({ profile: 'chrome-146' });
 await session.fetch(url, opts);`;
 
 const PROXY_FIX = `// Re-check whether this operation really needs a proxy.
@@ -375,7 +375,7 @@ function getBrowserIdleInsight(spans: Span[]): InsightResult {
 
 function getSessionExpiryInsight(spans: Span[]): InsightResult {
 	const refreshCount = spans.filter(
-		(span) => span.name === "auth.refresh",
+		(span) => span.name === "credential.refresh",
 	).length;
 	const requestCount = spans.filter(isRequestSpan).length;
 

package/src/runtime/key-derivation.ts

@@ -0,0 +1,122 @@
+import { createHash, hkdfSync } from "node:crypto";
+
+/**
+ * HKDF purpose enum. Closed set; adding a purpose requires a spec amendment in
+ * `provider-isolation-hardening`. Each purpose uses a distinct salt so a leak
+ * of one subkey cannot reveal another for the same provider.
+ *
+ * Tenant-scoped columns (`connections.external_ref`, `connections.metadata`)
+ * are plaintext with RLS + log redaction + audit log; no HKDF purpose exists
+ * for them.
+ */
+export type KeyPurpose =
+	| "credential-encryption"
+	| "context-namespace"
+	| "token-signing";
+
+const SALT_PREFIX = "apifuse:v1:";
+const OUTPUT_LENGTH = 32;
+
+const cache = new Map<string, Buffer>();
+
+function cacheKey(
+	keyVersion: number,
+	providerId: string,
+	purpose: KeyPurpose,
+): string {
+	return `${keyVersion}\u0000${providerId}\u0000${purpose}`;
+}
+
+function computeSalt(purpose: KeyPurpose): Buffer {
+	return createHash("sha256")
+		.update(SALT_PREFIX + purpose)
+		.digest();
+}
+
+function computeInfo(providerId: string): Buffer {
+	return Buffer.from(`provider=${providerId}`, "utf8");
+}
+
+/** @internal Trusted loaders only; not re-exported to provider-importable paths. */
+export function decodeMasterKey(encoded: string): Buffer {
+	if (typeof encoded !== "string" || encoded.length === 0) {
+		throw new ConfigurationError(
+			"master key is empty; set APIFUSE_MASTER_KEY_V{n} in the external secret manager",
+		);
+	}
+
+	const normalized = encoded.replace(/-/g, "+").replace(/_/g, "/");
+	const padded =
+		normalized.length % 4 === 0
+			? normalized
+			: normalized + "=".repeat(4 - (normalized.length % 4));
+
+	// Pre-decode character set guard — Buffer.from silently accepts invalid base64.
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(padded)) {
+		throw new ConfigurationError("master key is not valid base64");
+	}
+
+	const raw = Buffer.from(padded, "base64");
+
+	// Invalid base64 truncates silently; compare against the expected decode length.
+	const expectedMinLength = Math.floor((padded.length * 3) / 4) - 2;
+	if (raw.length < expectedMinLength) {
+		throw new ConfigurationError("master key is not valid base64");
+	}
+
+	if (raw.length < 32) {
+		throw new ConfigurationError(
+			`master key must be ≥ 32 bytes after base64 decode (got ${raw.length})`,
+		);
+	}
+
+	return raw;
+}
+
+export class ConfigurationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ConfigurationError";
+	}
+}
+
+/** @internal Trusted loaders only; not re-exported to provider-importable paths. */
+export function deriveSubkey(
+	masterSecret: Buffer,
+	providerId: string,
+	purpose: KeyPurpose,
+	keyVersion: number,
+): Buffer {
+	if (masterSecret.length < 32) {
+		throw new ConfigurationError(
+			`master key must be ≥ 32 bytes (got ${masterSecret.length})`,
+		);
+	}
+	if (providerId.length === 0) {
+		throw new ConfigurationError("providerId is empty");
+	}
+
+	const key = cacheKey(keyVersion, providerId, purpose);
+	const cached = cache.get(key);
+	if (cached) {
+		return cached;
+	}
+
+	const salt = computeSalt(purpose);
+	const info = computeInfo(providerId);
+	const subkey = Buffer.from(
+		hkdfSync("sha256", masterSecret, salt, info, OUTPUT_LENGTH),
+	);
+	cache.set(key, subkey);
+	return subkey;
+}
+
+/**
+ * Invalidate the subkey cache. Used by the master-key rotation worker after a
+ * writer version change, and by tests to assert determinism.
+ *
+ * @internal
+ */
+export function invalidateSubkeyCache(): void {
+	cache.clear();
+}

package/src/runtime/keyring.ts

@@ -0,0 +1,148 @@
+import { ConfigurationError, decodeMasterKey } from "./key-derivation";
+
+export interface KeyRingOptions {
+	env: NodeJS.ProcessEnv;
+	envPrefix?: string;
+	acceptListVar?: string;
+	writerVersionVar?: string;
+}
+
+export interface KeyRingEntry {
+	version: number;
+	key: Buffer;
+}
+
+export interface KeyRing {
+	accept(version: number): KeyRingEntry;
+	activeWriter(): KeyRingEntry;
+	versions(): number[];
+	purgeVersion(
+		version: number,
+		isActiveInStore: (v: number) => Promise<boolean>,
+	): Promise<void>;
+}
+
+const DEFAULT_KEY_PREFIX = "APIFUSE_MASTER_KEY_V";
+const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE_MASTER_KEY_ACCEPT_LIST";
+const DEFAULT_WRITER_VERSION_VAR = "APIFUSE_MASTER_KEY_WRITER_VERSION";
+
+function parseAcceptList(raw: string | undefined): number[] {
+	if (!raw || raw.trim().length === 0) {
+		throw new ConfigurationError(
+			`accept-list env var is empty; expected comma-separated master key versions`,
+		);
+	}
+
+	const parts = raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+	const versions: number[] = [];
+	for (const part of parts) {
+		const v = Number.parseInt(part, 10);
+		if (!Number.isInteger(v) || v <= 0 || String(v) !== part) {
+			throw new ConfigurationError(
+				`accept-list contains invalid version "${part}"; expected positive integers`,
+			);
+		}
+		versions.push(v);
+	}
+
+	if (versions.length === 0) {
+		throw new ConfigurationError("accept-list is empty after parsing");
+	}
+
+	return versions;
+}
+
+function parseWriterVersion(
+	raw: string | undefined,
+	acceptList: number[],
+): number {
+	if (!raw || raw.trim().length === 0) {
+		throw new ConfigurationError("writer-version env var is empty");
+	}
+	const trimmed = raw.trim();
+	const v = Number.parseInt(trimmed, 10);
+	if (!Number.isInteger(v) || v <= 0 || String(v) !== trimmed) {
+		throw new ConfigurationError(
+			`writer-version "${trimmed}" is not a positive integer`,
+		);
+	}
+	if (!acceptList.includes(v)) {
+		throw new ConfigurationError(
+			`writer-version ${v} is not in the accept-list [${acceptList.join(", ")}]`,
+		);
+	}
+	return v;
+}
+
+/**
+ * @internal Trusted loaders only; not re-exported to provider-importable paths.
+ *
+ * Loads master keys from the external-secret-manager-injected env (one entry per
+ * accepted version). Caller must keep the resulting {@link KeyRing} alive for the
+ * process lifetime; rotation requires a restart (or an explicit reload utility
+ * added later).
+ */
+export function loadKeyRing(options: KeyRingOptions): KeyRing {
+	const env = options.env;
+	const prefix = options.envPrefix ?? DEFAULT_KEY_PREFIX;
+	const acceptListVar = options.acceptListVar ?? DEFAULT_ACCEPT_LIST_VAR;
+	const writerVersionVar =
+		options.writerVersionVar ?? DEFAULT_WRITER_VERSION_VAR;
+
+	const acceptList = parseAcceptList(env[acceptListVar]);
+	const writerVersion = parseWriterVersion(env[writerVersionVar], acceptList);
+
+	const entries = new Map<number, KeyRingEntry>();
+	for (const version of acceptList) {
+		const raw = env[`${prefix}${version}`];
+		if (raw === undefined) {
+			throw new ConfigurationError(
+				`${prefix}${version} is missing (listed in accept-list)`,
+			);
+		}
+		const key = decodeMasterKey(raw);
+		entries.set(version, { version, key });
+	}
+
+	return {
+		accept(version) {
+			const entry = entries.get(version);
+			if (!entry) {
+				throw new ConfigurationError(
+					`version ${version} is not accepted; accept-list is [${acceptList.join(", ")}]`,
+				);
+			}
+			return entry;
+		},
+
+		activeWriter() {
+			const entry = entries.get(writerVersion);
+			if (!entry) {
+				throw new ConfigurationError(
+					`writer version ${writerVersion} is missing from accept-list entries`,
+				);
+			}
+			return entry;
+		},
+
+		versions() {
+			return [...acceptList];
+		},
+
+		async purgeVersion(version, isActiveInStore) {
+			if (!entries.has(version)) {
+				return;
+			}
+			const active = await isActiveInStore(version);
+			if (active) {
+				throw new ConfigurationError(
+					`cannot purge master-key version ${version}: active connection rows still reference it`,
+				);
+			}
+			entries.delete(version);
+		},
+	};
+}

package/src/runtime/namespace.ts

@@ -0,0 +1,33 @@
+import { createHmac } from "node:crypto";
+
+import { deriveSubkey } from "./key-derivation";
+
+const HMAC_HEX_LENGTH = 16;
+
+/**
+ * @internal Trusted loaders only; not re-exported to provider-importable paths.
+ *
+ * Returns `provider:{HMAC16(contextNamespaceSubkey, providerId)}:{sessionId}`
+ * per the `context-namespace` HKDF purpose. Knowing `providerId` alone is
+ * insufficient to reconstruct the namespace — the HMAC requires the derived
+ * subkey, which is never exposed outside trusted code.
+ */
+export function deriveContextNamespace(
+	masterSecret: Buffer,
+	providerId: string,
+	sessionId: string,
+	keyVersion: number,
+): string {
+	if (sessionId.length === 0) {
+		throw new Error("sessionId is empty");
+	}
+
+	const subkey = deriveSubkey(
+		masterSecret,
+		providerId,
+		"context-namespace",
+		keyVersion,
+	);
+	const hmac = createHmac("sha256", subkey).update(providerId).digest("hex");
+	return `provider:${hmac.slice(0, HMAC_HEX_LENGTH)}:${sessionId}`;
+}