@apifuse/provider-sdk 2.2.0-beta.40 → 2.2.0-beta.42

package/src/cli/templates/provider/provider.json.tpl

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "providerId": "{{PROVIDER_ID}}",
+  "owner": "bounty",
+  "lifecycle": "draft"
+}

package/src/contract.ts

@@ -167,6 +167,7 @@ function extractHealthCheck(value: HealthCheckSuite | undefined): JsonValue | un
 				name: item.name,
 				description: item.description,
 				input: toJsonValue(item.input),
+				scenario: toJsonValue(item.scenario),
 				degradedThresholdMs: item.degradedThresholdMs,
 				timeoutMs: item.timeoutMs,
 				expectedStatus: item.expectedStatus,

package/src/define.ts

@@ -6,6 +6,7 @@ import {
 } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
 import {
 	NativeEgressPolicyValidationError,
 	validateNativeProviderConfig,
@@ -1730,6 +1731,7 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
 	"input",
 	"prepareInput",
 	"assertions",
+	"scenario",
 	"degradedThresholdMs",
 	"timeoutMs",
 	"expectedStatus",
@@ -1979,7 +1981,19 @@ function validateHealthCheckCase(
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.name must be a non-empty string.`,
 		);
-	if (typeof c.assertions !== "function")
+	const hasScenario = c.scenario !== undefined;
+	const imperativeFields = [
+		...(c.prepareInput === undefined ? [] : ["prepareInput"]),
+		...(c.assertions === undefined ? [] : ["assertions"]),
+	];
+	if (hasScenario && imperativeFields.length > 0)
+		throw new ValidationError(
+			`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" cannot declare scenario with ${imperativeFields.join(" and ")}.`,
+			{
+				fix: `Remove ${imperativeFields.map((field) => `${fieldPath}.${field}`).join(" and ")} and keep ${fieldPath}.scenario, or remove ${fieldPath}.scenario to keep the imperative hooks.`,
+			},
+		);
+	if (!hasScenario && typeof c.assertions !== "function")
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.assertions must be a function.`,
 			{
@@ -1990,6 +2004,24 @@ function validateHealthCheckCase(
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.prepareInput must be a function.`,
 		);
+	if (hasScenario) {
+		const parsedScenario = HealthScenarioSchema.safeParse(c.scenario);
+		if (!parsedScenario.success)
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" has an invalid scenario: it must conform to HealthScenario.`,
+				{ fix: `Build ${fieldPath}.scenario with defineHealthScenario().` },
+			);
+		const unrelatedOperation = parsedScenario.data.coversOperations.find(
+			(operationId) => operationId !== operationName,
+		);
+		if (unrelatedOperation !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" scenario.coversOperations cannot claim unrelated operation "${unrelatedOperation}".`,
+				{
+					fix: `Set ${fieldPath}.scenario.coversOperations to ["${operationName}"].`,
+				},
+			);
+	}
 	if (
 		c.degradedThresholdMs !== undefined &&
 		(typeof c.degradedThresholdMs !== "number" ||

package/src/error-observability.ts

@@ -0,0 +1,64 @@
+import { isProviderError, type ProviderErrorObservability } from "./errors.js";
+
+const PROVIDER_OBSERVABILITY_TOKEN_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+const PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN = /^[A-Fa-f0-9]{12}$/;
+const MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH = 10_000_000;
+
+/**
+ * Extracts only own data properties from branded provider errors. In
+ * particular, descriptor reads reject options/observability accessors without
+ * invoking provider-controlled getters.
+ */
+export function safeProviderErrorObservability(
+	error: unknown,
+): ProviderErrorObservability | undefined {
+	if (!isProviderError(error)) return undefined;
+	let candidate: unknown;
+	let reason: unknown;
+	let fingerprint: unknown;
+	let messageLength: unknown;
+	try {
+		const optionsDescriptor = Object.getOwnPropertyDescriptor(error, "options");
+		if (optionsDescriptor === undefined || !Object.hasOwn(optionsDescriptor, "value")) {
+			return undefined;
+		}
+		const options = optionsDescriptor.value;
+		if (options === null || typeof options !== "object" || Array.isArray(options)) {
+			return undefined;
+		}
+		const observabilityDescriptor = Object.getOwnPropertyDescriptor(options, "observability");
+		if (observabilityDescriptor === undefined || !Object.hasOwn(observabilityDescriptor, "value")) {
+			return undefined;
+		}
+		candidate = observabilityDescriptor.value;
+		if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+			return undefined;
+		}
+		const ownValue = (key: keyof ProviderErrorObservability): unknown => {
+			const descriptor = Object.getOwnPropertyDescriptor(candidate as object, key);
+			return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+		};
+		reason = ownValue("reason");
+		fingerprint = ownValue("fingerprint");
+		messageLength = ownValue("messageLength");
+	} catch {
+		return undefined;
+	}
+	const safe: ProviderErrorObservability = {
+		...(typeof reason === "string" && PROVIDER_OBSERVABILITY_TOKEN_PATTERN.test(reason)
+			? { reason }
+			: {}),
+		...(typeof fingerprint === "string" &&
+		PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN.test(fingerprint)
+			? { fingerprint }
+			: {}),
+		...(typeof messageLength === "number" &&
+		Number.isInteger(messageLength) &&
+		messageLength >= 0 &&
+		messageLength <= MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH
+			? { messageLength }
+			: {}),
+	};
+
+	return Object.keys(safe).length > 0 ? safe : undefined;
+}

package/src/errors.ts

@@ -46,6 +46,22 @@ export type ProviderErrorOptions = {
 	cause?: Error;
 	category?: ProviderErrorCategory;
 	retryable?: boolean;
+	/** Provider-authored, bounded metadata safe for operational logs and error headers. */
+	observability?: ProviderErrorObservability;
+};
+
+/**
+ * Provider-authored error diagnostics whose runtime values are validated before emission.
+ * Classification tokens such as `reason` are source literals, not runtime user input or
+ * credentials. The gateway removes the observability header from tenant responses.
+ */
+export type ProviderErrorObservability = {
+	/** A 1-64 character `[A-Za-z0-9_.-]` classification token, for example `LOGIN_COMPLETE_FAILED`. */
+	reason?: string;
+	/** A provider-computed 12-hex-character fingerprint of private diagnostic input. */
+	fingerprint?: string;
+	/** The non-negative length of the private diagnostic input, capped at 10,000,000. */
+	messageLength?: number;
 };
 
 export class ProviderError extends Error {

package/src/fixture-sanitization.ts

@@ -5,6 +5,12 @@ export const REDACTED_FIXTURE_VALUE = "[REDACTED]";
 const OPAQUE_TOKEN = /^[A-Za-z0-9_+/=.:~-]+$/;
 const OPAQUE_TOKEN_RUN = /[A-Za-z0-9_+/=.:~-]{24,}/g;
 const URL_RUN = /https?:\/\/[^\s"'<>]+/gi;
+const EMAIL_ADDRESS_RUN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const DIAGNOSTIC_URL_SENTINEL_DELIMITER = String.fromCodePoint(0);
+const DIAGNOSTIC_URL_SENTINEL_RUN = new RegExp(
+	`${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL(\\d+)${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`,
+	"g",
+);
 const PEM_PRIVATE_KEY =
 	/-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g;
 
@@ -149,9 +155,15 @@ export function requestPathForFixture(value: string): string {
 
 /** Scrubs secrets and terminal/log control characters before diagnostic text is emitted. */
 export function sanitizeDiagnosticText(value: string): string {
-	let sanitized = value
-		.replace(URL_RUN, (url) => sanitizeUrlForLogs(url))
-		.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`);
+	const retainedUrls: string[] = [];
+	// Remove attacker-controlled NUL delimiters before introducing internal URL sentinels.
+	let sanitized = encodeDiagnosticControls(value)
+		.replace(URL_RUN, (url) => {
+			const index = retainedUrls.push(sanitizeUrlForLogs(url)) - 1;
+			return `${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL${index}${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`;
+		})
+		.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`)
+		.replace(EMAIL_ADDRESS_RUN, REDACTED_FIXTURE_VALUE);
 	sanitized = redactSensitiveAssignments(sanitized);
 	sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate, offset: number, source: string) => {
 		if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate)) return candidate;
@@ -159,6 +171,10 @@ export function sanitizeDiagnosticText(value: string): string {
 		if (/(?:request|trace|correlation)[-_]?id\s*[:=]\s*$/i.test(prefix)) return candidate;
 		return isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate;
 	});
+	sanitized = sanitized.replace(
+		DIAGNOSTIC_URL_SENTINEL_RUN,
+		(_match, index: string) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE,
+	);
 	return encodeDiagnosticControls(sanitized);
 }
 

package/src/index.ts

@@ -254,6 +254,7 @@ export {
 	createServerApp,
 	createServerAppAsync,
 	ERROR_OBSERVABILITY_HEADER,
+	type ProviderErrorCauseFrame,
 	type ServeOptions,
 	serve,
 } from "./server/serve.js";

package/src/provider.ts

@@ -122,6 +122,7 @@ export {
 	isSessionExpiredError,
 	isTransportError,
 	ProviderError,
+	type ProviderErrorObservability,
 	SessionExpiredError,
 	TransportError,
 	ValidationError,

package/src/runtime/executor.ts

@@ -1,7 +1,9 @@
+import { safeProviderErrorObservability } from "../error-observability.js";
 import {
 	isSessionExpiredError,
 	isValidationError,
 	ProviderError,
+	type ProviderErrorOptions,
 	SessionExpiredError,
 	ValidationError,
 } from "../errors.js";
@@ -15,6 +17,13 @@ export function isStreamingOperation(provider: ProviderDefinition, operationId:
 	return kind !== "json";
 }
 
+function preservedSessionExpiredOptions(error: unknown): ProviderErrorOptions {
+	const observability = safeProviderErrorObservability(error);
+	return observability
+		? { observability, retryable: true }
+		: { retryable: true };
+}
+
 /**
  * Execute a provider operation by calling its handler.
  *
@@ -84,7 +93,10 @@ export async function executeOperation<
 		// 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 });
+			// Preserve provider-authored safe metadata while forcing the retry signal.
+			// `cause` intentionally remains dropped, matching the pre-existing
+			// reconstruction semantics.
+			throw new SessionExpiredError(error.message, preservedSessionExpiredOptions(error));
 		}
 		throw error;
 	}

package/src/server/error-observability.ts

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/src/server/index.ts

@@ -17,6 +17,7 @@ export {
 	type ErrorObservabilityDetails,
 	type ProviderServerCloseOptions,
 	type ProviderServerHandle,
+	type ProviderErrorCauseFrame,
 	type ProviderServerLogEvent,
 	type ProviderServerLogger,
 	type ProviderServerOperationExecutor,
@@ -26,6 +27,7 @@ export {
 	type ServeOptions,
 	serve,
 } from "./serve.js";
+export type { ProviderErrorObservability } from "../errors.js";
 export {
 	computeSelfTestPlanDigest,
 	createSelfTestApp,

package/src/server/self-test.ts

@@ -1106,6 +1106,11 @@ async function executeSelfTestCase(
 		const { startedAtMs, finish } = caseScope;
 		try {
 			return await runWithCaseTimeout(async () => {
+				if (healthCase.assertions === undefined) {
+					throw new Error(
+						`Self-test cannot execute declarative health-check case "${healthCase.name}"; run its scenario through the health monitor.`,
+					);
+				}
 				const resolvedInput = resolveHealthCheckInputDateTokens(healthCase.input);
 				const preparedInput = healthCase.prepareInput
 					? await healthCase.prepareInput({