@plaud-ai/mcp 0.3.9 → 0.3.11

package/dist/{server-SYSE62NO.js → server-KMU2TWA5.js}

@@ -1,23 +1,24 @@
 import {
   normalizeMcpHost,
   registerTools
-} from "./chunk-FSNFNJXH.js";
+} from "./chunk-O6BKY23H.js";
 import {
-  PlaudClient
-} from "./chunk-5NWKLF3V.js";
+  PlaudClient,
+  classifyError
+} from "./chunk-VUPXBO2J.js";
 import {
   logger
-} from "./chunk-NPCCDRWQ.js";
+} from "./chunk-OEZV5MA4.js";
 import {
   httpRequestDuration,
   httpRequestsInProgress,
   oauthTokenRefresh
-} from "./chunk-RUFCT6DQ.js";
+} from "./chunk-DIPROABB.js";
 
 // src/http/server.ts
 import express from "express";
 import { createServer } from "http";
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createOAuthMetadata, mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
@@ -25,12 +26,13 @@ import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middlew
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 
 // src/http/oauth-provider.ts
-import { createCipheriv, createDecipheriv, createHmac, randomBytes, randomUUID, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash as createHash2, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import { ProxyOAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js";
 import {
   InvalidGrantError,
   InvalidTokenError,
-  ServerError as McpServerError
+  ServerError as McpServerError,
+  TooManyRequestsError
 } from "@modelcontextprotocol/sdk/server/auth/errors.js";
 
 // src/http/cimd.ts
@@ -266,6 +268,249 @@ function validateMetadata(parsed, expectedClientIdUrl) {
   };
 }
 
+// src/http/token-verifier.ts
+import { createHash } from "crypto";
+function decodeJwtClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const payload = parts[1];
+  if (!payload) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}
+var Lru = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const value = this.map.get(key);
+    if (value === void 0) return void 0;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== void 0) this.map.delete(oldest);
+    }
+    this.map.set(key, value);
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+var TokenBucket = class {
+  constructor(capacity, refillPerSec, nowMs) {
+    this.capacity = capacity;
+    this.refillPerSec = refillPerSec;
+    this.tokens = capacity;
+    this.lastRefillMs = nowMs;
+  }
+  capacity;
+  refillPerSec;
+  tokens;
+  lastRefillMs;
+  take(nowMs) {
+    const elapsedSec = (nowMs - this.lastRefillMs) / 1e3;
+    if (elapsedSec > 0) {
+      this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillPerSec);
+      this.lastRefillMs = nowMs;
+    }
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+};
+var DEFAULTS = {
+  cacheMaxEntries: 5e3,
+  positiveTtlMs: 6e4,
+  negativeTtlMs: 3e4,
+  strangerBurst: 40,
+  strangerRatePerSec: 20,
+  knownBurst: 10,
+  knownRatePerSec: 5,
+  knownSubMaxEntries: 2e4
+};
+var TokenVerifier = class {
+  cache;
+  subBuckets;
+  strangerBucket;
+  opts;
+  constructor(options) {
+    const now = options.now ?? (() => Date.now());
+    this.opts = {
+      verifyUpstream: options.verifyUpstream,
+      cacheEnabled: options.cacheEnabled ?? true,
+      cacheMaxEntries: options.cacheMaxEntries ?? DEFAULTS.cacheMaxEntries,
+      positiveTtlMs: options.positiveTtlMs ?? DEFAULTS.positiveTtlMs,
+      negativeTtlMs: options.negativeTtlMs ?? DEFAULTS.negativeTtlMs,
+      strangerBurst: options.strangerBurst ?? DEFAULTS.strangerBurst,
+      strangerRatePerSec: options.strangerRatePerSec ?? DEFAULTS.strangerRatePerSec,
+      knownBurst: options.knownBurst ?? DEFAULTS.knownBurst,
+      knownRatePerSec: options.knownRatePerSec ?? DEFAULTS.knownRatePerSec,
+      knownSubMaxEntries: options.knownSubMaxEntries ?? DEFAULTS.knownSubMaxEntries,
+      now
+    };
+    this.cache = new Lru(this.opts.cacheMaxEntries);
+    this.subBuckets = new Lru(this.opts.knownSubMaxEntries);
+    this.strangerBucket = new TokenBucket(
+      this.opts.strangerBurst,
+      this.opts.strangerRatePerSec,
+      now()
+    );
+  }
+  /**
+   * Seeds the cache with a token that was just minted upstream (OAuth code
+   * exchange or refresh).
+   *
+   * This is what keeps normal users out of the rate-limit tier entirely: their
+   * first request after logging in or rotating a token is already a cache hit,
+   * so it never draws from the budget that unrecognised tokens consume.
+   *
+   * clientId is taken from the JWT `sub` rather than the upstream user.id: we
+   * have not called upstream at this point and do not need to, since the token
+   * came straight from the token endpoint. Downstream only uses clientId for
+   * logging, and server.ts derives ctxUserId from `sub` first anyway.
+   */
+  prewarm(token) {
+    if (!this.opts.cacheEnabled) return;
+    const claims = decodeJwtClaims(token);
+    if (!claims) return;
+    const sub = typeof claims.sub === "string" ? claims.sub : void 0;
+    const exp = typeof claims.exp === "number" ? claims.exp : void 0;
+    if (!sub) return;
+    const nowMs = this.opts.now();
+    const expiresAt = exp ?? Math.floor(nowMs / 1e3) + 3600;
+    this.putPositive(sha256(token), sub, expiresAt, nowMs);
+    this.noteKnownSub(sub, nowMs);
+    logger.info({ event: "token_prewarmed", cache_size: this.cache.size });
+  }
+  async verify(token) {
+    const nowMs = this.opts.now();
+    const nowSec = Math.floor(nowMs / 1e3);
+    const claims = decodeJwtClaims(token);
+    if (!claims) {
+      logger.warn({ event: "token_rejected_local", reason: "malformed" });
+      return { ok: false, kind: "malformed" };
+    }
+    const sub = typeof claims.sub === "string" && claims.sub ? claims.sub : void 0;
+    const exp = typeof claims.exp === "number" ? claims.exp : void 0;
+    if (exp !== void 0 && exp <= nowSec) {
+      logger.warn({ event: "token_rejected_local", reason: "expired" });
+      return { ok: false, kind: "expired" };
+    }
+    const key = sha256(token);
+    if (this.opts.cacheEnabled) {
+      const hit = this.cache.get(key);
+      if (hit && hit.cacheExpiresAtMs > nowMs) {
+        return hit.valid ? { ok: true, clientId: hit.clientId, expiresAt: hit.expiresAt, source: "cache" } : { ok: false, kind: "invalid" };
+      }
+      if (hit) this.cache.delete(key);
+    }
+    const looksKnown = sub !== void 0 && sub.startsWith("client_user_");
+    const bucket = sub !== void 0 && looksKnown ? this.subBuckets.get(sub) : void 0;
+    const allowed = bucket ? bucket.take(nowMs) : this.strangerBucket.take(nowMs);
+    if (!allowed) {
+      logger.warn({
+        event: "token_verify_rate_limited",
+        scope: bucket ? "known_sub" : "stranger"
+      });
+      return { ok: false, kind: "rate_limited" };
+    }
+    const verdict = await this.opts.verifyUpstream(token);
+    if (verdict.kind === "valid") {
+      const expiresAt = exp ?? nowSec + 3600;
+      if (this.opts.cacheEnabled) this.putPositive(key, verdict.clientId, expiresAt, nowMs);
+      if (sub !== void 0) this.noteKnownSub(sub, nowMs);
+      logger.info({ event: "token_verified", client_id: verdict.clientId, expires_at: expiresAt });
+      return { ok: true, clientId: verdict.clientId, expiresAt, source: "upstream" };
+    }
+    if (verdict.kind === "invalid") {
+      if (this.opts.cacheEnabled) {
+        this.cache.set(key, {
+          valid: false,
+          clientId: "",
+          expiresAt: 0,
+          cacheExpiresAtMs: nowMs + this.opts.negativeTtlMs
+        });
+      }
+      logger.warn({ event: "token_verify_failed", reason: "invalid" });
+      return { ok: false, kind: "invalid" };
+    }
+    if (verdict.kind === "rate_limited") {
+      logger.warn({ event: "token_verify_upstream_rate_limited" });
+      return { ok: false, kind: "rate_limited" };
+    }
+    logger.error({ event: "token_verify_unavailable", reason: verdict.reason });
+    return { ok: false, kind: "unavailable" };
+  }
+  /** For /health and metrics — counts only, no tokens or user identifiers. */
+  stats() {
+    return {
+      cacheSize: this.cache.size,
+      knownSubs: this.subBuckets.size,
+      cacheEnabled: this.opts.cacheEnabled
+    };
+  }
+  putPositive(key, clientId, expiresAt, nowMs) {
+    const remainingMs = expiresAt * 1e3 - nowMs;
+    const ttlMs = Math.min(this.opts.positiveTtlMs, Math.max(0, remainingMs));
+    if (ttlMs <= 0) return;
+    this.cache.set(key, { valid: true, clientId, expiresAt, cacheExpiresAtMs: nowMs + ttlMs });
+  }
+  noteKnownSub(sub, nowMs) {
+    if (this.subBuckets.get(sub) === void 0) {
+      this.subBuckets.set(
+        sub,
+        new TokenBucket(this.opts.knownBurst, this.opts.knownRatePerSec, nowMs)
+      );
+    }
+  }
+};
+function tokenVerifierOptionsFromEnv() {
+  const num = (name, fallback) => {
+    const raw = process.env[name];
+    if (raw === void 0 || raw === "") return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      logger.warn({ event: "token_verifier_bad_env", name, value: raw, using: fallback });
+      return fallback;
+    }
+    return parsed;
+  };
+  return {
+    cacheEnabled: !["0", "false", "no", "off"].includes(
+      (process.env["PLAUD_TOKEN_CACHE_ENABLED"] ?? "").toLowerCase()
+    ),
+    cacheMaxEntries: num("PLAUD_TOKEN_CACHE_MAX", DEFAULTS.cacheMaxEntries),
+    positiveTtlMs: num("PLAUD_TOKEN_CACHE_TTL_MS", DEFAULTS.positiveTtlMs),
+    negativeTtlMs: num("PLAUD_TOKEN_NEGATIVE_TTL_MS", DEFAULTS.negativeTtlMs),
+    strangerBurst: num("PLAUD_TOKEN_VERIFY_BURST", DEFAULTS.strangerBurst),
+    strangerRatePerSec: num("PLAUD_TOKEN_VERIFY_RATE", DEFAULTS.strangerRatePerSec),
+    knownBurst: num("PLAUD_TOKEN_KNOWN_BURST", DEFAULTS.knownBurst),
+    knownRatePerSec: num("PLAUD_TOKEN_KNOWN_RATE", DEFAULTS.knownRatePerSec),
+    knownSubMaxEntries: num("PLAUD_TOKEN_KNOWN_SUB_MAX", DEFAULTS.knownSubMaxEntries)
+  };
+}
+
 // src/http/oauth-provider.ts
 function subFromJwt(token) {
   if (!token) return void 0;
@@ -276,6 +521,10 @@ function subFromJwt(token) {
     return void 0;
   }
 }
+function isUpstreamRateLimited(err) {
+  const msg = err instanceof Error ? err.message : String(err ?? "");
+  return /\bAPI error: 429\b/.test(msg);
+}
 var AUTO_RECOVERED_CLIENT_NAME = "auto-recovered client";
 var REDIRECT_HOST_CLIENT_NAMES = {
   "chatgpt.com": "chatgpt",
@@ -301,6 +550,8 @@ var DEFAULT_TOKEN_URL = "https://platform.plaud.ai/developer/api/oauth/third-par
 var DEFAULT_REFRESH_URL = "https://platform.plaud.ai/developer/api/oauth/third-party/access-token/refresh";
 var STATELESS_CODE_PREFIX = "pc1_";
 var AUTHORIZATION_CODE_TTL_MS = 10 * 60 * 1e3;
+var STATELESS_STATE_PREFIX = "st1_";
+var AUTHORIZATION_STATE_TTL_MS = 30 * 60 * 1e3;
 function urlParts(value) {
   if (!value || !URL.canParse(value)) {
     return { host: null, path: null };
@@ -318,57 +569,74 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
   _debugOAuthLogs;
   _cimdLoader;
   _tracker;
+  /** Local pre-checks + cache + tiered rate limit + upstream call, all in one
+   *  place. See token-verifier.ts. */
+  _verifier;
   _registeredClients = /* @__PURE__ */ new Map();
   // HMAC secret used to sign DCR-issued client_ids so we can recover them
   // across container restarts without persistent storage. See verifyAndRecover.
   _clientIdSecret;
-  // internalState → client redirect, original client state, and resource indicator
-  // We generate our own state to track the pending flow regardless of whether the client sent one.
-  _pendingStates = /* @__PURE__ */ new Map();
+  // NOTE: there is deliberately no in-process store for pending authorizations.
+  // This class used to keep `_pendingStates: Map<state, {clientRedirectUri, …}>`,
+  // which meant /authorize and /auth/callback had to be served by the same
+  // process — the callback looked the state up and hard-failed with 400 if it
+  // wasn't there. That single map is what pinned the deployment to one replica
+  // (and it was never swept, so abandoned authorizations accumulated for the
+  // lifetime of the pod). The state parameter is now a sealed, self-contained
+  // envelope instead; see encodeAuthorizationState.
+  //
+  // Everything else here was already replica-safe: client_ids are HMAC-signed
+  // and recoverable (verifyAndRecover), and authorization codes are sealed the
+  // same way. This was the last piece holding it back.
   constructor(options) {
     const authUrl = options.authUrl ?? "https://web.plaud.ai/platform/oauth";
     const tokenUrl = options.tokenUrl ?? DEFAULT_TOKEN_URL;
     const refreshUrl = options.refreshUrl ?? DEFAULT_REFRESH_URL;
     const apiBase = options.apiBase ?? "https://platform.plaud.ai/developer/api";
+    const holder = {};
+    const verifyUpstream = async (token) => {
+      const client = new PlaudClient({
+        clientId: options.clientId,
+        clientSecret: "",
+        redirectUri: "",
+        apiBase,
+        staticToken: token
+      });
+      try {
+        const user = await client.getCurrentUser();
+        return { kind: "valid", clientId: String(user.id ?? "unknown") };
+      } catch (err) {
+        const type = classifyError(err);
+        if (type === "auth") return { kind: "invalid" };
+        if (isUpstreamRateLimited(err)) return { kind: "rate_limited" };
+        return { kind: "unavailable", reason: type };
+      }
+    };
     super({
       endpoints: {
         authorizationUrl: authUrl,
         tokenUrl
       },
       verifyAccessToken: async (token) => {
-        const client = new PlaudClient({
-          clientId: options.clientId,
-          clientSecret: "",
-          redirectUri: "",
-          apiBase,
-          staticToken: token
-        });
-        try {
-          const user = await client.getCurrentUser();
-          let expiresAt;
-          try {
-            const payload = JSON.parse(
-              Buffer.from(token.split(".")[1], "base64url").toString()
-            );
-            expiresAt = typeof payload.exp === "number" ? payload.exp : Math.floor(Date.now() / 1e3) + 3600;
-          } catch {
-            expiresAt = Math.floor(Date.now() / 1e3) + 3600;
-          }
-          const authInfo = {
-            token,
-            clientId: String(user.id ?? "unknown"),
-            scopes: [],
-            expiresAt
-          };
-          logger.info({ event: "token_verified", client_id: authInfo.clientId, expires_at: expiresAt });
-          return authInfo;
-        } catch (err) {
-          logger.warn({ event: "token_verify_failed", error: String(err) });
-          throw new InvalidTokenError("Invalid or expired token");
+        const verifier = holder.verifier;
+        if (!verifier) throw new McpServerError("Token verifier not initialised");
+        const outcome = await verifier.verify(token);
+        if (outcome.ok) {
+          return { token, clientId: outcome.clientId, scopes: [], expiresAt: outcome.expiresAt };
+        }
+        switch (outcome.kind) {
+          case "unavailable":
+            throw new McpServerError("Upstream token verification temporarily unavailable");
+          case "rate_limited":
+            throw new TooManyRequestsError("Token verification rate limited");
+          default:
+            throw new InvalidTokenError("Invalid or expired token");
         }
       },
       getClient: async (id) => this._registeredClients.get(id)
     });
+    holder.verifier = new TokenVerifier({ ...tokenVerifierOptionsFromEnv(), verifyUpstream });
+    this._verifier = holder.verifier;
     this._plaudClientId = options.clientId;
     this._plaudClientSecret = options.clientSecret ?? "";
     this._plaudTokenUrl = tokenUrl;
@@ -390,6 +658,10 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     }
     this.skipLocalPkceValidation = true;
   }
+  /** For /health and metrics — counts only, no tokens or user identifiers. */
+  get verifierStats() {
+    return this._verifier.stats();
+  }
   // Override clientsStore. registerClient signs the issued client_id with HMAC
   // so verifyAndRecover can later resurrect it across container restarts.
   get clientsStore() {
@@ -495,49 +767,116 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     if (actual.length !== expected.length) return false;
     return timingSafeEqual(actual, expected);
   }
-  authorizationCodeKey() {
-    return createHmac("sha256", this._clientIdSecret).update("plaud-mcp-authorization-code").digest();
+  // Key is derived per purpose so a value sealed for one hop can never be
+  // unsealed as the other — an authorization code presented as a state (or vice
+  // versa) fails the GCM tag check rather than decoding into the wrong shape.
+  envelopeKey(purpose) {
+    return createHmac("sha256", this._clientIdSecret).update(purpose).digest();
   }
-  encodeAuthorizationCode(payload) {
+  // AES-256-GCM envelope: prefix + base64url(iv[12] | tag[16] | ciphertext).
+  // Self-contained, so any pod can open what any other pod sealed — that is what
+  // lets us run more than one replica without a shared store.
+  seal(purpose, prefix, payload, ttlMs) {
     const iv = randomBytes(12);
-    const cipher = createCipheriv("aes-256-gcm", this.authorizationCodeKey(), iv);
-    const plaintext = Buffer.from(JSON.stringify({
-      upstreamCode: payload.upstreamCode,
-      upstreamState: payload.upstreamState,
-      resource: payload.resource,
-      expiresAt: Date.now() + AUTHORIZATION_CODE_TTL_MS
-    }), "utf8");
+    const cipher = createCipheriv("aes-256-gcm", this.envelopeKey(purpose), iv);
+    const plaintext = Buffer.from(
+      JSON.stringify({ ...payload, expiresAt: Date.now() + ttlMs }),
+      "utf8"
+    );
     const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const tag = cipher.getAuthTag();
-    return `${STATELESS_CODE_PREFIX}${Buffer.concat([iv, tag, ciphertext]).toString("base64url")}`;
+    return `${prefix}${Buffer.concat([iv, tag, ciphertext]).toString("base64url")}`;
   }
-  decodeAuthorizationCode(code) {
-    if (!code.startsWith(STATELESS_CODE_PREFIX)) return null;
+  // Returns null for anything that isn't ours, has been tampered with, or has
+  // expired. Callers still validate the payload's own shape.
+  unseal(purpose, prefix, value) {
+    if (typeof value !== "string" || !value.startsWith(prefix)) return null;
     try {
-      const encoded = code.slice(STATELESS_CODE_PREFIX.length);
-      const data = Buffer.from(encoded, "base64url");
+      const data = Buffer.from(value.slice(prefix.length), "base64url");
       if (data.length <= 28) return null;
-      const iv = data.subarray(0, 12);
-      const tag = data.subarray(12, 28);
-      const ciphertext = data.subarray(28);
-      const decipher = createDecipheriv("aes-256-gcm", this.authorizationCodeKey(), iv);
-      decipher.setAuthTag(tag);
-      const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+      const decipher = createDecipheriv("aes-256-gcm", this.envelopeKey(purpose), data.subarray(0, 12));
+      decipher.setAuthTag(data.subarray(12, 28));
+      const plaintext = Buffer.concat([
+        decipher.update(data.subarray(28)),
+        decipher.final()
+      ]).toString("utf8");
       const payload = JSON.parse(plaintext);
-      if (typeof payload.upstreamCode !== "string" || typeof payload.upstreamState !== "string" || payload.resource !== void 0 && typeof payload.resource !== "string" || typeof payload.expiresAt !== "number") {
+      if (typeof payload["expiresAt"] !== "number" || Date.now() > payload["expiresAt"]) {
         return null;
       }
-      if (Date.now() > payload.expiresAt) {
-        return null;
-      }
-      return {
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+  encodeAuthorizationCode(payload) {
+    return this.seal(
+      "plaud-mcp-authorization-code",
+      STATELESS_CODE_PREFIX,
+      {
         upstreamCode: payload.upstreamCode,
         upstreamState: payload.upstreamState,
         resource: payload.resource
-      };
-    } catch {
+      },
+      AUTHORIZATION_CODE_TTL_MS
+    );
+  }
+  decodeAuthorizationCode(code) {
+    const payload = this.unseal(
+      "plaud-mcp-authorization-code",
+      STATELESS_CODE_PREFIX,
+      code
+    );
+    if (!payload) return null;
+    if (typeof payload.upstreamCode !== "string" || typeof payload.upstreamState !== "string" || payload.resource !== void 0 && typeof payload.resource !== "string") {
       return null;
     }
+    return {
+      upstreamCode: payload.upstreamCode,
+      upstreamState: payload.upstreamState,
+      resource: payload.resource
+    };
+  }
+  // The authorize→callback hop. Everything the callback needs travels inside the
+  // state parameter itself, so the pod that handles the callback need not be the
+  // pod that started the flow. This is what replaced the in-process
+  // _pendingStates map — see the class docstring for why that map capped us at
+  // one replica.
+  encodeAuthorizationState(payload) {
+    return this.seal(
+      "plaud-mcp-authorization-state",
+      STATELESS_STATE_PREFIX,
+      {
+        clientRedirectUri: payload.clientRedirectUri,
+        originalState: payload.originalState,
+        resource: payload.resource
+      },
+      AUTHORIZATION_STATE_TTL_MS
+    );
+  }
+  // Stable short handle for correlating authorize and callback log lines.
+  // Not a secret and not reversible — purely a join key for reading logs.
+  stateHandle(state) {
+    if (typeof state !== "string") return "non-string";
+    return createHash2("sha256").update(state).digest("base64url").slice(0, 12);
+  }
+  decodeAuthorizationState(state) {
+    const payload = this.unseal(
+      "plaud-mcp-authorization-state",
+      STATELESS_STATE_PREFIX,
+      state
+    );
+    if (!payload) return null;
+    if (typeof payload.clientRedirectUri !== "string" || !URL.canParse(payload.clientRedirectUri)) {
+      return null;
+    }
+    if (payload.originalState !== void 0 && typeof payload.originalState !== "string") return null;
+    if (payload.resource !== void 0 && typeof payload.resource !== "string") return null;
+    return {
+      clientRedirectUri: payload.clientRedirectUri,
+      originalState: payload.originalState,
+      resource: payload.resource
+    };
   }
   // Recover a client_id that the registry doesn't know about. Directory clients
   // (OpenAI Apps, Claude directory) cache the client_id they got from /register;
@@ -601,8 +940,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
    * Store the client's original redirect_uri keyed by state so we can forward after Plaud calls back.
    */
   async authorize(_client, params, res) {
-    const internalState = randomUUID();
-    this._pendingStates.set(internalState, {
+    const internalState = this.encodeAuthorizationState({
       clientRedirectUri: params.redirectUri,
       originalState: params.state,
       resource: params.resource?.href
@@ -610,7 +948,10 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     const redirectParts = urlParts(params.redirectUri);
     logger.info({
       event: "oauth_authorize_start",
-      internal_state: internalState,
+      // Short digest, not the sealed blob — it is 300+ chars and would bloat
+      // every line. Same value appears on the matching callback, so the two
+      // still correlate.
+      state_handle: this.stateHandle(internalState),
       redirect_uri: params.redirectUri,
       ...this._debugOAuthLogs ? {
         redirect_uri_host: redirectParts.host,
@@ -618,7 +959,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
         has_original_state: !!params.state,
         has_resource: !!params.resource,
         resource: params.resource?.href ?? null,
-        pending_states_count: this._pendingStates.size
+        state_len: internalState.length
       } : {}
     });
     const targetUrl = new URL(this._endpoints.authorizationUrl);
@@ -644,17 +985,25 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
    * Called when Plaud redirects to our /auth/callback (CALLBACK_PATH in
    * http/server.ts). NOT /oauth/callback — this comment said so until 2026-08-19
    * and a downstream client registration was configured from it by mistake.
-   * Looks up the original client redirect_uri and forwards the code+state to it.
+   * Opens the sealed state to recover the client's redirect_uri and forwards the
+   * code+state to it. No lookup — the state is the storage, which is what allows
+   * this to be served by a pod that never saw the /authorize request.
    */
   handleCallback(code, state, res) {
-    const pending = this._pendingStates.get(state);
+    const pending = this.decodeAuthorizationState(state);
     if (!pending) {
-      logger.warn({ event: "oauth_callback_unknown_state", state });
+      logger.warn({
+        event: "oauth_callback_unknown_state",
+        state_handle: this.stateHandle(state),
+        // typeof-guarded: this is the one log line reached by a request whose
+        // parameter shape we do not control.
+        state_len: typeof state === "string" ? state.length : null,
+        sealed_shape: typeof state === "string" && state.startsWith(STATELESS_STATE_PREFIX)
+      });
       res.status(400).send("Unknown state \u2014 authorization request not found");
       return;
     }
-    this._pendingStates.delete(state);
-    logger.info({ event: "oauth_callback_received", internal_state: state });
+    logger.info({ event: "oauth_callback_received", state_handle: this.stateHandle(state) });
     const pendingCode = {
       upstreamCode: code,
       upstreamState: state,
@@ -667,10 +1016,12 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       target.searchParams.set("state", pending.originalState);
     }
     const redirectParts = urlParts(pending.clientRedirectUri);
+    const isCustomScheme = !/^https?:$/.test(new URL(target.toString()).protocol);
     logger.info({
       event: "oauth_callback_redirect",
-      internal_state: state,
+      state_handle: this.stateHandle(state),
       redirect_uri: pending.clientRedirectUri,
+      custom_scheme: isCustomScheme,
       has_original_state: !!pending.originalState,
       original_state_len: pending.originalState?.length ?? 0,
       upstream_code_len: code.length,
@@ -685,7 +1036,37 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
         redirect_has_state: target.searchParams.has("state")
       } : {}
     });
-    res.redirect(target.toString());
+    if (!isCustomScheme) {
+      res.redirect(target.toString());
+      return;
+    }
+    res.status(200).type("html").send(this.appHandoffPage(target.toString()));
+  }
+  // Landing page for native-app callbacks. The URL goes into a data attribute
+  // rather than inline JS so nothing from `clientRedirectUri` can be parsed as
+  // script; it is only ever assigned to location.href.
+  appHandoffPage(redirectUrl) {
+    const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+    const href = esc(redirectUrl);
+    return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>\u6388\u6743\u6210\u529F \xB7 Plaud</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#fafafa;color:#111">
+<main id="p" data-href="${href}" style="text-align:center;padding:2rem;max-width:28rem">
+  <div style="font-size:2.5rem;line-height:1">\u2713</div>
+  <h1 style="font-size:1.25rem;margin:.75rem 0 .5rem">\u6388\u6743\u6210\u529F</h1>
+  <p style="color:#666;margin:0 0 1.5rem">\u6B63\u5728\u8FD4\u56DE\u5E94\u7528\uFF0C\u53EF\u4EE5\u5173\u95ED\u6B64\u9875\u9762\u3002</p>
+  <p style="font-size:.875rem;color:#888;margin:0">
+    \u6CA1\u6709\u81EA\u52A8\u8DF3\u8F6C\uFF1F<a id="m" href="#" style="color:#0066cc">\u70B9\u6B64\u624B\u52A8\u6253\u5F00</a>
+  </p>
+</main>
+<script>
+  var u = document.getElementById("p").dataset.href;
+  document.getElementById("m").href = u;
+  location.href = u;
+</script>
+</body></html>`;
   }
   // Override to use PKCE public-client flow — no Basic auth, client_id sent in body.
   async exchangeAuthorizationCode(client, authorizationCode, codeVerifier, _redirectUri, resource) {
@@ -762,6 +1143,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       throw new McpServerError("Token endpoint returned non-JSON response");
     }
     logger.info({ event: "oauth_token_exchange_ok", has_refresh_token: !!data.refresh_token });
+    this._verifier.prewarm(data.access_token);
     const authorizedUserId = subFromJwt(data.access_token);
     this._tracker?.track({
       name: "auth.oauth_callback_success",
@@ -834,6 +1216,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       throw new McpServerError("Refresh endpoint returned non-JSON response");
     }
     oauthTokenRefresh.inc({ result: "success" });
+    this._verifier.prewarm(data.access_token);
     this._tracker?.track({
       name: "auth.token_refresh_success",
       actorType: "user",
@@ -856,7 +1239,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
 };
 
 // src/telemetry-server/tracker.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
 
 // src/telemetry-server/transport.ts
 import { PostHog } from "posthog-node";
@@ -1018,7 +1401,7 @@ var WarehouseTracker = class {
       service_version: this.common.serviceVersion,
       ...this.common.buildId ? { build_id: this.common.buildId } : {},
       // timing / tracing
-      event_id: randomUUID2(),
+      event_id: randomUUID(),
       ...input.requestId ? { request_id: input.requestId } : {},
       // (trace_id/span_id omitted — no OpenTelemetry; spec forbids fabricating)
       // non-user actors: don't create a PostHog person
@@ -1283,8 +1666,8 @@ function startHttpServer() {
     common: {
       serviceName: process.env.PLAUD_WAREHOUSE_SERVICE_NAME ?? "plaudmcp",
       // matches §1.3 key label `plaudmcp:TRACKING_KEY_PLAUDMCP`; confirm exact string with David
-      serviceVersion: "0.3.9",
-      buildId: "ee2ff6d",
+      serviceVersion: "0.3.11",
+      buildId: "516b086",
       // mcp tsup TODO: inject git short SHA (like CLI)
       region: process.env.PLAUD_REGION ?? "US",
       env: process.env.PLAUD_ENV ?? process.env.NODE_ENV ?? "development"
@@ -1374,7 +1757,10 @@ function startHttpServer() {
         server_url: process.env.PLAUD_SERVER_URL ?? "(default:localhost)",
         oauth_debug_logs: OAUTH_DEBUG_LOGS,
         cimd_enabled: CIMD_ENABLED
-      }
+      },
+      // Size of the token-verification cache, to confirm it is actually in
+      // effect. Counts only — no tokens or user identifiers.
+      token_verifier: provider.verifierStats
     });
   });
   app.get("/", (_req, res) => {
@@ -1382,8 +1768,8 @@ function startHttpServer() {
   });
   if (process.env.PLAUD_CALLBACK_URL) {
     app.get(CALLBACK_PATH, (req, res) => {
-      const code = req.query["code"];
-      const state = req.query["state"];
+      const code = queryValue(req.query["code"]);
+      const state = queryValue(req.query["state"]);
       if (!code || !state) {
         logger.warn({ event: "oauth_callback_invalid", code: !!code, state: !!state });
         res.status(400).send("Missing code or state");
@@ -1393,7 +1779,7 @@ function startHttpServer() {
     });
   }
   app.use((req, res, next) => {
-    const reqId = req.headers["x-request-id"] ?? randomUUID3();
+    const reqId = req.headers["x-request-id"] ?? randomUUID2();
     const startMs = Date.now();
     res.locals["reqId"] = reqId;
     res.on("finish", () => {
@@ -1545,7 +1931,7 @@ function startHttpServer() {
     requireBearerAuth({ verifier: provider, resourceMetadataUrl: protectedResourceMetadataUrl }),
     async (req, res) => {
       const token = req.auth.token;
-      const reqId = res.locals["reqId"] ?? randomUUID3();
+      const reqId = res.locals["reqId"] ?? randomUUID2();
       const reqLog = logger.child({ req_id: reqId });
       const startMs = Date.now();
       reqLog.info({ event: "mcp_request_start", client_id: req.auth.clientId });
@@ -1556,7 +1942,7 @@ function startHttpServer() {
         apiBase,
         staticToken: token
       });
-      const mcpServer = new McpServer({ name: "plaud", version: "0.3.9" });
+      const mcpServer = new McpServer({ name: "plaud", version: "0.3.11" });
       registerTools(mcpServer, client, warehouseToolHooks);
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: void 0,
@@ -1594,8 +1980,8 @@ function startHttpServer() {
   if (!process.env.PLAUD_CALLBACK_URL) {
     const callbackApp = express();
     callbackApp.get(CALLBACK_PATH, (req, res) => {
-      const code = req.query["code"];
-      const state = req.query["state"];
+      const code = queryValue(req.query["code"]);
+      const state = queryValue(req.query["state"]);
       if (!code || !state) {
         logger.warn({ event: "oauth_callback_invalid", code: !!code, state: !!state });
         res.status(400).send("Missing code or state");