@mindbridgeio/muse 0.1.0

package/dist/agent-oauth.mjs

@@ -0,0 +1,984 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { cp, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+export const DEFAULT_SERVER_URL = "https://memory.ifelse.io";
+
+const KEYRING_SERVICE = "mindbridge-agent-oauth";
+const ACCESS_TOKEN_SKEW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const AUTH_TIMEOUT_MS = 5 * 60_000;
+const LOCK_TIMEOUT_MS = 35_000;
+const LOCK_STALE_MARGIN_MS = 15_000;
+// Keep a valid browser flow leased until it can finish, plus a small margin.
+const LOCK_STALE_MS = AUTH_TIMEOUT_MS + LOCK_STALE_MARGIN_MS;
+const LOCK_RETRY_MS = 50;
+const OUTBOX_MAX_BYTES = 10 * 1024 * 1024;
+const OUTBOX_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+const nativeRequire = createRequire(import.meta.url);
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function oauthError(reason, status) {
+  const error = new Error(`MindBridge OAuth ${reason.replaceAll("_", " ")}`);
+  error.reason = reason;
+  error.status = status;
+  return error;
+}
+
+export function oauthReason(error) {
+  return typeof error?.reason === "string" ? error.reason : "oauth_failed";
+}
+
+function loopback(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+/** Normalizes a trusted server URL; plain HTTP is limited to local development. */
+export function normalizeServerURL(value = DEFAULT_SERVER_URL) {
+  let parsed;
+  try {
+    parsed = new URL(text(value) || DEFAULT_SERVER_URL);
+  } catch {
+    throw oauthError("invalid_server_url");
+  }
+  if (parsed.username || parsed.password || parsed.hash || parsed.search || !parsed.hostname) throw oauthError("invalid_server_url");
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback(parsed.hostname))) {
+    throw oauthError("insecure_server_url");
+  }
+  parsed.pathname = parsed.pathname.replace(/\/mcp\/?$/i, "");
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+function platformConfigRoot({ env = process.env, home = homedir() } = {}) {
+  if (text(env.XDG_CONFIG_HOME)) return text(env.XDG_CONFIG_HOME);
+  if (process.platform === "win32") return text(env.APPDATA) || join(home, "AppData", "Roaming");
+  if (process.platform === "darwin") return join(home, "Library", "Application Support");
+  return join(home, ".config");
+}
+
+function platformStateRoot({ env = process.env, home = homedir() } = {}) {
+  if (text(env.XDG_STATE_HOME)) return text(env.XDG_STATE_HOME);
+  if (process.platform === "win32") return text(env.LOCALAPPDATA) || text(env.APPDATA) || join(home, "AppData", "Local");
+  if (process.platform === "darwin") return join(home, "Library", "Application Support");
+  return join(home, ".local", "state");
+}
+
+function serverDigest(serverURL) {
+  return createHash("sha256").update(serverURL).digest("hex").slice(0, 20);
+}
+
+function authPaths(host, options = {}) {
+  const configRoot = options.configRoot || platformConfigRoot(options);
+  const stateRoot = options.stateRoot || platformStateRoot(options);
+  return {
+    config: join(configRoot, "mindbridge", `${host}-oauth.json`),
+    lock: join(stateRoot, "mindbridge", "oauth", `${host}-${serverDigest(options.serverURL || "default")}.lock`),
+  };
+}
+
+async function readJSON(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw oauthError("invalid_config");
+  }
+}
+
+async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temp, content, { mode: 0o600 });
+    await rename(temp, path);
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}
+
+/** Reads only the nonsecret persisted server selection. */
+export async function readServerConfig(host, options = {}) {
+  const value = await readJSON(authPaths(host, options).config, undefined);
+  if (!value || typeof value !== "object" || !text(value.serverURL)) return undefined;
+  const mcpOAuthScope = text(value.mcpOAuthScope);
+  return {
+    serverURL: normalizeServerURL(value.serverURL),
+    ...(mcpOAuthScope ? { mcpOAuthScope } : {}),
+  };
+}
+
+export async function resolveServerURL({ host, serverURL, env = process.env, ...options }) {
+  const explicit = text(serverURL) || text(env.MINDBRIDGE_MCP_SERVER_URL);
+  if (explicit) return normalizeServerURL(explicit);
+  const stored = await readServerConfig(host, { ...options, env });
+  return stored?.serverURL || DEFAULT_SERVER_URL;
+}
+
+export async function saveServerConfig(host, serverURL, options = {}) {
+  const normalized = normalizeServerURL(serverURL);
+  const value = { version: 1, serverURL: normalized };
+  const mcpOAuthScope = text(options.mcpOAuthScope);
+  if (mcpOAuthScope) value.mcpOAuthScope = mcpOAuthScope;
+  await atomicWrite(authPaths(host, options).config, `${JSON.stringify(value)}\n`);
+  return normalized;
+}
+
+/** Validates both OAuth resources before setup writes host configuration. */
+export async function preflightServer(serverURL, { fetchImpl = globalThis.fetch, timeoutMs = 6_000 } = {}) {
+  const base = normalizeServerURL(serverURL);
+  const resources = [
+    ["mcp", `${base}/mcp`],
+    ["v1/sessions", `${base}/v1/sessions`],
+  ];
+  for (const [path, expectedResource] of resources) {
+    let response;
+    try {
+      response = await fetchImpl(`${base}/.well-known/oauth-protected-resource/${path}`, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch {
+      throw oauthError("unreachable");
+    }
+    const body = await responseJSON(response);
+    if (!response.ok || text(body.resource) !== expectedResource || !Array.isArray(body.authorization_servers) || !body.authorization_servers.length) {
+      throw oauthError("oauth_metadata_invalid", response.status);
+    }
+  }
+  return { serverURL: base };
+}
+
+function keyringMissing(error) {
+  return /not found|no (?:entry|password)|credentials? not found/i.test(String(error?.message || ""));
+}
+
+async function commandSucceeds(command, args) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: "ignore", shell: false, windowsHide: true });
+    } catch {
+      resolve(false);
+      return;
+    }
+    let settled = false;
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(false);
+    }, 2_000);
+    function finish(value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    }
+    child.once("error", () => finish(false));
+    child.once("close", (code) => finish(code === 0));
+  });
+}
+
+async function ensureLinuxSecretService() {
+  if (process.platform !== "linux") return;
+  if (!text(process.env.DBUS_SESSION_BUS_ADDRESS)) throw oauthError("keychain_unavailable");
+  const gdbus = await commandSucceeds("gdbus", [
+    "introspect", "--session", "--dest", "org.freedesktop.secrets",
+    "--object-path", "/org/freedesktop/secrets",
+  ]);
+  const dbusSend = gdbus || await commandSucceeds("dbus-send", [
+    "--session", "--print-reply", "--dest=org.freedesktop.secrets",
+    "/org/freedesktop/secrets", "org.freedesktop.DBus.Introspectable.Introspect",
+  ]);
+  if (!dbusSend) throw oauthError("keychain_unavailable");
+}
+
+function validCredential(value) {
+  if (!value || typeof value !== "object") return undefined;
+  const accessToken = text(value.accessToken);
+  const refreshToken = text(value.refreshToken);
+  const clientID = text(value.clientID);
+  const expiresAt = Number(value.expiresAt);
+  if (!accessToken || !refreshToken || !clientID || !Number.isFinite(expiresAt)) return undefined;
+  return { accessToken, refreshToken, clientID, expiresAt };
+}
+
+/** A keychain-only credential store. It intentionally has no file fallback. */
+export function createCredentialStore({ host, serverURL, keyring }) {
+  if (!keyring?.Entry) throw oauthError("keychain_unavailable");
+  let entry;
+  try {
+    entry = new keyring.Entry(KEYRING_SERVICE, `${host}:${serverDigest(serverURL)}`);
+  } catch {
+    throw oauthError("keychain_unavailable");
+  }
+  return {
+    async load() {
+      let raw;
+      try {
+        raw = await entry.getPassword();
+      } catch (error) {
+        if (keyringMissing(error)) return undefined;
+        throw oauthError("keychain_unavailable");
+      }
+      if (!raw) return undefined;
+      try {
+        const credential = validCredential(JSON.parse(raw));
+        if (!credential) throw new Error("invalid");
+        return credential;
+      } catch {
+        throw oauthError("keychain_invalid");
+      }
+    },
+    async save(credential) {
+      const valid = validCredential(credential);
+      if (!valid) throw oauthError("invalid_token_response");
+      try {
+        await entry.setPassword(JSON.stringify(valid));
+      } catch {
+        throw oauthError("keychain_unavailable");
+      }
+    },
+    async remove() {
+      try {
+        await entry.deletePassword();
+      } catch (error) {
+        if (!keyringMissing(error)) throw oauthError("keychain_unavailable");
+      }
+    },
+  };
+}
+
+export async function loadKeyring(keyring) {
+  try {
+    // The native Linux binding falls back to kernel keyutils when Secret
+    // Service is unavailable. Probe the durable backend first so setup never
+    // silently accepts a credential store that will disappear at logout.
+    if (!keyring) {
+      await ensureLinuxSecretService();
+      keyring = await import("@napi-rs/keyring");
+    }
+    if (!keyring.Entry) throw new Error("missing Entry");
+    const probeAccount = `probe-${process.pid}-${Date.now()}-${randomBytes(8).toString("hex")}`;
+    const probeValue = randomBytes(16).toString("hex");
+    const probe = new keyring.Entry(KEYRING_SERVICE, probeAccount);
+    try {
+      await probe.setPassword(probeValue);
+      if (await probe.getPassword() !== probeValue) throw new Error("keychain probe mismatch");
+    } finally {
+      try {
+        await probe.deletePassword();
+      } catch {}
+    }
+    return keyring;
+  } catch {
+    throw oauthError("keychain_unavailable");
+  }
+}
+
+/** Copies the package plus its selected native binding next to persistent hooks. */
+export async function copyKeyringRuntime({ targetRoot }) {
+  try {
+    const packageEntry = nativeRequire.resolve("@napi-rs/keyring");
+    const sourceScope = dirname(dirname(packageEntry));
+    const targetScope = join(targetRoot, "node_modules", "@napi-rs");
+    await mkdir(dirname(targetScope), { recursive: true, mode: 0o700 });
+    await cp(sourceScope, targetScope, { recursive: true, force: true, dereference: true });
+  } catch {
+    throw oauthError("keychain_runtime_unavailable");
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** A small cross-process lock for OAuth browser flows and nonsecret state updates. */
+export async function withFileLock(path, fn, { timeoutMs = LOCK_TIMEOUT_MS, staleMs = LOCK_STALE_MS } = {}) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    let handle;
+    try {
+      handle = await open(path, "wx", 0o600);
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw oauthError("lock_unavailable");
+      try {
+        const info = await stat(path);
+        if (Date.now() - info.mtimeMs > staleMs) await unlink(path);
+      } catch {
+        // A competing hook released its lock. The next iteration acquires it.
+      }
+      if (Date.now() >= deadline) throw oauthError("authentication_busy");
+      await sleep(LOCK_RETRY_MS);
+      continue;
+    }
+    await handle.close();
+    try {
+      return await fn();
+    } finally {
+      await unlink(path).catch(() => {});
+    }
+  }
+}
+
+async function responseJSON(response) {
+  const raw = await response.text();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+async function postForm(fetchImpl, url, values, timeoutMs = REQUEST_TIMEOUT_MS) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(values).toString(),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    throw oauthError("unreachable");
+  }
+  return { response, body: await responseJSON(response) };
+}
+
+async function postJSON(fetchImpl, url, value, timeoutMs = REQUEST_TIMEOUT_MS) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(value),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    throw oauthError("unreachable");
+  }
+  return { response, body: await responseJSON(response) };
+}
+
+function equalState(left, right) {
+  if (!left || !right || left.length !== right.length) return false;
+  return timingSafeEqual(Buffer.from(left), Buffer.from(right));
+}
+
+async function loopbackCallback(state, timeoutMs) {
+  let finish;
+  const result = new Promise((resolve, reject) => {
+    finish = { resolve, reject };
+  });
+  let settled = false;
+  let timer;
+  const server = createServer((request, response) => {
+    const callbackURL = new URL(request.url || "/", "http://127.0.0.1");
+    if (request.method !== "GET" || callbackURL.pathname !== "/callback") {
+      response.writeHead(404).end();
+      return;
+    }
+    if (!equalState(callbackURL.searchParams.get("state"), state)) {
+      response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }).end("Invalid OAuth response.");
+      settle(oauthError("authorization_state_invalid"));
+      return;
+    }
+    const code = text(callbackURL.searchParams.get("code"));
+    if (!code || callbackURL.searchParams.has("error")) {
+      response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }).end("Authorization was not completed.");
+      settle(oauthError("authorization_denied"));
+      return;
+    }
+    response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" }).end("MindBridge authorization complete. You can close this tab.");
+    settle(undefined, code);
+  });
+  function settle(error, code) {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    server.close();
+    if (error) finish.reject(error);
+    else finish.resolve(code);
+  }
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw oauthError("loopback_unavailable");
+  }
+  timer = setTimeout(() => settle(oauthError("authorization_timed_out")), timeoutMs);
+  timer.unref?.();
+  return {
+    redirectURI: `http://127.0.0.1:${address.port}/callback`,
+    wait: () => result,
+    close: () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      server.close();
+    },
+  };
+}
+
+/** Opens a browser without putting a token in a shell command or log. */
+export async function openBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
+  const command = platform === "darwin"
+    ? ["open", [url]]
+    : platform === "win32"
+      ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  await new Promise((resolve, reject) => {
+    const child = spawnImpl(command[0], command[1], { stdio: "ignore", windowsHide: true, shell: false });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref?.();
+      resolve();
+    });
+  }).catch(() => {
+    throw oauthError("browser_unavailable");
+  });
+}
+
+function fresh(credential, now) {
+  return credential.expiresAt > now() + ACCESS_TOKEN_SKEW_MS;
+}
+
+function credentialFromToken(body, clientID, now) {
+  const accessToken = text(body.access_token || body.accessToken);
+  const refreshToken = text(body.refresh_token || body.refreshToken);
+  const expiresIn = Number(body.expires_in || body.expiresIn);
+  if (!accessToken || !refreshToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw oauthError("invalid_token_response");
+  }
+  return { accessToken, refreshToken, clientID, expiresAt: now() + expiresIn * 1_000 };
+}
+
+/**
+ * OAuth client for lifecycle hooks. Credential material lives exclusively in
+ * the platform keychain; the companion config record contains only serverURL.
+ */
+export function createOAuthClient({
+  host,
+  serverURL,
+  env = process.env,
+  configRoot,
+  stateRoot,
+  keyring,
+  keyringLoader = loadKeyring,
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+  browser = openBrowser,
+  authorizationTimeoutMs = AUTH_TIMEOUT_MS,
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+} = {}) {
+  const normalizedServerURL = normalizeServerURL(serverURL);
+  const resource = `${normalizedServerURL}/v1/sessions`;
+  const paths = authPaths(host, { env, configRoot, stateRoot, serverURL: normalizedServerURL });
+  let storePromise;
+
+  async function store() {
+    storePromise ??= Promise.resolve(keyring || keyringLoader()).then((loaded) => createCredentialStore({
+      host,
+      serverURL: normalizedServerURL,
+      keyring: loaded,
+    }));
+    return storePromise;
+  }
+
+  async function refresh(credential) {
+    const { response, body } = await postForm(fetchImpl, `${normalizedServerURL}/oauth/token`, {
+      grant_type: "refresh_token",
+      refresh_token: credential.refreshToken,
+      client_id: credential.clientID,
+      resource,
+    }, requestTimeoutMs);
+    if (!response.ok) throw oauthError("refresh_rejected");
+    return credentialFromToken(body, credential.clientID, now);
+  }
+
+  async function register(redirectURI) {
+    const { response, body } = await postJSON(fetchImpl, `${normalizedServerURL}/oauth/register`, {
+      client_name: `MindBridge ${host} lifecycle hooks`,
+      redirect_uris: [redirectURI],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    }, requestTimeoutMs);
+    const clientID = text(body.client_id || body.clientId);
+    if (!response.ok || !clientID) throw oauthError("client_registration_failed");
+    return clientID;
+  }
+
+  async function authorize(credentialStore) {
+    const state = randomBytes(32).toString("base64url");
+    const verifier = randomBytes(48).toString("base64url");
+    const callback = await loopbackCallback(state, authorizationTimeoutMs);
+    try {
+      const clientID = await register(callback.redirectURI);
+      const authorizeURL = new URL(`${normalizedServerURL}/oauth/authorize`);
+      authorizeURL.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientID,
+        redirect_uri: callback.redirectURI,
+        scope: "sessions",
+        resource,
+        state,
+        code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+        code_challenge_method: "S256",
+      }).toString();
+      await browser(authorizeURL.toString());
+      const code = await callback.wait();
+      const { response, body } = await postForm(fetchImpl, `${normalizedServerURL}/oauth/token`, {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: callback.redirectURI,
+        client_id: clientID,
+        code_verifier: verifier,
+        resource,
+      }, requestTimeoutMs);
+      if (!response.ok) throw oauthError("token_rejected");
+      const credential = credentialFromToken(body, clientID, now);
+      await credentialStore.save(credential);
+      return credential;
+    } finally {
+      callback.close();
+    }
+  }
+
+  async function obtain({ force = false, interactive = false } = {}) {
+    const credentialStore = await store();
+    const initial = await credentialStore.load();
+    if (!force && initial && fresh(initial, now)) return initial;
+    if (!interactive && !initial?.refreshToken) throw oauthError("authentication_required");
+    return withFileLock(paths.lock, async () => {
+      const afterWait = await credentialStore.load();
+      if (afterWait && fresh(afterWait, now) && (!force || afterWait.accessToken !== initial?.accessToken)) return afterWait;
+      if (afterWait?.refreshToken) {
+        try {
+          const refreshed = await refresh(afterWait);
+          await credentialStore.save(refreshed);
+          return refreshed;
+        } catch (error) {
+          if (oauthReason(error) !== "refresh_rejected") throw error;
+          await credentialStore.remove();
+        }
+      }
+      if (!interactive) throw oauthError("authentication_required");
+      return authorize(credentialStore);
+    }, { staleMs: authorizationTimeoutMs + LOCK_STALE_MARGIN_MS });
+  }
+
+  async function send(path, body, accessToken, method = "POST") {
+    let response;
+    try {
+      response = await fetchImpl(`${normalizedServerURL}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
+    } catch {
+      throw oauthError("unreachable");
+    }
+    return { response, body: await responseJSON(response) };
+  }
+
+  async function authorizedRequest(path, body, { interactive = false, method = "POST" } = {}) {
+    let credential = await obtain({ interactive });
+    let result;
+    let transientRetried = false;
+    try {
+      result = await send(path, body, credential.accessToken, method);
+    } catch (error) {
+      if (oauthReason(error) !== "unreachable") throw error;
+      transientRetried = true;
+      result = await send(path, body, credential.accessToken, method);
+    }
+    if (result.response.status === 401 || result.response.status === 403) {
+      credential = await obtain({ force: true, interactive });
+      result = await send(path, body, credential.accessToken, method);
+    } else if (!transientRetried && (result.response.status === 408 || result.response.status === 429 || result.response.status >= 500)) {
+      result = await send(path, body, credential.accessToken, method);
+    }
+    if (!result.response.ok) {
+      const status = result.response.status;
+      const reason = status === 401 || status === 403
+        ? "unauthorized"
+        : status === 429
+          ? "rate_limited"
+          : status === 408 || status >= 500
+            ? "server_unavailable"
+            : "request_failed";
+      throw oauthError(reason, status);
+    }
+    return result.body;
+  }
+
+  return {
+    serverURL: normalizedServerURL,
+    async authenticate() {
+      return obtain({ interactive: true });
+    },
+    async status() {
+      const credential = await (await store()).load();
+      return { authenticated: Boolean(credential), expiresAt: credential?.expiresAt };
+    },
+    async logout() {
+      const credentialStore = await store();
+      const credential = await credentialStore.load();
+      if (!credential) return false;
+      try {
+        await postForm(fetchImpl, `${normalizedServerURL}/oauth/revoke`, {
+          token: credential.refreshToken,
+          token_type_hint: "refresh_token",
+          client_id: credential.clientID,
+        }, requestTimeoutMs);
+      } catch {
+        // Revocation is best effort; removing the local keychain entry is not.
+      }
+      await credentialStore.remove();
+      return true;
+    },
+    async request(path, body, { interactive = false, method = "POST" } = {}) {
+      return authorizedRequest(path, body, { interactive, method });
+    },
+    async check() {
+      return authorizedRequest("/v1/sessions/auth/check", undefined, { method: "GET" });
+    },
+  };
+}
+
+function sessionStatePaths(stateRoot, serverURL, externalRef) {
+  const digest = createHash("sha256").update(`${serverURL}\n${externalRef}`).digest("hex").slice(0, 12);
+  return {
+    state: join(stateRoot, `${digest}.json`),
+    lock: join(stateRoot, `${digest}.lock`),
+  };
+}
+
+async function loadState(path) {
+  return readJSON(path, undefined);
+}
+
+async function saveState(path, value) {
+  await atomicWrite(path, `${JSON.stringify(value)}\n`);
+}
+
+function positiveInteger(value, fallback = 1) {
+  return Number.isInteger(value) && value >= 1 ? value : fallback;
+}
+
+function automaticMessageRef(state, role, content) {
+  const assistant = role === "assistant";
+  const key = assistant ? "next_assistant_ref" : "next_user_ref";
+  const pendingKey = assistant ? "pending_assistant_ref" : "pending_user_ref";
+  const prefix = assistant ? "out" : "in";
+  const digest = createHash("sha256").update(`${role}\n${content}`).digest("hex");
+  const pending = state[pendingKey];
+  if (pending?.digest === digest && text(pending.message_ref)) {
+    return { key, pendingKey, value: pending.message_ref, next: positiveInteger(state[key]), digest, reused: true };
+  }
+  const ordinal = positiveInteger(state[key]);
+  return { key, pendingKey, value: `${prefix}:${ordinal}`, next: ordinal + 1, digest, reused: false };
+}
+
+function attribution(host, { userName, agentName, adapterName, adapterRef }) {
+  return {
+    user: { name: userName, external_ref: `${host}:user` },
+    agent: { name: agentName, external_ref: `${host}:agent` },
+    adapter: { kind: host, name: adapterName, external_ref: adapterRef },
+  };
+}
+
+function sessionMetadata(value) {
+  return text(value?.project?.key) ? value : undefined;
+}
+
+/** OAuth-backed lifecycle session client. Session state has no credentials. */
+export function createOAuthSessionClient({ serverURL, oauth, stateRoot }) {
+  function paths(externalRef) {
+    return sessionStatePaths(stateRoot, serverURL, externalRef);
+  }
+  function pendingBytes(state) {
+    const pending = Array.isArray(state?.pending) ? state.pending : [];
+    return pending.length ? Buffer.byteLength(JSON.stringify(pending)) : 0;
+  }
+  async function bytesOutside(excluded) {
+    let names = [];
+    try {
+      names = await readdir(stateRoot);
+    } catch (error) {
+      if (error?.code === "ENOENT") return 0;
+      throw error;
+    }
+    let total = 0;
+    for (const name of names.filter((value) => value.endsWith(".json"))) {
+      const path = join(stateRoot, name);
+      if (path === excluded) continue;
+      try {
+        total += pendingBytes(await loadState(path));
+      } catch (error) {
+        if (error?.code === "ENOENT") continue;
+        // Corrupt state is surfaced by doctor without preventing new writes.
+      }
+    }
+    return total;
+  }
+  async function saveOutbox(path, state) {
+    const content = `${JSON.stringify(state)}\n`;
+    if (pendingBytes(state) + await bytesOutside(path) > OUTBOX_MAX_BYTES) throw oauthError("outbox_full");
+    await atomicWrite(path, content);
+  }
+  async function usableState(path) {
+    const state = await loadState(path);
+    if (!state) return undefined;
+    state.pending = Array.isArray(state.pending) ? state.pending : [];
+    if (!state.quarantined && state.pending.some((entry) => Date.now() - Number(entry.created_at || 0) > OUTBOX_MAX_AGE_MS)) {
+      state.pending = [];
+      state.quarantined = { reason: "expired", at: Date.now() };
+      await saveState(path, state);
+    }
+    return state;
+  }
+  async function requireState(externalRef) {
+    const state = await usableState(paths(externalRef).state);
+    if (!state || (!state.session_id && !state.pending.some((entry) => entry.kind === "start"))) {
+      throw oauthError("missing_session_state");
+    }
+    if (state.quarantined) throw oauthError(`outbox_${state.quarantined.reason}`);
+    return state;
+  }
+  async function flush(path, state) {
+    let lastResult;
+    while (state.pending.length) {
+      const entry = state.pending[0];
+      const dynamicPath = entry.kind === "append"
+        ? `/v1/sessions/${encodeURIComponent(state.session_id)}/messages`
+        : entry.kind === "end"
+          ? `/v1/sessions/${encodeURIComponent(state.session_id)}/end`
+          : entry.kind === "reopen"
+            ? `/v1/sessions/${encodeURIComponent(state.session_id)}/reopen`
+            : entry.path;
+      lastResult = await oauth.request(dynamicPath, entry.body);
+      if (entry.kind === "start") {
+        const sessionID = text(lastResult.session_id);
+        if (!sessionID) throw oauthError("invalid_start_response");
+        state.session_id = sessionID;
+        state.metadata = sessionMetadata(lastResult.metadata) || state.metadata || sessionMetadata(entry.body.metadata);
+      }
+      if (entry.kind === "append" && entry.automatic) {
+        const pendingKey = entry.body.role === "assistant" ? "pending_assistant_ref" : "pending_user_ref";
+        if (state[pendingKey]?.message_ref === entry.body.external_ref) delete state[pendingKey];
+      }
+      state.pending.shift();
+      if (entry.kind === "end") state.ended = true;
+      if (entry.kind === "reopen") {
+        state.ended = false;
+        state.end_reason = "";
+      }
+      await saveOutbox(path, state);
+    }
+    return lastResult;
+  }
+  async function enqueue(path, state, entry, { front = false } = {}) {
+    const pending = { ...entry, created_at: Date.now() };
+    if (front) state.pending.unshift(pending);
+    else state.pending.push(pending);
+    try {
+      await saveOutbox(path, state);
+    } catch (error) {
+      if (front) state.pending.shift();
+      else state.pending.pop();
+      if (oauthReason(error) === "outbox_full") {
+        state.loss = { reason: "full", at: Date.now() };
+        await saveState(path, state);
+      }
+      throw error;
+    }
+  }
+  return {
+    async start({ externalRef, host, userName, agentName, adapterName, adapterRef, metadata }) {
+      const { state, lock } = paths(externalRef);
+      return withFileLock(lock, async () => {
+        const prior = await usableState(state);
+        const pendingStart = prior?.pending?.find((entry) => entry.kind === "start");
+        const startMetadata = sessionMetadata(prior?.metadata)
+          || sessionMetadata(pendingStart?.body?.metadata)
+          || sessionMetadata(metadata);
+        const body = {
+          external_ref: externalRef,
+          attribution: attribution(host, { userName, agentName, adapterName, adapterRef }),
+        };
+        if (startMetadata) body.metadata = startMetadata;
+        let current = prior;
+        let result;
+        if (!current) {
+          current = {
+            version: 1,
+            server_url: serverURL,
+            session_id: "",
+            external_ref: externalRef,
+            metadata: startMetadata,
+            next_user_ref: 1,
+            next_assistant_ref: 1,
+            ended: false,
+            end_reason: "",
+            pending: [],
+          };
+          await enqueue(state, current, { kind: "start", path: "/v1/sessions", body });
+          result = await flush(state, current);
+        } else if (!current.session_id) {
+          const queuedStart = current.pending.find((entry) => entry.kind === "start");
+          if (queuedStart) {
+            if (!sessionMetadata(queuedStart.body.metadata) && startMetadata) queuedStart.body.metadata = startMetadata;
+            current.metadata = sessionMetadata(current.metadata) || sessionMetadata(queuedStart.body.metadata);
+            await saveOutbox(state, current);
+          } else {
+            await enqueue(state, current, { kind: "start", path: "/v1/sessions", body }, { front: true });
+          }
+          result = await flush(state, current);
+        } else {
+          result = await oauth.request("/v1/sessions", body);
+          const sessionID = text(result.session_id);
+          if (!sessionID) throw oauthError("invalid_start_response");
+          current.session_id = sessionID;
+          current.metadata = sessionMetadata(result.metadata) || sessionMetadata(current.metadata) || startMetadata;
+          current.next_user_ref = positiveInteger(current.next_user_ref);
+          current.next_assistant_ref = positiveInteger(current.next_assistant_ref);
+          current.ended = Boolean(current.ended);
+          current.end_reason = text(current.end_reason);
+          current.pending = Array.isArray(current.pending) ? current.pending : [];
+          await saveOutbox(state, current);
+          await flush(state, current);
+        }
+        current.metadata = sessionMetadata(result?.metadata) || sessionMetadata(current.metadata) || startMetadata;
+        await saveOutbox(state, current);
+        return { session_id: current.session_id, metadata: current.metadata, prompt_block: text(result?.memory_block?.prompt_block) };
+      });
+    },
+    async append({ externalRef, role, eventType = "message", content, messageRef }) {
+      const { state, lock } = paths(externalRef);
+      return withFileLock(lock, async () => {
+        const current = await requireState(externalRef);
+        if (current.ended) throw oauthError("session_ended");
+        const automaticRef = messageRef ? undefined : automaticMessageRef(current, role, content);
+        const externalMessageRef = text(messageRef) || automaticRef.value;
+        if (automaticRef && !automaticRef.reused) {
+          current[automaticRef.key] = automaticRef.next;
+          current[automaticRef.pendingKey] = { message_ref: automaticRef.value, digest: automaticRef.digest };
+        }
+        const body = { role, event_type: eventType, content, external_ref: externalMessageRef };
+        await enqueue(state, current, {
+          kind: "append",
+          body,
+          automatic: Boolean(automaticRef),
+        });
+        await flush(state, current);
+        return { session_id: current.session_id, message_ref: externalMessageRef };
+      });
+    },
+    async reopen({ externalRef }) {
+      const { state, lock } = paths(externalRef);
+      return withFileLock(lock, async () => {
+        const current = await requireState(externalRef);
+        await enqueue(state, current, {
+          kind: "reopen",
+          body: {},
+        }, { front: true });
+        await flush(state, current);
+        return { session_id: current.session_id };
+      });
+    },
+    async end({ externalRef, reason }) {
+      const { state, lock } = paths(externalRef);
+      return withFileLock(lock, async () => {
+        const current = await requireState(externalRef);
+        const endReason = text(current.end_reason) || text(reason) || "unknown";
+        if (!current.end_reason) {
+          current.end_reason = endReason;
+        }
+        if (!current.pending.some((entry) => entry.kind === "end")) {
+          await enqueue(state, current, {
+            kind: "end",
+            body: { end_reason: endReason },
+          });
+        }
+        await flush(state, current);
+        return { session_id: current.session_id, end_reason: endReason };
+      });
+    },
+    async flushAll({ excludeExternalRef = "", limit = 1 } = {}) {
+      let names = [];
+      try {
+        names = await readdir(stateRoot);
+      } catch (error) {
+        if (error?.code === "ENOENT") return 0;
+        throw error;
+      }
+      const excluded = excludeExternalRef ? paths(excludeExternalRef).state : "";
+      let flushed = 0;
+      for (const name of names.filter((value) => value.endsWith(".json")).sort()) {
+        if (flushed >= limit) break;
+        const statePath = join(stateRoot, name);
+        if (statePath === excluded) continue;
+        try {
+          await withFileLock(statePath.replace(/\.json$/, ".lock"), async () => {
+            const current = await usableState(statePath);
+            if (!current?.pending?.length || current.quarantined) return;
+            await flush(statePath, current);
+            flushed += 1;
+          }, { timeoutMs: 500, staleMs: LOCK_STALE_MS });
+        } catch {
+          // A previous session never delays the current host event.
+        }
+      }
+      return flushed;
+    },
+  };
+}
+
+export async function outboxStatus(stateRoot) {
+  let names = [];
+  try {
+    names = await readdir(stateRoot);
+  } catch (error) {
+    if (error?.code === "ENOENT") return { pending: 0, sessions: 0, bytes: 0, oldestAt: undefined, losses: 0 };
+    throw error;
+  }
+  const result = { pending: 0, sessions: 0, bytes: 0, oldestAt: undefined, losses: 0 };
+  for (const name of names.filter((value) => value.endsWith(".json"))) {
+    const path = join(stateRoot, name);
+    try {
+      const state = await loadState(path);
+      const pending = Array.isArray(state?.pending) ? state.pending : [];
+      if (pending.length) result.bytes += Buffer.byteLength(JSON.stringify(pending));
+      if (pending.length) result.sessions += 1;
+      result.pending += pending.length;
+      if (state?.quarantined || state?.loss) result.losses += 1;
+      for (const entry of pending) {
+        const created = Number(entry.created_at || 0);
+        if (created && (!result.oldestAt || created < result.oldestAt)) result.oldestAt = created;
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") result.losses += 1;
+    }
+  }
+  return result;
+}
+
+export function agentHookStateRoot({ env = process.env, home = homedir(), stateRoot } = {}) {
+  return stateRoot || join(platformStateRoot({ env, home }), "mindbridge", "agent-hooks");
+}