terramend 0.2.0

package/src/utils/codexHome.test.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { log } from "#app/utils/cli";
+import { installCodexAuth, TERRAMEND_DATA_DIR } from "#app/utils/codexHome";
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return { ...actual, mkdirSync: vi.fn(), writeFileSync: vi.fn() };
+});
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, execFileSync: vi.fn() };
+});
+
+const SAVED_XDG_DATA_HOME = process.env.XDG_DATA_HOME;
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const segment = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `header.${segment}.signature`;
+}
+
+function codexAuthJson(tokens: Record<string, unknown>): string {
+  return JSON.stringify({ auth_mode: "chatgpt", tokens });
+}
+
+function writtenAuthFile(): { path: unknown; content: Record<string, unknown>; mode: unknown } {
+  const call = vi.mocked(writeFileSync).mock.calls[0];
+  if (!call) throw new Error("expected writeFileSync to have been called");
+  return {
+    path: call[0],
+    content: JSON.parse(String(call[1])) as Record<string, unknown>,
+    mode: call[2],
+  };
+}
+
+beforeEach(() => {
+  vi.stubEnv("CI", "false");
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+  if (SAVED_XDG_DATA_HOME === undefined) delete process.env.XDG_DATA_HOME;
+  else process.env.XDG_DATA_HOME = SAVED_XDG_DATA_HOME;
+});
+
+describe("installCodexAuth", () => {
+  it("returns null without touching disk when CODEX_AUTH_JSON is absent", () => {
+    vi.stubEnv("CODEX_AUTH_JSON", undefined);
+
+    expect(installCodexAuth()).toBeNull();
+    expect(vi.mocked(writeFileSync)).not.toHaveBeenCalled();
+    expect(vi.mocked(mkdirSync)).not.toHaveBeenCalled();
+  });
+
+  it("returns null and warns when CODEX_AUTH_JSON is not valid JSON", () => {
+    const warning = vi.spyOn(log, "warning").mockImplementation(() => {});
+    vi.stubEnv("CODEX_AUTH_JSON", "{not json");
+
+    expect(installCodexAuth()).toBeNull();
+    expect(warning).toHaveBeenCalledWith(expect.stringContaining("CODEX_AUTH_JSON"));
+    expect(vi.mocked(writeFileSync)).not.toHaveBeenCalled();
+  });
+
+  it("returns null and warns on a wrong auth_mode shape", () => {
+    const warning = vi.spyOn(log, "warning").mockImplementation(() => {});
+    vi.stubEnv(
+      "CODEX_AUTH_JSON",
+      JSON.stringify({ auth_mode: "apikey", tokens: { access_token: "a", refresh_token: "r" } }),
+    );
+
+    expect(installCodexAuth()).toBeNull();
+    expect(warning).toHaveBeenCalledOnce();
+  });
+
+  it("materializes auth.json under $HOME locally and exports XDG_DATA_HOME", () => {
+    const exp = 1_893_456_000; // 2030-01-01T00:00:00Z
+    const accessToken = makeJwt({ exp });
+    vi.stubEnv(
+      "CODEX_AUTH_JSON",
+      codexAuthJson({ access_token: accessToken, refresh_token: "r-1", account_id: "acct-9" }),
+    );
+
+    const result = installCodexAuth();
+
+    const xdgDataHome = join(homedir(), ".local", "share");
+    const authPath = join(xdgDataHome, "opencode", "auth.json");
+    expect(result).toEqual({ authPath, xdgDataHome, originalRefresh: "r-1" });
+    // load-bearing: every opencode subprocess discovers the auth.json via env
+    expect(process.env.XDG_DATA_HOME).toBe(xdgDataHome);
+    expect(vi.mocked(mkdirSync)).toHaveBeenCalledWith(join(xdgDataHome, "opencode"), {
+      recursive: true,
+    });
+
+    const written = writtenAuthFile();
+    expect(written.path).toBe(authPath);
+    expect(written.mode).toEqual({ mode: 0o600 });
+    expect(written.content).toEqual({
+      openai: {
+        type: "oauth",
+        refresh: "r-1",
+        access: accessToken,
+        expires: exp * 1000,
+        accountId: "acct-9",
+      },
+    });
+  });
+
+  it("falls back to expires 0 when the access token is not a decodable JWT", () => {
+    vi.stubEnv(
+      "CODEX_AUTH_JSON",
+      codexAuthJson({ access_token: "opaque-token", refresh_token: "r-2" }),
+    );
+
+    const result = installCodexAuth();
+
+    expect(result).not.toBeNull();
+    const written = writtenAuthFile();
+    expect(written.content).toEqual({
+      openai: { type: "oauth", refresh: "r-2", access: "opaque-token", expires: 0 },
+    });
+  });
+
+  it("uses the sudo-bootstrapped terramend data dir in CI", () => {
+    vi.stubEnv("CI", "true");
+    vi.stubEnv("CODEX_AUTH_JSON", codexAuthJson({ access_token: "a", refresh_token: "r-3" }));
+    vi.mocked(execFileSync).mockImplementation(((cmd: string) =>
+      cmd === "id" ? "runners\n" : "") as typeof execFileSync);
+
+    const result = installCodexAuth();
+
+    expect(result).toEqual({
+      authPath: join(TERRAMEND_DATA_DIR, "opencode", "auth.json"),
+      xdgDataHome: TERRAMEND_DATA_DIR,
+      originalRefresh: "r-3",
+    });
+    expect(process.env.XDG_DATA_HOME).toBe(TERRAMEND_DATA_DIR);
+    const user = userInfo().username;
+    expect(vi.mocked(execFileSync)).toHaveBeenCalledWith(
+      "sudo",
+      ["-n", "chown", `${user}:runners`, TERRAMEND_DATA_DIR],
+      { stdio: "pipe" },
+    );
+  });
+
+  it("falls back to the username as group when `id -gn` fails", () => {
+    vi.stubEnv("CI", "true");
+    vi.stubEnv("CODEX_AUTH_JSON", codexAuthJson({ access_token: "a", refresh_token: "r-4" }));
+    vi.mocked(execFileSync).mockImplementation(((cmd: string) => {
+      if (cmd === "id") throw new Error("id: command not found");
+      return "";
+    }) as typeof execFileSync);
+
+    expect(installCodexAuth()).not.toBeNull();
+
+    const user = userInfo().username;
+    expect(vi.mocked(execFileSync)).toHaveBeenCalledWith(
+      "sudo",
+      ["-n", "chown", `${user}:${user}`, TERRAMEND_DATA_DIR],
+      { stdio: "pipe" },
+    );
+  });
+
+  it("fails closed in CI when the sudo bootstrap is unavailable", () => {
+    vi.stubEnv("CI", "true");
+    vi.stubEnv("CODEX_AUTH_JSON", codexAuthJson({ access_token: "a", refresh_token: "r-5" }));
+    vi.mocked(execFileSync).mockImplementation((() => {
+      throw new Error("sudo: a password is required");
+    }) as typeof execFileSync);
+
+    expect(() => installCodexAuth()).toThrow(/failed to bootstrap .*terramend/);
+    expect(vi.mocked(writeFileSync)).not.toHaveBeenCalled();
+  });
+
+  it("stringifies non-Error bootstrap failures into the fail-closed message", () => {
+    vi.stubEnv("CI", "true");
+    vi.stubEnv("CODEX_AUTH_JSON", codexAuthJson({ access_token: "a", refresh_token: "r-6" }));
+    vi.mocked(execFileSync).mockImplementation((() => {
+      // eslint-style non-Error throw — exercises the String(err) fallback
+      throw "sudo denied";
+    }) as typeof execFileSync);
+
+    expect(() => installCodexAuth()).toThrow(/sudo denied/);
+  });
+});

package/src/utils/codexHome.ts

@@ -0,0 +1,191 @@
+// Codex-to-OpenCode auth bridging for the action runtime.
+//
+// `CODEX_AUTH_JSON` (a Codex CLI `auth.json` blob) is read from the environment
+// — supplied directly as a GitHub Actions secret or workflow `env:` value. The
+// hosted per-org secret store + `dbSecrets` delivery + server-side rotation
+// (`maybeRotateCodexSecret`) were removed with the rest of the managed backend,
+// so the standalone fork reads the env value verbatim.
+//
+// Caveat (GH Actions secrets are immutable at runtime): the OAuth refresh chain
+// rotates on use, so a token stashed as a static secret expires on its first
+// refresh (~1h). Codex auth is therefore best for short runs; longer runs rely
+// on OpenCode's in-process CodexAuthPlugin to refresh mid-run. `entryPost.ts`
+// still detects a mid-run rotation, but its hosted write-back is now a no-op
+// without a backend to persist to. See wiki/codex-auth.md.
+//
+// This utility then:
+//   1. parses + validates the env value
+//   2. decodes the access_token JWT's `exp` claim so opencode knows how
+//      long to trust the token before its CodexAuthPlugin attempts its
+//      own mid-run refresh
+//   3. converts Codex's shape `{ auth_mode, tokens: { access_token,
+//      refresh_token, id_token?, account_id? } }` into OpenCode's shape
+//      `{ openai: { type: "oauth", refresh, access, expires, accountId } }`
+//   4. materializes it to disk under a path the MCP-shell mount-namespace
+//      sandbox can hide from bash: `/var/lib/terramend/opencode/auth.json` in
+//      CI (sudo-bootstrapped, fail-closed if sudo unavailable),
+//      `$HOME/.local/share/opencode/auth.json` locally (sandbox is no-op
+//      locally so the path is irrelevant to security)
+//   5. returns the path + the original refresh token so the post-run hook
+//      can detect a mid-run rotation and write back to Terramend
+//
+// Why `/var/lib/terramend/` and not `$HOME` in CI: bash via MCP runs inside a
+// mount namespace that overlays tmpfs on `/var/lib/terramend/` (see FS_MOUNTS
+// in action/mcp/shell.ts), so bash sees an empty dir while opencode's
+// internal auth module — which runs in the agent process outside that
+// namespace — reads/writes the real file. `$HOME` can't be tmpfs-overlaid
+// without breaking the agent's legitimate need to access ~/.npm, ~/.cache,
+// etc.
+//
+// See [wiki/codex-auth.md] for the full data-flow picture.
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { log } from "#app/utils/cli";
+import { decodeJwtExpMs, parseCodexAuthBody } from "#app/utils/codexOAuth";
+
+const CODEX_AUTH_ENV = "CODEX_AUTH_JSON";
+
+/** sandbox-hidden home for terramend-managed on-disk secrets in CI. bash via
+ * MCP shell tmpfs-overlays this path; opencode's internal auth module
+ * bypasses external_directory and reaches the real file. mirrors the
+ * pattern in action/agents/claude.ts installManagedSettings.
+ *
+ * not used for codex auth in local dev — the sandbox is no-op there, so
+ * the path doesn't matter. local dev keeps the existing $HOME path. */
+export const TERRAMEND_DATA_DIR = "/var/lib/terramend";
+
+interface OpenCodeAuthFile {
+  openai: {
+    type: "oauth";
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+  };
+}
+
+export interface InstalledCodexAuth {
+  /** absolute path of the auth.json we wrote — caller passes this to the
+   * post-hook via core.saveState for refresh-detection later. */
+  authPath: string;
+  /** value to set as XDG_DATA_HOME for the OpenCode subprocess. */
+  xdgDataHome: string;
+  /** refresh_token from the env at materialization time. post-hook
+   * compares against the on-disk file after the run to detect whether
+   * OpenCode refreshed during the session (only happens on long runs
+   * that span >50min — see wiki/codex-auth.md "Concurrency"). */
+  originalRefresh: string;
+}
+
+/** materialize CODEX_AUTH_JSON from env into a disk path OpenCode reads from.
+ * returns null when the env var is absent, malformed, or wrong auth mode —
+ * caller treats null as "no codex auth, fall through to API key flow".
+ *
+ * The env value is read as-is — we parse + write it here and set
+ * `process.env.XDG_DATA_HOME` so every opencode subprocess discovers the
+ * auth.json; no refresh and no DB interaction. Freshness is the supplier's
+ * responsibility (see the header caveat on static-secret expiry). */
+export function installCodexAuth(): InstalledCodexAuth | null {
+  const raw = process.env[CODEX_AUTH_ENV];
+  if (!raw) return null;
+
+  const body = parseCodexAuthBody(raw);
+  if (!body) {
+    log.warning(`» ${CODEX_AUTH_ENV} present but malformed; ignoring`);
+    return null;
+  }
+
+  // decode the access_token's JWT exp so opencode trusts the token until
+  // its real expiry (no need to refresh on first request). null exp ->
+  // fall back to "expires: 0" so opencode refreshes immediately on first
+  // request (the old behavior).
+  const expiresMs = decodeJwtExpMs(body.tokens.access_token) ?? 0;
+
+  const xdgDataHome = resolveDataHome();
+  const opencodeDir = join(xdgDataHome, "opencode");
+  const authPath = join(opencodeDir, "auth.json");
+
+  const opencodeAuth: OpenCodeAuthFile = {
+    openai: {
+      type: "oauth",
+      refresh: body.tokens.refresh_token,
+      access: body.tokens.access_token,
+      expires: expiresMs,
+      ...(body.tokens.account_id ? { accountId: body.tokens.account_id } : {}),
+    },
+  };
+
+  mkdirSync(opencodeDir, { recursive: true });
+  writeFileSync(authPath, `${JSON.stringify(opencodeAuth, null, 2)}\n`, { mode: 0o600 });
+
+  // point every opencode subprocess in this run (agent spawn + `opencode
+  // models` introspection) at this auth.json. only opencode reads
+  // XDG_DATA_HOME and this only fires on codex runs, so the blast radius is
+  // exactly the subprocesses that must discover the OAuth-routed openai/* models.
+  process.env.XDG_DATA_HOME = xdgDataHome;
+
+  log.info(`» installed Codex auth at ${authPath}`);
+
+  return {
+    authPath,
+    xdgDataHome,
+    originalRefresh: body.tokens.refresh_token,
+  };
+}
+
+/** pick the XDG_DATA_HOME for codex auth.
+ *
+ * - **local dev (CI != true)**: use $HOME. mount-namespace sandbox is no-op
+ *   locally so the file isn't protected from bash either way; codex auth on
+ *   a developer's machine is the developer's responsibility.
+ * - **CI**: bootstrap /var/lib/terramend via sudo. MCP shell's mount namespace
+ *   tmpfs-overlays this path, and claude managed-settings + opencode
+ *   external_directory both deny it — three independent layers.
+ *
+ * **fail closed in CI** when the sudo bootstrap fails. falling back to
+ * $HOME silently strips two of the three protection layers — the wiki
+ * claims three layers; degrading to one without a hard error contradicts
+ * that claim and is exactly the kind of silent security regression the
+ * reviewer should never have to catch. operators on locked-down runners
+ * that can't passwordless-sudo should re-provision sudo or remove
+ * `CODEX_AUTH_JSON` from the run entirely. */
+function resolveDataHome(): string {
+  if (process.env.CI !== "true") return join(homedir(), ".local", "share");
+  bootstrapTerramendDataDir();
+  return TERRAMEND_DATA_DIR;
+}
+
+function bootstrapTerramendDataDir(): void {
+  const user = userInfo().username;
+  // `id -gn $user` resolves the user's primary group name correctly even on
+  // self-hosted images where the group isn't `<user>:<user>` (e.g., `runner`
+  // belongs to `runner`, but a self-hosted setup might use `users`, `docker`,
+  // or a project-specific gid). avoids the brittle "group has same name as
+  // user" assumption.
+  let primaryGroup: string;
+  try {
+    primaryGroup = execFileSync("id", ["-gn", user], { stdio: "pipe", encoding: "utf-8" }).trim();
+  } catch {
+    primaryGroup = user;
+  }
+  // `-n` (non-interactive) makes sudo fail-fast on locked-down runners
+  // instead of prompting and timing out.
+  try {
+    execFileSync("sudo", ["-n", "mkdir", "-p", TERRAMEND_DATA_DIR], { stdio: "pipe" });
+    execFileSync("sudo", ["-n", "chown", `${user}:${primaryGroup}`, TERRAMEND_DATA_DIR], {
+      stdio: "pipe",
+    });
+    execFileSync("sudo", ["-n", "chmod", "700", TERRAMEND_DATA_DIR], { stdio: "pipe" });
+  } catch (err) {
+    throw new Error(
+      `failed to bootstrap ${TERRAMEND_DATA_DIR} (required for codex auth in CI): ${err instanceof Error ? err.message : String(err)}. ` +
+        `the MCP shell's mount-namespace sandbox cannot protect the auth file when it lives under $HOME, ` +
+        `and silently falling back would contradict the "three independent layers" claim in wiki/codex-auth.md. ` +
+        `passwordless sudo is required for codex auth on this runner — either configure it, or remove ` +
+        `CODEX_AUTH_JSON from the run.`,
+    );
+  }
+}

package/src/utils/codexOAuth.ts

@@ -0,0 +1,147 @@
+/**
+ * Pure-stdlib (fetch + Buffer) Codex OAuth refresh + JWT exp decoding.
+ *
+ * Lives here (not in codexAuth.ts) so the Next.js server side can import it
+ * via terramend/internal without dragging in node:child_process / spawn /
+ * mkdtemp from the rest of codexAuth.ts. Used by:
+ *   - action/utils/codexAuth.ts (re-exports refreshCodexAuthBody)
+ *   - utils/codexSecretRotation.ts (server-side maybeRotate at run-context)
+ *
+ * See wiki/codex-auth.md for the end-to-end refresh lifecycle.
+ */
+
+export interface CodexAuthBody {
+  auth_mode: "chatgpt";
+  tokens: {
+    access_token: string;
+    refresh_token: string;
+    id_token?: string;
+    account_id?: string;
+  };
+  last_refresh?: string;
+}
+
+/** OAuth client id Codex CLI and OpenCode both use against `auth.openai.com`.
+ * Same chain — a refresh token minted via `codex login --device-auth` can be
+ * refreshed against this client_id. */
+export const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+
+interface OAuthTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  id_token?: string;
+  expires_in?: number;
+}
+
+/** thrown when the OAuth provider rejects the refresh token (4xx). callers
+ * can distinguish "race-lost / token revoked" from network errors via
+ * `instanceof OAuthInvalidGrantError`. */
+export class OAuthInvalidGrantError extends Error {
+  public readonly status: number;
+  constructor(status: number, body: string) {
+    super(`Codex token refresh failed: ${status} ${body}`);
+    this.name = "OAuthInvalidGrantError";
+    this.status = status;
+  }
+}
+
+/** force one refresh round-trip against the OAuth provider. returns the
+ * rotated Codex-shaped blob (the auth.json body verbatim). does NOT persist
+ * — caller is responsible for writing back to wherever the token lives.
+ *
+ * server-side callers (maybeRotateCodexSecret) hold a DB row lock around
+ * this call so concurrent runs serialize: first one rotates, subsequent
+ * ones see the fresh value and skip. The 10s timeout is critical for that
+ * use: it caps how long a stalled auth.openai.com holds the row lock,
+ * keeping us well under the enclosing 30s transaction budget so the lock
+ * always releases and queued callers get a turn instead of timing out on
+ * the tx wrapper. Real OAuth latency is sub-second; 10s is generous. */
+export async function refreshCodexAuthBody(body: CodexAuthBody): Promise<CodexAuthBody> {
+  const response = await fetch(CODEX_OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: body.tokens.refresh_token,
+      client_id: CODEX_OAUTH_CLIENT_ID,
+    }).toString(),
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    if (response.status >= 400 && response.status < 500) {
+      throw new OAuthInvalidGrantError(response.status, text);
+    }
+    throw new Error(`Codex token refresh failed: ${response.status} ${text}`);
+  }
+  const tokens = (await response.json()) as OAuthTokenResponse;
+  const idToken = tokens.id_token ?? body.tokens.id_token;
+  const accountId = body.tokens.account_id;
+  return {
+    auth_mode: "chatgpt",
+    tokens: {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      ...(idToken ? { id_token: idToken } : {}),
+      ...(accountId ? { account_id: accountId } : {}),
+    },
+    last_refresh: new Date().toISOString(),
+  };
+}
+
+/** decode the access_token's JWT payload and return its `exp` claim in ms
+ * since epoch. returns null if the token isn't a parseable JWT or has no
+ * `exp` claim — caller falls back to "treat as expired".
+ *
+ * We don't verify the JWT signature (we'd need OpenAI's JWKS); we're only
+ * using the claim as a freshness hint. The actual auth check happens
+ * server-side at OpenAI when the token is used — trusting a fake JWT here
+ * would just delay the inevitable 401 from OpenAI. No security boundary
+ * at this decode step. */
+export function decodeJwtExpMs(token: string): number | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  let payload: { exp?: unknown };
+  try {
+    payload = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) return null;
+  return payload.exp * 1000;
+}
+
+/** parse + validate a Codex auth.json body from its JSON-string form.
+ * returns null on any shape mismatch — caller treats as "no codex auth". */
+export function parseCodexAuthBody(raw: string): CodexAuthBody | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const v = parsed as Record<string, unknown>;
+  if (v.auth_mode !== "chatgpt") return null;
+  const tokens = v.tokens;
+  if (!tokens || typeof tokens !== "object") return null;
+  const t = tokens as Record<string, unknown>;
+  if (typeof t.access_token !== "string" || t.access_token.length === 0) return null;
+  if (typeof t.refresh_token !== "string" || t.refresh_token.length === 0) return null;
+  return {
+    auth_mode: "chatgpt",
+    tokens: {
+      access_token: t.access_token,
+      refresh_token: t.refresh_token,
+      ...(typeof t.id_token === "string" ? { id_token: t.id_token } : {}),
+      ...(typeof t.account_id === "string" ? { account_id: t.account_id } : {}),
+    },
+    ...(typeof v.last_refresh === "string" ? { last_refresh: v.last_refresh } : {}),
+  };
+}
+
+/** serialize a CodexAuthBody to its canonical on-disk form. */
+export function stringifyCodexAuthBody(body: CodexAuthBody): string {
+  return `${JSON.stringify(body, null, 2)}\n`;
+}

package/src/utils/codexRefreshDetect.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { detectCodexRefresh } from "#app/utils/codexRefreshDetect";
+
+// installCodexAuth touches the filesystem (mkdir + writeFile) — leaving it
+// untested here per AGENTS.md guidance ("be highly dubious of any test that
+// relies on mocks"). The conversion math is what we actually want to
+// protect; the disk write is one writeFileSync call.
+
+describe("detectCodexRefresh", () => {
+  const original = "rt_original_chain";
+
+  it("returns Codex-shape JSON when openai.refresh advanced", () => {
+    const authFileContent = JSON.stringify({
+      openai: {
+        type: "oauth",
+        refresh: "rt_new_chain",
+        access: "at_new",
+        expires: 9_999_999_999_999,
+        accountId: "acc_123",
+      },
+    });
+    const result = detectCodexRefresh({ authFileContent, originalRefresh: original });
+    expect(result).not.toBeNull();
+    const parsed = JSON.parse(result ?? "{}");
+    expect(parsed.auth_mode).toBe("chatgpt");
+    expect(parsed.tokens.refresh_token).toBe("rt_new_chain");
+    expect(parsed.tokens.access_token).toBe("at_new");
+    expect(parsed.tokens.account_id).toBe("acc_123");
+    expect(typeof parsed.last_refresh).toBe("string");
+  });
+
+  it("omits account_id when accountId is absent from OpenCode shape", () => {
+    const authFileContent = JSON.stringify({
+      openai: {
+        type: "oauth",
+        refresh: "rt_new",
+        access: "at_new",
+        expires: 0,
+      },
+    });
+    const result = detectCodexRefresh({ authFileContent, originalRefresh: original });
+    const parsed = JSON.parse(result ?? "{}");
+    expect("account_id" in parsed.tokens).toBe(false);
+  });
+
+  it("returns null when refresh token unchanged (no rotation happened)", () => {
+    const authFileContent = JSON.stringify({
+      openai: { type: "oauth", refresh: original, access: "at_same", expires: 0 },
+    });
+    expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
+  });
+
+  it("returns null when openai entry is missing", () => {
+    const authFileContent = JSON.stringify({
+      anthropic: { type: "oauth", refresh: "rt_other", access: "at_other", expires: 0 },
+    });
+    expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
+  });
+
+  it("returns null when openai is api-key type (no refresh chain)", () => {
+    const authFileContent = JSON.stringify({
+      openai: { type: "api", key: "sk-something" },
+    });
+    expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
+  });
+
+  it("returns null for malformed JSON", () => {
+    expect(
+      detectCodexRefresh({ authFileContent: "{not json", originalRefresh: original }),
+    ).toBeNull();
+  });
+
+  it("returns null for non-object content", () => {
+    expect(
+      detectCodexRefresh({ authFileContent: '"a string"', originalRefresh: original }),
+    ).toBeNull();
+  });
+
+  it("returns null when refresh field is missing", () => {
+    const authFileContent = JSON.stringify({
+      openai: { type: "oauth", access: "at_new", expires: 0 },
+    });
+    expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
+  });
+});

package/src/utils/codexRefreshDetect.ts

@@ -0,0 +1,35 @@
+/** Convert an on-disk OpenCode auth.json back to the Codex CLI shape so the
+ * post-hook can write it to the Terramend secret store. Returns null when the
+ * file's `openai` entry is missing, has the wrong type, or hasn't actually
+ * refreshed (refresh token unchanged from `originalRefresh`). Lives in its
+ * own module so `entryPost.ts` can import it without pulling in `codexHome.ts`
+ * (which imports `./cli.ts` and node fs helpers). */
+export function detectCodexRefresh(params: {
+  authFileContent: string;
+  originalRefresh: string;
+}): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(params.authFileContent);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const oauth = (parsed as Record<string, unknown>).openai;
+  if (!oauth || typeof oauth !== "object") return null;
+  const o = oauth as Record<string, unknown>;
+  if (o.type !== "oauth") return null;
+  if (typeof o.refresh !== "string" || typeof o.access !== "string") return null;
+  if (o.refresh === params.originalRefresh) return null;
+
+  const codexShape = {
+    auth_mode: "chatgpt",
+    tokens: {
+      access_token: o.access,
+      refresh_token: o.refresh,
+      ...(typeof o.accountId === "string" ? { account_id: o.accountId } : {}),
+    },
+    last_refresh: new Date().toISOString(),
+  };
+  return `${JSON.stringify(codexShape, null, 2)}\n`;
+}