mercuria 0.2.0 → 0.3.0

package/README.md

@@ -6,6 +6,7 @@ Mercuria is a world engine: a minimal static shell, a low-friction Node harness,
 
 - `mercuria build` compacts an NHFN-style range into a smaller world file for the static app.
 - `mercuria harness` serves the app and exposes a local API and event stream from one VPS-friendly process.
+- the harness includes a manual-paste OpenAI OAuth flow for staff login on a headless VPS
 - `app/` is the static Netlify shell.
 - `src/harness.mjs` is the embeddable runtime surface exported by the package.
 
@@ -30,6 +31,18 @@ mercuria build \
 - `mercuria harness`
 - `mercuria serve`
 - `mercuria command "show food gaps"`
+- `npm run verify:live`
+- `npm run capture:live`
+
+## Staff login
+
+Mercuria follows the VPS-safe manual paste flow:
+
+1. Click `Begin OpenAI sign-in`.
+2. Sign in with OpenAI in the browser.
+3. Copy the full redirect URL.
+4. Paste it back into the Mercuria staff panel.
+5. Complete the exchange on the harness.
 
 ## Deploy
 

package/app/app.js

@@ -1,5 +1,6 @@
 const API_HEALTH_PATH = "./api/health";
 const STATIC_WORLD_PATH = "./data/world.json";
+const SESSION_STORAGE_KEY = "mercuria-session-token";
 const BOUNDS = {
   west: -141,
   east: -52,
@@ -13,14 +14,35 @@ const state = {
   focusId: null,
   filterIds: [],
   regionCode: null,
-  thread: []
+  thread: [],
+  auth: {
+    available: false,
+    loggedIn: false,
+    session: null,
+    panelOpen: false,
+    flow: null,
+    error: ""
+  }
 };
 
 const refs = {
   shell: document.querySelector(".app-shell"),
   worldCaption: document.getElementById("world-caption"),
   presence: document.getElementById("presence-pill"),
+  identityButton: document.getElementById("identity-button"),
+  identityPill: document.getElementById("identity-pill"),
   surfaceDeck: document.getElementById("surface-deck"),
+  authPanel: document.getElementById("auth-panel"),
+  authPanelMeta: document.getElementById("auth-panel-meta"),
+  authCopy: document.getElementById("auth-copy"),
+  authStatusLine: document.getElementById("auth-status-line"),
+  authLink: document.getElementById("auth-link"),
+  authFlowMeta: document.getElementById("auth-flow-meta"),
+  authPaste: document.getElementById("auth-paste"),
+  authBegin: document.getElementById("auth-begin"),
+  authRefresh: document.getElementById("auth-refresh"),
+  authLogout: document.getElementById("auth-logout"),
+  authFinish: document.getElementById("auth-finish"),
   regionStrip: document.getElementById("region-strip"),
   focusStat: document.getElementById("focus-stat"),
   signalStat: document.getElementById("signal-stat"),
@@ -50,6 +72,41 @@ let familyMap = new Map();
 let communityMap = new Map();
 let resizeFrame = null;
 
+function readSessionToken() {
+  try {
+    return window.localStorage.getItem(SESSION_STORAGE_KEY) || "";
+  } catch {
+    return "";
+  }
+}
+
+function writeSessionToken(token) {
+  try {
+    if (token) window.localStorage.setItem(SESSION_STORAGE_KEY, token);
+    else window.localStorage.removeItem(SESSION_STORAGE_KEY);
+  } catch {}
+}
+
+function sessionHeaders(initial = {}) {
+  const headers = new Headers(initial);
+  const token = readSessionToken();
+  if (token) headers.set("X-Mercuria-Session", token);
+  return headers;
+}
+
+async function fetchApiJson(url, options = {}) {
+  const response = await fetch(url, {
+    cache: "no-store",
+    ...options,
+    headers: sessionHeaders(options.headers || {})
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(payload.error || `API request failed: ${response.status}`);
+  }
+  return payload;
+}
+
 function normalize(value) {
   return String(value || "")
     .toLowerCase()
@@ -131,11 +188,14 @@ async function maybeFetchApiMode() {
 async function loadWorld() {
   state.apiMode = await maybeFetchApiMode();
   const worldUrl = state.apiMode ? "./api/world" : STATIC_WORLD_PATH;
-  const response = await fetch(worldUrl, { cache: "no-store" });
-  if (!response.ok) {
-    throw new Error(`Could not load world file from ${worldUrl}`);
-  }
-  state.world = await response.json();
+  state.world = state.apiMode
+    ? await fetchApiJson(worldUrl)
+    : await fetch(worldUrl, { cache: "no-store" }).then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Could not load world file from ${worldUrl}`);
+        }
+        return response.json();
+      });
   buildCollections();
   state.filterIds = state.world.communities.map((community) => community.id);
   state.focusId = state.world.hotlist.signalLeaders[0] || state.world.communities[0]?.id || null;
@@ -144,6 +204,33 @@ async function loadWorld() {
     "Mercuria online",
     `${state.world.meta.range} loaded with ${state.world.meta.counts.communities} communities and ${state.world.meta.counts.programs} programs.`
   );
+  await refreshAuthStatus();
+}
+
+async function refreshAuthStatus() {
+  if (!state.apiMode) {
+    state.auth.available = false;
+    state.auth.loggedIn = false;
+    state.auth.session = null;
+    state.auth.error = "";
+    return;
+  }
+
+  try {
+    const payload = await fetchApiJson("./api/auth/status");
+    state.auth.available = Boolean(payload.available);
+    state.auth.loggedIn = Boolean(payload.loggedIn);
+    state.auth.session = payload.session || null;
+    state.auth.error = "";
+    if (!payload.loggedIn) {
+      writeSessionToken("");
+    }
+  } catch (error) {
+    state.auth.available = false;
+    state.auth.loggedIn = false;
+    state.auth.session = null;
+    state.auth.error = error.message;
+  }
 }
 
 function runLocalCommand(input) {
@@ -319,18 +406,97 @@ function runLocalCommand(input) {
 }
 
 async function issueCommand(input) {
-  const payload = state.apiMode
-    ? await fetch("./api/command", {
+  try {
+    const payload = state.apiMode
+      ? await fetchApiJson("./api/command", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ input })
+        })
+      : runLocalCommand(input);
+
+    state.filterIds = payload.filterIds || payload.state?.filterIds || state.filterIds;
+    state.focusId = payload.focusId || payload.state?.focusId || state.focusId;
+    state.regionCode = payload.regionCode || payload.state?.regionCode || null;
+    appendThread("command", input, payload.reply);
+  } catch (error) {
+    appendThread("error", input, error.message);
+  }
+  renderAll();
+}
+
+async function beginAuth() {
+  try {
+    if (!state.apiMode) {
+      throw new Error("Attach the Mercuria harness to enable operator login.");
+    }
+    const payload = await fetchApiJson("./api/auth/openai/begin", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ profile: "operator" })
+    });
+    state.auth.flow = payload;
+    state.auth.error = "";
+    state.auth.panelOpen = true;
+    appendThread("auth", "OpenAI sign-in prepared", "Open the sign-in link, finish in the browser, then paste the redirect URL back here.");
+  } catch (error) {
+    state.auth.error = error.message;
+    appendThread("auth", "Sign-in preparation failed", error.message);
+  }
+  renderAll();
+}
+
+async function finishAuth() {
+  try {
+    const redirectUrl = refs.authPaste.value.trim();
+    if (!redirectUrl) {
+      throw new Error("Paste the full redirect URL from the browser first.");
+    }
+    const payload = await fetchApiJson("./api/auth/openai/finish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        profile: "operator",
+        redirectUrl
+      })
+    });
+    if (payload.sessionToken) {
+      writeSessionToken(payload.sessionToken);
+    }
+    state.auth.loggedIn = true;
+    state.auth.session = payload.session || null;
+    state.auth.flow = null;
+    state.auth.error = "";
+    refs.authPaste.value = "";
+    appendThread("auth", "OpenAI sign-in completed", `Operator session linked to account ${payload.accountId}.`);
+  } catch (error) {
+    state.auth.error = error.message;
+    appendThread("auth", "Sign-in completion failed", error.message);
+  }
+  await refreshAuthStatus();
+  renderAll();
+}
+
+async function logoutAuth() {
+  try {
+    if (state.apiMode) {
+      await fetchApiJson("./api/auth/logout", {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ input })
-      }).then((response) => response.json())
-    : runLocalCommand(input);
-
-  state.filterIds = payload.filterIds || payload.state?.filterIds || state.filterIds;
-  state.focusId = payload.focusId || payload.state?.focusId || state.focusId;
-  state.regionCode = payload.regionCode || payload.state?.regionCode || null;
-  appendThread("command", input, payload.reply);
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    writeSessionToken("");
+    state.auth.loggedIn = false;
+    state.auth.session = null;
+    state.auth.flow = null;
+    state.auth.error = "";
+    refs.authPaste.value = "";
+    appendThread("auth", "Operator session cleared", "Mercuria returned to guest mode.");
+  } catch (error) {
+    state.auth.error = error.message;
+    appendThread("auth", "Logout failed", error.message);
+  }
+  await refreshAuthStatus();
   renderAll();
 }
 
@@ -349,6 +515,44 @@ function renderSuggestions() {
   }
 }
 
+function renderAuth() {
+  const panelVisible = state.auth.panelOpen;
+  refs.authPanel.hidden = !panelVisible;
+  refs.identityPill.textContent = state.auth.loggedIn
+    ? `Staff linked · ${state.auth.session?.accountId || "operator"}`
+    : state.apiMode
+      ? "Staff login"
+      : "Guest mode";
+
+  refs.authPanelMeta.textContent = state.auth.loggedIn ? "linked" : "manual paste";
+  refs.authCopy.textContent = state.auth.loggedIn
+    ? "Mercuria is carrying an active operator identity through the VPS-safe OpenAI flow."
+    : "Mercuria can attach a live operator identity through the VPS-safe OpenAI copy-paste OAuth flow.";
+  refs.authStatusLine.textContent = state.auth.error
+    ? state.auth.error
+    : state.auth.loggedIn
+      ? `Linked to ${state.auth.session?.accountId || "operator"} until ${new Date(state.auth.session?.expiresAt || Date.now()).toISOString()}.`
+      : state.apiMode
+        ? "Harness attached. Begin the OpenAI sign-in flow to link a staff operator."
+        : "Static shell mode. Start the harness to unlock staff login.";
+
+  if (state.auth.flow?.authUrl) {
+    refs.authLink.hidden = false;
+    refs.authLink.href = state.auth.flow.authUrl;
+    refs.authLink.textContent = "Open the OpenAI sign-in link";
+    refs.authFlowMeta.textContent = `Redirect URI: ${state.auth.flow.redirectUri} · state ${state.auth.flow.state}`;
+  } else {
+    refs.authLink.hidden = true;
+    refs.authLink.href = "#";
+    refs.authFlowMeta.textContent = state.auth.loggedIn
+      ? "Operator session is active."
+      : "No active sign-in flow.";
+  }
+
+  refs.authLogout.disabled = !state.auth.loggedIn;
+  refs.authFinish.disabled = !state.apiMode;
+}
+
 function renderThread() {
   refs.threadLog.innerHTML = "";
   for (const entry of state.thread) {
@@ -629,6 +833,7 @@ function renderTopline() {
 
 function renderAll() {
   renderTopline();
+  renderAuth();
   renderRegionStrip();
   renderThread();
   renderFocus();
@@ -664,6 +869,10 @@ function handleResize() {
 
 function bindEvents() {
   window.addEventListener("resize", handleResize);
+  refs.identityButton.addEventListener("click", () => {
+    state.auth.panelOpen = !state.auth.panelOpen;
+    renderAuth();
+  });
   refs.terrain.addEventListener("click", (event) => {
     const winner = nearestCommunity(event);
     if (!winner) return;
@@ -681,6 +890,13 @@ function bindEvents() {
     issueCommand(input);
     refs.commandInput.value = "";
   });
+  refs.authBegin.addEventListener("click", () => beginAuth());
+  refs.authRefresh.addEventListener("click", async () => {
+    await refreshAuthStatus();
+    renderAll();
+  });
+  refs.authLogout.addEventListener("click", () => logoutAuth());
+  refs.authFinish.addEventListener("click", () => finishAuth());
 }
 
 async function bootstrap() {

package/app/index.html

@@ -22,9 +22,33 @@
       <div class="topline-meta">
         <div id="world-caption" class="meta-pill">Loading range</div>
         <div id="presence-pill" class="meta-pill meta-pill--ghost">Static shell</div>
+        <button id="identity-button" class="meta-pill meta-pill--button" type="button">
+          <span id="identity-pill">Guest mode</span>
+        </button>
       </div>
     </header>
 
+    <section id="auth-panel" class="auth-panel panel" hidden>
+      <div class="panel-heading">
+        <span>Staff login</span>
+        <span id="auth-panel-meta" class="panel-heading__meta">manual paste</span>
+      </div>
+      <p id="auth-copy" class="body-copy">
+        Mercuria can attach a live operator identity through the VPS-safe OpenAI copy-paste OAuth flow.
+      </p>
+      <div id="auth-status-line" class="auth-status-line">Checking auth surface.</div>
+      <div class="auth-actions">
+        <button id="auth-begin" type="button">Begin OpenAI sign-in</button>
+        <button id="auth-refresh" type="button">Refresh status</button>
+        <button id="auth-logout" type="button">Logout</button>
+      </div>
+      <a id="auth-link" class="auth-link" href="#" target="_blank" rel="noreferrer" hidden>Open the OpenAI sign-in link</a>
+      <div id="auth-flow-meta" class="auth-flow-meta"></div>
+      <label class="auth-paste-label" for="auth-paste">Paste the full redirect URL after sign-in</label>
+      <textarea id="auth-paste" rows="3" placeholder="http://localhost:1455/auth/callback?code=...&state=..."></textarea>
+      <button id="auth-finish" class="auth-finish" type="button">Complete sign-in</button>
+    </section>
+
     <main class="workspace">
       <section class="surface-panel">
         <canvas id="terrain" aria-label="Mercuria terrain"></canvas>

package/app/styles.css

@@ -112,10 +112,92 @@ body {
   border: 1px solid var(--line);
 }
 
+.meta-pill--button {
+  color: var(--text);
+  cursor: pointer;
+  font: inherit;
+}
+
+.meta-pill--button:hover,
+.meta-pill--button:focus-visible {
+  border-color: var(--line-strong);
+  background: rgba(20, 33, 27, 0.84);
+}
+
 .meta-pill--ghost {
   background: rgba(16, 27, 21, 0.34);
 }
 
+.auth-panel {
+  margin-bottom: 18px;
+  gap: 14px;
+}
+
+.auth-status-line,
+.auth-flow-meta {
+  padding: 12px 14px;
+  border-radius: 16px;
+  border: 1px solid var(--line);
+  background: rgba(8, 14, 11, 0.7);
+  color: var(--muted);
+}
+
+.auth-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.auth-actions button,
+.auth-finish {
+  padding: 11px 15px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--line);
+  background: rgba(11, 19, 15, 0.82);
+  color: var(--text);
+  cursor: pointer;
+  font: inherit;
+}
+
+.auth-actions button:hover,
+.auth-actions button:focus-visible,
+.auth-finish:hover,
+.auth-finish:focus-visible {
+  border-color: var(--line-strong);
+  background: rgba(20, 33, 27, 0.84);
+}
+
+.auth-actions button:disabled,
+.auth-finish:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.auth-link {
+  color: var(--accent);
+  text-decoration: none;
+  font-size: 0.95rem;
+}
+
+.auth-paste-label {
+  color: var(--muted);
+  font-size: 0.78rem;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+#auth-paste {
+  width: 100%;
+  resize: vertical;
+  min-height: 88px;
+  padding: 14px;
+  border-radius: 18px;
+  border: 1px solid var(--line);
+  background: rgba(8, 14, 11, 0.78);
+  color: var(--text);
+  font: inherit;
+}
+
 .workspace {
   display: grid;
   grid-template-columns: minmax(0, 1.5fr) minmax(320px, 420px);

package/netlify.toml

@@ -1,6 +1,12 @@
 [build]
   publish = "app"
 
+[[redirects]]
+  from = "/api/*"
+  to = "https://dashboard.lmtlssss.fun/api/:splat"
+  status = 200
+  force = true
+
 [[headers]]
   for = "/*"
   [headers.values]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercuria",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Mercuria world engine CLI and harness.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "harness": "node ./bin/mercuria.js harness",
     "serve": "node ./bin/mercuria.js harness",
     "verify:local": "node ./tests/verify-site.mjs http://127.0.0.1:4177",
-    "verify:live": "node ./tests/verify-site.mjs https://nfndashboard.netlify.app"
+    "verify:live": "node ./tests/verify-site.mjs https://nfndashboard.netlify.app",
+    "capture:live": "node ./tests/capture-matrix.mjs https://nfndashboard.netlify.app"
   },
   "keywords": [
     "cli",

package/src/harness.mjs

@@ -1,9 +1,17 @@
 import http from "node:http";
+import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { defaultState, runCommand } from "./shared/commands.mjs";
+import {
+  beginOpenAILogin,
+  finishOpenAILogin,
+  readOpenAIProfile,
+  refreshOpenAIProfile
+} from "./shared/openai-auth.mjs";
+import { readSessionStore, writeSessionStore } from "./shared/oauth-store.mjs";
 import { readJson } from "./shared/world.mjs";
 
 const MIME_TYPES = {
@@ -21,7 +29,9 @@ function responseJson(res, status, body) {
   res.writeHead(status, {
     "Content-Type": "application/json; charset=utf-8",
     "Cache-Control": "no-store",
-    "Access-Control-Allow-Origin": "*"
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Headers": "Content-Type, X-Mercuria-Session",
+    "Access-Control-Allow-Methods": "GET,POST,OPTIONS"
   });
   res.end(`${JSON.stringify(body)}\n`);
 }
@@ -44,6 +54,23 @@ async function readBody(req) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+function sessionToken() {
+  return randomBytes(24).toString("base64url");
+}
+
+function sessionHeader(req) {
+  return req.headers["x-mercuria-session"] || null;
+}
+
+function summarizeSession(record) {
+  return {
+    accountId: record.accountId,
+    profile: record.profile,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt
+  };
+}
+
 export async function createHarness({
   worldPath,
   siteDir,
@@ -60,6 +87,8 @@ export async function createHarness({
     }
   ];
   const clients = new Set();
+  const storedSessions = await readSessionStore();
+  const sessions = new Map(Object.entries(storedSessions.tokens || {}));
 
   function broadcast(event) {
     const payload = `data: ${JSON.stringify(event)}\n\n`;
@@ -69,6 +98,42 @@ export async function createHarness({
     onEvent(event);
   }
 
+  async function persistSessions() {
+    await writeSessionStore({
+      tokens: Object.fromEntries(sessions.entries())
+    });
+  }
+
+  function getSession(req) {
+    const token = sessionHeader(req);
+    if (!token) return null;
+    const record = sessions.get(token);
+    if (!record) return null;
+    if (record.expiresAt && record.expiresAt <= Date.now()) {
+      sessions.delete(token);
+      persistSessions().catch(() => {});
+      return null;
+    }
+    return { token, record };
+  }
+
+  async function createSession(profile) {
+    const oauth = await readOpenAIProfile(profile);
+    if (!oauth) {
+      throw new Error(`No OAuth profile saved for "${profile}"`);
+    }
+    const token = sessionToken();
+    const record = {
+      profile,
+      accountId: oauth.account_id,
+      createdAt: new Date().toISOString(),
+      expiresAt: oauth.expires_at
+    };
+    sessions.set(token, record);
+    await persistSessions();
+    return { token, record };
+  }
+
   const server = http.createServer(async (req, res) => {
     try {
       const url = new URL(req.url || "/", "http://127.0.0.1");
@@ -77,14 +142,22 @@ export async function createHarness({
         res.writeHead(204, {
           "Access-Control-Allow-Origin": "*",
           "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
-          "Access-Control-Allow-Headers": "Content-Type"
+          "Access-Control-Allow-Headers": "Content-Type, X-Mercuria-Session"
         });
         res.end();
         return;
       }
 
       if (url.pathname === "/api/health") {
-        responseJson(res, 200, { ok: true, mode: "harness", range: world.meta.range });
+        responseJson(res, 200, {
+          ok: true,
+          mode: "harness",
+          range: world.meta.range,
+          auth: {
+            provider: "openai-codex",
+            manualPaste: true
+          }
+        });
         return;
       }
 
@@ -98,12 +171,101 @@ export async function createHarness({
         return;
       }
 
+      if (url.pathname === "/api/auth/status") {
+        const active = getSession(req);
+        responseJson(res, 200, {
+          available: true,
+          loggedIn: Boolean(active),
+          session: active ? summarizeSession(active.record) : null
+        });
+        return;
+      }
+
+      if (url.pathname === "/api/auth/openai/begin" && req.method === "POST") {
+        const body = await readBody(req);
+        const payload = body ? JSON.parse(body) : {};
+        const result = await beginOpenAILogin({
+          profile: payload.profile || "operator",
+          originator: payload.originator || "mercuria",
+          redirectUri: payload.redirectUri
+        });
+        const event = {
+          kind: "auth",
+          title: "OpenAI sign-in prepared",
+          body: `Manual paste flow prepared for profile ${result.profile}.`,
+          at: new Date().toISOString()
+        };
+        ledger.push(event);
+        ledger.splice(0, Math.max(0, ledger.length - 80));
+        broadcast(event);
+        responseJson(res, 200, result);
+        return;
+      }
+
+      if (url.pathname === "/api/auth/openai/finish" && req.method === "POST") {
+        const body = await readBody(req);
+        const payload = body ? JSON.parse(body) : {};
+        const result = await finishOpenAILogin({
+          profile: payload.profile || "operator",
+          redirectUrl: payload.redirectUrl
+        });
+        const session = await createSession(payload.profile || "operator");
+        const event = {
+          kind: "auth",
+          title: "OpenAI sign-in completed",
+          body: `Mercuria operator linked to account ${result.accountId}.`,
+          at: new Date().toISOString()
+        };
+        ledger.push(event);
+        ledger.splice(0, Math.max(0, ledger.length - 80));
+        broadcast(event);
+        responseJson(res, 200, {
+          ok: true,
+          accountId: result.accountId,
+          expiresAt: result.expiresAt,
+          sessionToken: session.token,
+          session: summarizeSession(session.record)
+        });
+        return;
+      }
+
+      if (url.pathname === "/api/auth/openai/refresh" && req.method === "POST") {
+        const active = getSession(req);
+        if (!active) {
+          responseJson(res, 401, { ok: false, error: "No active staff session" });
+          return;
+        }
+        const refreshed = await refreshOpenAIProfile(active.record.profile);
+        const renewed = await createSession(active.record.profile);
+        sessions.delete(active.token);
+        await persistSessions();
+        responseJson(res, 200, {
+          ok: true,
+          accountId: refreshed.accountId,
+          expiresAt: refreshed.expiresAt,
+          sessionToken: renewed.token,
+          session: summarizeSession(renewed.record)
+        });
+        return;
+      }
+
+      if (url.pathname === "/api/auth/logout" && req.method === "POST") {
+        const active = getSession(req);
+        if (active) {
+          sessions.delete(active.token);
+          await persistSessions();
+        }
+        responseJson(res, 200, { ok: true });
+        return;
+      }
+
       if (url.pathname === "/api/stream") {
         res.writeHead(200, {
           "Content-Type": "text/event-stream; charset=utf-8",
           "Cache-Control": "no-cache, no-transform",
           Connection: "keep-alive",
-          "Access-Control-Allow-Origin": "*"
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Headers": "Content-Type, X-Mercuria-Session"
         });
         res.write(`data: ${JSON.stringify({ kind: "sync", events: ledger.slice(-16) })}\n\n`);
         clients.add(res);

package/src/index.mjs

@@ -1,3 +1,10 @@
 export { createHarness } from "./harness.mjs";
 export { buildWorldFile, buildWorldFromNhfn, readJson, summarizeWorld, writeJson } from "./shared/world.mjs";
 export { defaultState, runCommand } from "./shared/commands.mjs";
+export {
+  beginOpenAILogin,
+  finishOpenAILogin,
+  refreshOpenAIProfile,
+  readOpenAIProfile,
+  parseAuthorizationInput
+} from "./shared/openai-auth.mjs";

package/src/shared/oauth-store.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+function rootDir() {
+  return path.join(os.homedir(), ".config", "mercuria");
+}
+
+function oauthDir() {
+  return path.join(rootDir(), "oauth");
+}
+
+function sessionDir() {
+  return path.join(rootDir(), "sessions");
+}
+
+export function oauthProfilePath(profile = "default") {
+  return path.join(oauthDir(), `${profile}.json`);
+}
+
+export function oauthPendingPath(profile = "default") {
+  return path.join(oauthDir(), `${profile}.pending.json`);
+}
+
+export function sessionStorePath() {
+  return path.join(sessionDir(), "tokens.json");
+}
+
+export async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeJsonFile(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  return filePath;
+}
+
+export async function deleteFile(filePath) {
+  await fs.rm(filePath, { force: true });
+}
+
+export async function readOAuthProfile(profile = "default") {
+  return readJsonFile(oauthProfilePath(profile));
+}
+
+export async function writeOAuthProfile(profile, value) {
+  return writeJsonFile(oauthProfilePath(profile), value);
+}
+
+export async function readOAuthPending(profile = "default") {
+  return readJsonFile(oauthPendingPath(profile));
+}
+
+export async function writeOAuthPending(profile, value) {
+  return writeJsonFile(oauthPendingPath(profile), value);
+}
+
+export async function deleteOAuthPending(profile = "default") {
+  return deleteFile(oauthPendingPath(profile));
+}
+
+export async function readSessionStore() {
+  const current = await readJsonFile(sessionStorePath());
+  return current && typeof current === "object" ? current : { tokens: {} };
+}
+
+export async function writeSessionStore(value) {
+  return writeJsonFile(sessionStorePath(), value);
+}

package/src/shared/openai-auth.mjs

@@ -0,0 +1,250 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import {
+  deleteOAuthPending,
+  readOAuthPending,
+  readOAuthProfile,
+  writeOAuthPending,
+  writeOAuthProfile
+} from "./oauth-store.mjs";
+
+export const OPENAI_CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export const OPENAI_CODEX_AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
+export const OPENAI_CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
+export const OPENAI_CODEX_REDIRECT_URI = "http://localhost:1455/auth/callback";
+export const OPENAI_CODEX_SCOPE = "openid profile email offline_access";
+export const OPENAI_CODEX_JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+function base64Url(buffer) {
+  return buffer.toString("base64url");
+}
+
+function buildPkce() {
+  const verifier = base64Url(randomBytes(32));
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+function createState() {
+  return randomBytes(16).toString("hex");
+}
+
+function now() {
+  return Date.now();
+}
+
+function normalizeExpiresAt(expiresInSeconds) {
+  const expiresIn = Number(expiresInSeconds);
+  if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new Error("OpenAI token response missing valid expires_in");
+  }
+  return now() + expiresIn * 1000;
+}
+
+function decodeJwtPayload(token) {
+  try {
+    const parts = String(token || "").split(".");
+    if (parts.length !== 3) return null;
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function extractOpenAIAccountId(accessToken) {
+  const payload = decodeJwtPayload(accessToken);
+  const accountId = payload?.[OPENAI_CODEX_JWT_CLAIM_PATH]?.chatgpt_account_id;
+  return typeof accountId === "string" && accountId ? accountId : null;
+}
+
+export function createAuthorizationFlow({ originator = "mercuria", redirectUri = OPENAI_CODEX_REDIRECT_URI } = {}) {
+  const { verifier, challenge } = buildPkce();
+  const state = createState();
+  const url = new URL(OPENAI_CODEX_AUTHORIZE_URL);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", OPENAI_CODEX_CLIENT_ID);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("scope", OPENAI_CODEX_SCOPE);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("id_token_add_organizations", "true");
+  url.searchParams.set("codex_cli_simplified_flow", "true");
+  url.searchParams.set("originator", originator);
+  return {
+    verifier,
+    state,
+    url: url.toString(),
+    originator,
+    redirectUri
+  };
+}
+
+export function parseAuthorizationInput(input) {
+  const value = String(input || "").trim();
+  if (!value) return {};
+
+  try {
+    const url = new URL(value);
+    return {
+      code: url.searchParams.get("code") || undefined,
+      state: url.searchParams.get("state") || undefined
+    };
+  } catch {}
+
+  if (value.includes("code=")) {
+    const params = new URLSearchParams(value);
+    return {
+      code: params.get("code") || undefined,
+      state: params.get("state") || undefined
+    };
+  }
+
+  if (value.includes("#")) {
+    const [code, state] = value.split("#", 2);
+    return { code: code || undefined, state: state || undefined };
+  }
+
+  return { code: value };
+}
+
+function normalizeTokenRecord(record = {}, existing = {}) {
+  const accessToken = record.access_token || existing.access_token;
+  const refreshToken = record.refresh_token || existing.refresh_token;
+  if (!accessToken) throw new Error("OpenAI token response missing access token");
+  if (!refreshToken) throw new Error("OpenAI token response missing refresh token");
+
+  const expiresAt = record.expires_at || (record.expires_in ? normalizeExpiresAt(record.expires_in) : existing.expires_at);
+  if (!expiresAt) throw new Error("OpenAI token response missing expiry");
+
+  const accountId = record.account_id || existing.account_id || extractOpenAIAccountId(accessToken);
+  if (!accountId) throw new Error("Failed to extract OpenAI account id");
+
+  return {
+    provider: "openai-codex",
+    client_id: OPENAI_CODEX_CLIENT_ID,
+    authorize_url: OPENAI_CODEX_AUTHORIZE_URL,
+    token_url: OPENAI_CODEX_TOKEN_URL,
+    redirect_uri: record.redirect_uri || existing.redirect_uri || OPENAI_CODEX_REDIRECT_URI,
+    scope: record.scope || existing.scope || OPENAI_CODEX_SCOPE,
+    originator: record.originator || existing.originator || "mercuria",
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_at: expiresAt,
+    account_id: accountId,
+    saved_at: new Date().toISOString()
+  };
+}
+
+export async function beginOpenAILogin({ profile = "operator", originator = "mercuria", redirectUri = OPENAI_CODEX_REDIRECT_URI } = {}) {
+  const flow = createAuthorizationFlow({ originator, redirectUri });
+  await writeOAuthPending(profile, {
+    schemaVersion: 1,
+    provider: "openai-codex",
+    profile,
+    originator,
+    verifier: flow.verifier,
+    state: flow.state,
+    redirect_uri: redirectUri,
+    authorize_url: OPENAI_CODEX_AUTHORIZE_URL,
+    token_url: OPENAI_CODEX_TOKEN_URL,
+    client_id: OPENAI_CODEX_CLIENT_ID,
+    scope: OPENAI_CODEX_SCOPE,
+    created_at: new Date().toISOString()
+  });
+
+  return {
+    profile,
+    authUrl: flow.url,
+    state: flow.state,
+    redirectUri
+  };
+}
+
+export async function exchangeAuthorizationCode({ code, verifier, redirectUri = OPENAI_CODEX_REDIRECT_URI, fetchImpl = fetch } = {}) {
+  const response = await fetchImpl(OPENAI_CODEX_TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: OPENAI_CODEX_CLIENT_ID,
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirectUri
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(`OpenAI code exchange failed: ${response.status} ${await response.text()}`);
+  }
+
+  return normalizeTokenRecord(await response.json(), { redirect_uri: redirectUri });
+}
+
+export async function finishOpenAILogin({ profile = "operator", redirectUrl, fetchImpl = fetch } = {}) {
+  const pending = await readOAuthPending(profile);
+  if (!pending) {
+    throw new Error(`No pending OpenAI OAuth flow for profile "${profile}"`);
+  }
+
+  const parsed = parseAuthorizationInput(redirectUrl);
+  if (!parsed.code) throw new Error("Missing authorization code in pasted redirect URL");
+  if (parsed.state && parsed.state !== pending.state) throw new Error("OpenAI OAuth state mismatch");
+
+  const record = await exchangeAuthorizationCode({
+    code: parsed.code,
+    verifier: pending.verifier,
+    redirectUri: pending.redirect_uri,
+    fetchImpl
+  });
+
+  await writeOAuthProfile(profile, {
+    ...record,
+    originator: pending.originator || record.originator
+  });
+  await deleteOAuthPending(profile);
+
+  return {
+    profile,
+    accountId: record.account_id,
+    expiresAt: record.expires_at
+  };
+}
+
+export async function refreshOpenAIProfile(profile = "operator", { fetchImpl = fetch } = {}) {
+  const stored = await readOAuthProfile(profile);
+  if (!stored?.refresh_token) {
+    throw new Error(`No refresh token stored for profile "${profile}"`);
+  }
+
+  const response = await fetchImpl(OPENAI_CODEX_TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: stored.refresh_token,
+      client_id: OPENAI_CODEX_CLIENT_ID
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(`OpenAI refresh failed: ${response.status} ${await response.text()}`);
+  }
+
+  const updated = normalizeTokenRecord(await response.json(), stored);
+  await writeOAuthProfile(profile, {
+    ...stored,
+    ...updated
+  });
+
+  return {
+    profile,
+    accountId: updated.account_id,
+    expiresAt: updated.expires_at
+  };
+}
+
+export async function readOpenAIProfile(profile = "operator") {
+  return readOAuthProfile(profile);
+}
+