@beignet/core 0.0.31 → 0.0.33

package/src/server/runtime-integrity.ts

@@ -0,0 +1,322 @@
+import type { EventPayloadDef, ListenerDef } from "../events/index.js";
+import type { JobDef } from "../jobs/index.js";
+import type { OutboxRegistry } from "../outbox/index.js";
+import type { ScheduleDef } from "../schedules/index.js";
+import type { TaskDef } from "../tasks/index.js";
+
+export type RuntimeIntegrityArtifact =
+  | "listener"
+  | "schedule"
+  | "task"
+  | "outboxEvent"
+  | "outboxJob";
+
+export type RuntimeIntegrityFindingCode =
+  | "missing_listener_registration"
+  | "missing_schedule_registration"
+  | "missing_task_registration"
+  | "missing_outbox_event_registration"
+  | "missing_outbox_job_registration"
+  | "duplicate_runtime_manifest_entry"
+  | "duplicate_runtime_registry_entry";
+
+export type RuntimeIntegrityFindingLocation = "manifest" | "registry";
+
+export interface RuntimeIntegrityFinding {
+  readonly code: RuntimeIntegrityFindingCode;
+  readonly artifact: RuntimeIntegrityArtifact;
+  readonly name: string;
+  readonly message: string;
+  readonly location?: RuntimeIntegrityFindingLocation;
+}
+
+export interface RuntimeIntegrityResult {
+  readonly ok: boolean;
+  readonly findings: readonly RuntimeIntegrityFinding[];
+}
+
+export interface RuntimeOutboxManifest {
+  readonly events?: readonly EventPayloadDef[];
+  readonly jobs?: readonly JobDef[];
+}
+
+export interface RuntimeManifestInput {
+  readonly listeners?: readonly ListenerDef[];
+  readonly schedules?: readonly ScheduleDef[];
+  readonly tasks?: readonly TaskDef[];
+  readonly outbox?: RuntimeOutboxManifest;
+}
+
+export interface RuntimeManifest {
+  readonly listeners: readonly ListenerDef[];
+  readonly schedules: readonly ScheduleDef[];
+  readonly tasks: readonly TaskDef[];
+  readonly outbox: {
+    readonly events: readonly EventPayloadDef[];
+    readonly jobs: readonly JobDef[];
+  };
+}
+
+export interface RuntimeRegistriesInput {
+  readonly listeners?: readonly ListenerDef[];
+  readonly schedules?: readonly ScheduleDef[];
+  readonly tasks?: readonly TaskDef[];
+  readonly outbox?: OutboxRegistry;
+}
+
+export interface RuntimeRegistries {
+  readonly listeners: readonly ListenerDef[];
+  readonly schedules: readonly ScheduleDef[];
+  readonly tasks: readonly TaskDef[];
+  readonly outbox?: OutboxRegistry;
+}
+
+export type RuntimeIntegrityMode = "error" | "warn";
+
+export interface RuntimeIntegrityLogger {
+  warn(message: string): void;
+}
+
+export interface CreateRuntimeIntegrityOptions {
+  readonly manifest: RuntimeManifest;
+  readonly registries: RuntimeRegistries;
+  /**
+   * How to handle integrity findings.
+   *
+   * @default "error"
+   */
+  readonly mode?: RuntimeIntegrityMode;
+  /**
+   * Logger used when `mode` is `"warn"`.
+   *
+   * @default console
+   */
+  readonly logger?: RuntimeIntegrityLogger;
+}
+
+export interface RuntimeIntegrityCheck {
+  readonly kind: "runtime-integrity";
+  check(): RuntimeIntegrityResult;
+}
+
+type NamedDefinition = {
+  readonly name: string;
+};
+
+type IntegrityArtifactConfig = {
+  readonly artifact: RuntimeIntegrityArtifact;
+  readonly label: string;
+  readonly manifestNames: readonly string[];
+  readonly registryNames: readonly string[];
+  readonly missingCode: RuntimeIntegrityFindingCode;
+  readonly registryDescription: string;
+};
+
+export class RuntimeIntegrityError extends Error {
+  readonly findings: readonly RuntimeIntegrityFinding[];
+
+  constructor(findings: readonly RuntimeIntegrityFinding[]) {
+    super(formatRuntimeIntegrityFailure(findings));
+    this.name = "RuntimeIntegrityError";
+    this.findings = findings;
+  }
+}
+
+export function defineRuntimeManifest(
+  input: RuntimeManifestInput,
+): RuntimeManifest {
+  return {
+    listeners: input.listeners ?? [],
+    schedules: input.schedules ?? [],
+    tasks: input.tasks ?? [],
+    outbox: {
+      events: input.outbox?.events ?? [],
+      jobs: input.outbox?.jobs ?? [],
+    },
+  };
+}
+
+export function defineRuntimeRegistries(
+  input: RuntimeRegistriesInput,
+): RuntimeRegistries {
+  return {
+    listeners: input.listeners ?? [],
+    schedules: input.schedules ?? [],
+    tasks: input.tasks ?? [],
+    outbox: input.outbox,
+  };
+}
+
+export function inspectRuntimeIntegrity(
+  manifest: RuntimeManifest,
+  registries: RuntimeRegistries,
+): RuntimeIntegrityResult {
+  const configs: readonly IntegrityArtifactConfig[] = [
+    {
+      artifact: "listener",
+      label: "listener",
+      manifestNames: namesFromDefinitions(manifest.listeners),
+      registryNames: namesFromDefinitions(registries.listeners),
+      missingCode: "missing_listener_registration",
+      registryDescription: "runtime registries.listeners",
+    },
+    {
+      artifact: "schedule",
+      label: "schedule",
+      manifestNames: namesFromDefinitions(manifest.schedules),
+      registryNames: namesFromDefinitions(registries.schedules),
+      missingCode: "missing_schedule_registration",
+      registryDescription: "runtime registries.schedules",
+    },
+    {
+      artifact: "task",
+      label: "task",
+      manifestNames: namesFromDefinitions(manifest.tasks),
+      registryNames: namesFromDefinitions(registries.tasks),
+      missingCode: "missing_task_registration",
+      registryDescription: "runtime registries.tasks",
+    },
+    {
+      artifact: "outboxEvent",
+      label: "outbox event",
+      manifestNames: namesFromDefinitions(manifest.outbox.events),
+      registryNames: namesFromMap(registries.outbox?.events),
+      missingCode: "missing_outbox_event_registration",
+      registryDescription: "runtime registries.outbox.events",
+    },
+    {
+      artifact: "outboxJob",
+      label: "outbox job",
+      manifestNames: namesFromDefinitions(manifest.outbox.jobs),
+      registryNames: namesFromMap(registries.outbox?.jobs),
+      missingCode: "missing_outbox_job_registration",
+      registryDescription: "runtime registries.outbox.jobs",
+    },
+  ];
+
+  const findings = configs.flatMap((config) =>
+    inspectArtifactIntegrity(config),
+  );
+
+  return {
+    ok: findings.length === 0,
+    findings,
+  };
+}
+
+export function createRuntimeIntegrity(
+  options: CreateRuntimeIntegrityOptions,
+): RuntimeIntegrityCheck {
+  const mode = options.mode ?? "error";
+  const logger = options.logger ?? console;
+
+  return {
+    kind: "runtime-integrity",
+    check() {
+      const result = inspectRuntimeIntegrity(
+        options.manifest,
+        options.registries,
+      );
+
+      if (result.ok) return result;
+
+      if (mode === "warn") {
+        logger.warn(
+          `[beignet] ${formatRuntimeIntegrityFailure(result.findings)}`,
+        );
+        return result;
+      }
+
+      throw new RuntimeIntegrityError(result.findings);
+    },
+  };
+}
+
+export function runRuntimeIntegrityCheck(
+  check: RuntimeIntegrityCheck | undefined,
+): RuntimeIntegrityResult | undefined {
+  return check?.check();
+}
+
+function inspectArtifactIntegrity(
+  config: IntegrityArtifactConfig,
+): RuntimeIntegrityFinding[] {
+  const findings: RuntimeIntegrityFinding[] = [];
+  const manifestDuplicates = duplicateNames(config.manifestNames);
+  const registryDuplicates = duplicateNames(config.registryNames);
+
+  for (const name of manifestDuplicates) {
+    findings.push({
+      code: "duplicate_runtime_manifest_entry",
+      artifact: config.artifact,
+      name,
+      location: "manifest",
+      message: `Duplicate ${config.label} "${name}" in runtime manifest.`,
+    });
+  }
+
+  for (const name of registryDuplicates) {
+    findings.push({
+      code: "duplicate_runtime_registry_entry",
+      artifact: config.artifact,
+      name,
+      location: "registry",
+      message: `Duplicate ${config.label} "${name}" in ${config.registryDescription}.`,
+    });
+  }
+
+  const registryNameSet = new Set(config.registryNames);
+  for (const name of uniqueNames(config.manifestNames)) {
+    if (registryNameSet.has(name)) continue;
+    findings.push({
+      code: config.missingCode,
+      artifact: config.artifact,
+      name,
+      message: `Missing ${config.label} registration "${name}": declared in runtime manifest but not present in ${config.registryDescription}.`,
+    });
+  }
+
+  return findings;
+}
+
+function namesFromDefinitions(
+  definitions: readonly NamedDefinition[] | undefined,
+): string[] {
+  return (definitions ?? []).map((definition) => definition.name);
+}
+
+function namesFromMap<T extends NamedDefinition>(
+  definitions: ReadonlyMap<string, T> | undefined,
+): string[] {
+  return [...(definitions?.keys() ?? [])];
+}
+
+function duplicateNames(names: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+
+  for (const name of names) {
+    if (seen.has(name)) {
+      duplicates.add(name);
+      continue;
+    }
+    seen.add(name);
+  }
+
+  return [...duplicates].sort();
+}
+
+function uniqueNames(names: readonly string[]): string[] {
+  return [...new Set(names)].sort();
+}
+
+function formatRuntimeIntegrityFailure(
+  findings: readonly RuntimeIntegrityFinding[],
+): string {
+  const summary = `Runtime integrity check failed with ${findings.length} finding${findings.length === 1 ? "" : "s"}.`;
+  const details = findings
+    .map((finding) => `- [${finding.code}] ${finding.message}`)
+    .join("\n");
+
+  return `${summary}\n${details}`;
+}

package/src/server/server.ts

@@ -44,6 +44,12 @@ import {
   resolveProviderInstrumentationPort,
   type ServiceProvider,
 } from "../providers/index.js";
+import {
+  parseTraceparent,
+  resolveTracingPort,
+  runWithTracing,
+  type TraceContextInput,
+} from "../tracing/index.js";
 import type {
   ContextSeed,
   ServerContextConfig,
@@ -87,6 +93,8 @@ import {
   runWithActiveRequestContext,
   setActiveRequestIdentity,
 } from "./request-context.js";
+import type { RuntimeIntegrityCheck } from "./runtime-integrity.js";
+import { runRuntimeIntegrityCheck } from "./runtime-integrity.js";
 import type {
   AnyUseCaseLike,
   AnyUseCaseRouteDef,
@@ -353,6 +361,15 @@ export type CreateServerOptions<
    * Server hooks that wrap every registered route.
    */
   hooks?: ServerHook<Ctx, Ports & InferProviderPorts<Providers>>[];
+  /**
+   * Optional pure startup check for app workflow registrations.
+   *
+   * Runtime integrity compares app-declared workflow artifacts against the
+   * registries passed to runtime entrypoints. It performs no filesystem,
+   * provider, database, network, worker, or background-loop work, so it is safe
+   * to run during serverless cold starts.
+   */
+  integrity?: RuntimeIntegrityCheck;
   /**
    * Server-owned request instrumentation.
    *
@@ -1192,7 +1209,7 @@ function createRequestExecutor<
   const warnedNativeReplacementHooks = new WeakSet<object>();
   const maxRequestBodyBytes = requestBodyLimit(options.requestBody);
 
-  return async (
+  const executeRequest = async (
     target: ExecutionTarget<Ctx, C>,
     req: HttpRequestLike,
     preMatchedParams?: Record<string, string>,
@@ -2131,6 +2148,72 @@ function createRequestExecutor<
       );
     }
   };
+
+  return async (
+    target: ExecutionTarget<Ctx, C>,
+    req: HttpRequestLike,
+    preMatchedParams?: Record<string, string>,
+  ) => {
+    const tracing = resolveTracingPort(finalPorts);
+    const instrumentationOptions =
+      options.instrumentation === false ? undefined : options.instrumentation;
+    const pathname = (() => {
+      try {
+        return new URL(req.url).pathname;
+      } catch {
+        return req.url;
+      }
+    })();
+    const ignored = (
+      instrumentationOptions?.ignorePaths ?? ["/api/devtools"]
+    ).some((prefix) => {
+      const normalized = prefix.replace(/\/+$/, "");
+      return pathname === normalized || pathname.startsWith(`${normalized}/`);
+    });
+
+    if (!tracing || ignored) {
+      return executeRequest(target, req, preMatchedParams);
+    }
+
+    const traceContextHeader =
+      instrumentationOptions?.traceContextHeader ?? "traceparent";
+    const active = tracing.current();
+    const parsedTraceparent =
+      traceContextHeader === false
+        ? undefined
+        : parseTraceparent(req.headers.get(traceContextHeader));
+    const parent: TraceContextInput | undefined = active
+      ? undefined
+      : !parsedTraceparent
+        ? undefined
+        : {
+            traceparent: parsedTraceparent.traceparent,
+            tracestate: req.headers.get("tracestate") ?? undefined,
+          };
+    const traceAttributes = {
+      "beignet.contract.name": target.contract.name,
+      "http.request.method": req.method.toUpperCase(),
+      "http.route": target.contract.path,
+    } as const;
+
+    return await runWithTracing(
+      tracing,
+      {
+        name: `beignet.request ${target.contract.name}`,
+        type: "request",
+        kind: active ? "internal" : "server",
+        parent,
+        attributes: traceAttributes,
+        metricAttributes: traceAttributes,
+      },
+      async (span) => {
+        const response = await executeRequest(target, req, preMatchedParams);
+        span?.setAttribute("http.response.status_code", response.status);
+        if (response.status >= 500) span?.setStatus("error");
+        return response;
+      },
+    );
+  };
 }
 
 /**
@@ -2581,6 +2664,8 @@ export async function createServer<
     }
   }
 
+  runRuntimeIntegrityCheck(options.integrity);
+
   try {
     for (const provider of providers) {
       const cfg = await loadProviderConfig(provider, env, overrides);

package/src/server/trusted-proxy.ts

@@ -0,0 +1,249 @@
+import type { HttpRequestLike } from "./http.js";
+
+/**
+ * Header source used to resolve a client IP after an app has explicitly opted
+ * into trusting its deployment proxy or edge.
+ */
+export type TrustedProxyClientIpSource =
+  | "x-forwarded-for-last"
+  | "x-forwarded-for-first"
+  | "x-real-ip"
+  | "cf-connecting-ip"
+  | { header: string }
+  | ((req: HttpRequestLike) => string | undefined);
+
+/**
+ * Trusted proxy configuration for request metadata.
+ *
+ * Beignet trusts no forwarding headers by default. Configure this only when
+ * the app is always behind a platform or reverse proxy that strips or
+ * normalizes these headers before they reach application code.
+ */
+export interface TrustedProxyOptions {
+  /**
+   * Header source for the end-user client IP. Omit or set to `false` when no
+   * client-IP header should be trusted.
+   */
+  clientIp?: TrustedProxyClientIpSource | false;
+  /**
+   * Header that carries the external request protocol.
+   *
+   * Defaults to `x-forwarded-proto` when trusted proxy handling is enabled.
+   */
+  protocolHeader?: string | false;
+  /**
+   * Header that carries the external request host.
+   *
+   * Defaults to `x-forwarded-host` when trusted proxy handling is enabled.
+   */
+  hostHeader?: string | false;
+}
+
+/**
+ * Set to `false` or omit the config to trust no forwarding headers.
+ */
+export type TrustedProxyConfig = false | TrustedProxyOptions;
+
+/**
+ * Request metadata after applying an explicit trusted-proxy policy.
+ */
+export interface TrustedRequestInfo {
+  /**
+   * URL as seen by the app or reconstructed from trusted proxy headers.
+   */
+  url: URL;
+  /**
+   * External request origin.
+   */
+  origin: string;
+  /**
+   * External request protocol without a trailing colon.
+   */
+  protocol: "http" | "https";
+  /**
+   * External request host, including port when present.
+   */
+  host: string;
+  /**
+   * Resolved client IP when a trusted client-IP source is configured.
+   */
+  clientIp?: string;
+  /**
+   * Whether forwarding headers were eligible to affect this result.
+   */
+  trustedProxy: boolean;
+}
+
+const DEFAULT_PROTOCOL_HEADER = "x-forwarded-proto";
+const DEFAULT_HOST_HEADER = "x-forwarded-host";
+
+function splitForwardedHeader(value: string | null): string[] {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function firstHeaderValue(
+  req: HttpRequestLike,
+  header: string,
+): string | undefined {
+  return splitForwardedHeader(req.headers.get(header))[0];
+}
+
+function requireHeaderName(name: string, optionName: string): string {
+  const header = name.trim();
+  if (!header) {
+    throw new Error(`${optionName} must be a non-empty header name.`);
+  }
+  return header;
+}
+
+function normalizeProtocol(
+  value: string | undefined,
+): "http" | "https" | undefined {
+  if (!value) return undefined;
+  const protocol = value.toLowerCase().replace(/:$/, "");
+  if (protocol === "http" || protocol === "https") return protocol;
+  return undefined;
+}
+
+function hasInvalidHostCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (
+      code <= 32 ||
+      code === 127 ||
+      char === "/" ||
+      char === "\\" ||
+      char === "@" ||
+      char === "?" ||
+      char === "#"
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function normalizeHost(
+  value: string | undefined,
+  protocol: "http" | "https",
+): string | undefined {
+  if (!value || hasInvalidHostCharacter(value)) {
+    return undefined;
+  }
+
+  try {
+    return new URL(`${protocol}://${value}`).host;
+  } catch {
+    return undefined;
+  }
+}
+
+function baseRequestUrl(req: HttpRequestLike): URL {
+  try {
+    return new URL(req.url);
+  } catch {
+    throw new Error("req.url must be an absolute URL.");
+  }
+}
+
+function normalizedBaseProtocol(url: URL): "http" | "https" {
+  const protocol = normalizeProtocol(url.protocol);
+  if (protocol) return protocol;
+  throw new Error("req.url must use http or https.");
+}
+
+/**
+ * Resolve a client IP from a configured trusted proxy source.
+ */
+export function resolveTrustedClientIp(
+  req: HttpRequestLike,
+  source: TrustedProxyClientIpSource | false | undefined,
+): string | undefined {
+  if (!source) return undefined;
+
+  if (typeof source === "function") {
+    return source(req)?.trim() || undefined;
+  }
+
+  if (typeof source === "object") {
+    return firstHeaderValue(
+      req,
+      requireHeaderName(source.header, "trustedProxy.clientIp.header"),
+    );
+  }
+
+  if (source === "x-forwarded-for-first" || source === "x-forwarded-for-last") {
+    const entries = splitForwardedHeader(req.headers.get("x-forwarded-for"));
+    if (entries.length === 0) return undefined;
+    return source === "x-forwarded-for-first"
+      ? entries[0]
+      : entries[entries.length - 1];
+  }
+
+  return firstHeaderValue(req, source);
+}
+
+/**
+ * Resolve request metadata using only app-visible URL data unless a trusted
+ * proxy policy is explicitly configured.
+ */
+export function resolveTrustedRequest(
+  req: HttpRequestLike,
+  config: TrustedProxyConfig | undefined = false,
+): TrustedRequestInfo {
+  const baseUrl = baseRequestUrl(req);
+  const baseProtocol = normalizedBaseProtocol(baseUrl);
+  const baseHost = baseUrl.host;
+
+  if (!config) {
+    return {
+      url: baseUrl,
+      origin: baseUrl.origin,
+      protocol: baseProtocol,
+      host: baseHost,
+      trustedProxy: false,
+    };
+  }
+
+  const protocolHeader =
+    config.protocolHeader === false
+      ? undefined
+      : requireHeaderName(
+          config.protocolHeader ?? DEFAULT_PROTOCOL_HEADER,
+          "trustedProxy.protocolHeader",
+        );
+  const hostHeader =
+    config.hostHeader === false
+      ? undefined
+      : requireHeaderName(
+          config.hostHeader ?? DEFAULT_HOST_HEADER,
+          "trustedProxy.hostHeader",
+        );
+
+  const protocol =
+    normalizeProtocol(
+      protocolHeader ? firstHeaderValue(req, protocolHeader) : undefined,
+    ) ?? baseProtocol;
+  const host =
+    normalizeHost(
+      hostHeader ? firstHeaderValue(req, hostHeader) : undefined,
+      protocol,
+    ) ?? baseHost;
+  const url = new URL(baseUrl);
+  url.protocol = `${protocol}:`;
+  url.host = host;
+  const clientIp = resolveTrustedClientIp(req, config.clientIp);
+
+  return {
+    url,
+    origin: url.origin,
+    protocol,
+    host,
+    ...(clientIp !== undefined ? { clientIp } : {}),
+    trustedProxy: true,
+  };
+}