@apifuse/provider-sdk 2.1.0-beta.8 → 2.2.0-beta.1

package/src/runtime/stealth.ts

@@ -18,6 +18,7 @@ import type {
 	HttpRetryOptions,
 	StealthClient,
 	StealthFetchOptions,
+	StealthRedirectHop,
 	StealthResponse,
 	StealthSession,
 } from "../types";
@@ -128,10 +129,16 @@ const FIREFOX_IMPIT_BY_MAJOR: Record<number, ImpitBrowser> = {
 
 type StealthTransportResponse = Pick<
 	ImpitResponse,
-	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text" | "url"
->;
+	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"
+> & {
+	url?: string;
+	redirected?: boolean;
+};
 
 type StealthMethod = NonNullable<ImpitRequestInit["method"]>;
+type StealthRequestInit = ImpitRequestInit & {
+	redirect?: NonNullable<StealthFetchOptions["redirect"]>;
+};
 type NormalizedStealthRetryOptions = {
 	attempts: number;
 	methods: readonly string[];
@@ -177,12 +184,37 @@ class CookieJarImpl implements CookieJar {
 		return { ...this.cookies };
 	}
 
+	has(name: string): boolean {
+		return Object.hasOwn(this.cookies, name);
+	}
+
 	toString(): string {
 		return Object.entries(this.cookies)
 			.map(([name, value]) => `${name}=${value}`)
 			.join("; ");
 	}
 
+	toHeader(): string {
+		return this.toString();
+	}
+
+	snapshot(): Record<string, string> {
+		return this.getAll();
+	}
+
+	restore(cookies: Record<string, string>): void {
+		this.clear();
+		for (const [name, value] of Object.entries(cookies)) {
+			if (name) this.cookies[name] = value;
+		}
+	}
+
+	clear(): void {
+		for (const name of Object.keys(this.cookies)) {
+			delete this.cookies[name];
+		}
+	}
+
 	find(predicate: (cookie: string) => boolean): string | undefined {
 		for (const [name, value] of Object.entries(this.cookies)) {
 			const cookie = `${name}=${value}`;
@@ -335,16 +367,24 @@ function splitCombinedSetCookieHeader(headerValue: string): string[] {
 
 export async function normalizeResponse(
 	response: StealthTransportResponse,
+	requestUrl?: string,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
 	const cookies = new CookieJarImpl(
 		setCookieHeadersFromResponse(response.headers),
 	);
-	const body = await response.text();
+	const bodyBytes = await response.arrayBuffer();
+	const body = new TextDecoder().decode(bodyBytes);
 
 	return {
 		status: response.status,
 		ok: response.status >= 200 && response.status < 300,
+		...(response.url ? { url: response.url } : {}),
+		...(response.redirected !== undefined
+			? { redirected: response.redirected }
+			: requestUrl && response.url
+				? { redirected: response.url !== requestUrl }
+				: {}),
 		headers,
 		rawHeaders: headerEntriesFromHeaders(response.headers),
 		body,
@@ -352,6 +392,12 @@ export async function normalizeResponse(
 		json<T>(): Promise<T> {
 			return Promise.resolve(JSON.parse(body));
 		},
+		arrayBuffer(): Promise<ArrayBuffer> {
+			return Promise.resolve(bodyBytes.slice(0));
+		},
+		bytes(): Promise<Uint8Array> {
+			return Promise.resolve(new Uint8Array(bodyBytes.slice(0)));
+		},
 	};
 }
 
@@ -736,6 +782,26 @@ function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	}
 }
 
+function isRedirectStatus(status: number): boolean {
+	return [301, 302, 303, 307, 308].includes(status);
+}
+
+function nextRedirectMethod(
+	status: number,
+	method: StealthMethod,
+): StealthMethod {
+	if (status === 303 && method !== "HEAD") return "GET";
+	if ((status === 301 || status === 302) && method === "POST") return "GET";
+	return method;
+}
+
+function locationHeader(headers: Record<string, string>): string | undefined {
+	for (const [name, value] of Object.entries(headers)) {
+		if (name.toLowerCase() === "location") return value;
+	}
+	return undefined;
+}
+
 function createSessionFetcher(
 	baseUrl: string,
 	defaultProfile: string,
@@ -804,7 +870,7 @@ function createSessionFetcher(
 		};
 	}
 
-	return {
+	const session: StealthSession = {
 		async fetch(url, options: StealthFetchOptions = {}) {
 			const method = normalizeMethod(options.method ?? "GET");
 			const hasExplicitRetryPolicy = options.retry !== undefined;
@@ -889,9 +955,10 @@ function createSessionFetcher(
 							const cookieHeader = cookieJar.toString();
 							if (cookieHeader) headers.Cookie = cookieHeader;
 						}
-						const requestInit: ImpitRequestInit = {
+						const requestInit: StealthRequestInit = {
 							headers: normalizeHeaders(headers),
 							method,
+							...(options.redirect ? { redirect: options.redirect } : {}),
 							...(options.timeout ? { timeout: options.timeout } : {}),
 						};
 						if (options.body !== undefined) {
@@ -902,7 +969,7 @@ function createSessionFetcher(
 							proxy,
 							ignoreTlsErrors,
 						).fetch(requestUrl, requestInit);
-						const normalized = await normalizeResponse(response);
+						const normalized = await normalizeResponse(response, requestUrl);
 						cookieJar.setFromCookieStrings(
 							setCookieHeadersFromResponse(response.headers),
 						);
@@ -1045,11 +1112,128 @@ function createSessionFetcher(
 
 			throw normalizeStealthTransportError(lastError);
 		},
+		cookies: cookieJar,
+		redirects: {
+			async run(options) {
+				const maxHops =
+					options.maxHops === undefined || !Number.isFinite(options.maxHops)
+						? 10
+						: Math.max(0, Math.floor(options.maxHops));
+				const hops: StealthRedirectHop[] = [];
+				let currentUrl = resolveUrl(baseUrl, options.url);
+				let method = normalizeMethod(options.method ?? "GET");
+				let body = options.body;
+				let response: StealthResponse | undefined;
+				const visitedRequests = new Set<string>();
+
+				const {
+					url: _url,
+					maxHops: _maxHops,
+					stopWhen,
+					params,
+					...fetchOptions
+				} = options;
+
+				for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
+					visitedRequests.add(`${method} ${currentUrl}`);
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(hopIndex === 0 && params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+
+					if (!isRedirectStatus(response.status)) {
+						return {
+							final: response,
+							hops,
+							reason: "completed",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const location = locationHeader(response.headers);
+					const nextUrl = location
+						? new URL(location, response.url ?? currentUrl).toString()
+						: undefined;
+					const hop: StealthRedirectHop = {
+						url: response.url ?? currentUrl,
+						status: response.status,
+						method,
+						...(location ? { location } : {}),
+						...(nextUrl ? { nextUrl } : {}),
+					};
+					hops.push(hop);
+
+					if (stopWhen && (await stopWhen(hop))) {
+						return {
+							final: response,
+							hops,
+							reason: "stopped",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (!nextUrl) {
+						return {
+							final: response,
+							hops,
+							reason: "missing_location",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (hops.length > maxHops) {
+						return {
+							final: response,
+							hops,
+							reason: "max_hops",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const nextMethod = nextRedirectMethod(response.status, method);
+					if (nextMethod !== method) {
+						body = undefined;
+					}
+					if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
+						return {
+							final: response,
+							hops,
+							reason: "loop",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+					method = nextMethod;
+					currentUrl = nextUrl;
+				}
+
+				if (!response) {
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+				}
+				return {
+					final: response,
+					hops,
+					reason: "max_hops",
+					cookies: cookieJar.snapshot(),
+				};
+			},
+		},
 		close() {
 			closed = true;
 			clients.clear();
 		},
 	};
+	return session;
 
 	async function classifyProxyAuthDiagnostic(
 		profileName: string,

package/src/server/index.ts

@@ -1,4 +1,40 @@
 export { createServerApp, type ServeOptions, serve } from "./serve";
+export {
+	computeSelfTestPlanDigest,
+	createSelfTestApp,
+	createSelfTestInvoke,
+	DEFAULT_SELF_TEST_REQUEST_BUDGET_MS,
+	isSelfTestReadOnlyOperation,
+	PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV,
+	resolveSelfTestPort,
+	SELF_TEST_HEALTHZ_PATH,
+	SELF_TEST_PATH,
+	SELF_TEST_SCHEMA_VERSION,
+	type SelfTestAppOptions,
+	type SelfTestCaseResult,
+	type SelfTestCaseStatus,
+	type SelfTestOperationInvoke,
+	type SelfTestRequest,
+	SelfTestRequestSchema,
+	type SelfTestResponse,
+} from "./self-test";
+export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
+export {
+	collectSelfTestSensitiveValues,
+	redactSelfTestText,
+	SELF_TEST_MAX_TEXT_LENGTH,
+	SELF_TEST_REDACTED_PLACEHOLDER,
+} from "./self-test-redaction";
+export {
+	DEFAULT_SELF_TEST_PORT,
+	deriveSelfTestToken,
+	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
+	PROVIDER_RUNTIME_SELF_TEST_PORT_ENV,
+	resolveSelfTestMasterSecrets,
+	type SelfTestMasterSecrets,
+	verifySelfTestAuthorization,
+} from "./self-test-token";
 export type {
 	AuthFlowRequest,
 	AuthFlowResponse,

package/src/server/self-test-input-tokens.ts

@@ -0,0 +1,46 @@
+/**
+ * Relative-KST date token resolution for health-check case inputs, ported from
+ * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
+ * so provider self-tests resolve durable probe inputs identically.
+ *
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ */
+const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+
+function dateFromKstDaysAhead(
+	daysAhead: number,
+	now = new Date(),
+	format: "YYYY-MM-DD" | "YYYYMMDD" = "YYYY-MM-DD",
+): string {
+	const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
+	const date = new Date(
+		Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead),
+	);
+	const isoDate = date.toISOString().slice(0, 10);
+	return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
+}
+
+export function resolveHealthCheckInputDateTokens(value: unknown, now = new Date()): unknown {
+	if (typeof value === "string") {
+		const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+		if (!relative) return value;
+		const daysAhead = Number(relative[1]);
+		if (!Number.isInteger(daysAhead) || daysAhead < 1 || daysAhead > 365) {
+			return value;
+		}
+		const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
+		return dateFromKstDaysAhead(daysAhead, now, format);
+	}
+	if (Array.isArray(value)) {
+		return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+	}
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value).map(([key, entry]) => [
+				key,
+				resolveHealthCheckInputDateTokens(entry, now),
+			]),
+		);
+	}
+	return value;
+}

package/src/server/self-test-redaction.ts

@@ -0,0 +1,97 @@
+import type { ProviderDefinition } from "../types";
+import {
+	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
+} from "./self-test-token";
+
+export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
+
+/** Maximum length of any string echoed in a self-test response. */
+export const SELF_TEST_MAX_TEXT_LENGTH = 300;
+
+/** Values shorter than this are too generic to be treated as secrets. */
+const MIN_SENSITIVE_VALUE_LENGTH = 4;
+
+const HEADER_SHAPED_SECRETS: readonly RegExp[] = [
+	/(authorization\s*[:=]\s*)[^\s;,]+/gi,
+	/(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi,
+	/((?:set-)?cookie\s*[:=]\s*)[^;\n]+/gi,
+];
+
+/**
+ * Collects every secret-shaped value known to the self-test runtime so probe
+ * results can be scrubbed before they leave the pod: master secrets, declared
+ * provider env secrets, health-probe credential env values, and request-supplied
+ * credential inputs.
+ */
+export function collectSelfTestSensitiveValues(
+	provider: ProviderDefinition,
+	options: {
+		env?: Readonly<Record<string, string | undefined>>;
+		credentialInputs?: Readonly<Record<string, string>>;
+	} = {},
+): string[] {
+	const env = options.env ?? process.env;
+	const envNames = new Set<string>([
+		PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
+		PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
+	]);
+	for (const secret of provider.secrets ?? []) {
+		envNames.add(secret.name);
+	}
+	const healthProbe = provider.healthProbe ?? provider.healthMonitor;
+	for (const name of healthProbe?.requiredSecrets ?? []) {
+		envNames.add(name);
+	}
+	for (const name of Object.values(healthProbe?.credentialInputs ?? {})) {
+		envNames.add(name);
+	}
+
+	const values = new Set<string>();
+	for (const name of envNames) {
+		const value = env[name];
+		if (typeof value === "string" && value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
+			values.add(value);
+		}
+	}
+	for (const value of Object.values(options.credentialInputs ?? {})) {
+		if (value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
+			values.add(value);
+		}
+	}
+	return [...values];
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Scrubs known secret values and header-shaped credentials from a string and
+ * caps its length. Every string embedded in a SelfTestResponse MUST pass
+ * through this before serialization.
+ */
+export function redactSelfTestText(
+	text: string,
+	sensitiveValues: readonly string[],
+	maxLength: number = SELF_TEST_MAX_TEXT_LENGTH,
+): string {
+	let redacted = text;
+	for (const value of sensitiveValues) {
+		if (value.length < MIN_SENSITIVE_VALUE_LENGTH) continue;
+		redacted = redacted.replace(
+			new RegExp(escapeRegExp(value), "g"),
+			SELF_TEST_REDACTED_PLACEHOLDER,
+		);
+	}
+	for (const pattern of HEADER_SHAPED_SECRETS) {
+		redacted = redacted.replace(
+			pattern,
+			(_match, prefix: string) => `${prefix}${SELF_TEST_REDACTED_PLACEHOLDER}`,
+		);
+	}
+	if (redacted.length > maxLength) {
+		redacted = `${redacted.slice(0, maxLength)}… [truncated]`;
+	}
+	return redacted;
+}

package/src/server/self-test-token.ts

@@ -0,0 +1,70 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Shared master secret injected into every provider pod. The per-provider
+ * bearer token is derived from it, so compromise of one pod's env cannot
+ * unlock another provider's self-test endpoint.
+ */
+export const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV =
+	"APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET";
+
+/**
+ * Previous master secret accepted during a rotation window so fleet-wide
+ * rotation does not need to be atomic.
+ */
+export const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV =
+	"APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET_PREVIOUS";
+
+/** Internal self-test listener port (never the tenant-facing serve() port). */
+export const PROVIDER_RUNTIME_SELF_TEST_PORT_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT";
+
+export const DEFAULT_SELF_TEST_PORT = 3001;
+
+export interface SelfTestMasterSecrets {
+	readonly current: string;
+	readonly previous?: string;
+}
+
+/**
+ * Per-provider self-test bearer token: HMAC-SHA256(masterSecret, providerId),
+ * hex-encoded. Computed identically by the provider pod and the scheduler.
+ */
+export function deriveSelfTestToken(masterSecret: string, providerId: string): string {
+	return createHmac("sha256", masterSecret).update(providerId).digest("hex");
+}
+
+export function resolveSelfTestMasterSecrets(
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): SelfTestMasterSecrets | undefined {
+	const current = env[PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV]?.trim();
+	if (!current) return undefined;
+	const previous = env[PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV]?.trim();
+	return previous ? { current, previous } : { current };
+}
+
+function digestsMatch(presented: string, expected: string): boolean {
+	// Hash both sides before comparison so timingSafeEqual sees equal-length
+	// buffers regardless of what the caller presented (constant-time path).
+	const presentedDigest = createHash("sha256").update(presented).digest();
+	const expectedDigest = createHash("sha256").update(expected).digest();
+	return timingSafeEqual(presentedDigest, expectedDigest);
+}
+
+/**
+ * Verifies an Authorization header against the current-or-previous derived
+ * token (dual acceptance for one rotation window). Constant-time comparison;
+ * returns only a boolean so callers cannot leak which check failed.
+ */
+export function verifySelfTestAuthorization(
+	authorizationHeader: string | undefined,
+	providerId: string,
+	secrets: SelfTestMasterSecrets,
+): boolean {
+	const match = /^Bearer\s+(\S+)$/i.exec(authorizationHeader ?? "");
+	const presented = match?.[1] ?? "";
+	const currentOk = digestsMatch(presented, deriveSelfTestToken(secrets.current, providerId));
+	const previousOk = secrets.previous
+		? digestsMatch(presented, deriveSelfTestToken(secrets.previous, providerId))
+		: false;
+	return currentOk || previousOk;
+}