@iislee/opencodex 2.31.0 → 2.35.0

package/src/compatibility/manifest.ts

@@ -0,0 +1,253 @@
+export const COMPATIBILITY_MANIFEST_SCHEMA_VERSION = 1 as const;
+
+export const COMPATIBILITY_DISPOSITIONS = [
+  "passthrough",
+  "translated",
+  "degraded",
+  "unsupported",
+] as const;
+
+export type CompatibilityDisposition = typeof COMPATIBILITY_DISPOSITIONS[number];
+export type CompatibilityEvidenceKind = "fixture" | "lab-scenario";
+
+export interface CompatibilityEvidenceRefV1 {
+  kind: CompatibilityEvidenceKind;
+  id: string;
+  /** Exact fixture assertions that prove this claim. Required for fixture evidence. */
+  assertionIds?: readonly string[];
+}
+
+export interface CompatibilityClaimV1 {
+  /** Stable manifest-local claim id. */
+  id: string;
+  /** Stable public feature key, such as `request.previous_response_id`. */
+  feature: string;
+  disposition: CompatibilityDisposition;
+  summary: string;
+  /** Required when behavior is not byte/semantic passthrough. */
+  limitation?: string;
+  evidence: readonly CompatibilityEvidenceRefV1[];
+}
+
+export interface CompatibilitySubjectV1 {
+  providerId: string;
+  /** Exact normalized provider base URL; destination changes require a new subject/version. */
+  baseUrl: string;
+  adapterId: string;
+  authMode: "forward" | "key" | "oauth" | "local";
+  inboundProtocol: "responses" | "chat" | "messages";
+  upstreamProtocol: string;
+  /** Claims apply only to these exact wire model ids. */
+  modelIds: readonly string[];
+}
+
+export interface CompatibilityManifestV1 {
+  schemaVersion: typeof COMPATIBILITY_MANIFEST_SCHEMA_VERSION;
+  id: string;
+  version: string;
+  subject: CompatibilitySubjectV1;
+  claims: readonly CompatibilityClaimV1[];
+}
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const FEATURE_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/;
+const DISPOSITIONS = new Set<string>(COMPATIBILITY_DISPOSITIONS);
+const EVIDENCE_KINDS = new Set<string>(["fixture", "lab-scenario"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function checkKnownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  issues: string[],
+): void {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key)) issues.push(`${path}${path ? "." : ""}${key} is not allowed by schema v1`);
+  }
+}
+
+function checkId(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+    issues.push(`${path} must match ${ID_PATTERN}`);
+    return false;
+  }
+  return true;
+}
+
+function checkNonBlank(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push(`${path} must be a non-blank string`);
+    return false;
+  }
+  return true;
+}
+
+function checkNormalizedBaseUrl(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string") {
+    issues.push(`${path} must be a normalized absolute HTTP(S) base URL`);
+    return false;
+  }
+  try {
+    const parsed = new URL(value);
+    if (
+      (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+      || parsed.username
+      || parsed.password
+      || parsed.search
+      || parsed.hash
+    ) {
+      issues.push(`${path} must be a normalized absolute HTTP(S) base URL without credentials, query, or fragment`);
+      return false;
+    }
+    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+    const normalized = `${parsed.origin}${normalizedPath}`;
+    if (value !== normalized) {
+      issues.push(`${path} must be normalized as ${normalized}`);
+      return false;
+    }
+    return true;
+  } catch {
+    issues.push(`${path} must be a normalized absolute HTTP(S) base URL`);
+    return false;
+  }
+}
+
+function checkSortedUniqueStrings(
+  value: unknown,
+  path: string,
+  issues: string[],
+  options: { nonEmpty?: boolean } = {},
+): value is string[] {
+  if (!Array.isArray(value) || (options.nonEmpty === true && value.length === 0)) {
+    issues.push(`${path} must be${options.nonEmpty === true ? " a non-empty" : " an"} array`);
+    return false;
+  }
+  if (value.some(item => typeof item !== "string" || item.trim().length === 0)) {
+    issues.push(`${path} must contain only non-blank strings`);
+    return false;
+  }
+  const strings = value as string[];
+  if (new Set(strings).size !== strings.length) issues.push(`${path} must not contain duplicates`);
+  const sorted = [...strings].sort();
+  if (strings.some((item, index) => item !== sorted[index])) issues.push(`${path} must be sorted`);
+  return true;
+}
+
+function checkEvidence(value: unknown, path: string, issues: string[]): void {
+  if (!Array.isArray(value) || value.length === 0) {
+    issues.push(`${path} must be a non-empty array`);
+    return;
+  }
+  const seen = new Set<string>();
+  value.forEach((raw, index) => {
+    const evidencePath = `${path}[${index}]`;
+    if (!isRecord(raw)) {
+      issues.push(`${evidencePath} must be an object`);
+      return;
+    }
+    checkKnownKeys(raw, ["kind", "id", "assertionIds"], evidencePath, issues);
+    if (!EVIDENCE_KINDS.has(String(raw.kind))) {
+      issues.push(`${evidencePath}.kind must be fixture or lab-scenario`);
+    }
+    const id = checkId(raw.id, `${evidencePath}.id`, issues) ? raw.id : "";
+    const assertionIds = raw.assertionIds;
+    if (raw.kind === "fixture") {
+      checkSortedUniqueStrings(assertionIds, `${evidencePath}.assertionIds`, issues, { nonEmpty: true });
+    } else if (assertionIds !== undefined) {
+      checkSortedUniqueStrings(assertionIds, `${evidencePath}.assertionIds`, issues, { nonEmpty: true });
+    }
+    const key = `${String(raw.kind)}:${id}:${JSON.stringify(assertionIds ?? [])}`;
+    if (seen.has(key)) issues.push(`${evidencePath} duplicates an earlier evidence reference`);
+    seen.add(key);
+  });
+}
+
+/**
+ * Validate one versioned compatibility manifest without importing provider or Lab state.
+ * Keeping this as a leaf lets future CLI/GUI readers load contracts without activating Lab.
+ */
+export function compatibilityManifestIssues(value: unknown): string[] {
+  const issues: string[] = [];
+  if (!isRecord(value)) return ["manifest must be an object"];
+  checkKnownKeys(value, ["schemaVersion", "id", "version", "subject", "claims"], "", issues);
+  if (value.schemaVersion !== COMPATIBILITY_MANIFEST_SCHEMA_VERSION) {
+    issues.push(`schemaVersion must be ${COMPATIBILITY_MANIFEST_SCHEMA_VERSION}`);
+  }
+  checkId(value.id, "id", issues);
+  checkNonBlank(value.version, "version", issues);
+
+  if (!isRecord(value.subject)) {
+    issues.push("subject must be an object");
+  } else {
+    checkKnownKeys(
+      value.subject,
+      ["providerId", "baseUrl", "adapterId", "authMode", "inboundProtocol", "upstreamProtocol", "modelIds"],
+      "subject",
+      issues,
+    );
+    checkId(value.subject.providerId, "subject.providerId", issues);
+    checkNormalizedBaseUrl(value.subject.baseUrl, "subject.baseUrl", issues);
+    checkId(value.subject.adapterId, "subject.adapterId", issues);
+    if (!["forward", "key", "oauth", "local"].includes(String(value.subject.authMode))) {
+      issues.push("subject.authMode must be forward, key, oauth, or local");
+    }
+    if (!["responses", "chat", "messages"].includes(String(value.subject.inboundProtocol))) {
+      issues.push("subject.inboundProtocol must be responses, chat, or messages");
+    }
+    checkNonBlank(value.subject.upstreamProtocol, "subject.upstreamProtocol", issues);
+    checkSortedUniqueStrings(value.subject.modelIds, "subject.modelIds", issues, { nonEmpty: true });
+  }
+
+  if (!Array.isArray(value.claims) || value.claims.length === 0) {
+    issues.push("claims must be a non-empty array");
+    return issues;
+  }
+  const claimIds = new Set<string>();
+  const claimFeatures = new Set<string>();
+  value.claims.forEach((raw, index) => {
+    const path = `claims[${index}]`;
+    if (!isRecord(raw)) {
+      issues.push(`${path} must be an object`);
+      return;
+    }
+    checkKnownKeys(raw, ["id", "feature", "disposition", "summary", "limitation", "evidence"], path, issues);
+    const id = checkId(raw.id, `${path}.id`, issues) ? raw.id : "";
+    if (id && claimIds.has(id)) issues.push(`${path}.id duplicates ${id}`);
+    if (id) claimIds.add(id);
+    if (typeof raw.feature !== "string" || !FEATURE_PATTERN.test(raw.feature)) {
+      issues.push(`${path}.feature must be a dotted stable feature key`);
+    } else if (claimFeatures.has(raw.feature)) {
+      issues.push(`${path}.feature duplicates ${raw.feature}`);
+    } else {
+      claimFeatures.add(raw.feature);
+    }
+    if (!DISPOSITIONS.has(String(raw.disposition))) {
+      issues.push(`${path}.disposition is invalid`);
+    }
+    checkNonBlank(raw.summary, `${path}.summary`, issues);
+    if (raw.disposition !== "passthrough") {
+      checkNonBlank(raw.limitation, `${path}.limitation`, issues);
+    } else if (raw.limitation !== undefined) {
+      issues.push(`${path}.limitation must be omitted for passthrough claims`);
+    }
+    checkEvidence(raw.evidence, `${path}.evidence`, issues);
+  });
+  return issues;
+}
+
+function deepFreeze<T>(value: T, seen = new WeakSet<object>()): Readonly<T> {
+  if (!value || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested, seen);
+  return Object.freeze(value);
+}
+
+export function defineCompatibilityManifest<T extends CompatibilityManifestV1>(manifest: T): Readonly<T> {
+  const issues = compatibilityManifestIssues(manifest);
+  if (issues.length > 0) throw new TypeError(`Invalid compatibility manifest ${manifest.id}: ${issues.join("; ")}`);
+  return deepFreeze(manifest);
+}

package/src/compatibility/openai-responses.ts

@@ -0,0 +1,121 @@
+import { defineCompatibilityManifest } from "./manifest";
+
+const FIXTURE_ID = "openai-codex-forward-gpt56-sol-v1";
+
+/**
+ * First deliberately narrow compatibility slice: one exact native Codex-login model.
+ * Broader model/provider claims require their own fixtures instead of inheriting this row.
+ */
+export const OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST = defineCompatibilityManifest({
+  schemaVersion: 1,
+  id: "openai.codex-forward.gpt-5-6-sol.responses",
+  version: "1.3.0",
+  subject: {
+    providerId: "openai",
+    baseUrl: "https://chatgpt.com/backend-api/codex",
+    adapterId: "openai-responses",
+    authMode: "forward",
+    inboundProtocol: "responses",
+    upstreamProtocol: "openai-responses",
+    modelIds: ["gpt-5.6-sol"],
+  },
+  claims: [
+    {
+      id: "custom-tools",
+      feature: "request.custom_tools",
+      disposition: "passthrough",
+      summary: "Native custom-tool declarations retain their Responses representation.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-preserved"] }],
+    },
+    {
+      id: "prompt-cache-key",
+      feature: "request.prompt_cache_key",
+      disposition: "passthrough",
+      summary: "The caller's prompt cache key is forwarded unchanged.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-key-preserved"] }],
+    },
+    {
+      id: "previous-response-id",
+      feature: "request.previous_response_id",
+      disposition: "translated",
+      summary: "Continuation is owned by the proxy rather than the ChatGPT backend field.",
+      limitation: "OpenCodex expands remembered input locally and removes previous_response_id before dispatch.",
+      evidence: [
+        { kind: "fixture", id: FIXTURE_ID, assertionIds: ["previous-response-id-removed"] },
+        { kind: "lab-scenario", id: "codex-core.protocol.previous-response-replay" },
+      ],
+    },
+    {
+      id: "orphan-tool-output",
+      feature: "continuation.orphan_tool_output",
+      disposition: "degraded",
+      summary: "An output whose prior call is unavailable remains visible to the model.",
+      limitation: "The orphan output is converted to user text because the forward backend cannot accept the unmatched item.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["orphan-output-converted"] }],
+    },
+    {
+      id: "max-output-tokens",
+      feature: "request.max_output_tokens",
+      disposition: "unsupported",
+      summary: "The ChatGPT Codex forward route does not receive max_output_tokens.",
+      limitation: "The field is removed before dispatch to avoid a backend parameter rejection.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["max-output-tokens-removed"] }],
+    },
+    {
+      id: "metadata",
+      feature: "request.metadata",
+      disposition: "unsupported",
+      summary: "Caller metadata is not forwarded to the ChatGPT Codex backend.",
+      limitation: "The field is removed before dispatch.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["metadata-removed"] }],
+    },
+    {
+      id: "system-input-messages",
+      feature: "request.input.system_messages",
+      disposition: "translated",
+      summary: "Text-only input system messages are folded into top-level instructions.",
+      limitation: "The destination does not accept system-role input items; multimodal system messages stay unchanged rather than being dropped.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["system-message-folded", "system-message-removed"] }],
+    },
+    {
+      id: "truncation",
+      feature: "request.truncation",
+      disposition: "unsupported",
+      summary: "The ChatGPT Codex forward route does not receive truncation.",
+      limitation: "The field is removed only for the canonical forward destination; public and custom Responses providers keep it.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["truncation-removed"] }],
+    },
+    {
+      id: "prompt-cache-breakpoint",
+      feature: "request.prompt_cache_breakpoint",
+      disposition: "unsupported",
+      summary: "Client-only prompt cache breakpoint markers do not reach the forward backend.",
+      limitation: "Markers are removed recursively from input within bounded depth and node budgets.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-breakpoint-removed"] }],
+    },
+    {
+      id: "unstored-item-reference",
+      feature: "continuation.item_reference",
+      disposition: "degraded",
+      summary: "Unpersisted item references are omitted from store-false continuations.",
+      limitation: "The referenced item cannot exist at the backend when store is false; tool call_id pairs remain unchanged.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["unstored-item-reference-removed"] }],
+    },
+    {
+      id: "prompt-cache-retention",
+      feature: "request.prompt_cache_retention",
+      disposition: "unsupported",
+      summary: "The retired retention field is not sent for gpt-5.6-sol.",
+      limitation: "The field is removed without inventing a replacement prompt_cache_options value.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-retention-removed"] }],
+    },
+    {
+      id: "prompt-cache-options",
+      feature: "request.prompt_cache_options",
+      disposition: "unsupported",
+      summary: "The ChatGPT Codex forward route does not receive public prompt cache options.",
+      limitation: "The field is removed only for the canonical forward destination; public and custom Responses providers keep it.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-options-removed"] }],
+    },
+  ],
+} as const);

package/src/config/atomic-write.ts

@@ -0,0 +1,219 @@
+import {
+  chmodSync,
+  lstatSync,
+  realpathSync,
+  truncateSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import {
+  forgetEphemeralSecretPath,
+  hardenSecretPath,
+  hardenSecretPathAsync,
+} from "../lib/windows-secret-acl";
+import {
+  renameAtomicFile,
+  renameAtomicFileAsync,
+} from "../lib/windows-atomic-replace";
+import { getConfigDir } from "./paths";
+
+let atomicSequence = 0;
+
+/** Shared process-wide suffix source for config-owned atomic sibling files. */
+export function nextAtomicTempSequence(): number {
+  return ++atomicSequence;
+}
+/** Internal error classifier shared by config backup and atomic-write paths. */
+export function isMissingPathError(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}
+
+export type { AtomicRenameIO } from "../lib/windows-atomic-replace";
+export { renameAtomicFile } from "../lib/windows-atomic-replace";
+
+export interface AtomicWriteIO {
+  write: (path: string, content: string) => void;
+  harden: (path: string) => void;
+  rename: (source: string, destination: string) => void;
+  truncate: (path: string) => void;
+  unlink: (path: string) => void;
+}
+
+export class AtomicWriteResidualTempError extends Error {
+  constructor(readonly tempPath: string, readonly hardened = true, options?: ErrorOptions) {
+    super(`Atomic config write left a ${hardened ? "hardened " : ""}zero-byte temporary file`, options);
+    this.name = "AtomicWriteResidualTempError";
+  }
+}
+
+export class AtomicWriteSecretResidualError extends Error {
+  constructor(readonly tempPath: string, options?: ErrorOptions) {
+    super("Atomic config write could not scrub or remove a secret-bearing temporary file", options);
+    this.name = "AtomicWriteSecretResidualError";
+  }
+}
+
+/**
+ * Resolve a write target through any symlink before the temp+rename dance so
+ * dotfiles-managed links survive an atomic replacement.
+ */
+export function resolveWriteTarget(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch (cause) {
+    let entry;
+    try {
+      entry = lstatSync(path);
+    } catch (error) {
+      if (isMissingPathError(error)) return path;
+      throw error;
+    }
+    if (entry.isSymbolicLink()) {
+      throw new Error(`refusing to replace unresolvable symlinked write target: ${path}`, { cause });
+    }
+    return path;
+  }
+}
+
+function assertResolvedTargetAllowed(path: string, target: string): void {
+  if (target === path) {
+    let realParent: string;
+    try {
+      realParent = realpathSync(dirname(target));
+    } catch {
+      return;
+    }
+    if (realParent !== dirname(target)) assertNotRealHomeUnderTest(realParent);
+    return;
+  }
+  assertNotRealHomeUnderTest(dirname(target));
+}
+
+export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO = {
+  write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
+  harden: target => {
+    try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
+    if (process.platform === "win32") hardenSecretPath(target, { required: true, timeoutMemoKey: path });
+  },
+  rename: renameAtomicFile,
+  truncate: target => truncateSync(target, 0),
+  unlink: unlinkSync,
+}): void {
+  recordOwnedConfigPath(getConfigDir(), path);
+  const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
+  const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
+  let hardened = false;
+  try {
+    io.write(tmp, content);
+    io.harden(tmp);
+    hardened = true;
+    io.rename(tmp, target);
+    forgetEphemeralSecretPath(tmp);
+  } catch (cause) {
+    let scrubbed = false;
+    try {
+      io.truncate(tmp);
+      scrubbed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) scrubbed = true;
+      else {
+        try { io.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
+      }
+    }
+    let removed = false;
+    try {
+      io.unlink(tmp);
+      removed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) removed = true;
+      else {
+        try { io.unlink(tmp); removed = true; }
+        catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
+      }
+    }
+    if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
+    if (!removed && !hardened) {
+      try { io.harden(tmp); hardened = true; } catch { /* reported below */ }
+    }
+    if (removed) forgetEphemeralSecretPath(tmp);
+    if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
+    throw cause;
+  }
+}
+
+export interface AtomicWriteAsyncIO {
+  write: (path: string, content: string) => void | Promise<void>;
+  harden: (path: string) => void | Promise<void>;
+  rename: (source: string, destination: string) => void | Promise<void>;
+  truncate: (path: string) => void | Promise<void>;
+  unlink: (path: string) => void | Promise<void>;
+}
+
+export interface AtomicWriteAsyncTestSeam {
+  afterTempWrite?: (tempPath: string) => void | Promise<void>;
+}
+
+export async function atomicWriteFileAsync(
+  path: string,
+  content: string,
+  io?: AtomicWriteAsyncIO,
+  testSeam?: AtomicWriteAsyncTestSeam,
+): Promise<void> {
+  const effective: AtomicWriteAsyncIO = io ?? {
+    write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
+    harden: async target => {
+      try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
+      if (process.platform === "win32") {
+        await hardenSecretPathAsync(target, { required: true, timeoutMemoKey: path });
+      }
+    },
+    rename: renameAtomicFileAsync,
+    truncate: target => truncateSync(target, 0),
+    unlink: unlinkSync,
+  };
+  const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
+  const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
+  let hardened = false;
+  try {
+    await effective.write(tmp, content);
+    await testSeam?.afterTempWrite?.(tmp);
+    await effective.harden(tmp);
+    hardened = true;
+    await effective.rename(tmp, target);
+    forgetEphemeralSecretPath(tmp);
+  } catch (cause) {
+    let scrubbed = false;
+    try {
+      await effective.truncate(tmp);
+      scrubbed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) scrubbed = true;
+      else {
+        try { await effective.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
+      }
+    }
+    let removed = false;
+    try {
+      await effective.unlink(tmp);
+      removed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) removed = true;
+      else {
+        try { await effective.unlink(tmp); removed = true; }
+        catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
+      }
+    }
+    if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
+    if (!removed && !hardened) {
+      try { await effective.harden(tmp); hardened = true; } catch { /* reported below */ }
+    }
+    if (removed) forgetEphemeralSecretPath(tmp);
+    if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
+    throw cause;
+  }
+}

package/src/config/paths.ts

@@ -0,0 +1,40 @@
+import { chmodSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+
+/**
+ * Expand a leading `~` in user-supplied paths without interpreting shell
+ * variables or `~user` forms that belong to the caller's shell.
+ */
+export function expandUserPath(raw: string): string {
+  if (raw === "~") return homedir();
+  if (raw.startsWith("~/") || raw.startsWith("~\\")) return join(homedir(), raw.slice(2));
+  return raw;
+}
+let resolvedConfigDirCache: { raw: string | undefined; path: string } | null = null;
+
+export function getConfigDir(): string {
+  const raw = process.env["OPENCODEX_HOME"]?.trim() || undefined;
+  if (resolvedConfigDirCache && resolvedConfigDirCache.raw === raw) return resolvedConfigDirCache.path;
+  const path = raw ? resolve(expandUserPath(raw)) : join(homedir(), ".opencodex");
+  resolvedConfigDirCache = { raw, path };
+  return path;
+}
+
+export function getConfigPath(): string {
+  return join(getConfigDir(), "config.json");
+}
+
+export function hardenConfigDir(): void {
+  const dir = getConfigDir();
+  // The guard runs before any mutation: refusing after chmod/ACL would already
+  // have changed the protected directory used by the test-home boundary.
+  assertNotRealHomeUnderTest(dir);
+  if (!existsSync(dir)) return;
+  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  if (process.platform === "win32") {
+    hardenSecretDir(dir, { required: false });
+  }
+}