@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/user-identity.ts

@@ -0,0 +1,266 @@
+/**
+ * Environment-independent identity and namespace resolution for Codex writes.
+ *
+ * Bun 1.3.14 made the obvious implementation unsafe: both `os.homedir()` and
+ * `os.userInfo().homedir` follow HOME. A service and CLI for the same account
+ * could therefore coordinate through different databases. The namespace is
+ * keyed only by the effective uid/SID and the canonical CODEX_HOME.
+ *
+ * Design record: devlog/_plan/260804_codex_write_substrate/005_contract.md §7.
+ */
+import { createHash } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+import type {
+  ResolveCodexCoordinatorDatabasePath,
+  ResolveCodexCatalogSerializationDatabasePath,
+  ResolveCodexHistorySerializationDatabasePath,
+  ResolveEffectiveUserIdentity,
+  UserIdentity,
+} from "./convergence-types";
+
+const POSIX_PRIVATE_MODE = 0o700;
+const POSIX_TMP_REQUIRED_MODE = 0o1003;
+const POSIX_TMP_PATH = "/tmp";
+const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
+
+export class CodexUserIdentityRefusal extends Error {
+  readonly code = "CODEX_USER_IDENTITY_REFUSED";
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CodexUserIdentityRefusal";
+  }
+}
+
+function refuse(message: string, cause?: unknown): never {
+  throw new CodexUserIdentityRefusal(message, cause === undefined ? undefined : { cause });
+}
+
+function powershellValue(expression: string): string {
+  let result: ReturnType<typeof Bun.spawnSync>;
+  try {
+    result = Bun.spawnSync([
+      "powershell.exe",
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-Command",
+      expression,
+    ], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch (cause) {
+    refuse("Windows effective-account lookup could not start.", cause);
+  }
+  if (result.exitCode !== 0) refuse("Windows effective-account lookup failed.");
+  const value = new TextDecoder().decode(result.stdout).trim();
+  if (!value) refuse("Windows effective-account lookup returned an empty value.");
+  return value;
+}
+
+function resolveWindowsSid(): string {
+  const sid = powershellValue(
+    "[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value",
+  );
+  if (!SID_PATTERN.test(sid)) refuse("Windows effective-account lookup returned an invalid SID.");
+  return sid.toUpperCase();
+}
+
+export const resolveEffectiveUserIdentity: ResolveEffectiveUserIdentity = () => {
+  if (process.platform === "win32") {
+    return { platform: "win32", sid: resolveWindowsSid() };
+  }
+
+  const getuid = process.getuid;
+  if (typeof getuid !== "function") {
+    refuse("The runtime does not expose the effective POSIX uid.");
+  }
+  let uid: number;
+  try {
+    uid = getuid.call(process);
+  } catch (cause) {
+    refuse("The effective POSIX uid lookup failed.", cause);
+  }
+  if (!Number.isSafeInteger(uid) || uid < 0) {
+    refuse("The runtime returned an invalid effective POSIX uid.");
+  }
+  return { platform: "posix", uid };
+};
+
+function assertPrivatePosixDirectory(path: string, uid: number): void {
+  let entry;
+  try {
+    entry = lstatSync(path);
+  } catch (cause) {
+    refuse("The Codex coordinator namespace cannot be inspected.", cause);
+  }
+  if (entry.isSymbolicLink() || !entry.isDirectory()) {
+    refuse("The Codex coordinator namespace is not a real directory.");
+  }
+  if (entry.uid !== uid || (entry.mode & 0o777) !== POSIX_PRIVATE_MODE) {
+    refuse("The Codex coordinator namespace has unsafe ownership or permissions.");
+  }
+}
+
+function ensurePrivatePosixDirectory(path: string, uid: number): void {
+  try {
+    mkdirSync(path, { mode: POSIX_PRIVATE_MODE });
+  } catch (cause) {
+    const code = cause && typeof cause === "object" && "code" in cause
+      ? String((cause as { code?: unknown }).code)
+      : "";
+    if (code !== "EEXIST") refuse("The Codex coordinator namespace cannot be created.", cause);
+  }
+  assertPrivatePosixDirectory(path, uid);
+}
+
+function resolvePosixRuntimeRoot(uid: number): string {
+  let realTmp: string;
+  try {
+    realTmp = realpathSync.native(POSIX_TMP_PATH);
+    const entry = statSync(realTmp);
+    if (!entry.isDirectory() || entry.uid !== 0) {
+      refuse("The system temporary directory has unsafe ownership.");
+    }
+    if ((entry.mode & POSIX_TMP_REQUIRED_MODE) !== POSIX_TMP_REQUIRED_MODE) {
+      refuse("The system temporary directory lacks sticky world write/search permissions.");
+    }
+  } catch (cause) {
+    if (cause instanceof CodexUserIdentityRefusal) throw cause;
+    refuse("The system temporary directory cannot be trusted.", cause);
+  }
+
+  const root = join(realTmp, `opencodex-runtime-v1-${uid}`);
+  ensurePrivatePosixDirectory(root, uid);
+  return root;
+}
+
+function resolveWindowsRuntimeRoot(identity: Extract<UserIdentity, { platform: "win32" }>): string {
+  if (!SID_PATTERN.test(identity.sid)) refuse("The coordinator identity contains an invalid SID.");
+  const localAppData = powershellValue(
+    "[Environment]::GetFolderPath([Environment+SpecialFolder]::LocalApplicationData)",
+  );
+  if (!isAbsolute(localAppData)) refuse("Windows LocalAppData resolution returned a relative path.");
+
+  // The SID and known-folder values come from the effective token/.NET OS APIs,
+  // never USERPROFILE or LOCALAPPDATA. WP11 adds descriptor/reparse/ACL checks at
+  // the stable-database open boundary where those checks can cover SQLite too.
+  const root = resolve(localAppData, "OpenCodex", "Runtime", "v1", identity.sid.toUpperCase());
+  try {
+    mkdirSync(root, { recursive: true });
+  } catch (cause) {
+    refuse("The Windows coordinator namespace cannot be created.", cause);
+  }
+  return root;
+}
+
+export const resolveCodexCoordinatorDatabasePath: ResolveCodexCoordinatorDatabasePath = (
+  identity,
+  canonicalCodexHome,
+) => {
+  if (!isAbsolute(canonicalCodexHome)) {
+    refuse("The canonical CODEX_HOME must be an absolute path.");
+  }
+  const root = identity.platform === "posix"
+    ? resolvePosixRuntimeRoot(identity.uid)
+    : resolveWindowsRuntimeRoot(identity);
+  const locks = join(root, "native-write-locks");
+  if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
+  else {
+    try {
+      mkdirSync(locks, { recursive: true });
+    } catch (cause) {
+      refuse("The Windows coordinator lock directory cannot be created.", cause);
+    }
+  }
+
+  const homeDigest = createHash("sha256").update(canonicalCodexHome).digest("hex");
+  return join(locks, `${homeDigest}.sqlite`);
+};
+
+/**
+ * K's FINAL database path. Never the native coordinator path.
+ *
+ * Catalog serialization is a different ownership surface from the native
+ * coordinator N: `K -> C` is a legal order and `N -> K` nests, so sharing one
+ * database would make the required nesting self-contend. The two live in
+ * sibling directories under the same per-user runtime root — same identity
+ * namespace, same environment-independent parent, distinct exclusion.
+ *
+ * Consumers use the returned path verbatim and append nothing
+ * (`005_contract.md:1256-1330`).
+ */
+export const resolveCodexCatalogSerializationDatabasePath:
+  ResolveCodexCatalogSerializationDatabasePath = (identity, canonicalCodexHome) => {
+    if (!isAbsolute(canonicalCodexHome)) {
+      refuse("The canonical CODEX_HOME must be an absolute path.");
+    }
+    const root = identity.platform === "posix"
+      ? resolvePosixRuntimeRoot(identity.uid)
+      : resolveWindowsRuntimeRoot(identity);
+    const locks = join(root, "catalog-write-locks");
+    if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
+    else {
+      try {
+        mkdirSync(locks, { recursive: true });
+      } catch (cause) {
+        refuse("The Windows catalog serialization directory cannot be created.", cause);
+      }
+    }
+
+    const homeDigest = createHash("sha256").update(canonicalCodexHome).digest("hex");
+    return join(locks, `${homeDigest}.sqlite`);
+  };
+
+/**
+ * H's FINAL database path.
+ *
+ * Keyed by the canonical state DB in addition to the canonical home, unlike N and
+ * K. One `CODEX_HOME` can name a different `state_5.sqlite` — `model_catalog_json`
+ * has the same shape of indirection for catalogs — and two operations against
+ * different history databases are not the same exclusion. Hashing only the home
+ * would serialize them together, and hashing the raw request path would let two
+ * spellings of one database take different locks.
+ */
+export const resolveCodexHistorySerializationDatabasePath:
+  ResolveCodexHistorySerializationDatabasePath = (
+    identity,
+    canonicalCodexHome,
+    canonicalStateDbPath,
+  ) => {
+    if (!isAbsolute(canonicalCodexHome)) {
+      refuse("The canonical CODEX_HOME must be an absolute path.");
+    }
+    if (!isAbsolute(canonicalStateDbPath)) {
+      refuse("The canonical Codex state database must be an absolute path.");
+    }
+    const root = identity.platform === "posix"
+      ? resolvePosixRuntimeRoot(identity.uid)
+      : resolveWindowsRuntimeRoot(identity);
+    const locks = join(root, "history-write-locks");
+    if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
+    else {
+      try {
+        mkdirSync(locks, { recursive: true });
+      } catch (cause) {
+        refuse("The Windows history serialization directory cannot be created.", cause);
+      }
+    }
+
+    // Both components are length-prefixed so no pair of (home, stateDb) values can
+    // collide by concatenation.
+    const digest = createHash("sha256")
+      .update(`${canonicalCodexHome.length}:${canonicalCodexHome}`)
+      .update(`${canonicalStateDbPath.length}:${canonicalStateDbPath}`)
+      .digest("hex");
+    return join(locks, `${digest}.sqlite`);
+  };

package/src/codex/write-coordination.ts

@@ -0,0 +1,114 @@
+/**
+ * The witness a native Codex write is coordinated by.
+ *
+ * NOT an `AdmissionSnapshot`, and the difference is the whole reason this file
+ * exists. `admitCodexWrite` refuses before it constructs a snapshot unless
+ * ownership is `owned` (`admission.ts`), so every snapshot it produces carries
+ * `owned` — the field cannot hold `unknown` at all. Reusing that type here would
+ * have meant one of two untruths: either the call becomes gated on ownership,
+ * which refuses Codex injection on every Windows machine and on Linux without a
+ * reachable user bus, or a hand-built snapshot claims an admission that never
+ * happened.
+ *
+ * So this type authorizes THE WRITE, not the DECISION to write. Deciding whether
+ * a write should happen at all is admission's job and belongs to its own phase,
+ * behind the Windows definition-chain walk.
+ *
+ * What the id covers, and why it is the OUTPUT rather than the inputs: the bytes
+ * `injectCodexConfig` emits depend on the port, the resolved catalog path, the
+ * hostname, websocket mode, legacy mode and the managed sub-agent defaults. An
+ * enumeration of those was already incomplete once. Hashing the computed
+ * candidate bytes closes the class instead of the instance — an input that
+ * changes the output changes the id whether or not anyone remembered to list it.
+ */
+import { createHash } from "node:crypto";
+
+export interface CodexWriteCandidate {
+  /** The exact string about to replace `config.toml`. */
+  readonly configBytes: string;
+  /** The exact string about to replace the profile. */
+  readonly profileBytes: string;
+  /** The RESOLVED catalog path, never the raw option. */
+  readonly catalogPath: string | null;
+}
+
+export interface CodexWriteEvidence {
+  /** sha256 of the `config.toml` bytes this operation read as its input. */
+  readonly nativeInputIdentity: string;
+  /** Digest of the persisted OpenCodex config these bytes were derived from. */
+  readonly persistedIdentity: string;
+  /** Generation as observed before the lock; `present:false` means no coordinator yet. */
+  readonly generation: Readonly<{ present: boolean; value: number }>;
+  /** Content identity of the journal, or a stable marker for absence. */
+  readonly journalIdentity: string;
+  readonly canonicalTargets: Readonly<{
+    config: string;
+    profile: string;
+    journal: string;
+  }>;
+}
+
+export interface CodexWriteCoordination {
+  readonly candidate: CodexWriteCandidate;
+  readonly evidence: CodexWriteEvidence;
+  /**
+   * Recorded context, deliberately OUTSIDE `comparisonId`.
+   *
+   * The lock compares one id and nothing else, so a field that is copied rather
+   * than re-observed detects no drift by being in it — it would only match
+   * itself. Ownership is not re-observed under the lock (that would mean running
+   * a service-manager subprocess while N and C are held), so it travels as
+   * something the operation SAW, not as something the comparison PROVES.
+   */
+  readonly observedOwnership: "owned" | "foreign" | "unknown";
+  readonly comparisonId: string;
+}
+
+/**
+ * Collapse a generation to one token.
+ *
+ * Absent and present-zero are the same authority — no cooperating write has
+ * committed — and they cannot be observed the same way: before the lock only
+ * absence is visible, and inside it only the committed zero is. Without this
+ * they never match and every first write refuses.
+ */
+function generationToken(generation: CodexWriteEvidence["generation"]): string {
+  const { present, value } = generation;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`A config generation must be a non-negative safe integer, got ${String(value)}.`);
+  }
+  return present && value > 0 ? `gen:${value}` : "gen:0";
+}
+
+export function hashCodexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+): string {
+  return createHash("sha256")
+    .update(JSON.stringify([
+      // The output, hashed directly. Two operations that intend different bytes
+      // cannot share an id, however they came to differ.
+      createHash("sha256").update(candidate.configBytes).digest("hex"),
+      createHash("sha256").update(candidate.profileBytes).digest("hex"),
+      candidate.catalogPath,
+      evidence.nativeInputIdentity,
+      evidence.persistedIdentity,
+      generationToken(evidence.generation),
+      evidence.journalIdentity,
+      evidence.canonicalTargets,
+    ]))
+    .digest("hex");
+}
+
+export function codexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+  observedOwnership: CodexWriteCoordination["observedOwnership"],
+): CodexWriteCoordination {
+  return {
+    candidate,
+    evidence,
+    observedOwnership,
+    comparisonId: hashCodexWriteCoordination(candidate, evidence),
+  };
+}