memroot 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/index.js

@@ -1127,6 +1127,15 @@ var SELECT_INSTRUCTIONS = [
 ];
 var i = `${styleText("gray", S_BAR)}  `;
 
+// src/auth.ts
+import { spawn } from "node:child_process";
+import { createHash as createHash2, randomBytes } from "node:crypto";
+import { createServer, request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+
+// src/codex-mcp.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+
 // src/native.ts
 import { spawnSync } from "node:child_process";
 import { accessSync, constants, realpathSync, statSync } from "node:fs";
@@ -1242,7 +1251,11 @@ function inspectNative(path, agent, marketplace, previousMarketplace) {
           "PLUGIN_DISABLED: Memroot is disabled in Grok. Enable it in the native plugin manager when ready."
         );
     }
-    return { registered: false, installed: matching.length > 0 };
+    return {
+      registered: false,
+      currentMarketplace: false,
+      installed: matching.length > 0
+    };
   }
   const markets = rows(
     native(path, agent, ["plugin", "marketplace", "list", "--json"]),
@@ -1253,6 +1266,10 @@ function inspectNative(path, agent, marketplace, previousMarketplace) {
     agent === "codex" ? "installed" : void 0
   );
   const matchingMarkets = markets.filter((row) => row.name === "memroot");
+  if (matchingMarkets.length > 1)
+    throw new Error(
+      "MARKETPLACE_COLLISION: Multiple Memroot marketplaces were reported; refusing to change them."
+    );
   for (const market of matchingMarkets) {
     const source = agent === "codex" ? market.root : market.path;
     if (!samePath(source, marketplace) && !(previousMarketplace && samePath(source, previousMarketplace)))
@@ -1277,12 +1294,132 @@ function inspectNative(path, agent, marketplace, previousMarketplace) {
         "PLUGIN_COLLISION: Existing Memroot plugin status or scope cannot be safely managed. Check the native plugin manager."
       );
   }
+  const currentMarketplace = matchingMarkets.some(
+    (market) => samePath(agent === "codex" ? market.root : market.path, marketplace)
+  );
+  if (agent === "codex" && matchingMarkets.length > 0 && !currentMarketplace && plugins.some(
+    (plugin) => plugin.marketplaceName === "memroot" && plugin.pluginId !== "memroot@memroot"
+  ))
+    throw new Error(
+      "MARKETPLACE_COLLISION: The previous Memroot marketplace contains another installed plugin; refusing to remove it."
+    );
   return {
     registered: matchingMarkets.length > 0,
+    currentMarketplace,
     installed: matchingPlugins.length > 0
   };
 }
 
+// src/codex-mcp.ts
+var codexMcpUrl = "https://api.memroot.dev/mcp";
+function command(path, args, interactive = false) {
+  const result = spawnSync2(path, ["mcp", ...args], {
+    shell: false,
+    encoding: "utf8",
+    timeout: interactive ? 3e5 : 3e4,
+    maxBuffer: 1024 * 1024,
+    // Let Codex present browser authentication directly; never capture credentials.
+    stdio: interactive ? "inherit" : "pipe"
+  });
+  if (result.error || result.status !== 0)
+    throw new Error(
+      "MCP_COMMAND_FAILED: Codex MCP command did not complete. Your configuration is preserved; retry memroot setup --agent codex --yes."
+    );
+  return result.stdout ?? "";
+}
+function inspectCodexMcp(path) {
+  let rows2;
+  try {
+    rows2 = JSON.parse(command(path, ["list", "--json"]));
+  } catch {
+    throw new Error(
+      "MCP_STATUS_UNAVAILABLE: Cannot inspect Codex MCP state. Retry later; no new authorization was requested."
+    );
+  }
+  if (!Array.isArray(rows2) || rows2.some((row2) => !row2 || typeof row2 !== "object"))
+    throw new Error(
+      "MCP_STATUS_UNAVAILABLE: Unsupported Codex MCP status format."
+    );
+  const matching = rows2.filter((row2) => row2.name === "memroot");
+  if (!matching.length)
+    return { configured: false, authorized: false, verified: false };
+  const row = matching[0];
+  if (matching.length !== 1 || row.enabled !== true || row.transport?.type !== "streamable_http" || row.transport?.url !== codexMcpUrl || row.transport?.bearer_token_env_var || row.transport?.http_headers || row.transport?.env_http_headers || row.transport?.http_headers_helper)
+    throw new Error(
+      "MCP_CONFLICT: Existing memroot MCP configuration differs from production OAuth or is disabled. Inspect it in Codex; setup preserves your settings."
+    );
+  if (row.auth_status !== "oauth" && row.auth_status !== "not_logged_in")
+    throw new Error(
+      "MCP_AUTH_UNKNOWN: Codex could not establish OAuth status. Resolve it in Codex before retrying; no replacement grant was requested."
+    );
+  return {
+    configured: true,
+    authorized: row.auth_status === "oauth",
+    verified: false
+  };
+}
+function codexMcpPreflight(path) {
+  for (const [args, flags] of [
+    [["list", "--help"], ["--json"]],
+    [
+      ["add", "--help"],
+      ["--url", "--oauth-resource"]
+    ],
+    [["login", "--help"], []]
+  ]) {
+    const help2 = command(path, [...args]);
+    if (flags.some((flag) => !help2.includes(flag)))
+      throw new Error(
+        "MCP_UNSUPPORTED: Update Codex to a version supporting native remote OAuth MCP setup."
+      );
+  }
+}
+async function ensureCodexMcp(options) {
+  if (options.dryRun)
+    return { configured: false, authorized: false, verified: false };
+  const path = executable("codex");
+  if (!path)
+    throw new Error("AGENT_NOT_FOUND: Install Codex before linking Memroot.");
+  codexMcpPreflight(path);
+  let state = inspectCodexMcp(path);
+  if (!state.configured) {
+    command(
+      path,
+      ["add", "memroot", "--url", codexMcpUrl, "--oauth-resource", codexMcpUrl],
+      true
+    );
+    state = inspectCodexMcp(path);
+    if (!state.authorized)
+      throw new Error(
+        "MCP_AUTH_PENDING: Codex MCP is configured; authorization has not completed. Retry setup to resume."
+      );
+  } else if (!state.authorized) {
+    command(path, ["login", "memroot"], true);
+    state = inspectCodexMcp(path);
+  }
+  if (!state.authorized)
+    throw new Error(
+      "MCP_AUTH_PENDING: Codex has not confirmed OAuth authorization."
+    );
+  return state;
+}
+function describeCodexMcp(state) {
+  return `Codex MCP: ${state.configured ? "configured" : "not configured"}; OAuth: ${state.authorized ? "authorized" : "not authorized"}; memory verification: not verified. Ask Codex to call connection_status, then save and retrieve a test memory.`;
+}
+
+// src/config.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  chmod,
+  lstat as lstat2,
+  readFile as readFile2,
+  rename as rename2,
+  rm as rm2,
+  writeFile as writeFile2
+} from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+
 // src/storage.ts
 import { createHash, randomUUID } from "node:crypto";
 import {
@@ -1298,7 +1435,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, isAbsolute as isAbsolute2, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
-var version = "0.1.0-alpha.0";
+var version = "0.1.0-alpha.1";
 function dataDirectory() {
   const base = process.platform === "win32" ? process.env.LOCALAPPDATA ?? join2(homedir(), "AppData", "Local") : process.env.XDG_DATA_HOME ?? join2(homedir(), ".local", "share");
   if (!isAbsolute2(base))
@@ -1483,49 +1620,981 @@ async function acquireLock(data) {
   };
 }
 
+// src/config.ts
+function configDirectory() {
+  return join3(homedir2(), ".memroot");
+}
+function configPath() {
+  return join3(configDirectory(), "config.json");
+}
+function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1" || hostname === "[::1]";
+}
+function isAllowedApiBase(value) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash) return false;
+    if (url.protocol === "https:") return true;
+    return url.protocol === "http:" && isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+function optionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function containsCredential(value) {
+  if (!value || typeof value !== "object") return false;
+  return Object.entries(value).some(
+    ([key, entry]) => /token|secret|password|credential|api[_-]?key/i.test(key) || containsCredential(entry)
+  );
+}
+async function migrateLegacy(record, raw) {
+  if (!(typeof record.user_id === "string" || typeof record.email === "string") || containsCredential(record) || record.apiBase !== void 0 && (typeof record.apiBase !== "string" || !isAllowedApiBase(record.apiBase)))
+    throw new Error(
+      "INVALID_CONFIG: Legacy config cannot be safely migrated. No credentials were imported."
+    );
+  await safeDirectory(configDirectory());
+  const backup = `${configPath()}.legacy-backup`;
+  try {
+    await writeFile2(backup, raw, { flag: "wx", mode: 384 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const info = await lstat2(backup);
+    if (!info.isFile() || info.isSymbolicLink() || await readFile2(backup, "utf8") !== raw)
+      throw new Error(
+        "INVALID_CONFIG: Legacy backup differs or is unsafe. Original config was preserved."
+      );
+    await chmod(backup, 384);
+  }
+  const config = { schemaVersion: 1 };
+  await writeConfig(config);
+  return config;
+}
+async function readConfig() {
+  const path = configPath();
+  let raw;
+  try {
+    const info = await lstat2(path);
+    if (!info.isFile() || info.isSymbolicLink())
+      throw new Error("INVALID_CONFIG: Expected a regular config file.");
+    raw = await readFile2(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { schemaVersion: 1 };
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      "INVALID_CONFIG: ~/.memroot/config.json is not valid JSON. Fix or remove it."
+    );
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("INVALID_CONFIG: Cannot safely read CLI config.");
+  const record = value;
+  if (record.schemaVersion === void 0) return migrateLegacy(record, raw);
+  const apiBase = optionalString(record.apiBase);
+  if (record.schemaVersion !== 1 || apiBase && !isAllowedApiBase(apiBase))
+    throw new Error("INVALID_CONFIG: Cannot safely read CLI config.");
+  const config = { schemaVersion: 1 };
+  if (apiBase) config.apiBase = apiBase;
+  const clientId = optionalString(record.clientId);
+  if (clientId) config.clientId = clientId;
+  const clientIdApiBase = optionalString(record.clientIdApiBase);
+  if (clientIdApiBase) config.clientIdApiBase = clientIdApiBase;
+  const userId = optionalString(record.userId);
+  if (userId) config.userId = userId;
+  return config;
+}
+async function writeConfig(config) {
+  const directory = configDirectory();
+  await safeDirectory(directory);
+  const path = configPath();
+  const temporary = `${path}.${randomUUID2()}.tmp`;
+  try {
+    await writeFile2(temporary, `${JSON.stringify(config, null, 2)}
+`, {
+      flag: "wx",
+      mode: 384
+    });
+    await rename2(temporary, path);
+    await chmod(path, 384);
+  } finally {
+    await rm2(temporary, { force: true });
+  }
+}
+
+// src/credentials.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import {
+  chmod as chmod2,
+  lstat as lstat3,
+  readFile as readFile3,
+  rename as rename3,
+  rm as rm3,
+  writeFile as writeFile3
+} from "node:fs/promises";
+import { join as join4 } from "node:path";
+var SERVICE = "memroot";
+var TOOL_TIMEOUT_MS = 15e3;
+function credentialStoreKind() {
+  const override = process.env.MEMROOT_TEST_CREDENTIAL_STORE;
+  if (override === "file" && process.env.NODE_ENV === "test")
+    return "test-file";
+  if (override)
+    throw new Error(
+      "INVALID_CREDENTIAL_STORE: MEMROOT_TEST_CREDENTIAL_STORE=file is honored only when NODE_ENV=test; refusing to file-back credentials."
+    );
+  return process.platform === "darwin" ? "macos-keychain" : "libsecret";
+}
+function unavailable(tool) {
+  return new Error(
+    `AUTH_KEYCHAIN_UNAVAILABLE: ${tool} is not installed, so there is no OS credential store for the Memroot refresh token. Tokens are never written to files; install ${tool === "security" ? "the macOS security tool" : "libsecret's secret-tool"} or sign in on a supported system.`
+  );
+}
+function run(tool, args, input, allowNotFound = false) {
+  const result = spawnSync3(tool, args, {
+    encoding: "utf8",
+    input,
+    timeout: TOOL_TIMEOUT_MS,
+    shell: false,
+    maxBuffer: 1024 * 1024
+  });
+  if (result.error) {
+    if (result.error.code === "ENOENT")
+      throw unavailable(tool);
+    throw new Error(
+      `AUTH_KEYCHAIN_FAILED: ${tool} could not run (${result.error.code ?? "error"}).`
+    );
+  }
+  if (allowNotFound) return result;
+  if (result.status !== 0)
+    throw new Error(
+      `AUTH_KEYCHAIN_FAILED: ${tool} ${args[0] ?? ""} failed (${result.status ?? "signal"}). No credential was read or written.`
+    );
+  return result;
+}
+function quote(value) {
+  return JSON.stringify(value);
+}
+function testStorePath() {
+  return join4(configDirectory(), "test-credentials.json");
+}
+async function readTestStore() {
+  try {
+    const info = await lstat3(testStorePath());
+    if (!info.isFile() || info.isSymbolicLink())
+      throw new Error("INVALID_CREDENTIAL_STORE: Expected a regular file.");
+    const value = JSON.parse(await readFile3(testStorePath(), "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+async function writeTestStore(entries) {
+  const directory = configDirectory();
+  await safeDirectory(directory);
+  const path = testStorePath();
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    await writeFile3(temporary, `${JSON.stringify(entries, null, 2)}
+`, {
+      flag: "wx",
+      mode: 384
+    });
+    await rename3(temporary, path);
+    await chmod2(path, 384);
+  } finally {
+    await rm3(temporary, { force: true });
+  }
+}
+function assertCredentialStoreAvailable() {
+  const kind = credentialStoreKind();
+  if (kind === "test-file") return;
+  if (kind === "macos-keychain")
+    run(
+      "security",
+      ["find-generic-password", "-s", SERVICE, "-a", "memroot:probe"],
+      void 0,
+      true
+    );
+  else
+    run(
+      "secret-tool",
+      ["lookup", "service", SERVICE, "account", "memroot:probe"],
+      void 0,
+      true
+    );
+}
+async function storeSecret(account, secret) {
+  const kind = credentialStoreKind();
+  if (kind === "test-file") {
+    const entries = await readTestStore();
+    entries[account] = secret;
+    await writeTestStore(entries);
+    return;
+  }
+  if (kind === "macos-keychain") {
+    run(
+      "security",
+      ["-i"],
+      `add-generic-password -U -s ${quote(SERVICE)} -a ${quote(account)} -w ${quote(secret)}
+`
+    );
+    return;
+  }
+  run(
+    "secret-tool",
+    ["store", "--label", "Memroot CLI", "service", SERVICE, "account", account],
+    secret
+  );
+}
+async function readSecret(account) {
+  const kind = credentialStoreKind();
+  if (kind === "test-file") return (await readTestStore())[account];
+  if (kind === "macos-keychain") {
+    const result2 = run(
+      "security",
+      ["find-generic-password", "-s", SERVICE, "-a", account, "-w"],
+      void 0,
+      true
+    );
+    if (result2.status !== 0) {
+      if (/could not be found|item not found/i.test(result2.stderr))
+        return void 0;
+      throw new Error(
+        `AUTH_KEYCHAIN_FAILED: security find-generic-password failed (${result2.status ?? "signal"}).`
+      );
+    }
+    const secret2 = result2.stdout.replace(/\n$/, "");
+    return secret2.length ? secret2 : void 0;
+  }
+  const result = run(
+    "secret-tool",
+    ["lookup", "service", SERVICE, "account", account],
+    void 0,
+    true
+  );
+  if (result.status !== 0) return void 0;
+  const secret = result.stdout.replace(/\n$/, "");
+  return secret.length ? secret : void 0;
+}
+async function deleteSecret(account) {
+  const kind = credentialStoreKind();
+  if (kind === "test-file") {
+    const entries = await readTestStore();
+    if (account in entries) {
+      delete entries[account];
+      await writeTestStore(entries);
+    }
+    return;
+  }
+  if (kind === "macos-keychain") {
+    const result = run(
+      "security",
+      ["delete-generic-password", "-s", SERVICE, "-a", account],
+      void 0,
+      true
+    );
+    if (result.status !== 0 && !/could not be found|item not found/i.test(result.stderr))
+      throw new Error(
+        `AUTH_KEYCHAIN_FAILED: security delete-generic-password failed (${result.status ?? "signal"}).`
+      );
+    return;
+  }
+  run(
+    "secret-tool",
+    ["clear", "service", SERVICE, "account", account],
+    void 0,
+    true
+  );
+}
+
+// src/auth.ts
+var PROD_API_BASE = "https://api.memroot.dev";
+var DEV_API_BASE = "http://localhost:8787";
+var STATIC_CLIENT_ID = "memroot-cli";
+var CALLBACK_PATH = "/callback";
+var LOGIN_TIMEOUT_MS = 18e4;
+var REFRESH_SKEW_MS = 3e4;
+var REQUESTED_SCOPE = "memory.read memory.write";
+var OAuthError = class extends Error {
+  constructor(oauth, message) {
+    super(message);
+    this.oauth = oauth;
+  }
+  oauth;
+};
+function resolveApiBase(options, config) {
+  const base = options.apiBase ?? process.env.MEMROOT_API_BASE ?? (options.env ? options.env === "dev" ? DEV_API_BASE : PROD_API_BASE : void 0) ?? config.apiBase ?? PROD_API_BASE;
+  const normalized = base.replace(/\/+$/, "");
+  if (!isAllowedApiBase(normalized))
+    throw new Error(
+      "INSECURE_API_BASE: The API base must use https, or http only on a loopback address for local development."
+    );
+  return normalized;
+}
+function decodeClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return void 0;
+  try {
+    const claims = JSON.parse(
+      Buffer.from(parts[1] ?? "", "base64url").toString("utf8")
+    );
+    if (!claims || typeof claims !== "object" || Array.isArray(claims))
+      return void 0;
+    return claims;
+  } catch {
+    return void 0;
+  }
+}
+function claimsExpiry(claims) {
+  return typeof claims?.exp === "number" ? claims.exp * 1e3 : 0;
+}
+function parseTokenSet(body) {
+  if (typeof body.access_token !== "string" || !body.access_token)
+    throw new Error(
+      "AUTH_RESPONSE_INVALID: The token endpoint returned no access token."
+    );
+  const tokens = { accessToken: body.access_token };
+  if (typeof body.refresh_token === "string" && body.refresh_token)
+    tokens.refreshToken = body.refresh_token;
+  if (typeof body.expires_in === "number") tokens.expiresIn = body.expires_in;
+  return tokens;
+}
+var REQUEST_TIMEOUT_MS = 3e4;
+function request(target, method, contentType, payload) {
+  const transport = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const headers = {
+    accept: "application/json"
+  };
+  if (contentType) headers["content-type"] = contentType;
+  if (payload !== void 0)
+    headers["content-length"] = Buffer.byteLength(payload);
+  return new Promise((resolve, reject) => {
+    const request2 = transport(
+      target,
+      {
+        method,
+        agent: false,
+        timeout: REQUEST_TIMEOUT_MS,
+        headers
+      },
+      (response) => {
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on(
+          "end",
+          () => resolve({ status: response.statusCode ?? 0, body })
+        );
+      }
+    );
+    request2.on("timeout", () => request2.destroy(new Error("request timeout")));
+    request2.on(
+      "error",
+      () => reject(
+        new Error(
+          `AUTH_UNREACHABLE: Cannot reach ${target.origin}. Check the network connection and API base URL.`
+        )
+      )
+    );
+    request2.end(payload);
+  });
+}
+async function getJson(url) {
+  const response = await request(new URL(url), "GET");
+  if (response.status >= 400)
+    throw new Error(
+      `AUTH_METADATA_FAILED: ${url} returned ${response.status}.`
+    );
+  return parseJsonBody(response.body);
+}
+function parseJsonBody(text) {
+  let body;
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = void 0;
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body))
+    throw new Error(
+      "AUTH_RESPONSE_INVALID: The server returned a malformed response."
+    );
+  return body;
+}
+function oauthFailure(record, status2) {
+  const code = typeof record.error === "string" ? record.error : `http_${status2}`;
+  const description = typeof record.error_description === "string" ? ` ${record.error_description}` : "";
+  return new OAuthError(code, `AUTH_TOKEN_REJECTED: ${code}.${description}`);
+}
+async function postForm(apiBase, path, params) {
+  const response = await request(
+    new URL(`${apiBase}${path}`),
+    "POST",
+    "application/x-www-form-urlencoded",
+    new URLSearchParams(params).toString()
+  );
+  let record = {};
+  try {
+    record = response.body ? parseJsonBody(response.body) : {};
+  } catch (error) {
+    if (response.status < 400) throw error;
+  }
+  if (response.status >= 400) throw oauthFailure(record, response.status);
+  return parseJsonBody(response.body);
+}
+async function registerClient(apiBase, redirectUri) {
+  const response = await request(
+    new URL(`${apiBase}/oauth/register`),
+    "POST",
+    "application/json",
+    JSON.stringify({
+      client_name: "Memroot CLI",
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      scope: REQUESTED_SCOPE
+    })
+  );
+  if (response.status === 404 || response.status === 405 || response.status === 501)
+    return void 0;
+  let record = {};
+  try {
+    record = parseJsonBody(response.body);
+  } catch {
+    record = {};
+  }
+  if (response.status >= 400) {
+    const code = typeof record.error === "string" ? record.error : `http_${response.status}`;
+    throw new OAuthError(
+      code,
+      `AUTH_REGISTRATION_FAILED: Client registration failed (${code}).`
+    );
+  }
+  if (typeof record.client_id !== "string" || !record.client_id)
+    throw new Error(
+      "AUTH_RESPONSE_INVALID: Client registration returned no client_id."
+    );
+  return record.client_id;
+}
+async function exchangeCode(apiBase, clientId, redirectUri, code, verifier) {
+  return parseTokenSet(
+    await postForm(apiBase, "/oauth/token", {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: verifier
+    })
+  );
+}
+async function revokeRefreshToken(apiBase, refreshToken, clientId) {
+  const metadata = await getJson(
+    `${apiBase}/.well-known/oauth-authorization-server`
+  );
+  const endpoint = metadata.revocation_endpoint;
+  if (typeof endpoint !== "string" || !endpoint || !isAllowedApiBase(endpoint))
+    throw new Error(
+      "AUTH_REVOKE_UNSUPPORTED: The server does not advertise a usable revocation endpoint."
+    );
+  const response = await request(
+    new URL(endpoint),
+    "POST",
+    "application/x-www-form-urlencoded",
+    new URLSearchParams({
+      token: refreshToken,
+      token_type_hint: "refresh_token",
+      client_id: clientId
+    }).toString()
+  );
+  if (response.status >= 400)
+    throw new Error(
+      `AUTH_REVOKE_FAILED: Revocation returned ${response.status}.`
+    );
+}
+async function refreshTokens(apiBase, refreshToken, clientId) {
+  try {
+    return parseTokenSet(
+      await postForm(apiBase, "/oauth/token", {
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId
+      })
+    );
+  } catch (error) {
+    if (error instanceof OAuthError && error.oauth === "invalid_grant")
+      throw new OAuthError(
+        "invalid_grant",
+        "AUTH_EXPIRED: Stored credentials were rejected or expired. Run memroot login."
+      );
+    if (error instanceof OAuthError && error.oauth === "invalid_client")
+      throw new OAuthError(
+        "invalid_client",
+        "AUTH_INVALID_CLIENT: The stored client registration was rejected. Run memroot login."
+      );
+    throw error;
+  }
+}
+function page(title, detail) {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Memroot \u2014 ${title}</title></head><body><h1>${title}</h1><p>${detail}</p></body></html>`;
+}
+function startCallbackServer(expectedState, apiBase) {
+  let failure;
+  let timer;
+  const pending = [];
+  const waiters = [];
+  const deliver = (result) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter.resolve(result);
+    else pending.push(result);
+  };
+  const server = createServer((request2, response) => {
+    const url = new URL(request2.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== CALLBACK_PATH) {
+      response.writeHead(404).end("Not found");
+      return;
+    }
+    const errorParam = url.searchParams.get("error");
+    if (errorParam) {
+      const description = url.searchParams.get("error_description");
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Sign-in failed", "Return to the terminal for details."));
+      deliver({
+        kind: "error",
+        error: errorParam,
+        ...typeof description === "string" ? { description } : {}
+      });
+      return;
+    }
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (!code || !state) {
+      response.writeHead(400).end("Missing code or state.");
+      return;
+    }
+    if (state !== expectedState) {
+      response.writeHead(400).end("State mismatch; rejected.");
+      return;
+    }
+    const issuer = url.searchParams.get("iss");
+    const issuerOrigin = (() => {
+      try {
+        return issuer ? new URL(issuer).origin : void 0;
+      } catch {
+        return void 0;
+      }
+    })();
+    if (!issuer || !issuerOrigin) {
+      response.writeHead(400).end("Missing or malformed issuer; rejected.");
+      deliver({ kind: "error", error: "iss_missing" });
+      return;
+    }
+    if (issuerOrigin !== new URL(apiBase).origin) {
+      response.writeHead(400).end("Issuer mismatch; rejected.");
+      deliver({ kind: "error", error: "iss_mismatch" });
+      return;
+    }
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(
+      page(
+        "Sign-in complete",
+        "You can close this tab and return to the terminal."
+      )
+    );
+    deliver({ kind: "code", code });
+  });
+  const fail = (error) => {
+    if (failure) return;
+    failure = error;
+    if (timer) clearTimeout(timer);
+    server.close();
+    server.closeAllConnections();
+    for (const waiter of waiters.splice(0)) waiter.reject(error);
+  };
+  timer = setTimeout(
+    () => fail(
+      new Error(
+        "AUTH_TIMEOUT: Timed out waiting for the browser sign-in callback. Retry memroot login."
+      )
+    ),
+    LOGIN_TIMEOUT_MS
+  );
+  return new Promise((resolve, reject) => {
+    server.once("error", (error) => {
+      fail(error);
+      reject(error);
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      resolve({
+        port: address.port,
+        next: () => {
+          if (failure) return Promise.reject(failure);
+          const queued = pending.shift();
+          if (queued) return Promise.resolve(queued);
+          const result = new Promise(
+            (resolve2, rejectPromise) => waiters.push({ resolve: resolve2, reject: rejectPromise })
+          );
+          result.catch(() => {
+          });
+          return result;
+        },
+        close: () => fail(new Error("AUTH_ABORTED: Sign-in was aborted."))
+      });
+    });
+  });
+}
+function openBrowser(url) {
+  const tool = process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    const child = spawn(tool, [url], {
+      detached: true,
+      stdio: "ignore",
+      shell: false
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+var cachedAccessToken;
+async function getAccessToken(options = {}) {
+  if (cachedAccessToken && cachedAccessToken.expiresAt - Date.now() > REFRESH_SKEW_MS)
+    return cachedAccessToken.token;
+  const config = await readConfig();
+  const apiBase = resolveApiBase(options, config);
+  const stored = await readSecret(apiBase);
+  if (!stored)
+    throw new Error(
+      "AUTH_REQUIRED: Not signed in. Run memroot login to connect your account."
+    );
+  const clientId = config.clientId && config.clientIdApiBase === apiBase ? config.clientId : STATIC_CLIENT_ID;
+  const tokens = await refreshTokens(apiBase, stored, clientId);
+  if (tokens.refreshToken && tokens.refreshToken !== stored)
+    await storeSecret(apiBase, tokens.refreshToken);
+  const claims = decodeClaims(tokens.accessToken);
+  cachedAccessToken = {
+    token: tokens.accessToken,
+    expiresAt: claimsExpiry(claims) || Date.now() + (tokens.expiresIn ?? 0) * 1e3
+  };
+  if (typeof claims?.sub === "string" && claims.sub !== config.userId) {
+    config.userId = claims.sub;
+    await writeConfig(config);
+  }
+  return tokens.accessToken;
+}
+async function tryExistingSession(apiBase, config) {
+  const stored = await readSecret(apiBase);
+  if (!stored) return false;
+  const clientId = config.clientId && config.clientIdApiBase === apiBase ? config.clientId : STATIC_CLIENT_ID;
+  try {
+    const tokens = await refreshTokens(apiBase, stored, clientId);
+    if (tokens.refreshToken && tokens.refreshToken !== stored)
+      await storeSecret(apiBase, tokens.refreshToken);
+    const sub = decodeClaims(tokens.accessToken)?.sub;
+    console.log(
+      `Already signed in to ${apiBase}${typeof sub === "string" ? ` as ${sub}` : ""}. Use --force to re-authenticate.`
+    );
+    return true;
+  } catch (error) {
+    if (error instanceof OAuthError && (error.oauth === "invalid_grant" || error.oauth === "invalid_client")) {
+      await deleteSecret(apiBase).catch(() => {
+      });
+      return false;
+    }
+    throw error;
+  }
+}
+async function login(options) {
+  if (process.platform !== "darwin" && process.platform !== "linux")
+    throw new Error(
+      "UNSUPPORTED_PLATFORM: memroot login supports macOS and Linux."
+    );
+  assertCredentialStoreAvailable();
+  const config = await readConfig();
+  const apiBase = resolveApiBase(options, config);
+  if (!options.force && await tryExistingSession(apiBase, config)) return;
+  const state = randomBytes(24).toString("base64url");
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash2("sha256").update(verifier).digest("base64url");
+  const waiter = await startCallbackServer(state, apiBase);
+  try {
+    const redirectUri = `http://127.0.0.1:${waiter.port}${CALLBACK_PATH}`;
+    let clientId = config.clientId && config.clientIdApiBase === apiBase ? config.clientId : STATIC_CLIENT_ID;
+    let retriedWithRegistration = false;
+    for (; ; ) {
+      const authorize = new URL(`${apiBase}/authorize`);
+      authorize.searchParams.set("response_type", "code");
+      authorize.searchParams.set("client_id", clientId);
+      authorize.searchParams.set("redirect_uri", redirectUri);
+      authorize.searchParams.set("state", state);
+      authorize.searchParams.set("code_challenge", challenge);
+      authorize.searchParams.set("code_challenge_method", "S256");
+      authorize.searchParams.set("scope", REQUESTED_SCOPE);
+      const url = authorize.toString();
+      if (options.noBrowser) console.log(`Open this URL to sign in:
+${url}`);
+      else {
+        openBrowser(url);
+        console.log(
+          `Opening ${apiBase} for sign-in. If the browser did not open, visit:
+${url}`
+        );
+      }
+      console.log("Waiting for the browser sign-in callback\u2026");
+      const result = await waiter.next();
+      if (result.kind === "code") {
+        const tokens = await exchangeCode(
+          apiBase,
+          clientId,
+          redirectUri,
+          result.code,
+          verifier
+        );
+        if (!tokens.refreshToken)
+          throw new Error(
+            "AUTH_RESPONSE_INVALID: The token endpoint returned no refresh token."
+          );
+        await storeSecret(apiBase, tokens.refreshToken);
+        const claims = decodeClaims(tokens.accessToken);
+        const next = {
+          schemaVersion: 1,
+          apiBase,
+          clientId,
+          clientIdApiBase: apiBase
+        };
+        if (typeof claims?.sub === "string") next.userId = claims.sub;
+        await writeConfig(next);
+        console.log(
+          `Signed in to ${apiBase}${next.userId ? ` as ${next.userId}` : ""}.`
+        );
+        console.log(
+          "Refresh token stored in the OS credential store; no tokens were written to files."
+        );
+        return;
+      }
+      if ((result.error === "invalid_client" || result.error === "unauthorized_client") && !retriedWithRegistration) {
+        retriedWithRegistration = true;
+        const registered = await registerClient(apiBase, redirectUri);
+        if (registered && registered !== clientId) {
+          clientId = registered;
+          console.log(
+            "Client was not recognized; registered a fresh client and retrying sign-in."
+          );
+          continue;
+        }
+      }
+      if (result.error === "iss_missing" || result.error === "iss_mismatch")
+        throw new Error(
+          "AUTH_ISS_MISMATCH: The callback issuer is missing or does not match the API base. Retry memroot login."
+        );
+      throw new OAuthError(
+        result.error,
+        `AUTH_AUTHORIZATION_FAILED: ${result.error}${result.description ? ` \u2014 ${result.description}` : ""}`
+      );
+    }
+  } finally {
+    waiter.close();
+  }
+}
+async function logout(options) {
+  const config = await readConfig();
+  const apiBase = resolveApiBase(options, config);
+  const stored = await readSecret(apiBase).catch(() => void 0);
+  if (stored) {
+    const clientId = config.clientId && config.clientIdApiBase === apiBase ? config.clientId : STATIC_CLIENT_ID;
+    try {
+      await revokeRefreshToken(apiBase, stored, clientId);
+    } catch (error) {
+      console.error(
+        `AUTH_REVOKE_FAILED: ${error instanceof Error ? error.message : "revocation failed"} Removing local credentials anyway.`
+      );
+    }
+  }
+  try {
+    await deleteSecret(apiBase);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.startsWith("AUTH_KEYCHAIN_UNAVAILABLE")) throw error;
+    console.error(message);
+  }
+  cachedAccessToken = void 0;
+  const next = { schemaVersion: 1 };
+  if (config.apiBase) next.apiBase = config.apiBase;
+  await writeConfig(next);
+  console.log("Signed out. Stored credentials and client state were removed.");
+}
+async function whoami(options) {
+  const config = await readConfig();
+  const apiBase = resolveApiBase(options, config);
+  const token = await getAccessToken({ ...options, apiBase });
+  const claims = decodeClaims(token);
+  if (!claims)
+    throw new Error(
+      "AUTH_RESPONSE_INVALID: Could not decode the access token claims."
+    );
+  console.log(`Signed in to ${apiBase}`);
+  console.log(
+    `  sub: ${typeof claims.sub === "string" ? claims.sub : "unknown"}`
+  );
+  console.log(
+    `  iss: ${typeof claims.iss === "string" ? claims.iss : "unknown"}`
+  );
+  console.log(
+    `  exp: ${claimsExpiry(claims) ? new Date(claimsExpiry(claims)).toISOString() : "unknown"}`
+  );
+}
+async function printAccessToken(options) {
+  console.log(await getAccessToken(options));
+}
+async function status(options) {
+  const config = await readConfig();
+  const apiBase = resolveApiBase(options, config);
+  console.log(`API base: ${apiBase}`);
+  console.log(`Credential store: ${credentialStoreKind()}`);
+  try {
+    const token = await getAccessToken({ ...options, apiBase });
+    const claims = decodeClaims(token);
+    const subject = typeof claims?.sub === "string" ? claims.sub : config.userId ?? "unknown";
+    const expiry = claimsExpiry(claims) ? `; access token valid until ${new Date(claimsExpiry(claims)).toISOString()}` : "";
+    console.log(`Cloud auth: signed in as ${subject}${expiry}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("AUTH_REQUIRED"))
+      console.log("Cloud auth: not signed in. Run memroot login.");
+    else if (message.startsWith("AUTH_EXPIRED"))
+      console.log(
+        "Cloud auth: stored credentials were rejected. Run memroot login."
+      );
+    else console.log(`Cloud auth: ${message}`);
+  }
+  const data = dataDirectory();
+  console.log("Agents:");
+  for (const agent of agents) {
+    const path = executable(agent);
+    let detail = "no plugin receipt";
+    try {
+      const receipt = await readReceipt(data, agent);
+      if (receipt) detail = `plugin installed (${receipt.version})`;
+    } catch {
+      detail = "plugin receipt unreadable";
+    }
+    console.log(
+      `  ${labels[agent]}: ${path ? "CLI detected" : "CLI not found"}; ${detail}`
+    );
+    if (agent === "codex" && path) {
+      try {
+        console.log(`  ${describeCodexMcp(inspectCodexMcp(path))}`);
+      } catch {
+        console.log(
+          "  Codex MCP: status unavailable; memory verification: not verified."
+        );
+      }
+    }
+  }
+}
+
 // src/index.ts
 var installationDocs = {
   claude: "https://code.claude.com/docs/en/quickstart",
   codex: "https://developers.openai.com/codex/cli",
   grok: "https://docs.x.ai/build/overview"
 };
-var setupComplete = "Plugins ready. Cloud memory is not connected.";
-var cloudStatus = "Cloud memory: not connected. This installer alpha does not provide cloud authentication, memory retrieval, or session upload.";
-var help = `Memroot ${version} \u2014 native agent plugin installer
+var setupComplete = "Plugins ready. Codex uses native MCP OAuth; other agent adapters use memroot login.";
+var cloudStatus = "Cloud memory: Codex setup links production MCP through its browser sign-in. Other adapters use memroot login. Automatic session upload is not available.";
+var help = `Memroot ${version} \u2014 native agent plugin installer and cloud sign-in
 
 Usage:
   npx memroot setup
   memroot setup --agent codex --yes
   memroot setup --agent claude --agent grok --yes --dry-run
+  memroot login
   memroot doctor
+  memroot status
 
 Commands:
   setup       Install native plugins for your user account
   doctor      Check installer receipts and plugin file integrity
+  login       Connect your Memroot account via browser sign-in
+  logout      Remove stored cloud credentials
+  whoami      Show the signed-in account identity
+  status      Show cloud auth and agent install state
+  token       Print a fresh access token for agent adapters
 
 Options:
-  --agent     claude, codex, or grok; repeat to select more than one
-  --yes       Use the explicitly selected agents without interactive prompts
-  --dry-run   Show planned changes without running agent CLIs or writing files
-  --help      Show help
-  --version   Show version
+  --agent       claude, codex, or grok; repeat to select more than one (setup, doctor)
+  --yes         Use the explicitly selected agents without prompts (setup)
+  --dry-run     Show planned changes without running agent CLIs or writing files (setup)
+  --no-browser  Print the sign-in URL instead of opening a browser (login)
+  --force       Re-authenticate even if credentials are still valid (login)
+  --env         prod or dev; dev targets a local API stub on localhost:8787
+  --api-base    Override the API base URL (MEMROOT_API_BASE also works)
+  --help        Show help
+  --version     Show version
 
 ${cloudStatus}
 Grok setup trusts the selected local plugin via its native --trust option.
 Hook execution trust remains controlled by each agent.
 `;
+var commands = [
+  "setup",
+  "doctor",
+  "login",
+  "logout",
+  "whoami",
+  "status",
+  "token"
+];
+var authCommands = [
+  "login",
+  "logout",
+  "whoami",
+  "status",
+  "token"
+];
 function parse(args) {
-  const command = args.shift();
-  if (command !== "setup" && command !== "doctor")
+  const command2 = args.shift();
+  if (!command2 || !commands.includes(command2))
     throw new Error(
-      "INVALID_ARGUMENT: Choose setup or doctor. Run memroot --help."
+      "INVALID_ARGUMENT: Choose setup, doctor, login, logout, whoami, status, or token. Run memroot --help."
     );
-  const options = { command, selected: [], yes: false, dryRun: false };
+  const options = {
+    command: command2,
+    selected: [],
+    yes: false,
+    dryRun: false,
+    noBrowser: false,
+    force: false
+  };
   while (args.length) {
     const flag = args.shift();
     if (flag === "--yes") options.yes = true;
     else if (flag === "--dry-run") options.dryRun = true;
-    else if (flag === "--agent") {
+    else if (flag === "--no-browser") options.noBrowser = true;
+    else if (flag === "--force") options.force = true;
+    else if (flag === "--env") {
+      const value = args.shift();
+      if (value !== "prod" && value !== "dev")
+        throw new Error("INVALID_ARGUMENT: --env must be prod or dev.");
+      options.env = value;
+    } else if (flag === "--api-base") {
+      const value = args.shift();
+      try {
+        if (!value) throw new Error("missing");
+        new URL(value);
+      } catch {
+        throw new Error("INVALID_ARGUMENT: --api-base needs a valid URL.");
+      }
+      options.apiBase = value;
+    } else if (flag === "--agent") {
       const value = args.shift();
       if (!agents.includes(value))
         throw new Error("INVALID_AGENT: Use claude, codex, or grok.");
@@ -1536,7 +2605,20 @@ function parse(args) {
         `INVALID_ARGUMENT: Unknown option ${flag}. Run memroot --help.`
       );
   }
-  if (command === "doctor" && (options.yes || options.dryRun))
+  if (authCommands.includes(command2)) {
+    if (options.selected.length || options.yes || options.dryRun)
+      throw new Error(
+        `INVALID_ARGUMENT: ${command2} does not support --agent, --yes, or --dry-run.`
+      );
+    if (command2 !== "login" && (options.noBrowser || options.force))
+      throw new Error(
+        `INVALID_ARGUMENT: ${command2} does not support --no-browser or --force.`
+      );
+  } else if (options.noBrowser || options.force || options.env || options.apiBase)
+    throw new Error(
+      `INVALID_ARGUMENT: ${command2} does not support cloud sign-in options.`
+    );
+  if (command2 === "doctor" && (options.yes || options.dryRun))
     throw new Error("INVALID_ARGUMENT: doctor supports only --agent.");
   return options;
 }
@@ -1564,6 +2646,8 @@ async function doctor(selected) {
       console.log(
         `${labels[agent]}: plugin files verified (${receipt.version}); CLI ${path ? "detected" : "not found"}. ${path ? "Native plugin present" : "Native presence not verified"}; hook execution trust remains controlled by the agent.`
       );
+      if (agent === "codex" && path)
+        console.log(describeCodexMcp(inspectCodexMcp(path)));
       if (!path) failures++;
     } catch (error) {
       failures++;
@@ -1587,7 +2671,7 @@ async function setup(options) {
   if (interactive) {
     intro(`Memroot ${version}`);
     note(
-      "Install Memroot plugins for your coding agents.\nCloud memory connection is not available in this alpha.",
+      "Install Memroot plugins for your coding agents.\nCodex setup opens browser sign-in for production memory.",
       "Set up your agents"
     );
     if (!options.selected.length) {
@@ -1632,6 +2716,10 @@ ${summary}`);
       console.log(
         `${agent}: ${JSON.stringify(installCommands(agent, `${data}/releases/${version}/${agent}`))}`
       );
+    if (options.selected.includes("codex"))
+      console.log(
+        `codex: mcp add memroot --url ${codexMcpUrl} --oauth-resource ${codexMcpUrl}; reuse existing OAuth authorization.`
+      );
     return;
   }
   if (interactive) {
@@ -1663,17 +2751,41 @@ ${summary}`);
         console.log(
           `${labels[agent]}: already installed; plugin files verified. Check native enablement in the agent.`
         );
+        if (agent === "codex")
+          console.log(
+            describeCodexMcp(await ensureCodexMcp({ dryRun: false }))
+          );
         continue;
       }
-      const commands = installCommands(agent, candidate.marketplace);
-      if (state.registered && (!receipt || receipt.marketplace === candidate.marketplace))
-        commands.shift();
-      for (const args of commands)
+      const commands2 = installCommands(agent, candidate.marketplace);
+      if (agent === "codex" && receipt && state.registered && !state.currentMarketplace) {
+        const removeHelp = native(found.get(agent), agent, [
+          "plugin",
+          "marketplace",
+          "remove",
+          "--help"
+        ]);
+        if (!removeHelp.includes("--json"))
+          throw new Error(
+            "NATIVE_COMMAND_UNSUPPORTED: Update Codex to support marketplace remove --json before upgrading Memroot. The previous installation is preserved."
+          );
+        native(found.get(agent), agent, [
+          "plugin",
+          "marketplace",
+          "remove",
+          "memroot",
+          "--json"
+        ]);
+      }
+      if (state.currentMarketplace) commands2.shift();
+      for (const args of commands2)
         native(found.get(agent), agent, args);
       await writeReceipt(data, candidate);
       console.log(
         `${labels[agent]}: plugin installed. Restart the agent to load it.`
       );
+      if (agent === "codex")
+        console.log(describeCodexMcp(await ensureCodexMcp({ dryRun: false })));
     }
   } finally {
     await release();
@@ -1692,12 +2804,22 @@ async function main() {
     return;
   }
   const options = parse(args);
-  if (options.command === "doctor") await doctor(options.selected);
-  else await setup(options);
+  const auth = {};
+  if (options.env) auth.env = options.env;
+  if (options.apiBase) auth.apiBase = options.apiBase;
+  if (options.noBrowser) auth.noBrowser = true;
+  if (options.force) auth.force = true;
+  if (options.command === "setup") await setup(options);
+  else if (options.command === "doctor") await doctor(options.selected);
+  else if (options.command === "login") await login(auth);
+  else if (options.command === "logout") await logout(auth);
+  else if (options.command === "whoami") await whoami(auth);
+  else if (options.command === "status") await status(auth);
+  else await printAccessToken(auth);
 }
 main().catch((error) => {
   console.error(
-    error instanceof Error ? error.message : "SETUP_FAILED: Unexpected installer failure."
+    error instanceof Error ? error.message : "MEMROOT_FAILED: Unexpected CLI failure."
   );
   process.exitCode = 1;
 });