refactor(auth): extract shared provider auth helpers (C1-C7)

~250 lines of near-identical callback/login/session/store/lock twins
across codex and xai collapse onto seven shared helpers, each taking a
small provider spec of explicit hooks. Deliberate provider differences
stay hooks, not knobs: the codex inter-process refresh lock is a
serializeRefresh hook (xai has none by design), accountId merge and
token expiry stay per-provider, the divergent stale horizons carry
must-not-unify comments, and exact-code vs substring error matching is
untouched. Lock contention still never surfaces as credential_failure.

One deliberate delta: the unified file lock propagates non-ENOENT fs
errors where the codex refresh lock used to swallow every fs error;
the store contract was the stronger one. The propagation is pinned at
both levels — this suite exercises the refresh path and file-lock.test
pins the primitive.

Author: TheGreatAxios

src/auth/bearer-headers.ts

@@ -0,0 +1,12 @@
+export interface BearerToken {
+  readonly access: string;
+}
+
+// The one header every provider carries on an inference request; provider
+// extras (account ids, client identifiers) ride alongside via the spread.
+export function bearerHeaders(
+  token: BearerToken,
+  extra: Record<string, string> = {},
+): Record<string, string> {
+  return { authorization: `Bearer ${token.access}`, ...extra };
+}

src/auth/codex/auth-headers.ts

@@ -1,3 +1,4 @@
+import { bearerHeaders } from "../bearer-headers.js";
 import { CODEX_CLIENT_VERSION, CODEX_ORIGINATOR } from "./constants.js";
 
 export function codexAuthHeadersForToken(
@@ -7,11 +8,10 @@ export function codexAuthHeadersForToken(
   },
   commandName: string,
 ): Record<string, string> {
-  const headers: Record<string, string> = {
-    authorization: `Bearer ${token.access}`,
+  const headers = bearerHeaders(token, {
     originator: CODEX_ORIGINATOR,
     "user-agent": `${commandName} (${CODEX_ORIGINATOR}/${CODEX_CLIENT_VERSION})`,
-  };
+  });
   // An empty account id carries no identity — sending it as a header value
   // would label the request with a meaningless id. Only a non-empty id rides.
   if (token.accountId) headers["chatgpt-account-id"] = token.accountId;

src/auth/codex/callback-server.ts

@@ -1,10 +1,9 @@
-import { startCallbackServer, type CallbackServer } from "@corbits/oauth-core";
-
 import {
-  authorizationDoneHtml,
-  callbackPageHtml,
-  type CallbackPageCopy,
-} from "../callback-page.js";
+  startProviderCallbackServer,
+  type CallbackServer,
+} from "../provider-callback-server.js";
+
+import type { CallbackPageCopy } from "../callback-page.js";
 import {
   CODEX_CALLBACK_HOST,
   CODEX_CALLBACK_PATH,
@@ -19,13 +18,15 @@ export async function startCodexCallbackServer(
   expectedState: string,
   copy: CallbackPageCopy,
 ): Promise<CodexCallbackServer> {
-  return startCallbackServer(expectedState, {
-    port: CODEX_CALLBACK_PORT,
-    // Codex's registered redirect_uri uses localhost (not 127.0.0.1).
-    host: CODEX_CALLBACK_HOST,
-    path: CODEX_CALLBACK_PATH,
-    doneHtml: authorizationDoneHtml("Codex", copy),
-    failedHtml: (reason) =>
-      callbackPageHtml({ subject: "Codex", error: reason }, copy),
-  });
+  return startProviderCallbackServer(
+    "Codex",
+    {
+      port: CODEX_CALLBACK_PORT,
+      // Codex's registered redirect_uri uses localhost (not 127.0.0.1).
+      host: CODEX_CALLBACK_HOST,
+      path: CODEX_CALLBACK_PATH,
+    },
+    expectedState,
+    copy,
+  );
 }

src/auth/codex/login.ts

@@ -1,15 +1,14 @@
 import {
-  buildAuthorizeUrl,
+  exchangeCodexCode,
+  codexOAuthConfig,
+  type CodexTokens,
+} from "@corbits/codex-provider";
+import {
   openInBrowser,
-  startOAuthLogin,
   type OAuthLoginHandle,
   type StartOAuthLoginOptions,
 } from "@corbits/oauth-core";
-import {
-  codexOAuthConfig,
-  exchangeCodexCode,
-  type CodexTokens,
-} from "@corbits/codex-provider";
+import { startProviderLogin } from "../provider-login.js";
 
 import type { CallbackPageCopy } from "../callback-page.js";
 import { saveCodexProfile } from "../../config/oauth-stores.js";
@@ -28,10 +27,10 @@ export async function startCodexLogin(
   opts: StartCodexLoginOptions,
 ): Promise<CodexLoginHandle> {
   const { home, copy, ...loginOpts } = opts;
-  return startOAuthLogin(loginOpts, {
+  return startProviderLogin<CodexTokens>(loginOpts, {
+    oauthConfig: codexOAuthConfig,
     startCallbackServer: (state) => startCodexCallbackServer(state, copy),
-    buildAuthorizeUrl: (pkce, state) =>
-      buildAuthorizeUrl(codexOAuthConfig, pkce, state),
+    // The mapper leaves expiresAt unset when the response omits expires_in.
     exchangeCode: async (code, verifier, now) =>
       withDefaultCodexExpiry(await exchangeCodexCode(code, verifier, now), now),
     saveProfile: (profile) => saveCodexProfile(profile, home),

src/auth/codex/refresh-lock.test.ts

@@ -9,10 +9,36 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, test } from "bun:test";
-import {
-  CodexRefreshLockTimeoutError,
-  withCodexRefreshLock,
-} from "./refresh-lock.js";
+import { CodexRefreshLockTimeoutError } from "./refresh-lock.js";
+
+import { withMockedModule } from "../../../testkit/mock-module.js";
+
+// Non-ENOENT lock-file failures must surface raw instead of being swallowed
+// (the pre-unification codex lock caught every fs error). Flags gate each
+// failure to its own test; undefined keeps every call on the real module.
+let failingReadPath: string | undefined;
+let failingStatPath: string | undefined;
+let failingUnlinkPath: string | undefined;
+await withMockedModule(
+  import.meta.resolve("node:fs/promises"),
+  (real: typeof import("node:fs/promises")) => ({
+    ...real,
+    readFile: async (...args: Parameters<typeof real.readFile>) => {
+      if (args[0] === failingReadPath) throw new Error("lock read failed");
+      return real.readFile(...args);
+    },
+    stat: async (...args: Parameters<typeof real.stat>) => {
+      if (args[0] === failingStatPath) throw new Error("lock stat failed");
+      return real.stat(...args);
+    },
+    unlink: async (...args: Parameters<typeof real.unlink>) => {
+      if (args[0] === failingUnlinkPath) throw new Error("lock release failed");
+      return real.unlink(...args);
+    },
+  }),
+);
+
+const { withCodexRefreshLock } = await import("./refresh-lock.js");
 
 async function tempDir(): Promise<string> {
   return mkdtemp(join(tmpdir(), "cl8628-lock-"));
@@ -214,4 +240,77 @@ describe("codex refresh lock", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("a non-ENOENT read failure while contending propagates raw", async () => {
+    const dir = await tempDir();
+    try {
+      const lock = join(dir, "refresh.lock");
+      await writeFile(lock, "");
+      failingReadPath = lock;
+      try {
+        // The unified lock re-reads the holder content while contending; a
+        // permission/disk failure there must surface, not read as "no lock".
+        await expect(
+          withCodexRefreshLock(lock, async () => "never", {
+            timeoutMs: 1_000,
+            retryMs: 10,
+          }),
+        ).rejects.toThrow("lock read failed");
+      } finally {
+        failingReadPath = undefined;
+      }
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a non-ENOENT stat failure while deciding staleness propagates raw", async () => {
+    const dir = await tempDir();
+    try {
+      const lock = join(dir, "refresh.lock");
+      // Untagged content routes the staleness decision through mtime stat;
+      // a non-ENOENT stat failure must surface, not read as "not stale".
+      await writeFile(lock, "");
+      failingStatPath = lock;
+      try {
+        await expect(
+          withCodexRefreshLock(lock, async () => "never", {
+            timeoutMs: 1_000,
+            retryMs: 10,
+          }),
+        ).rejects.toThrow("lock stat failed");
+      } finally {
+        failingStatPath = undefined;
+      }
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a non-ENOENT release failure surfaces after the work value", async () => {
+    const dir = await tempDir();
+    try {
+      const lock = join(dir, "refresh.lock");
+      failingUnlinkPath = lock;
+      try {
+        // The refresh succeeded, but a release that fails for a real reason
+        // (not a steal's ENOENT) must not vanish: the caller has to know the
+        // lock file is still on disk.
+        await expect(
+          withCodexRefreshLock(lock, async () => "done", {
+            timeoutMs: 1_000,
+            retryMs: 10,
+          }),
+        ).rejects.toThrow("lock release failed");
+        // The failed release leaves the claim file in place for recovery.
+        await expect(readFile(lock, "utf8")).resolves.toContain(
+          String(process.pid),
+        );
+      } finally {
+        failingUnlinkPath = undefined;
+      }
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });