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

package/dist/server/self-test-redaction.js

@@ -0,0 +1,70 @@
+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 = [
+    /(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, options = {}) {
+    const env = options.env ?? process.env;
+    const envNames = new Set([
+        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();
+    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) {
+    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, sensitiveValues, maxLength = SELF_TEST_MAX_TEXT_LENGTH) {
+    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) => `${prefix}${SELF_TEST_REDACTED_PLACEHOLDER}`);
+    }
+    if (redacted.length > maxLength) {
+        redacted = `${redacted.slice(0, maxLength)}… [truncated]`;
+    }
+    return redacted;
+}

package/dist/server/self-test-token.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare 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 declare 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 declare const PROVIDER_RUNTIME_SELF_TEST_PORT_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT";
+export declare 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 declare function deriveSelfTestToken(masterSecret: string, providerId: string): string;
+export declare function resolveSelfTestMasterSecrets(env?: Readonly<Record<string, string | undefined>>): SelfTestMasterSecrets | undefined;
+/**
+ * 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 declare function verifySelfTestAuthorization(authorizationHeader: string | undefined, providerId: string, secrets: SelfTestMasterSecrets): boolean;

package/dist/server/self-test-token.js

@@ -0,0 +1,50 @@
+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;
+/**
+ * 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, providerId) {
+    return createHmac("sha256", masterSecret).update(providerId).digest("hex");
+}
+export function resolveSelfTestMasterSecrets(env = process.env) {
+    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, expected) {
+    // 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, providerId, secrets) {
+    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;
+}

package/dist/server/self-test.d.ts

@@ -0,0 +1,98 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import type { OperationDefinition, ProviderDefinition } from "../types";
+import { type SelfTestMasterSecrets } from "./self-test-token";
+import type { OperationConnection } from "./types";
+export declare const SELF_TEST_SCHEMA_VERSION: 1;
+export declare const SELF_TEST_PATH = "/internal/health/self-test";
+export declare const SELF_TEST_HEALTHZ_PATH = "/healthz";
+/** Overall wall-clock budget for one self-test request (all selected cases). */
+export declare const PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_REQUEST_BUDGET_MS";
+export declare const DEFAULT_SELF_TEST_REQUEST_BUDGET_MS = 120000;
+export declare const SelfTestRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    requestId: z.ZodString;
+    operationId: z.ZodOptional<z.ZodString>;
+    caseName: z.ZodOptional<z.ZodString>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    caseNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    credentials: z.ZodOptional<z.ZodObject<{
+        inputs: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SelfTestRequest = z.infer<typeof SelfTestRequestSchema>;
+export type SelfTestCaseStatus = "ok" | "degraded" | "failed" | "error" | "skipped";
+export interface SelfTestCaseResult {
+    operationId: string;
+    caseName: string;
+    status: SelfTestCaseStatus;
+    label: string;
+    responseTimeMs: number;
+    httpStatus?: number;
+    assertion?: {
+        passed: boolean;
+        message?: string;
+    };
+    skipReason?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    startedAt: string;
+    finishedAt: string;
+}
+export interface SelfTestResponse {
+    schemaVersion: typeof SELF_TEST_SCHEMA_VERSION;
+    providerId: string;
+    sdkVersion: string;
+    planDigest: string;
+    /** Present for single-case requests (mirrors results[0]). */
+    result?: SelfTestCaseResult;
+    results: SelfTestCaseResult[];
+}
+export type SelfTestOperationInvoke = (args: {
+    operationId: string;
+    input: unknown;
+    connection?: OperationConnection;
+    requestId: string;
+}) => Promise<{
+    status: number;
+    data: unknown;
+    meta?: Record<string, unknown>;
+}>;
+export interface SelfTestAppOptions {
+    /** Derived-token verification secrets; without them every self-test route 404s. */
+    secrets?: SelfTestMasterSecrets;
+    /** In-process invoke bound to the tenant-facing app's /v1 pipeline. */
+    invoke: SelfTestOperationInvoke;
+    /** Overall request budget; defaults to env / 120s. */
+    requestBudgetMs?: number;
+    /** Env override for secret collection + budget resolution (tests). */
+    env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Stable sha256 over the provider's declared health plan (operations, case
+ * names, timeouts) so the scheduler can detect plan/image skew by comparing
+ * the manifest planDigest against the pod-reported one.
+ */
+export declare function computeSelfTestPlanDigest(provider: ProviderDefinition): string;
+/**
+ * Fail-closed read-only classification: an operation may self-test only when
+ * its own metadata marks it read-only (annotations.readOnly or
+ * toolRouter.riskClass "read") and nothing marks it side-effecting. Unclassified
+ * operations are refused so the endpoint cannot become a mutation oracle.
+ */
+export declare function isSelfTestReadOnlyOperation(operation: OperationDefinition): boolean;
+/** Binds the self-test executor to a tenant app's /v1 pipeline in-process. */
+export declare function createSelfTestInvoke(app: {
+    request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
+}): SelfTestOperationInvoke;
+export declare function resolveSelfTestPort(env?: Readonly<Record<string, string | undefined>>): number;
+/**
+ * Builds the internal self-test Hono app. This app is served on a SEPARATE
+ * listener (default :3001) that the tenant-facing gateway never dials; when no
+ * master secret is resolvable the self-test route responds 404 (safe default
+ * off) while `GET /healthz` stays available for liveness.
+ */
+export declare function createSelfTestApp(provider: ProviderDefinition, options: SelfTestAppOptions): Hono;