@remnic/server 9.3.768 → 9.3.770

package/dist/index.js

@@ -3,7 +3,685 @@
 // src/index.ts
 import fs from "fs";
 import path from "path";
-import { parseConfig, isOpenaiApiKeyDisabled, resolveRemnicConfigRecord, Orchestrator, EngramAccessService, EngramAccessHttpServer, initLogger, log, getAllValidTokens, getAllValidTokensCached, expandTildePath } from "@remnic/core";
+import { parseConfig, isOpenaiApiKeyDisabled, resolveRemnicConfigRecord, Orchestrator, EngramAccessService, EngramAccessHttpServer, initLogger, log as log2, getAllValidTokens, getAllValidTokenEntriesCached, expandTildePath } from "@remnic/core";
+
+// src/oauth.ts
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+import express from "express";
+import { rateLimit } from "express-rate-limit";
+import { authorizationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/authorize.js";
+import { tokenHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/token.js";
+import { createOAuthMetadata, mcpAuthMetadataRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import {
+  InvalidGrantError,
+  InvalidTokenError,
+  ServerError,
+  UnsupportedGrantTypeError
+} from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { buildTokenEntry, commitTokenEntry, getAllValidTokensCached, log } from "@remnic/core";
+var ALLOWED_TOKEN_AUTH_METHODS = ["client_secret_post", "none"];
+var DEFAULT_APPROVAL_TTL_SECONDS = 600;
+var AUTHORIZATION_CODE_TTL_MS = 12e4;
+var HIGH_ENTROPY_HEX_BYTES = 16;
+var CHATGPT_CONNECTOR_ID = "chatgpt";
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function coerceBoolean(value, source) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized)) return true;
+    if (["false", "0", "no", "off"].includes(normalized)) return false;
+  }
+  throw new Error(`Invalid ${source}: expected a boolean (got: ${JSON.stringify(value)})`);
+}
+function coerceNonEmptyString(value, source) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${source}: expected a non-empty string`);
+  }
+  return value.trim();
+}
+function coercePositiveInteger(value, source) {
+  const num = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  if (typeof num !== "number" || !Number.isInteger(num) || num <= 0) {
+    throw new Error(`Invalid ${source}: expected a positive integer (got: ${JSON.stringify(value)})`);
+  }
+  return num;
+}
+function coerceAbsoluteHttpsUrl(value, source, opts) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${source}: expected a non-empty URL string`);
+  }
+  const trimmed = value.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Invalid ${source}: "${trimmed}" is not a valid URL`);
+  }
+  if (parsed.hash || parsed.search) {
+    throw new Error(`Invalid ${source}: URL must not include a query string or fragment`);
+  }
+  const isHttps = parsed.protocol === "https:";
+  const isLocalhostHttp = opts.allowHttpForLocalhost && parsed.protocol === "http:" && (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost");
+  if (!isHttps && !isLocalhostHttp) {
+    throw new Error(
+      `Invalid ${source}: must be an absolute https:// URL (http:// allowed only for 127.0.0.1/localhost)`
+    );
+  }
+  return trimmed;
+}
+function coerceTokenAuthMethod(value, source) {
+  if (typeof value !== "string") {
+    throw new Error(`Invalid ${source}: expected one of ${ALLOWED_TOKEN_AUTH_METHODS.join(", ")}`);
+  }
+  const trimmed = value.trim();
+  const match = ALLOWED_TOKEN_AUTH_METHODS.find((method) => method === trimmed);
+  if (!match) {
+    throw new Error(
+      `Invalid ${source}: "${trimmed}" is not allowed. Use one of ${ALLOWED_TOKEN_AUTH_METHODS.join(", ")}.`
+    );
+  }
+  return match;
+}
+function coerceRedirectUris(value, source) {
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid ${source}: expected an array of exact redirect URI strings`);
+  }
+  return value.map(
+    (entry, index) => coerceAbsoluteHttpsUrl(entry, `${source}[${index}]`, { allowHttpForLocalhost: true })
+  );
+}
+var DISABLED_OAUTH_CONFIG = {
+  enabled: false,
+  issuerUrl: "",
+  clientId: "",
+  clientSecret: "",
+  tokenEndpointAuthMethod: "client_secret_post",
+  redirectUris: [],
+  approvalTtlSeconds: DEFAULT_APPROVAL_TTL_SECONDS
+};
+function parseOAuthConfig(raw) {
+  if (raw === void 0) return { ...DISABLED_OAUTH_CONFIG };
+  if (!isPlainObject(raw)) {
+    throw new Error("Invalid server.oauth: expected a JSON object");
+  }
+  const input = raw;
+  const enabled = input.enabled === void 0 ? false : coerceBoolean(input.enabled, "server.oauth.enabled");
+  if (!enabled) return { ...DISABLED_OAUTH_CONFIG };
+  const issuerUrl = input.issuerUrl === void 0 ? "" : coerceAbsoluteHttpsUrl(input.issuerUrl, "server.oauth.issuerUrl", { allowHttpForLocalhost: true });
+  const clientId = input.clientId === void 0 ? "" : coerceNonEmptyString(input.clientId, "server.oauth.clientId");
+  const clientSecret = input.clientSecret === void 0 ? "" : coerceNonEmptyString(input.clientSecret, "server.oauth.clientSecret");
+  const tokenEndpointAuthMethod = input.tokenEndpointAuthMethod === void 0 ? "client_secret_post" : coerceTokenAuthMethod(input.tokenEndpointAuthMethod, "server.oauth.tokenEndpointAuthMethod");
+  const redirectUris = input.redirectUris === void 0 ? [] : coerceRedirectUris(input.redirectUris, "server.oauth.redirectUris");
+  const approvalTtlSeconds = input.approvalTtlSeconds === void 0 ? DEFAULT_APPROVAL_TTL_SECONDS : coercePositiveInteger(input.approvalTtlSeconds, "server.oauth.approvalTtlSeconds");
+  if (issuerUrl === "") {
+    throw new Error("Invalid server.oauth.issuerUrl: required when enabled (absolute https URL)");
+  }
+  if (clientId === "") {
+    throw new Error("Invalid server.oauth.clientId: required when enabled (non-empty string)");
+  }
+  if (tokenEndpointAuthMethod !== "none" && clientSecret === "") {
+    throw new Error(
+      `Invalid server.oauth.clientSecret: required when enabled and tokenEndpointAuthMethod is "${tokenEndpointAuthMethod}"`
+    );
+  }
+  return {
+    enabled: true,
+    issuerUrl,
+    clientId,
+    clientSecret,
+    tokenEndpointAuthMethod,
+    redirectUris,
+    approvalTtlSeconds
+  };
+}
+function readOAuthEnvOverrides() {
+  const overrides = {};
+  if (process.env.REMNIC_OAUTH_ENABLED !== void 0) overrides.enabled = process.env.REMNIC_OAUTH_ENABLED;
+  if (process.env.REMNIC_OAUTH_ISSUER_URL !== void 0) overrides.issuerUrl = process.env.REMNIC_OAUTH_ISSUER_URL;
+  if (process.env.REMNIC_OAUTH_CLIENT_ID !== void 0) overrides.clientId = process.env.REMNIC_OAUTH_CLIENT_ID;
+  if (process.env.REMNIC_OAUTH_CLIENT_SECRET !== void 0) {
+    overrides.clientSecret = process.env.REMNIC_OAUTH_CLIENT_SECRET;
+  }
+  if (process.env.REMNIC_OAUTH_TOKEN_AUTH_METHOD !== void 0) {
+    overrides.tokenEndpointAuthMethod = process.env.REMNIC_OAUTH_TOKEN_AUTH_METHOD;
+  }
+  if (process.env.REMNIC_OAUTH_REDIRECT_URIS !== void 0) {
+    overrides.redirectUris = process.env.REMNIC_OAUTH_REDIRECT_URIS.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  }
+  if (process.env.REMNIC_OAUTH_APPROVAL_TTL_SECONDS !== void 0) {
+    overrides.approvalTtlSeconds = process.env.REMNIC_OAUTH_APPROVAL_TTL_SECONDS;
+  }
+  return overrides;
+}
+function applyOAuthEnvOverrides(fileBlock) {
+  if (fileBlock !== void 0 && !isPlainObject(fileBlock)) {
+    return parseOAuthConfig(fileBlock);
+  }
+  const overrides = readOAuthEnvOverrides();
+  const merged = isPlainObject(fileBlock) ? { ...fileBlock } : {};
+  for (const [key, value] of Object.entries(overrides)) {
+    merged[key] = value;
+  }
+  return parseOAuthConfig(merged);
+}
+function timingSafeStringEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const digestA = createHash("sha256").update(a, "utf8").digest();
+  const digestB = createHash("sha256").update(b, "utf8").digest();
+  return timingSafeEqual(digestA, digestB);
+}
+function randomHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+function newApprovalRef() {
+  return BigInt(`0x${randomHex(8)}`).toString(36);
+}
+var OAuthState = class {
+  pending = /* @__PURE__ */ new Map();
+  codes = /* @__PURE__ */ new Map();
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  get approvalTtlMs() {
+    return this.config.approvalTtlSeconds * 1e3;
+  }
+  /** Delete expired entries. Run before each lookup. */
+  gc(now) {
+    for (const [key, code] of this.codes) {
+      if (code.expiresAt < now) this.codes.delete(key);
+    }
+    for (const [key, txn] of this.pending) {
+      if (txn.expiresAt >= now) continue;
+      if (txn.outcome?.kind === "approved" && this.codes.has(txn.outcome.code)) continue;
+      this.pending.delete(key);
+    }
+  }
+  createPending(args) {
+    const now = Date.now();
+    this.gc(now);
+    const txn = {
+      txn: randomHex(HIGH_ENTROPY_HEX_BYTES),
+      pollSecret: randomHex(HIGH_ENTROPY_HEX_BYTES),
+      ref: newApprovalRef(),
+      clientId: args.clientId,
+      redirectUri: args.redirectUri,
+      scopes: args.scopes,
+      resource: args.resource,
+      state: args.state,
+      codeChallenge: args.codeChallenge,
+      createdAt: now,
+      expiresAt: now + this.approvalTtlMs
+    };
+    this.pending.set(txn.txn, txn);
+    return txn;
+  }
+  listPending() {
+    const now = Date.now();
+    this.gc(now);
+    return Array.from(this.pending.values()).filter((txn) => !txn.outcome).sort((a, b) => a.createdAt === b.createdAt ? a.txn.localeCompare(b.txn) : a.createdAt - b.createdAt);
+  }
+  findByRef(ref) {
+    const now = Date.now();
+    this.gc(now);
+    for (const txn of this.pending.values()) {
+      if (txn.ref === ref) return txn;
+    }
+    return void 0;
+  }
+  /**
+   * Approve a pending transaction by ref. Returns the authorization code.
+   * Re-approval of an already-approved txn returns the same code so the
+   * operator can recover from a client-side miss. Throws on
+   * missing/expired/denied.
+   */
+  approveByRef(ref) {
+    const now = Date.now();
+    this.gc(now);
+    const txn = this.findByRef(ref);
+    if (!txn) throw new Error("unknown or expired ref");
+    if (txn.outcome) {
+      if (txn.outcome.kind === "approved") return { code: txn.outcome.code, txn };
+      throw new Error("denied");
+    }
+    const code = randomHex(HIGH_ENTROPY_HEX_BYTES);
+    this.codes.set(code, {
+      code,
+      clientId: txn.clientId,
+      redirectUri: txn.redirectUri,
+      codeChallenge: txn.codeChallenge,
+      resource: txn.resource,
+      expiresAt: now + AUTHORIZATION_CODE_TTL_MS,
+      consumed: false
+    });
+    txn.outcome = { kind: "approved", code };
+    return { code, txn };
+  }
+  denyByRef(ref) {
+    const now = Date.now();
+    this.gc(now);
+    const txn = this.findByRef(ref);
+    if (!txn) throw new Error("unknown or expired ref");
+    if (txn.outcome) {
+      if (txn.outcome.kind === "denied") return;
+      throw new Error("already approved");
+    }
+    txn.outcome = { kind: "denied" };
+  }
+  /** Redirect target carrying the code (+ state) back to the client. */
+  buildRedirect(txn, code) {
+    const url = new URL(txn.redirectUri);
+    url.searchParams.set("code", code);
+    if (txn.state) url.searchParams.set("state", txn.state);
+    return url.toString();
+  }
+  /** Poll status; `undefined` on wrong pollSecret. */
+  poll(txnId, pollSecret) {
+    const now = Date.now();
+    this.gc(now);
+    const txn = this.pending.get(txnId);
+    if (!txn) return { status: "expired" };
+    if (!timingSafeStringEqual(txn.pollSecret, pollSecret)) return void 0;
+    if (!txn.outcome) {
+      if (txn.expiresAt < now) return { status: "expired" };
+      return { status: "pending" };
+    }
+    if (txn.outcome.kind === "denied") return { status: "denied" };
+    if (!this.peekCode(txn.outcome.code)) return { status: "expired" };
+    return { status: "approved", redirect: this.buildRedirect(txn, txn.outcome.code) };
+  }
+  /**
+   * Read a code entry without consuming it (SDK PKCE verification path).
+   * Returns undefined on unknown/expired/consumed.
+   */
+  peekCode(code) {
+    const now = Date.now();
+    this.gc(now);
+    const entry = this.codes.get(code);
+    if (!entry || entry.consumed || entry.expiresAt < now) return void 0;
+    return entry;
+  }
+  /**
+   * Consume a code after the SDK verified PKCE. Enforces single use and
+   * the client/redirect/resource bindings. Returns the entry on success,
+   * undefined on any mismatch.
+   */
+  takeCode(args) {
+    const entry = this.peekCode(args.code);
+    if (!entry) return void 0;
+    entry.consumed = true;
+    if (!timingSafeStringEqual(entry.clientId, args.clientId)) return void 0;
+    if (args.redirectUri !== void 0 && entry.redirectUri !== args.redirectUri) return void 0;
+    if (entry.resource !== void 0) {
+      if (args.resource === void 0) return void 0;
+      if (entry.resource !== args.resource) return void 0;
+    }
+    return entry;
+  }
+  /**
+   * Un-burn a code consumed by takeCode when the downstream token persist
+   * fails (disk full, permissions). Lets the client retry the exchange
+   * instead of being forced through a fresh authorize+approve. Only
+   * revives an entry still present and within TTL; a binding/PKCE
+   * mismatch is NOT revived (that is a genuine client error, and OAuth
+   * 2.1 revokes a code presented incorrectly).
+   */
+  reviveCode(code) {
+    const entry = this.codes.get(code);
+    if (entry && entry.expiresAt >= Date.now()) {
+      entry.consumed = false;
+    }
+  }
+};
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function renderApprovalPage(args) {
+  const { txn, issuerUrl, command } = args;
+  const safeRef = escapeHtml(txn.ref);
+  const safeClientId = escapeHtml(txn.clientId);
+  const safeRedirect = escapeHtml(txn.redirectUri);
+  const safeResource = txn.resource ? escapeHtml(txn.resource) : "";
+  const safeCommand = escapeHtml(command);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Remnic MCP authorization</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 640px; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; color: #1a1a1a; }
+  h1 { font-size: 1.4rem; }
+  .ref { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 1.1rem; background: #f4f4f5; padding: 0.25rem 0.5rem; border-radius: 4px; }
+  details { margin: 1rem 0; padding: 0.75rem 1rem; background: #fafafa; border: 1px solid #e4e4e7; border-radius: 6px; }
+  summary { cursor: pointer; font-weight: 600; }
+  code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9rem; }
+  pre { background: #f4f4f5; padding: 0.75rem; border-radius: 4px; overflow-x: auto; }
+  #status { margin-top: 1.5rem; padding: 0.75rem 1rem; border-radius: 6px; font-weight: 600; }
+  .pending { background: #fef9c3; color: #713f12; }
+  .approved { background: #dcfce7; color: #14532d; }
+  .denied { background: #fee2e2; color: #7f1d1d; }
+  .expired { background: #f3f4f6; color: #374151; }
+</style>
+</head>
+<body>
+<h1>Remnic MCP authorization pending</h1>
+<p>An external application has requested access to your Remnic MCP server.
+Open a terminal on the Remnic host and run:</p>
+<pre>${safeCommand}</pre>
+<p>Approval ref: <span class="ref">${safeRef}</span></p>
+<details>
+  <summary>Request details</summary>
+  <ul>
+    <li>Client ID: <code>${safeClientId}</code></li>
+    <li>Redirect URI: <code>${safeRedirect}</code></li>
+    ${safeResource ? `<li>Resource: <code>${safeResource}</code></li>` : ""}
+    <li>Scopes: <code>${escapeHtml(txn.scopes.join(" ")) || "(none requested)"}</code></li>
+  </ul>
+</details>
+<div id="status" class="pending">Waiting for operator approval&hellip;</div>
+<script>
+(function () {
+  var statusEl = document.getElementById("status");
+  var txn = ${JSON.stringify(txn.txn)};
+  var secret = ${JSON.stringify(txn.pollSecret)};
+  var issuer = ${JSON.stringify(issuerUrl)};
+  var done = false;
+  function render(result) {
+    if (result.status === "pending") return;
+    done = true;
+    if (result.status === "approved") {
+      statusEl.className = "approved";
+      statusEl.textContent = "Approved \u2014 redirecting\\u2026";
+      window.location.replace(result.redirect);
+    } else if (result.status === "denied") {
+      statusEl.className = "denied";
+      statusEl.textContent = "Denied by operator. Return to the calling app to retry or cancel.";
+    } else {
+      statusEl.className = "expired";
+      statusEl.textContent = "This request expired. Return to the calling app to retry.";
+    }
+  }
+  function poll() {
+    if (done) return;
+    fetch(issuer + "/oauth/authorize/poll", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ txn: txn, pollSecret: secret }),
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error("poll failed");
+        return res.json();
+      })
+      .then(render)
+      .catch(function () { /* transient; next interval retries */ });
+  }
+  poll();
+  setInterval(poll, 3000);
+})();
+</script>
+</body>
+</html>`;
+}
+var RemnicOAuthProvider = class {
+  config;
+  state;
+  staticClient;
+  /** Token-store override for tests; production uses the default path. */
+  tokensPath;
+  constructor(config, state, tokensPath) {
+    this.config = config;
+    this.state = state;
+    this.tokensPath = tokensPath;
+    this.staticClient = {
+      client_id: config.clientId,
+      // With `none`, the client is public: no secret is stored, so the
+      // SDK's client-auth middleware will not demand one. Otherwise the
+      // secret is REQUIRED on every token request.
+      ...config.tokenEndpointAuthMethod === "none" ? {} : { client_secret: config.clientSecret },
+      redirect_uris: config.redirectUris,
+      token_endpoint_auth_method: config.tokenEndpointAuthMethod,
+      grant_types: ["authorization_code"],
+      response_types: ["code"]
+    };
+  }
+  get clientsStore() {
+    const client = this.staticClient;
+    return {
+      getClient: (clientId) => clientId === client.client_id ? client : void 0
+      // No registerClient: dynamic client registration is deliberately
+      // NOT supported — the single client is pre-registered via config.
+    };
+  }
+  async authorize(client, params, res) {
+    const txn = this.state.createPending({
+      clientId: client.client_id,
+      redirectUri: params.redirectUri,
+      scopes: params.scopes ?? [],
+      resource: params.resource?.href,
+      state: params.state,
+      codeChallenge: params.codeChallenge
+    });
+    log.info(
+      `OAuth authorization pending: ref=${txn.ref} client=${txn.clientId} redirect=${txn.redirectUri} \u2014 run \`remnic oauth approve ${txn.ref}\` to approve`
+    );
+    res.status(200).type("html").send(
+      renderApprovalPage({
+        txn,
+        issuerUrl: this.config.issuerUrl.replace(/\/+$/, ""),
+        command: `remnic oauth approve ${txn.ref}`
+      })
+    );
+  }
+  async challengeForAuthorizationCode(client, authorizationCode) {
+    const entry = this.state.peekCode(authorizationCode);
+    if (!entry || !timingSafeStringEqual(entry.clientId, client.client_id)) {
+      throw new InvalidGrantError("authorization code is invalid, expired, or already used");
+    }
+    return entry.codeChallenge;
+  }
+  async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri, resource) {
+    const entry = this.state.takeCode({
+      code: authorizationCode,
+      clientId: client.client_id,
+      redirectUri,
+      resource: resource?.href
+    });
+    if (!entry) {
+      throw new InvalidGrantError("authorization code is invalid, expired, or already used");
+    }
+    const tokenEntry = buildTokenEntry(CHATGPT_CONNECTOR_ID);
+    try {
+      commitTokenEntry(tokenEntry, this.tokensPath);
+    } catch (err) {
+      this.state.reviveCode(authorizationCode);
+      log.warn(
+        `OAuth token persist failed; authorization code revived for retry: ${err instanceof Error ? err.message : String(err)}`
+      );
+      throw new ServerError("failed to persist the issued token; retry the exchange");
+    }
+    log.info(`OAuth token issued for connector "${CHATGPT_CONNECTOR_ID}" (client=${client.client_id})`);
+    return {
+      access_token: tokenEntry.token,
+      token_type: "Bearer"
+    };
+  }
+  async exchangeRefreshToken() {
+    throw new UnsupportedGrantTypeError(
+      "refresh_token grant is not supported; re-link the app to rotate the token"
+    );
+  }
+  async verifyAccessToken(token) {
+    const valid = getAllValidTokensCached(this.tokensPath).some(
+      (candidate) => timingSafeStringEqual(candidate, token)
+    );
+    if (!valid) {
+      throw new InvalidTokenError("unknown or revoked token");
+    }
+    return {
+      token,
+      clientId: this.config.clientId,
+      scopes: []
+    };
+  }
+};
+function buildOAuthApp(config, authCtxLookup, deps) {
+  const state = new OAuthState(config);
+  const provider = new RemnicOAuthProvider(config, state, deps?.tokensPath);
+  const issuer = new URL(config.issuerUrl);
+  const resourceServerUrl = new URL("/mcp", issuer);
+  if (config.redirectUris.length === 0) {
+    log.warn(
+      "server.oauth.redirectUris is empty \u2014 OAuth discovery is live but every authorization will be refused until the exact callback URL from ChatGPT's app management page is added (setup mode)."
+    );
+  }
+  const app = express();
+  app.disable("x-powered-by");
+  const oauthMetadata = createOAuthMetadata({ provider, issuerUrl: issuer });
+  oauthMetadata.token_endpoint_auth_methods_supported = [config.tokenEndpointAuthMethod];
+  oauthMetadata.grant_types_supported = ["authorization_code"];
+  app.use("/authorize", authorizationHandler({ provider }));
+  app.use("/token", tokenHandler({ provider }));
+  app.use(mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl, resourceName: "Remnic" }));
+  app.get("/.well-known/oauth-protected-resource", (_req, res) => {
+    res.status(200).json({
+      resource: resourceServerUrl.href,
+      authorization_servers: [oauthMetadata.issuer],
+      resource_name: "Remnic"
+    });
+  });
+  app.use(express.json({ limit: "32kb" }));
+  const makeLimiter = (max) => rateLimit({
+    windowMs: 6e4,
+    max,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: "rate_limited", error_description: "too many requests; retry later" }
+  });
+  const pollLimiter = makeLimiter(120);
+  const operatorReadLimiter = makeLimiter(60);
+  const operatorDecisionLimiter = makeLimiter(30);
+  app.post("/oauth/authorize/poll", pollLimiter, (req, res) => {
+    const body = req.body;
+    if (!isPlainObject(body) || typeof body.txn !== "string" || typeof body.pollSecret !== "string" || body.txn.length === 0 || body.pollSecret.length === 0) {
+      res.status(400).json({ error: "invalid_request", error_description: "txn and pollSecret are required" });
+      return;
+    }
+    const result = state.poll(body.txn, body.pollSecret);
+    if (result === void 0) {
+      res.status(401).json({ error: "invalid_request", error_description: "unknown txn or wrong pollSecret" });
+      return;
+    }
+    res.status(200).json(result);
+  });
+  function operatorGuard(req, res) {
+    if (authCtxLookup(req).authorized === true) return true;
+    res.status(401).json({ error: "unauthorized", error_description: "operator authentication required" });
+    return false;
+  }
+  app.get("/oauth/pending", operatorReadLimiter, (req, res) => {
+    if (!operatorGuard(req, res)) return;
+    const pending = state.listPending().map((txn) => ({
+      ref: txn.ref,
+      clientId: txn.clientId,
+      redirectUri: txn.redirectUri,
+      scopes: txn.scopes,
+      resource: txn.resource ?? null,
+      createdAt: new Date(txn.createdAt).toISOString(),
+      expiresAt: new Date(txn.expiresAt).toISOString()
+    }));
+    res.status(200).json({ pending });
+  });
+  function decisionHandler(action) {
+    return (req, res) => {
+      if (!operatorGuard(req, res)) return;
+      const ref = req.params.ref;
+      if (!ref) {
+        res.status(400).json({ error: "invalid_request", error_description: "ref is required" });
+        return;
+      }
+      try {
+        if (action === "approve") {
+          const { txn, code } = state.approveByRef(ref);
+          res.status(200).json({ ref, status: "approved", redirect: state.buildRedirect(txn, code) });
+        } else {
+          state.denyByRef(ref);
+          res.status(200).json({ ref, status: "denied" });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message === "unknown or expired ref") {
+          res.status(404).json({ error: "invalid_request", error_description: message });
+          return;
+        }
+        if (message === "denied" || message === "already approved") {
+          res.status(409).json({ error: "invalid_request", error_description: message });
+          return;
+        }
+        log.warn(`OAuth ${action} endpoint unexpected error: ${message}`);
+        res.status(500).json({ error: "server_error", error_description: "internal error" });
+      }
+    };
+  }
+  app.post("/oauth/pending/:ref/approve", operatorDecisionLimiter, decisionHandler("approve"));
+  app.post("/oauth/pending/:ref/deny", operatorDecisionLimiter, decisionHandler("deny"));
+  return {
+    app,
+    state,
+    ownedExactPaths: [
+      "/authorize",
+      "/token",
+      "/.well-known/oauth-authorization-server",
+      "/.well-known/oauth-protected-resource",
+      "/.well-known/oauth-protected-resource/mcp"
+    ],
+    ownedPathPrefixes: ["/oauth/"]
+  };
+}
+function buildOAuthRequestHandler(config, deps) {
+  if (!config.enabled) {
+    return async () => false;
+  }
+  const ctxByRequest = /* @__PURE__ */ new WeakMap();
+  const bundle = buildOAuthApp(config, (req) => ctxByRequest.get(req) ?? { authorized: false }, deps);
+  const exactPaths = new Set(bundle.ownedExactPaths);
+  return (req, res, ctx) => {
+    let pathname;
+    try {
+      pathname = new URL(req.url ?? "/", "http://placeholder").pathname;
+    } catch {
+      return Promise.resolve(false);
+    }
+    const owned = exactPaths.has(pathname) || bundle.ownedPathPrefixes.some((prefix) => pathname.startsWith(prefix));
+    if (!owned) return Promise.resolve(false);
+    ctxByRequest.set(req, ctx);
+    const { promise, resolve } = Promise.withResolvers();
+    const finish = () => resolve(true);
+    res.on("finish", finish);
+    res.on("close", finish);
+    bundle.app(req, res, (err) => {
+      if (!res.headersSent) {
+        if (err) {
+          log.warn(`OAuth facade error: ${err instanceof Error ? err.message : String(err)}`);
+          res.statusCode = 500;
+          res.setHeader("content-type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({ error: "server_error", error_description: "internal error" }));
+        } else {
+          res.statusCode = 404;
+          res.setHeader("content-type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({ error: "not_found", error_description: "unknown OAuth endpoint" }));
+        }
+      }
+      resolve(true);
+    });
+    return promise;
+  };
+}
+
+// src/index.ts
 function readCompatEnv(primary, legacy) {
   return process.env[primary] ?? process.env[legacy];
 }
@@ -569,9 +1247,9 @@ async function runStartupSearchWarmup(options) {
 async function completeStartupReadiness(options) {
   const timeoutMs = options.timeoutMs ?? STARTUP_WARMUP_TIMEOUT_MS;
   const retryIntervalMs = options.retryIntervalMs ?? STARTUP_WARMUP_RETRY_INTERVAL_MS;
-  const warn = options.warn ?? ((message) => log.warn(message));
-  const info = options.info ?? ((message) => log.info(message));
-  const error = options.error ?? ((message) => log.error(message));
+  const warn = options.warn ?? ((message) => log2.warn(message));
+  const info = options.info ?? ((message) => log2.info(message));
+  const error = options.error ?? ((message) => log2.error(message));
   options.state.ready = false;
   options.state.lastError = null;
   if (options.override) {
@@ -672,12 +1350,12 @@ async function cleanupFailedStartup(orchestrator, httpServer) {
   try {
     await httpServer.stop();
   } catch (err) {
-    log.warn(`HTTP startup failure cleanup could not stop server: ${err}`);
+    log2.warn(`HTTP startup failure cleanup could not stop server: ${err}`);
   }
   try {
     await orchestrator.destroy();
   } catch (err) {
-    log.warn(`HTTP startup failure cleanup could not destroy orchestrator: ${err}`);
+    log2.warn(`HTTP startup failure cleanup could not destroy orchestrator: ${err}`);
   }
 }
 async function startServer(options) {
@@ -705,14 +1383,22 @@ async function startServer(options) {
   const readiness = { ready: false, warmupAttempts: 0, lastError: null };
   const authToken = parsedServerConfig.authToken ?? readCompatEnv("REMNIC_AUTH_TOKEN", "ENGRAM_AUTH_TOKEN") ?? "";
   if (!authToken && getAllValidTokens().length === 0) {
-    log.warn("No auth token set \u2014 server will reject all requests. Set REMNIC_AUTH_TOKEN, server.authToken in config, or generate tokens with 'remnic token generate'.");
+    log2.warn("No auth token set \u2014 server will reject all requests. Set REMNIC_AUTH_TOKEN, server.authToken in config, or generate tokens with 'remnic token generate'.");
   }
+  const oauthConfig = applyOAuthEnvOverrides(serverConfig.oauth);
+  const oauthRequestHandler = buildOAuthRequestHandler(oauthConfig);
   const httpServer = new EngramAccessHttpServer({
     service,
     host: parsedServerConfig.host,
     port: parsedServerConfig.port,
     authToken: authToken || void 0,
-    authTokensGetter: () => getAllValidTokensCached(),
+    // Entry-based getter: validation + connector identity from ONE cached
+    // snapshot (see tokens.ts). The path policy pins ChatGPT-minted OAuth
+    // tokens (connector "chatgpt") to the MCP endpoint only — they never
+    // authorize REST/admin routes. All other connector tokens keep full
+    // access, matching pre-OAuth behavior.
+    authTokenEntriesGetter: () => getAllValidTokenEntriesCached(),
+    tokenPathPolicy: (connector, pathname) => connector !== "chatgpt" || pathname === "/mcp",
     readiness: () => readiness,
     principal: parsedServerConfig.principal,
     maxBodyBytes: parsedServerConfig.maxBodyBytes,
@@ -722,7 +1408,14 @@ async function startServer(options) {
     adminControls: parsedServerConfig.adminConsoleEnabled ? createAdminControls(resolvedConfigPath.path, config, parsedServerConfig) : void 0,
     citationsEnabled: config.citationsEnabled,
     citationsAutoDetect: config.citationsAutoDetect,
-    emitLegacyTools: config.emitLegacyTools
+    emitLegacyTools: config.emitLegacyTools,
+    ...oauthConfig.enabled ? {
+      externalRequestHandler: oauthRequestHandler,
+      resourceMetadataUrl: new URL(
+        "/.well-known/oauth-protected-resource/mcp",
+        oauthConfig.issuerUrl
+      ).href
+    } : {}
   });
   let host;
   let port;
@@ -797,47 +1490,47 @@ async function startServer(options) {
   httpServer.stop = stop;
   orchestrator.deferredReady.then(() => {
     if (startupSyncAbort.signal.aborted) {
-      log.debug("QMD startup-sync: cancelled before deferred init completed");
+      log2.debug("QMD startup-sync: cancelled before deferred init completed");
       return;
     }
     if (!config.qmdEnabled || orchestrator.qmd.debugStatus() === "backend=noop") {
-      log.debug("QMD startup-sync: search disabled or noop backend, skipping retries");
+      log2.debug("QMD startup-sync: search disabled or noop backend, skipping retries");
       return;
     }
     const needsRetry = !orchestrator.qmd.isAvailable() || !orchestrator.deferredSyncSucceeded;
     if (!needsRetry) {
-      log.debug("QMD startup-sync: deferred init completed successfully, no retries needed");
+      log2.debug("QMD startup-sync: deferred init completed successfully, no retries needed");
       return;
     }
     const RETRY_DELAYS_MS = [5e3, 15e3, 3e4, 6e4, 12e4];
     if (startupSyncAbort.signal.aborted) {
-      log.debug("QMD startup-sync retry: cancelled before retry task started");
+      log2.debug("QMD startup-sync retry: cancelled before retry task started");
       return;
     }
     (async () => {
       for (const delay of RETRY_DELAYS_MS) {
         await abortableDelay(delay, startupSyncAbort.signal);
         if (startupSyncAbort.signal.aborted) {
-          log.debug("QMD startup-sync retry: cancelled by shutdown");
+          log2.debug("QMD startup-sync retry: cancelled by shutdown");
           return;
         }
         const synced = await ensureStartupSync(startupSyncAbort.signal);
         if (!synced) {
           if (orchestrator.qmd.debugStatus() === "backend=noop") {
-            log.debug("QMD startup-sync retry: search intentionally disabled; stopping retries");
+            log2.debug("QMD startup-sync retry: search intentionally disabled; stopping retries");
             return;
           }
-          log.debug(`QMD startup-sync retry: not available yet (next retry in ${RETRY_DELAYS_MS[RETRY_DELAYS_MS.indexOf(delay) + 1] ?? "n/a"}ms)`);
+          log2.debug(`QMD startup-sync retry: not available yet (next retry in ${RETRY_DELAYS_MS[RETRY_DELAYS_MS.indexOf(delay) + 1] ?? "n/a"}ms)`);
           continue;
         }
         return;
       }
-      log.warn("QMD startup-sync retry: exhausted all retries; search index may be stale");
+      log2.warn("QMD startup-sync retry: exhausted all retries; search index may be stale");
     })().catch((err) => {
-      log.warn(`QMD startup-sync retry: unexpected error: ${err}`);
+      log2.warn(`QMD startup-sync retry: unexpected error: ${err}`);
     });
   }).catch((err) => {
-    log.warn(`Deferred init error: ${err}`);
+    log2.warn(`Deferred init error: ${err}`);
   });
   return { config, service, httpServer, host, port, stop, cancelStartupSync: () => startupSyncAbort.abort(), abortDeferredInit: () => orchestrator.abortDeferredInit() };
 }