@iislee/opencodex 2.11.0 → 2.35.0

package/src/lib/lab-live-route-production.ts

@@ -0,0 +1,130 @@
+/**
+ * Production host integration for CL-03 trusted exact-route execution.
+ *
+ * Issues a host-recognized `TrustedLabRouteExecutor` that routes provider traffic
+ * through the CL-03 credential lease, pinned transport, and observation normalization
+ * pipeline. Secret material stays outside Lab modules.
+ *
+ * @internal host integration only
+ */
+import { resolveEnvValue } from "../config";
+import {
+  getValidAccessTokenSnapshot,
+  OAuthLoginRequiredError,
+  UnsupportedOAuthProviderError,
+} from "../oauth";
+import type { OcxConfig } from "../types";
+import { createCredentialLease } from "../lab/live/credential-lease";
+import {
+  liveUpstreamRequestPath,
+  normalizeLabLiveTransportObservation,
+} from "../lab/live/executor";
+import { createPinnedTransport } from "../lab/live/transport";
+import { TransportError } from "../lab/live/transport";
+import type { LabRouteContext } from "../lab/live/types";
+import { createLabAuthorizedPinnedSender } from "./lab-live-pinned-sender";
+import { createHostIssuedLabRouteExecutor } from "./lab-live-host";
+import type { TrustedLabRouteExecutor } from "../lab/live/types";
+
+const CREDENTIAL_HEADER = /(authorization|api[-_]?key|token|secret|credential|cookie)/i;
+
+export interface ProductionLabRouteExecutorDeps {
+  configDir?: string;
+  loadConfig: () => OcxConfig;
+}
+
+async function buildLabProviderAuthHeaders(
+  routeContext: LabRouteContext,
+  config: OcxConfig,
+): Promise<Record<string, string>> {
+  const provider = config.providers?.[routeContext.providerId];
+  if (!provider || provider.disabled === true) {
+    throw new TransportError("auth_blocked", "provider unavailable");
+  }
+  if (provider.authMode === "forward") {
+    throw new TransportError("auth_blocked", "forward auth unsupported for lab probes");
+  }
+  if (provider.authMode === "local") {
+    throw new TransportError("auth_blocked", "local provider unsupported for lab probes");
+  }
+
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+
+  if (provider.authMode === "oauth") {
+    let protocol: string;
+    try {
+      protocol = new URL(routeContext.baseUrl).protocol;
+    } catch {
+      throw new TransportError("auth_blocked", "invalid OAuth provider destination");
+    }
+    if (protocol !== "https:") {
+      throw new TransportError("auth_blocked", "OAuth lab probes require HTTPS");
+    }
+    try {
+      const snapshot = await getValidAccessTokenSnapshot(routeContext.providerId);
+      headers.Authorization = `Bearer ${snapshot.accessToken}`;
+    } catch (error) {
+      if (error instanceof OAuthLoginRequiredError || error instanceof UnsupportedOAuthProviderError) {
+        throw new TransportError("auth_blocked", "oauth unavailable");
+      }
+      // Non-terminal refresh failures (network, lock contention, provider transient errors)
+      // are harness/infrastructure failures rather than evidence that credentials are invalid.
+      throw new TransportError("harness_failure", "oauth refresh unavailable");
+    }
+  } else {
+    const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+    if (!apiKey) throw new TransportError("auth_blocked", "missing api key");
+    if (provider.adapter === "anthropic" && provider.apiKeyTransport === "x-api-key") {
+      headers["x-api-key"] = apiKey;
+    } else {
+      headers.Authorization = `Bearer ${apiKey}`;
+    }
+  }
+
+  if (provider.headers) {
+    for (const [name, value] of Object.entries(provider.headers)) {
+      if (CREDENTIAL_HEADER.test(name)) continue;
+      const resolved = resolveEnvValue(value);
+      headers[name] = typeof resolved === "string" ? resolved : value;
+    }
+  }
+
+  return headers;
+}
+
+/** Create the process-local trusted CL-03 route executor for Lab automation dispatch. */
+export function createProductionLabRouteExecutor(
+  deps: ProductionLabRouteExecutorDeps,
+): TrustedLabRouteExecutor {
+  return createHostIssuedLabRouteExecutor(async (input) => {
+    if (!input.initiatingRequest) {
+      throw new TransportError("harness_failure", "live scenario missing initiating request");
+    }
+    const config = deps.loadConfig();
+    const lease = createCredentialLease({
+      destination: input.destination,
+      transportId: "lab-automation",
+      budget: input.limits.maxRequests,
+    });
+    const authHeaders = await buildLabProviderAuthHeaders(input.routeContext, config);
+    const sender = createLabAuthorizedPinnedSender(async () => authHeaders);
+    const transport = createPinnedTransport({
+      destination: input.destination,
+      lease,
+      sender,
+      limits: input.limits,
+      transportId: "lab-automation",
+    });
+    const path = liveUpstreamRequestPath(input.routeContext.upstreamProtocol);
+    const response = await transport.request({
+      method: "POST",
+      path,
+      body: input.initiatingRequest,
+      signal: input.signal,
+    });
+    return normalizeLabLiveTransportObservation(input.routeContext, response);
+  });
+}

package/src/lib/lab-passive-linker-registration.ts

@@ -0,0 +1,26 @@
+/**
+ * Registers Compatibility Lab's passive route-subject linker into the core slot.
+ *
+ * Imported only from the Lab activation path, never from the request path. This module
+ * lives outside `src/lab/` for the same reason the other `src/lib/lab-*.ts` host
+ * integrations do: it is the seam between core and the subsystem, not the subsystem.
+ *
+ * @internal host integration only
+ */
+import { setPassiveRouteLinker } from "../server/passive-route-linker";
+import { resolveProductionRouteSubject } from "../routing/compatibility/subject";
+
+/** Install the Lab linker. Returns a detach function. */
+export function registerLabPassiveRouteLinker(configDir?: string): () => void {
+  return setPassiveRouteLinker((config, providerName, modelId, routed, inboundWire) => {
+    const subject = resolveProductionRouteSubject(
+      config,
+      providerName,
+      modelId,
+      routed,
+      inboundWire,
+      configDir,
+    );
+    return subject ? subject.subjectId : null;
+  });
+}

package/src/lib/local-management-attestation.ts

@@ -0,0 +1,51 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export const LOCAL_ATTESTATION_CHALLENGE_HEADER = "x-opencodex-attestation-challenge";
+export const LOCAL_ATTESTATION_PROOF_HEADER = "x-opencodex-attestation-proof";
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export function isLocalAttestationSecret(value: unknown): value is string {
+  return typeof value === "string" && BASE64URL_256.test(value);
+}
+
+export function createLocalAttestationSecret(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function createLocalAttestationChallenge(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+function attestationPayload(challenge: string, pid: number, port: number): string | null {
+  if (!BASE64URL_256.test(challenge)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return `opencodex-local-management-v1\n${challenge}\n${pid}\n${port}`;
+}
+
+export function createLocalAttestationProof(
+  secret: string,
+  challenge: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = attestationPayload(challenge, pid, port);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalAttestationProof(
+  secret: string,
+  challenge: string,
+  pid: number,
+  port: number,
+  proof: string | null,
+): boolean {
+  const expected = createLocalAttestationProof(secret, challenge, pid, port);
+  if (!expected || !proof || !BASE64URL_256.test(proof)) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(proof);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/local-management-capability.ts

@@ -0,0 +1,100 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const LOCAL_MANAGEMENT_EXPECTED_PID_HEADER = "x-opencodex-local-expected-pid";
+export const LOCAL_MANAGEMENT_NONCE_HEADER = "x-opencodex-local-nonce";
+export const LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER = "x-opencodex-local-expires-at";
+export const LOCAL_MANAGEMENT_CAPABILITY_HEADER = "x-opencodex-local-capability";
+export const LOCAL_MANAGEMENT_CAPABILITY_TTL_MS = 10_000;
+
+export const LOCAL_MANAGEMENT_READ_PATHS = {
+  codexAccounts: "/api/codex-auth/accounts",
+  systemMemory: "/api/system/memory",
+} as const;
+
+export type LocalManagementReadPath =
+  typeof LOCAL_MANAGEMENT_READ_PATHS[keyof typeof LOCAL_MANAGEMENT_READ_PATHS];
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+const LOCAL_READ_METHOD = "GET";
+
+export type ExpectedLocalManagementPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedLocalManagementPid(value: string | null): ExpectedLocalManagementPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+function isLocalManagementReadPath(path: string): path is LocalManagementReadPath {
+  return path === LOCAL_MANAGEMENT_READ_PATHS.codexAccounts
+    || path === LOCAL_MANAGEMENT_READ_PATHS.systemMemory;
+}
+
+function localReadCapabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== LOCAL_READ_METHOD || !isLocalManagementReadPath(path)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) return null;
+  return `opencodex-local-management-read-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}\n${expiresAt}`;
+}
+
+/** Process-scoped authorization for one allowlisted local management GET. */
+export function createLocalManagementReadCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = localReadCapabilityPayload(nonce, method, path, pid, port, expiresAt);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalManagementReadCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+  capability: string | null,
+  now = Date.now(),
+): boolean {
+  if (!nonce || !capability || !BASE64URL_256.test(capability)) return false;
+  if (
+    !Number.isSafeInteger(now)
+    || expiresAt <= now
+    || expiresAt > now + LOCAL_MANAGEMENT_CAPABILITY_TTL_MS
+  ) return false;
+  const expected = createLocalManagementReadCapability(
+    secret,
+    nonce,
+    method,
+    path,
+    pid,
+    port,
+    expiresAt,
+  );
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/local-provider-reload-contract.ts

@@ -0,0 +1,100 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const LOCAL_PROVIDER_RELOAD_METHOD = "POST";
+export const LOCAL_PROVIDER_RELOAD_PATH = "/api/providers/reload";
+export const LOCAL_PROVIDER_RELOAD_CAPABILITY_VERSION = "v1";
+export const LOCAL_PROVIDER_RELOAD_EXPECTED_PID_HEADER = "x-opencodex-provider-reload-expected-pid";
+export const LOCAL_PROVIDER_RELOAD_NONCE_HEADER = "x-opencodex-provider-reload-nonce";
+export const LOCAL_PROVIDER_RELOAD_EXPIRES_AT_HEADER = "x-opencodex-provider-reload-expires-at";
+export const LOCAL_PROVIDER_RELOAD_NAME_HEADER = "x-opencodex-provider-reload-name";
+export const LOCAL_PROVIDER_RELOAD_CAPABILITY_HEADER = "x-opencodex-provider-reload-capability";
+export const LOCAL_PROVIDER_RELOAD_CAPABILITY_TTL_MS = 10_000;
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+const PROVIDER_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/;
+
+export type ExpectedLocalProviderReloadPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedLocalProviderReloadPid(value: string | null): ExpectedLocalProviderReloadPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+export function isLocalProviderReloadName(value: unknown): value is string {
+  return typeof value === "string" && PROVIDER_NAME.test(value);
+}
+
+function capabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  name: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== LOCAL_PROVIDER_RELOAD_METHOD || path !== LOCAL_PROVIDER_RELOAD_PATH) return null;
+  if (!isLocalProviderReloadName(name)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) return null;
+  return `opencodex-local-provider-reload-v1\n${nonce}\n${method}\n${path}\n${name}\n${pid}\n${port}\n${expiresAt}`;
+}
+
+/** Process-scoped authorization to reload one named provider from protected disk state. */
+export function createLocalProviderReloadCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  name: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = capabilityPayload(nonce, method, path, name, pid, port, expiresAt);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalProviderReloadCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  name: string | null,
+  pid: number,
+  port: number,
+  expiresAt: number,
+  capability: string | null,
+  now = Date.now(),
+): boolean {
+  if (!nonce || !name || !capability || !BASE64URL_256.test(capability)) return false;
+  if (
+    !Number.isSafeInteger(now)
+    || expiresAt <= now
+    || expiresAt > now + LOCAL_PROVIDER_RELOAD_CAPABILITY_TTL_MS
+  ) return false;
+  const expected = createLocalProviderReloadCapability(
+    secret,
+    nonce,
+    method,
+    path,
+    name,
+    pid,
+    port,
+    expiresAt,
+  );
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/optional-shutdown-hooks.ts

@@ -0,0 +1,57 @@
+/**
+ * Core-owned registry for optional-subsystem shutdown work.
+ *
+ * The proxy core must not import an optional subsystem merely to be able to stop it.
+ * Compatibility Lab is the first case: `server/lifecycle.ts` imported
+ * `lab/automation/orchestrator` for two teardown calls, and that single edge closed an
+ * import cycle (`routing/compatibility/assemble` → `routing/quota` → `providers/quota` →
+ * `codex/auth-api` → `codex/native-main-admission` → `server/lifecycle` → Lab) that pulled
+ * ~69 `src/lab/` modules into the graph of every install, including installs with no
+ * routing profile at all.
+ *
+ * A subsystem registers its teardown when it activates. A process that never activates it
+ * registers nothing, so shutdown does no work and loads no module.
+ *
+ * Hooks are synchronous and best-effort by contract: `drainAndShutdown` runs under an
+ * absolute deadline, so a hook that throws must not prevent its siblings — or
+ * `server.stop` — from running.
+ *
+ * See devlog/_fin/260814_lab_core_decoupling/010_lifecycle_shutdown_registry.md
+ */
+
+type ShutdownHook = () => void;
+
+const hooks = new Map<string, ShutdownHook>();
+
+/**
+ * Register (or replace) the teardown for one optional subsystem.
+ *
+ * Keyed so repeated activation of the same subsystem cannot accumulate duplicate hooks.
+ * Returns a detach function so an owner-scoped lease can release its registration.
+ */
+export function registerOptionalShutdownHook(key: string, hook: ShutdownHook): () => void {
+  hooks.set(key, hook);
+  return () => {
+    // Only detach our own registration: a later activation may have replaced it.
+    if (hooks.get(key) === hook) hooks.delete(key);
+  };
+}
+
+/** Run every registered teardown. Never throws. */
+export function runOptionalShutdownHooks(): void {
+  for (const [key, hook] of [...hooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(
+        `[shutdown] optional subsystem "${key}" teardown failed:`,
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+}
+
+/** Test-only reset so an isolated lifecycle test does not inherit registrations. */
+export function resetOptionalShutdownHooksForTests(): void {
+  hooks.clear();
+}

package/src/lib/package-tree-integrity.ts

@@ -0,0 +1,101 @@
+import { statSync } from "node:fs";
+
+export interface PackageTreeObservation {
+  readonly device: bigint;
+  readonly inode: bigint;
+  readonly contentTimeNs: bigint;
+  readonly size: bigint;
+}
+
+export type PackageTreeIntegrityStatus =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "package_tree_replaced" | "package_tree_unreadable" };
+
+export interface PackageTreeIntegrityGuard {
+  status(): PackageTreeIntegrityStatus;
+}
+
+type ObservePackageTree = () => PackageTreeObservation | null;
+type PackageTreeRuntimeInstall = "bun" | "npm" | "source";
+
+const packageManifestUrl = new URL("../../package.json", import.meta.url);
+
+function observePackageManifest(): PackageTreeObservation | null {
+  try {
+    const stat = statSync(packageManifestUrl, { bigint: true });
+    return {
+      device: stat.dev,
+      inode: stat.ino,
+      // mtimeNs, NOT ctimeNs. An inode-change time moves for METADATA writes that
+      // replace nothing: chmod, chown, touch, an editor normalizing permissions, a
+      // backup tool restoring modes. Each of those left device, inode and size
+      // identical, so the comparison below called the manifest "replaced" and every
+      // /v1/* request answered 503 until the process was restarted. Measured on
+      // macOS: chmod alone moved ctimeNs and left mtimeNs untouched.
+      //
+      // mtimeNs still catches every real replacement. An in-place rewrite of the
+      // same byte length moves mtimeNs while inode and size hold; an atomic
+      // install (write-then-rename, which is what a package manager does) changes
+      // the inode as well. Both were measured before this change was made.
+      contentTimeNs: stat.mtimeNs,
+      size: stat.size,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function sameObservation(left: PackageTreeObservation, right: PackageTreeObservation): boolean {
+  return left.device === right.device
+    && left.inode === right.inode
+    && left.contentTimeNs === right.contentTimeNs
+    && left.size === right.size;
+}
+
+/**
+ * How long an `ok` observation is reused before the manifest is stat'd again.
+ *
+ * `status()` runs on `/healthz`, `/readyz` and every `/v1/*` request, so an unthrottled guard
+ * adds a filesystem syscall to the proxy's hot path to detect an event that happens at most
+ * once per install. A replaced tree is not time-critical either: the process is already
+ * serving broken imports, and one more second of that is not worse than a syscall per turn
+ * forever.
+ *
+ * A NEGATIVE result is never cached — once the tree looks wrong, every later request re-checks,
+ * so a repaired install recovers on its own instead of staying refused for a window.
+ */
+const PACKAGE_TREE_RECHECK_MS = 1_000;
+
+export function createPackageTreeIntegrityGuard(
+  observe: ObservePackageTree = observePackageManifest,
+  now: () => number = Date.now,
+): PackageTreeIntegrityGuard {
+  const boot = observe();
+  let lastOkAt: number | null = null;
+  return {
+    status(): PackageTreeIntegrityStatus {
+      const at = now();
+      if (lastOkAt !== null && at - lastOkAt < PACKAGE_TREE_RECHECK_MS) return { ok: true };
+      const current = observe();
+      if (boot === null || current === null) return { ok: false, reason: "package_tree_unreadable" };
+      if (!sameObservation(boot, current)) return { ok: false, reason: "package_tree_replaced" };
+      lastOkAt = at;
+      return { ok: true };
+    },
+  };
+}
+
+/**
+ * Installed packages fail closed when their manifest is replaced under a live process.
+ * A source checkout is different: editing package.json is ordinary development work, and
+ * Bun keeps serving the module snapshot already loaded by this process until the operator
+ * chooses to restart. Fencing every request there makes running dev directly impossible.
+ */
+export function createRuntimePackageTreeIntegrityGuard(
+  installer: PackageTreeRuntimeInstall,
+  observe: ObservePackageTree = observePackageManifest,
+  now: () => number = Date.now,
+): PackageTreeIntegrityGuard {
+  if (installer === "source") return { status: () => ({ ok: true }) };
+  return createPackageTreeIntegrityGuard(observe, now);
+}