@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/trace.js

@@ -1,6 +1,20 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { sanitizeSpanNameForOutput } from "../trace-sanitization.js";
+import { diagnosticStructuredRedactor, redactDiagnosticAttributeKey, copyDiagnosticAttributeTypes, redactedKeyAllocator, isRedactedKey, redactCriticalDiagnosticText, diagnosticAttributeRedactor, REDACTION_FAILED, redactDiagnosticText, } from "./diagnostic-redactor.js";
 import { exportSpansOTLP } from "./otlp.js";
+import { REDACTED_QUERY_VALUE } from "./request-options.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
+const TRACE_EXPORT_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/trace-export-metadata");
+function assertValidTraceId(traceId) {
+    if (!/^[0-9a-f]{32}$/.test(traceId) || /^0{32}$/.test(traceId)) {
+        throw new TypeError("traceId must be 32 lowercase hexadecimal characters and non-zero");
+    }
+}
+/** Updates request metadata before its pending root span completes and exports. */
+export function updateTraceContextExportMetadata(trace, input) {
+    trace[TRACE_EXPORT_METADATA]?.update(input);
+}
 function buildOTLPExportOptions(config) {
     if (config?.exporter !== "otlp") {
         return undefined;
@@ -22,23 +36,76 @@ export function resolveTraceContextOptions(config) {
         exportOptions: buildOTLPExportOptions(config),
     };
 }
-function normalizeAttributeValue(value) {
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-        return value;
+function normalizeAttributeValue(value, redact, retainBigints = false) {
+    if (typeof value === "number" || typeof value === "boolean") {
+        // Typed columns are contracts: unlike string tokens, number/boolean/bigint
+        // values only consult the registry at >=8 characters in string form.
+        const text = String(value);
+        if (text.length < 8)
+            return value;
+        const redacted = redactDiagnosticText(text, diagnosticStructuredRedactor(redact));
+        return redacted === text ? value : redacted;
+    }
+    if (typeof value === "bigint") {
+        // Bigints are not valid OTLP attribute primitives, so retain their prior
+        // string normalization while still checking their diagnostic form.
+        const text = String(value);
+        if (text.length < 8)
+            return retainBigints ? value : text;
+        const redacted = redactDiagnosticText(text, diagnosticStructuredRedactor(redact));
+        return retainBigints && redacted === text ? value : redacted;
     }
     if (value === null || value === undefined) {
         return undefined;
     }
-    return String(value);
+    return redactDiagnosticText(String(value), redact);
 }
-function normalizeAttributes(attributes) {
+function normalizeAttributes(attributes, redact, retainBigints = false) {
     if (!attributes) {
         return {};
     }
+    const nextKey = redactedKeyAllocator(Object.keys(attributes));
     const normalizedEntries = Object.entries(attributes)
-        .map(([key, value]) => [key, normalizeAttributeValue(value)])
+        .map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const normalizedKey = keyChanged ? nextKey() : key;
+        // Once a key changes, its original sensitivity classification is no
+        // longer available to later output sanitizers. Suppress the value here.
+        const normalizedValue = keyChanged
+            ? redactedKey === REDACTION_FAILED
+                ? REDACTION_FAILED
+                : REDACTED_QUERY_VALUE
+            : normalizeAttributeValue(value, diagnosticAttributeRedactor(key, redact, value), retainBigints);
+        return [normalizedKey, normalizedValue];
+    })
         .filter((entry) => entry[1] !== undefined);
-    return Object.fromEntries(normalizedEntries);
+    return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(normalizedEntries));
+}
+function prepareResourceAttributesForExport(attributes, redact, sanitize) {
+    if (!attributes)
+        return undefined;
+    if (sanitize) {
+        const sanitized = sanitize({ ...attributes });
+        if (!sanitized || typeof sanitized !== "object") {
+            throw new Error("resource attribute sanitizer returned no attributes");
+        }
+        return sanitized;
+    }
+    const nextKey = redactedKeyAllocator(Object.keys(attributes));
+    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+        return [
+            sanitizedKey,
+            keyChanged
+                ? redactedKey === REDACTION_FAILED
+                    ? REDACTION_FAILED
+                    : REDACTED_QUERY_VALUE
+                : sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact, value)),
+        ];
+    }));
 }
 function insertCompletedSpan(completed, entry, maxSpans) {
     const insertAt = completed.findIndex((existingEntry) => existingEntry.sequence > entry.sequence);
@@ -52,56 +119,133 @@ function insertCompletedSpan(completed, entry, maxSpans) {
         completed.splice(0, completed.length - maxSpans);
     }
 }
+/** Hands the hook a copy whose attributes are detached from the recorded span; a hook that returns nothing fails closed. */
+function prepareSpanForExport(span, sanitize) {
+    const copy = {
+        ...span,
+        attributes: copyDiagnosticAttributeTypes(span.attributes, { ...span.attributes }),
+    };
+    if (!sanitize)
+        return copy;
+    const sanitized = sanitize(copy);
+    if (!sanitized || typeof sanitized !== "object") {
+        throw new Error("sanitizeSpanForExport returned no span");
+    }
+    return sanitized;
+}
 export function getTraceRecorder(trace) {
     return trace[TRACE_RECORDER] ?? null;
 }
+const droppedOTLPSpans = new Map();
+/** Internal, read-only process counters; no reset can re-arm a warning. */
+export function getDroppedOTLPSpanCount(reason) {
+    return droppedOTLPSpans.get(reason) ?? 0;
+}
+function warnDroppedOTLPSpans(reason, count) {
+    const previous = getDroppedOTLPSpanCount(reason);
+    const total = previous + count;
+    droppedOTLPSpans.set(reason, total);
+    if (previous !== 0)
+        return;
+    try {
+        console.warn(`[apifuse] OTLP export skipped; reason=${reason}; dropped_spans=${total}`);
+    }
+    catch {
+        // Warning sinks are best-effort. The counter/latch survives a failed sink.
+    }
+}
 export function createTraceContext(options = {}) {
+    if (options.traceId !== undefined)
+        assertValidTraceId(options.traceId);
     const maxSpans = options.maxSpans ?? 1000;
     const completed = [];
     const activeSpanStorage = new AsyncLocalStorage();
     let sequence = 0;
-    let traceContext;
+    // Export configuration (which can carry collector credentials) stays in this closure;
+    // the context object handed to provider code never exposes it.
+    const exportOptions = options.exportOptions;
+    const resourceAttributeOptions = options.resourceAttributes;
+    const exportResourceAttributes = resourceAttributeOptions
+        ? { ...resourceAttributeOptions }
+        : undefined;
+    const exportResourceAttributeSanitizer = resourceAttributeOptions?.[TRACE_RESOURCE_ATTRIBUTE_SANITIZER];
+    // One trace id per context so every export batch of this request shares it and
+    // two processes can never mint the same id.
+    let exportTraceId = options.traceId ?? crypto.randomUUID().replace(/-/g, "");
+    let exportScheduled = false;
+    // One pending batch per context: roots completing before the flush share it, and a span is
+    // handed to the exporter exactly once, so later roots never re-send earlier spans.
     const scheduleExport = () => {
-        if (!traceContext._exportOptions) {
+        if (!exportOptions || exportScheduled) {
             return;
         }
-        const spans = completed.map((entry) => ({ ...entry.span }));
+        exportScheduled = true;
         setImmediate(() => {
-            void exportSpansOTLP(spans, traceContext._exportOptions, traceContext._resourceAttributes);
+            exportScheduled = false;
+            const pending = completed.filter((entry) => !entry.exported);
+            for (const entry of pending)
+                entry.exported = true;
+            if (pending.length === 0)
+                return;
+            // Sanitization runs off the request path; a faulty sanitizer drops the batch, never the request.
+            let spans;
+            let resourceAttributes;
+            try {
+                spans = pending.map((entry) => prepareSpanForExport(entry.span, options.sanitizeSpanForExport));
+                resourceAttributes = prepareResourceAttributesForExport(exportResourceAttributes, options.redact, exportResourceAttributeSanitizer);
+            }
+            catch {
+                try {
+                    console.warn("[apifuse] OTLP export skipped; span sanitization failed.");
+                }
+                catch {
+                    // A broken diagnostic sink must not escape this detached callback.
+                }
+                return;
+            }
+            // A matching trace ID cannot be replaced with non-hex text on the wire. Emit less.
+            if (redactCriticalDiagnosticText(exportTraceId, options.redact) !== exportTraceId) {
+                warnDroppedOTLPSpans("unverifiable_trace_id", pending.length);
+                return;
+            }
+            void exportSpansOTLP(spans, exportOptions, resourceAttributes, exportTraceId);
         });
     };
     const recorder = {
         async runSpan(name, fn, spanOptions = {}) {
             const pendingSpan = {
                 id: crypto.randomUUID(),
-                name,
+                name: redactCriticalDiagnosticText(name, options.redact),
                 startedAt: Date.now(),
                 parentId: activeSpanStorage.getStore()?.id,
                 sequence: sequence++,
-                attributes: normalizeAttributes(spanOptions.attributes),
+                attributes: normalizeAttributes(spanOptions.attributes, options.redact, true),
             };
             const finalize = (status, extraAttributes, error) => {
                 const endedAt = Date.now();
                 const duration = endedAt - pendingSpan.startedAt;
                 const attributes = {
                     ...pendingSpan.attributes,
-                    ...normalizeAttributes(extraAttributes),
+                    ...extraAttributes,
                 };
                 if (attributes.duration_ms === undefined) {
                     attributes.duration_ms = duration;
                 }
                 const span = {
-                    id: pendingSpan.id,
-                    name: pendingSpan.name,
+                    id: redactCriticalDiagnosticText(pendingSpan.id, options.redact),
+                    // Recheck at recording: harvest and live env reads may follow span start.
+                    name: redactCriticalDiagnosticText(pendingSpan.name, options.redact),
                     startedAt: pendingSpan.startedAt,
                     endedAt,
                     duration_ms: duration,
                     status,
-                    attributes,
-                    ...(error ? { error } : {}),
-                    ...(pendingSpan.parentId ? { parentId: pendingSpan.parentId } : {}),
+                    attributes: normalizeAttributes(attributes, options.redact),
+                    ...(error ? { error: redactDiagnosticText(error, options.redact) } : {}),
+                    ...(pendingSpan.parentId
+                        ? { parentId: redactCriticalDiagnosticText(pendingSpan.parentId, options.redact) }
+                        : {}),
                 };
-                insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span }, maxSpans);
+                insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span, exported: false }, maxSpans);
                 options.onSpan?.(span);
                 if (!pendingSpan.parentId) {
                     scheduleExport();
@@ -123,18 +267,25 @@ export function createTraceContext(options = {}) {
             });
         },
     };
-    traceContext = {
+    const traceContext = {
         span(name, fn) {
             return recorder.runSpan(name, fn);
         },
         getSpans() {
             return completed.map((entry) => ({ ...entry.span }));
         },
-        ...(options.exportOptions ? { _exportOptions: options.exportOptions } : {}),
-        ...(options.resourceAttributes
-            ? { _resourceAttributes: { ...options.resourceAttributes } }
-            : {}),
         [TRACE_RECORDER]: recorder,
+        [TRACE_EXPORT_METADATA]: {
+            update(input) {
+                if (input.traceId !== undefined) {
+                    assertValidTraceId(input.traceId);
+                    exportTraceId = input.traceId;
+                }
+                if (input.resourceAttributes !== undefined && exportResourceAttributes) {
+                    Object.assign(exportResourceAttributes, input.resourceAttributes);
+                }
+            },
+        },
     };
     return traceContext;
 }

package/dist/runtime-boundary-lint.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime boundary lint: provider runtime source must reach the outside world
+ * through the SDK context (`ctx.http`, `ctx.stealth`, `ctx.env`,
+ * `ctx.credential`, `ctx.browser`), not through ambient Node/Bun globals.
+ *
+ * Three rules, reported at `error` level: a finding fails `apifuse check` and
+ * `apifuse submit-check` (official and standalone mode alike). The first
+ * release reported them at `warn` as a migration window; the window closed once
+ * the fleet's request-path hits were fixed or acknowledged. A deliberate
+ * exception is acknowledged in code (see below), never through a hidden
+ * allowlist.
+ *
+ * - `process-env-direct-read`: `process.env.X`, `process.env["X"]`, a bare
+ *   `process.env` object use, and the `Bun.env` equivalents. Runtime bootstrap
+ *   keys (`APIFUSE__RUNTIME__*`) are exempt everywhere because `serve()`
+ *   callers read the port and pod identity before a context exists.
+ * - `node-runtime-module-import`: value imports of `fs`, `fs/promises`, `net`,
+ *   `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+ *   the `node:` prefix) via import/export declarations, `require()`, or dynamic
+ *   `import()`, plus the Bun equivalents `Bun.spawn`, `Bun.spawnSync`, `Bun.$`,
+ *   `Bun.file`, `Bun.write`. Type-only imports are not runtime reach and are
+ *   ignored.
+ * - `direct-fetch-call`: a call to the global `fetch` (bare identifier, or
+ *   `globalThis`/`window`/`self`/`global` member). A bare `fetch` call whose
+ *   enclosing scope declares a `fetch` binding (parameter, variable, import,
+ *   function, catch clause) is calling that binding, not the global, and is
+ *   left alone; the check is lexical, so a wrapper that takes `fetch` as a
+ *   parameter does not hide a global `fetch()` elsewhere in the same file.
+ *   `ctx.stealth.fetch()` is a member call and never matches.
+ *
+ * Files are parsed with the script kind their extension implies (`.ts` as
+ * TypeScript, `.tsx` as TSX, …). Parsing everything as TSX would make a
+ * generic arrow (`<T>(value: T) => value`) or an angle-bracket assertion in an
+ * ordinary `.ts` file read as JSX, and everything after it would silently drop
+ * out of the AST.
+ *
+ * Scope is the provider *runtime* source: JavaScript/TypeScript files under
+ * `providerSourceFiles` minus tests, recorded fixtures, the root bootstrap
+ * entrypoints (`dev.ts`, `start.ts`, `deploy.ts`) and the operator tooling
+ * directories (`scripts/`, `tools/`, `bin/`). Tooling legitimately reads the
+ * ambient environment and the filesystem when a human runs it; the rule is
+ * about code the pod executes on behalf of a request.
+ *
+ * A deliberate exception is acknowledged with the same escape hatch the submit
+ * check uses: `// @apifuse-allow <rule>: <reason>` on the finding line or the
+ * line directly above it. Acknowledged findings are reported as information so
+ * `apifuse check` still lists them.
+ */
+import type { LintDiagnostic, ProviderLintInformation, ProviderLintResult } from "./lint.js";
+import { type TypeScriptCompilerModuleLike, type TypeScriptModule } from "./typescript-module.js";
+export declare const PROCESS_ENV_DIRECT_READ_RULE = "process-env-direct-read";
+export declare const NODE_RUNTIME_MODULE_IMPORT_RULE = "node-runtime-module-import";
+export declare const DIRECT_FETCH_CALL_RULE = "direct-fetch-call";
+export declare const RUNTIME_BOUNDARY_RULES: readonly ["process-env-direct-read", "node-runtime-module-import", "direct-fetch-call"];
+export type RuntimeBoundaryRule = (typeof RUNTIME_BOUNDARY_RULES)[number];
+/**
+ * Environment names a provider may read from `process.env` directly. These
+ * are consumed before `serve()` builds a context (port, pod identity), so
+ * `ctx.env` cannot carry them. The whole `APIFUSE__RUNTIME__` family is the
+ * bootstrap contract; nothing else is exempt.
+ */
+export declare const BOOTSTRAP_ENV_NAME_PREFIX = "APIFUSE__RUNTIME__";
+export declare function isBootstrapEnvName(name: string): boolean;
+export declare const TEST_SOURCE_FILE_PATTERN: RegExp;
+type RuntimeBoundaryFinding = {
+    rule: RuntimeBoundaryRule;
+    /** 1-based line. */
+    line: number;
+    /** What was reached: the env name, module specifier, or call text. */
+    subject: string;
+};
+type RuntimeBoundaryFileReport = {
+    findings: RuntimeBoundaryFinding[];
+    acknowledged: Array<RuntimeBoundaryFinding & {
+        reason: string;
+    }>;
+};
+/** True for the files the runtime boundary rules look at. */
+export declare function isRuntimeBoundarySourceFile(relativePath: string): boolean;
+/**
+ * Script kind for a provider source file, from its extension. `.tsx`/`.jsx`
+ * enable JSX; everything else (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`,
+ * and the synthetic names used for in-memory sources) does not, so a generic
+ * arrow or `<T>value` assertion in a `.ts` file parses as TypeScript instead
+ * of swallowing the rest of the file as unterminated JSX.
+ */
+export declare function scriptKindForSourceFile(ts: TypeScriptModule, fileName: string): import("typescript").ScriptKind;
+export declare function analyzeRuntimeBoundary(ts: TypeScriptModule, fileName: string, source: string): RuntimeBoundaryFileReport;
+export type RuntimeBoundaryLintInput = {
+    authFlowSource?: string;
+    providerSourceFiles?: Record<string, string>;
+    operations?: Record<string, {
+        handler?: unknown;
+        source?: string;
+    }>;
+};
+/**
+ * Lint the provider runtime boundary. Returns error-level diagnostics (one per
+ * file and rule, listing every line) and information entries for findings
+ * acknowledged with `@apifuse-allow`.
+ */
+export declare function lintRuntimeBoundary(ts: TypeScriptModule, provider: RuntimeBoundaryLintInput, readOperationSource: (operation: {
+    handler?: unknown;
+    source?: string;
+}) => string): {
+    diagnostics: LintDiagnostic[];
+    information: ProviderLintInformation[];
+};
+export type LintRuntimeBoundarySourcesOptions = {
+    /**
+     * A loaded TypeScript compiler API module to parse with (`typescript` 6.x
+     * or `@typescript/typescript6`). When omitted the SDK resolves one from its
+     * own install location, trying `typescript` first and falling back to
+     * `@typescript/typescript6` when `typescript` is the 7.x native shell
+     * without `createSourceFile`. A caller whose dependency tree pins its own
+     * compiler module (the APIFuse monorepo contract check) passes it here so
+     * the parse does not depend on what hoists next to the SDK.
+     */
+    typescript?: TypeScriptCompilerModuleLike;
+};
+/**
+ * Lint provider runtime source files for the runtime boundary rules without a
+ * provider definition: `files` maps provider-root-relative paths to source
+ * text (the same shape `apifuse check` collects as `providerSourceFiles`).
+ * Out-of-scope paths (tests, recorded fixtures, `.d.ts`, the root
+ * `dev.ts`/`start.ts`/`deploy.ts`, `scripts/`, `tools/`, `bin/`) are skipped
+ * with `isRuntimeBoundarySourceFile`. Diagnostics carry
+ * `field: "sourceFiles.<path>"`; `@apifuse-allow` acknowledgements come back
+ * as `information`.
+ *
+ * Parses with `options.typescript` when given, otherwise with the compiler
+ * module resolved from the installed SDK (see `getTypeScript`). This is the
+ * entry point the platform contract check uses to apply the rules with the
+ * monorepo's SDK pin instead of each provider's own pin.
+ */
+export declare function lintRuntimeBoundarySources(files: Record<string, string>, options?: LintRuntimeBoundarySourcesOptions): ProviderLintResult;
+export {};