@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

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;
+}