@frontmcp/sdk 0.4.1 → 0.5.0

package/src/auth/session/utils/session-id.utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encryptJson = encryptJson;
+exports.decryptPublicSession = decryptPublicSession;
 exports.parseSessionHeader = parseSessionHeader;
 exports.createSessionId = createSessionId;
 exports.generateSessionCookie = generateSessionCookie;
@@ -9,6 +10,7 @@ exports.extractSessionFromCookie = extractSessionFromCookie;
 const crypto_1 = require("crypto");
 const tiny_ttl_cache_1 = require("./tiny-ttl-cache");
 const auth_token_utils_1 = require("./auth-token.utils");
+const notification_service_1 = require("../../../notification/notification.service");
 // 5s TTL cache for decrypted headers
 const cache = new tiny_ttl_cache_1.TinyTtlCache(5000);
 // Single-process machine id generated at server launch
@@ -39,27 +41,64 @@ function encryptJson(obj) {
     // Pack iv.tag.ct as base64url(iv.tag.ct)
     return `${b64urlEncode(iv)}.${b64urlEncode(tag)}.${b64urlEncode(ct)}`;
 }
-function decryptSessionId(sessionId, sig) {
-    const key = getKey();
-    const [ivB64, tagB64, ctB64] = sessionId.split('.');
+/**
+ * Low-level decryption that returns the raw JSON payload or null.
+ * Handles all crypto/parsing failures by returning null.
+ */
+function decryptSessionJson(sessionId) {
+    const parts = sessionId.split('.');
+    if (parts.length !== 3)
+        return null;
+    const [ivB64, tagB64, ctB64] = parts;
     if (!ivB64 || !tagB64 || !ctB64)
         return null;
+    const key = getKey();
+    const iv = b64urlDecode(ivB64);
+    const tag = b64urlDecode(tagB64);
+    const ct = b64urlDecode(ctB64);
+    const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return JSON.parse(pt.toString('utf8'));
+}
+function isValidSessionPayload(dec, sig) {
+    if (typeof dec !== 'object' || dec === null)
+        return false;
+    const d = dec;
+    return (typeof d['nodeId'] === 'string' &&
+        typeof d['authSig'] === 'string' &&
+        typeof d['uuid'] === 'string' &&
+        typeof d['iat'] === 'number' &&
+        d['authSig'] === sig);
+}
+function isValidPublicSessionPayload(dec) {
+    if (typeof dec !== 'object' || dec === null)
+        return false;
+    const d = dec;
+    return (typeof d['nodeId'] === 'string' &&
+        d['authSig'] === 'public' &&
+        typeof d['uuid'] === 'string' &&
+        typeof d['iat'] === 'number' &&
+        d['isPublic'] === true);
+}
+function decryptSessionId(sessionId, sig) {
+    const dec = safeDecrypt(sessionId);
+    return isValidSessionPayload(dec, sig) ? dec : null;
+}
+/**
+ * Decrypt a public session ID without signature verification.
+ * Public sessions use authSig: 'public' and isPublic: true
+ */
+function decryptPublicSession(sessionId) {
+    const dec = safeDecrypt(sessionId);
+    return isValidPublicSessionPayload(dec) ? dec : null;
+}
+/**
+ * Safe wrapper around decryptSessionJson that catches crypto/parse errors.
+ */
+function safeDecrypt(sessionId) {
     try {
-        const iv = b64urlDecode(ivB64);
-        const tag = b64urlDecode(tagB64);
-        const ct = b64urlDecode(ctB64);
-        const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
-        decipher.setAuthTag(tag);
-        const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
-        const dec = JSON.parse(pt.toString('utf8'));
-        if (typeof dec.nodeId === 'string' &&
-            typeof dec.authSig === 'string' &&
-            typeof dec.uuid === 'string' &&
-            typeof dec.iat === 'number' &&
-            dec.authSig === sig) {
-            return dec;
-        }
-        throw new Error('Invalid session id');
+        return decryptSessionJson(sessionId);
     }
     catch {
         return null;
@@ -103,14 +142,24 @@ function parseSessionHeader(sessionHeader, token) {
     // cache.set(headerSse, decodedSse);
     // return { header, decoded, headerSse, isNew: true };
 }
-function createSessionId(protocol, token) {
+function createSessionId(protocol, token, options) {
     const authSig = (0, auth_token_utils_1.getTokenSignatureFingerprint)(token);
+    // Detect platform from user-agent if provided (before MCP initialize)
+    let platformType;
+    if (options?.userAgent) {
+        platformType = (0, notification_service_1.detectPlatformFromUserAgent)(options.userAgent, options.platformDetectionConfig);
+        // Only set if we detected something meaningful
+        if (platformType === 'unknown') {
+            platformType = undefined;
+        }
+    }
     const payload = {
         nodeId: MACHINE_ID,
         authSig,
         uuid: (0, crypto_1.randomUUID)(),
         iat: nowSec(),
         protocol,
+        platformType,
     };
     const id = encryptJson(payload);
     cache.set(id, payload);

package/src/auth/session/utils/session-id.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-id.utils.js","sourceRoot":"","sources":["../../../../../src/auth/session/utils/session-id.utils.ts"],"names":[],"mappings":";;AA+BA,kCASC;AAuCD,gDAmCC;AAED,0CAYC;AAED,sDAGC;AAED,4DAIC;AA3ID,yCAAyC;AACzC,mCAA+F;AAC/F,qDAAgD;AAEhD,yDAAkE;AAElE,qCAAqC;AACrC,MAAM,KAAK,GAAG,IAAI,6BAAY,CAA2B,IAAI,CAAC,CAAC;AAE/D,uDAAuD;AACvD,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;IACvB,2FAA2F;IAC3F,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAA,mBAAU,GAAE,CAAC,CAAC,sCAAsC;AAC1F,CAAC,CAAC,EAAE,CAAC;AAEL,2EAA2E;AAC3E,SAAS,MAAM;IACb,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,UAAU,CAAC,CAAC,sCAAsC;IACpG,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW;AAChE,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC5F,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED,SAAgB,WAAW,CAAC,GAAY;IACtC,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,GAAG,IAAA,oBAAW,EAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB;IAChD,MAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,yCAAyC;IACzC,OAAO,GAAG,YAAY,CAAC,EAAE,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAiB,EAAE,GAAW;IACtD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,IAAA,yBAAgB,EAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QAC1D,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,IACE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAC9B,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAC/B,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAC5B,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;YAC3B,GAAG,CAAC,OAAO,KAAK,GAAG,EACnB,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,MAAM;IACb,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,aAAiC,EACjC,KAAa;IAEb,MAAM,cAAc,GAAG,IAAA,+CAA4B,EAAC,KAAK,CAAC,CAAC;IAC3D,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,MAAM,CAAC,OAAO,KAAK,cAAc,EAAE,CAAC;gBACtC,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;YAChD,CAAC;YACD,wCAAwC;QAC1C,CAAC;QAED,MAAM,GAAG,GAAG,gBAAgB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;QAC5D,IAAI,GAAG,EAAE,CAAC;YACR,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,GAAuB,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;IACjB,kBAAkB;IAElB,yCAAyC;IACzC,wBAAwB;IACxB,6BAA6B;IAC7B,wBAAwB;IACxB,mBAAmB;IACnB,KAAK;IACL,uCAAuC;IACvC,6CAA6C;IAC7C,8BAA8B;IAC9B,oCAAoC;IACpC,sDAAsD;AACxD,CAAC;AAED,SAAgB,eAAe,CAAC,QAA2B,EAAE,KAAa;IACxE,MAAM,OAAO,GAAG,IAAA,+CAA4B,EAAC,KAAK,CAAC,CAAC;IACpD,MAAM,OAAO,GAAqB;QAChC,MAAM,EAAE,UAAU;QAClB,OAAO;QACP,IAAI,EAAE,IAAA,mBAAU,GAAE;QAClB,GAAG,EAAE,MAAM,EAAE;QACb,QAAQ;KACT,CAAC;IACF,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAChC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvB,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AACzB,CAAC;AAED,SAAgB,qBAAqB,CAAC,SAAiB,EAAE,YAAY,GAAG,EAAE,GAAG,EAAE;IAC7E,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9E,OAAO,kBAAkB,SAAS,qBAAqB,OAAO,0BAA0B,CAAC;AAC3F,CAAC;AAED,SAAgB,wBAAwB,CAAC,MAAe;IACtD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC/D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9B,CAAC","sourcesContent":["// auth/session/utils/session-id.utils.ts\nimport { randomUUID, createHash, randomBytes, createCipheriv, createDecipheriv } from 'crypto';\nimport { TinyTtlCache } from './tiny-ttl-cache';\nimport { HttpRequestIntent, SessionIdPayload } from '../../../common';\nimport { getTokenSignatureFingerprint } from './auth-token.utils';\n\n// 5s TTL cache for decrypted headers\nconst cache = new TinyTtlCache<string, SessionIdPayload>(5000);\n\n// Single-process machine id generated at server launch\nconst MACHINE_ID = (() => {\n  // Prefer an injected env (stable across restarts) if you have one; else random per launch:\n  return process.env['MACHINE_ID'] || randomUUID(); // TODO: move to gateway config module\n})();\n\n// Symmetric key derived from secret or machine id (stable for the process)\nfunction getKey(): Buffer {\n  const base = process.env['MCP_SESSION_SECRET'] || MACHINE_ID; // TODO: move to gateway config module\n  return createHash('sha256').update(base).digest(); // 32 bytes\n}\n\nfunction b64urlEncode(buf: Buffer): string {\n  return buf.toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '');\n}\n\nfunction b64urlDecode(s: string): Buffer {\n  const pad = 4 - (s.length % 4);\n  const base64 = s.replace(/-/g, '+').replace(/_/g, '/') + (pad < 4 ? '='.repeat(pad) : '');\n  return Buffer.from(base64, 'base64');\n}\n\nexport function encryptJson(obj: unknown): string {\n  const key = getKey();\n  const iv = randomBytes(12); // AES-GCM 96-bit IV\n  const cipher = createCipheriv('aes-256-gcm', key, iv);\n  const pt = Buffer.from(JSON.stringify(obj), 'utf8');\n  const ct = Buffer.concat([cipher.update(pt), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  // Pack iv.tag.ct as base64url(iv.tag.ct)\n  return `${b64urlEncode(iv)}.${b64urlEncode(tag)}.${b64urlEncode(ct)}`;\n}\n\nfunction decryptSessionId(sessionId: string, sig: string): SessionIdPayload | null {\n  const key = getKey();\n  const [ivB64, tagB64, ctB64] = sessionId.split('.');\n  if (!ivB64 || !tagB64 || !ctB64) return null;\n  try {\n    const iv = b64urlDecode(ivB64);\n    const tag = b64urlDecode(tagB64);\n    const ct = b64urlDecode(ctB64);\n    const decipher = createDecipheriv('aes-256-gcm', key, iv);\n    decipher.setAuthTag(tag);\n    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);\n    const dec = JSON.parse(pt.toString('utf8'));\n    if (\n      typeof dec.nodeId === 'string' &&\n      typeof dec.authSig === 'string' &&\n      typeof dec.uuid === 'string' &&\n      typeof dec.iat === 'number' &&\n      dec.authSig === sig\n    ) {\n      return dec;\n    }\n\n    throw new Error('Invalid session id');\n  } catch {\n    return null;\n  }\n}\n\nfunction nowSec(): number {\n  return Math.floor(Date.now() / 1000);\n}\n\n/**\n * Validates an existing session header OR creates a fresh one.\n * - Valid: nodeId matches local, authSig matches current Authorization\n * - On any mismatch/decrypt error → generate new\n */\nexport function parseSessionHeader(\n  sessionHeader: string | undefined,\n  token: string,\n): { id: string; payload: SessionIdPayload } | undefined {\n  const currentAuthSig = getTokenSignatureFingerprint(token);\n  if (sessionHeader) {\n    const cached = cache.get(sessionHeader);\n    if (cached) {\n      if (cached.authSig === currentAuthSig) {\n        return { id: sessionHeader, payload: cached };\n      }\n      // fallthrough to regenerate if mismatch\n    }\n\n    const dec = decryptSessionId(sessionHeader, currentAuthSig);\n    if (dec) {\n      cache.set(sessionHeader, dec);\n      return { id: sessionHeader, payload: dec as SessionIdPayload };\n    }\n  }\n\n  return undefined;\n  // // Create fresh\n\n  // const decodedSse: SessionIdPayload = {\n  //   nodeId: MACHINE_ID,\n  //   authSig: currentAuthSig,\n  //   uuid: randomUUID(),\n  //   iat: nowSec(),\n  // };\n  // const header = encryptJson(decoded);\n  // const headerSse = encryptJson(decodedSse);\n  // cache.set(header, decoded);\n  // cache.set(headerSse, decodedSse);\n  // return { header, decoded, headerSse, isNew: true };\n}\n\nexport function createSessionId(protocol: HttpRequestIntent, token: string) {\n  const authSig = getTokenSignatureFingerprint(token);\n  const payload: SessionIdPayload = {\n    nodeId: MACHINE_ID,\n    authSig,\n    uuid: randomUUID(),\n    iat: nowSec(),\n    protocol,\n  };\n  const id = encryptJson(payload);\n  cache.set(id, payload);\n  return { id, payload };\n}\n\nexport function generateSessionCookie(sessionId: string, ttlInMinutes = 60 * 24): string {\n  const expires = new Date(Date.now() + ttlInMinutes * 60 * 1000).toUTCString();\n  return `mcp_session_id=${sessionId}; Path=/; Expires=${expires}; HttpOnly; SameSite=Lax`;\n}\n\nexport function extractSessionFromCookie(cookie?: string): string | undefined {\n  if (!cookie) return undefined;\n  const m = cookie.match(/(^|;)\\s*mcp_session_id\\s*=\\s*([^;]*)/);\n  return m ? m[2] : undefined;\n}\n\n\n"]}
+{"version":3,"file":"session-id.utils.js","sourceRoot":"","sources":["../../../../../src/auth/session/utils/session-id.utils.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/session/utils/session-id.utils.ts\nimport { randomUUID, createHash, randomBytes, createCipheriv, createDecipheriv } from 'crypto';\nimport { TinyTtlCache } from './tiny-ttl-cache';\nimport { SessionIdPayload, TransportProtocolType, AIPlatformType } from '../../../common';\nimport { getTokenSignatureFingerprint } from './auth-token.utils';\nimport { detectPlatformFromUserAgent } from '../../../notification/notification.service';\nimport type { PlatformDetectionConfig } from '../../../common/types/options/session.options';\n\n// 5s TTL cache for decrypted headers\nconst cache = new TinyTtlCache<string, SessionIdPayload>(5000);\n\n// Single-process machine id generated at server launch\nconst MACHINE_ID = (() => {\n  // Prefer an injected env (stable across restarts) if you have one; else random per launch:\n  return process.env['MACHINE_ID'] || randomUUID(); // TODO: move to gateway config module\n})();\n\n// Symmetric key derived from secret or machine id (stable for the process)\nfunction getKey(): Buffer {\n  const base = process.env['MCP_SESSION_SECRET'] || MACHINE_ID; // TODO: move to gateway config module\n  return createHash('sha256').update(base).digest(); // 32 bytes\n}\n\nfunction b64urlEncode(buf: Buffer): string {\n  return buf.toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '');\n}\n\nfunction b64urlDecode(s: string): Buffer {\n  const pad = 4 - (s.length % 4);\n  const base64 = s.replace(/-/g, '+').replace(/_/g, '/') + (pad < 4 ? '='.repeat(pad) : '');\n  return Buffer.from(base64, 'base64');\n}\n\nexport function encryptJson(obj: unknown): string {\n  const key = getKey();\n  const iv = randomBytes(12); // AES-GCM 96-bit IV\n  const cipher = createCipheriv('aes-256-gcm', key, iv);\n  const pt = Buffer.from(JSON.stringify(obj), 'utf8');\n  const ct = Buffer.concat([cipher.update(pt), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  // Pack iv.tag.ct as base64url(iv.tag.ct)\n  return `${b64urlEncode(iv)}.${b64urlEncode(tag)}.${b64urlEncode(ct)}`;\n}\n\n/**\n * Low-level decryption that returns the raw JSON payload or null.\n * Handles all crypto/parsing failures by returning null.\n */\nfunction decryptSessionJson(sessionId: string): unknown {\n  const parts = sessionId.split('.');\n  if (parts.length !== 3) return null;\n\n  const [ivB64, tagB64, ctB64] = parts;\n  if (!ivB64 || !tagB64 || !ctB64) return null;\n\n  const key = getKey();\n  const iv = b64urlDecode(ivB64);\n  const tag = b64urlDecode(tagB64);\n  const ct = b64urlDecode(ctB64);\n\n  const decipher = createDecipheriv('aes-256-gcm', key, iv);\n  decipher.setAuthTag(tag);\n  const pt = Buffer.concat([decipher.update(ct), decipher.final()]);\n  return JSON.parse(pt.toString('utf8'));\n}\n\nfunction isValidSessionPayload(dec: unknown, sig: string): dec is SessionIdPayload {\n  if (typeof dec !== 'object' || dec === null) return false;\n  const d = dec as Record<string, unknown>;\n  return (\n    typeof d['nodeId'] === 'string' &&\n    typeof d['authSig'] === 'string' &&\n    typeof d['uuid'] === 'string' &&\n    typeof d['iat'] === 'number' &&\n    d['authSig'] === sig\n  );\n}\n\nfunction isValidPublicSessionPayload(dec: unknown): dec is SessionIdPayload {\n  if (typeof dec !== 'object' || dec === null) return false;\n  const d = dec as Record<string, unknown>;\n  return (\n    typeof d['nodeId'] === 'string' &&\n    d['authSig'] === 'public' &&\n    typeof d['uuid'] === 'string' &&\n    typeof d['iat'] === 'number' &&\n    d['isPublic'] === true\n  );\n}\n\nfunction decryptSessionId(sessionId: string, sig: string): SessionIdPayload | null {\n  const dec = safeDecrypt(sessionId);\n  return isValidSessionPayload(dec, sig) ? dec : null;\n}\n\n/**\n * Decrypt a public session ID without signature verification.\n * Public sessions use authSig: 'public' and isPublic: true\n */\nexport function decryptPublicSession(sessionId: string): SessionIdPayload | null {\n  const dec = safeDecrypt(sessionId);\n  return isValidPublicSessionPayload(dec) ? dec : null;\n}\n\n/**\n * Safe wrapper around decryptSessionJson that catches crypto/parse errors.\n */\nfunction safeDecrypt(sessionId: string): unknown {\n  try {\n    return decryptSessionJson(sessionId);\n  } catch {\n    return null;\n  }\n}\n\nfunction nowSec(): number {\n  return Math.floor(Date.now() / 1000);\n}\n\n/**\n * Validates an existing session header OR creates a fresh one.\n * - Valid: nodeId matches local, authSig matches current Authorization\n * - On any mismatch/decrypt error → generate new\n */\nexport function parseSessionHeader(\n  sessionHeader: string | undefined,\n  token: string,\n): { id: string; payload: SessionIdPayload } | undefined {\n  const currentAuthSig = getTokenSignatureFingerprint(token);\n  if (sessionHeader) {\n    const cached = cache.get(sessionHeader);\n    if (cached) {\n      if (cached.authSig === currentAuthSig) {\n        return { id: sessionHeader, payload: cached };\n      }\n      // fallthrough to regenerate if mismatch\n    }\n\n    const dec = decryptSessionId(sessionHeader, currentAuthSig);\n    if (dec) {\n      cache.set(sessionHeader, dec);\n      return { id: sessionHeader, payload: dec as SessionIdPayload };\n    }\n  }\n\n  return undefined;\n  // // Create fresh\n\n  // const decodedSse: SessionIdPayload = {\n  //   nodeId: MACHINE_ID,\n  //   authSig: currentAuthSig,\n  //   uuid: randomUUID(),\n  //   iat: nowSec(),\n  // };\n  // const header = encryptJson(decoded);\n  // const headerSse = encryptJson(decodedSse);\n  // cache.set(header, decoded);\n  // cache.set(headerSse, decodedSse);\n  // return { header, decoded, headerSse, isNew: true };\n}\n\nexport interface CreateSessionOptions {\n  /** User-Agent header for pre-initialize platform detection */\n  userAgent?: string;\n  /** Platform detection configuration from scope */\n  platformDetectionConfig?: PlatformDetectionConfig;\n}\n\nexport function createSessionId(protocol: TransportProtocolType, token: string, options?: CreateSessionOptions) {\n  const authSig = getTokenSignatureFingerprint(token);\n\n  // Detect platform from user-agent if provided (before MCP initialize)\n  let platformType: AIPlatformType | undefined;\n  if (options?.userAgent) {\n    platformType = detectPlatformFromUserAgent(options.userAgent, options.platformDetectionConfig);\n    // Only set if we detected something meaningful\n    if (platformType === 'unknown') {\n      platformType = undefined;\n    }\n  }\n\n  const payload: SessionIdPayload = {\n    nodeId: MACHINE_ID,\n    authSig,\n    uuid: randomUUID(),\n    iat: nowSec(),\n    protocol,\n    platformType,\n  };\n  const id = encryptJson(payload);\n  cache.set(id, payload);\n  return { id, payload };\n}\n\nexport function generateSessionCookie(sessionId: string, ttlInMinutes = 60 * 24): string {\n  const expires = new Date(Date.now() + ttlInMinutes * 60 * 1000).toUTCString();\n  return `mcp_session_id=${sessionId}; Path=/; Expires=${expires}; HttpOnly; SameSite=Lax`;\n}\n\nexport function extractSessionFromCookie(cookie?: string): string | undefined {\n  if (!cookie) return undefined;\n  const m = cookie.match(/(^|;)\\s*mcp_session_id\\s*=\\s*([^;]*)/);\n  return m ? m[2] : undefined;\n}\n"]}

package/src/auth/session/vault-encryption.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Vault Encryption
+ *
+ * Client-side key derivation for zero-knowledge credential storage.
+ *
+ * Security Model:
+ * - The JWT authorization token contains a unique `jti` (JWT ID) claim
+ * - A secret portion of the token (or a derived key) is used as the encryption key
+ * - The server stores encrypted blobs in Redis but CANNOT decrypt them
+ * - Only the client presenting the valid JWT can decrypt their vault
+ *
+ * Key Derivation:
+ * - Input: JWT token (after signature verification)
+ * - Extract: jti + a secret claim (e.g., `vaultKey` or derived from signature)
+ * - Derive: HKDF-SHA256 to produce AES-256 key
+ *
+ * Encryption:
+ * - Algorithm: AES-256-GCM (authenticated encryption)
+ * - IV: Random 12 bytes per encryption (stored with ciphertext)
+ * - Auth Tag: 16 bytes (ensures integrity)
+ */
+import { z } from 'zod';
+/**
+ * Encrypted data format stored in Redis
+ */
+export declare const encryptedDataSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    alg: z.ZodLiteral<"aes-256-gcm">;
+    iv: z.ZodString;
+    ct: z.ZodString;
+    tag: z.ZodString;
+}, z.core.$strip>;
+export type EncryptedData = z.infer<typeof encryptedDataSchema>;
+/**
+ * JWT claims required for key derivation
+ */
+export interface VaultKeyDerivationClaims {
+    /** JWT ID - unique identifier for this token/vault */
+    jti: string;
+    /** Vault key material - secret claim added during token generation */
+    vaultKey?: string;
+    /** Subject - user identifier */
+    sub: string;
+    /** Issued at timestamp */
+    iat: number;
+}
+/**
+ * Vault encryption configuration
+ */
+export interface VaultEncryptionConfig {
+    /**
+     * Server-side pepper added to key derivation
+     * This adds defense-in-depth: even with a stolen JWT,
+     * attacker needs the pepper to derive the key
+     */
+    pepper?: string;
+    /**
+     * Key derivation info string for HKDF
+     * Allows domain separation between different uses
+     */
+    hkdfInfo?: string;
+}
+/**
+ * VaultEncryption handles encryption/decryption of vault credentials
+ * using keys derived from the client's JWT authorization token.
+ *
+ * @example
+ * ```typescript
+ * const encryption = new VaultEncryption({ pepper: process.env.VAULT_PEPPER });
+ *
+ * // After JWT verification, derive the encryption key
+ * const key = encryption.deriveKey(jwtClaims);
+ *
+ * // Encrypt credentials before storing
+ * const encrypted = encryption.encrypt(JSON.stringify(credentials), key);
+ *
+ * // Decrypt when reading
+ * const decrypted = encryption.decrypt(encrypted, key);
+ * const credentials = JSON.parse(decrypted);
+ * ```
+ */
+export declare class VaultEncryption {
+    private readonly pepper;
+    private readonly hkdfInfo;
+    constructor(config?: VaultEncryptionConfig);
+    /**
+     * Derive an encryption key from JWT claims
+     *
+     * The key derivation uses HKDF-like construction:
+     * 1. Combine jti + vaultKey + sub + iat + pepper
+     * 2. Apply HMAC-SHA256 to derive a 256-bit key
+     *
+     * @param claims - JWT claims containing key material
+     * @returns 32-byte encryption key
+     */
+    deriveKey(claims: VaultKeyDerivationClaims): Buffer;
+    /**
+     * Derive a key directly from the raw JWT token string
+     *
+     * This is useful when you want to derive the key from the token
+     * before or without fully parsing the claims. Uses the token's
+     * signature portion as additional entropy.
+     *
+     * @param token - The raw JWT token string
+     * @param claims - Parsed JWT claims
+     * @returns 32-byte encryption key
+     */
+    deriveKeyFromToken(token: string, claims: VaultKeyDerivationClaims): Buffer;
+    /**
+     * Encrypt plaintext data using AES-256-GCM
+     *
+     * @param plaintext - Data to encrypt (typically JSON string)
+     * @param key - 32-byte encryption key from deriveKey()
+     * @returns Encrypted data object (safe to store in Redis)
+     */
+    encrypt(plaintext: string, key: Buffer): EncryptedData;
+    /**
+     * Decrypt encrypted data using AES-256-GCM
+     *
+     * @param encrypted - Encrypted data object from encrypt()
+     * @param key - 32-byte encryption key from deriveKey()
+     * @returns Decrypted plaintext
+     * @throws Error if decryption fails (wrong key, tampered data, etc.)
+     */
+    decrypt(encrypted: EncryptedData, key: Buffer): string;
+    /**
+     * Encrypt a JavaScript object (serializes to JSON first)
+     *
+     * @param data - Object to encrypt
+     * @param key - Encryption key
+     * @returns Encrypted data
+     */
+    encryptObject<T>(data: T, key: Buffer): EncryptedData;
+    /**
+     * Decrypt and parse a JavaScript object
+     *
+     * @param encrypted - Encrypted data
+     * @param key - Encryption key
+     * @returns Decrypted and parsed object
+     */
+    decryptObject<T>(encrypted: EncryptedData, key: Buffer): T;
+    /**
+     * Check if data is in encrypted format
+     *
+     * @param data - Data to check
+     * @returns True if data appears to be encrypted
+     */
+    isEncrypted(data: unknown): data is EncryptedData;
+}
+/**
+ * Vault entry with encrypted credentials
+ *
+ * The structure separates:
+ * - Metadata (unencrypted): id, userSub, timestamps, app lists
+ * - Sensitive data (encrypted): provider tokens, app credentials
+ */
+export declare const encryptedVaultEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    userSub: z.ZodString;
+    userEmail: z.ZodOptional<z.ZodString>;
+    userName: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodString;
+    createdAt: z.ZodNumber;
+    lastAccessAt: z.ZodNumber;
+    encryptedData: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        alg: z.ZodLiteral<"aes-256-gcm">;
+        iv: z.ZodString;
+        ct: z.ZodString;
+        tag: z.ZodString;
+    }, z.core.$strip>;
+    authorizedAppIds: z.ZodArray<z.ZodString>;
+    skippedAppIds: z.ZodArray<z.ZodString>;
+    pendingAuthIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type EncryptedVaultEntry = z.infer<typeof encryptedVaultEntrySchema>;
+/**
+ * Sensitive data that gets encrypted
+ */
+export interface VaultSensitiveData {
+    /** App credentials */
+    appCredentials: Record<string, unknown>;
+    /** Consent record */
+    consent?: unknown;
+    /** Federated login record */
+    federated?: unknown;
+    /** Pending auth details (URLs, scopes, etc.) */
+    pendingAuths: unknown[];
+}

package/src/auth/session/vault-encryption.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Vault Encryption
+ *
+ * Client-side key derivation for zero-knowledge credential storage.
+ *
+ * Security Model:
+ * - The JWT authorization token contains a unique `jti` (JWT ID) claim
+ * - A secret portion of the token (or a derived key) is used as the encryption key
+ * - The server stores encrypted blobs in Redis but CANNOT decrypt them
+ * - Only the client presenting the valid JWT can decrypt their vault
+ *
+ * Key Derivation:
+ * - Input: JWT token (after signature verification)
+ * - Extract: jti + a secret claim (e.g., `vaultKey` or derived from signature)
+ * - Derive: HKDF-SHA256 to produce AES-256 key
+ *
+ * Encryption:
+ * - Algorithm: AES-256-GCM (authenticated encryption)
+ * - IV: Random 12 bytes per encryption (stored with ciphertext)
+ * - Auth Tag: 16 bytes (ensures integrity)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptedVaultEntrySchema = exports.VaultEncryption = exports.encryptedDataSchema = void 0;
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+// ============================================
+// Types and Schemas
+// ============================================
+/**
+ * Encrypted data format stored in Redis
+ */
+exports.encryptedDataSchema = zod_1.z.object({
+    /** Version for future algorithm changes */
+    v: zod_1.z.literal(1),
+    /** Algorithm identifier */
+    alg: zod_1.z.literal('aes-256-gcm'),
+    /** Initialization vector (base64) */
+    iv: zod_1.z.string(),
+    /** Ciphertext (base64) */
+    ct: zod_1.z.string(),
+    /** Authentication tag (base64) */
+    tag: zod_1.z.string(),
+});
+// ============================================
+// Vault Encryption Class
+// ============================================
+/**
+ * VaultEncryption handles encryption/decryption of vault credentials
+ * using keys derived from the client's JWT authorization token.
+ *
+ * @example
+ * ```typescript
+ * const encryption = new VaultEncryption({ pepper: process.env.VAULT_PEPPER });
+ *
+ * // After JWT verification, derive the encryption key
+ * const key = encryption.deriveKey(jwtClaims);
+ *
+ * // Encrypt credentials before storing
+ * const encrypted = encryption.encrypt(JSON.stringify(credentials), key);
+ *
+ * // Decrypt when reading
+ * const decrypted = encryption.decrypt(encrypted, key);
+ * const credentials = JSON.parse(decrypted);
+ * ```
+ */
+class VaultEncryption {
+    pepper;
+    hkdfInfo;
+    constructor(config = {}) {
+        // Convert pepper to buffer, use empty if not provided
+        this.pepper = Buffer.from(config.pepper ?? '', 'utf8');
+        this.hkdfInfo = Buffer.from(config.hkdfInfo ?? 'frontmcp-vault-v1', 'utf8');
+    }
+    /**
+     * Derive an encryption key from JWT claims
+     *
+     * The key derivation uses HKDF-like construction:
+     * 1. Combine jti + vaultKey + sub + iat + pepper
+     * 2. Apply HMAC-SHA256 to derive a 256-bit key
+     *
+     * @param claims - JWT claims containing key material
+     * @returns 32-byte encryption key
+     */
+    deriveKey(claims) {
+        // Build the input key material (IKM)
+        // Using multiple claims ensures the key is unique per token
+        const ikm = Buffer.concat([
+            Buffer.from(claims.jti, 'utf8'),
+            Buffer.from(claims.vaultKey ?? '', 'utf8'),
+            Buffer.from(claims.sub, 'utf8'),
+            Buffer.from(claims.iat.toString(), 'utf8'),
+            this.pepper,
+        ]);
+        // HKDF-Extract: PRK = HMAC-SHA256(salt, IKM)
+        // Using hkdfInfo as salt for domain separation
+        const prk = (0, node_crypto_1.createHmac)('sha256', this.hkdfInfo).update(ikm).digest();
+        // HKDF-Expand: OKM = HMAC-SHA256(PRK, info || 0x01)
+        // We only need 32 bytes, so single iteration is sufficient
+        const okm = (0, node_crypto_1.createHmac)('sha256', prk)
+            .update(Buffer.concat([this.hkdfInfo, Buffer.from([0x01])]))
+            .digest();
+        return okm;
+    }
+    /**
+     * Derive a key directly from the raw JWT token string
+     *
+     * This is useful when you want to derive the key from the token
+     * before or without fully parsing the claims. Uses the token's
+     * signature portion as additional entropy.
+     *
+     * @param token - The raw JWT token string
+     * @param claims - Parsed JWT claims
+     * @returns 32-byte encryption key
+     */
+    deriveKeyFromToken(token, claims) {
+        // Extract signature from JWT (last part after final dot)
+        const parts = token.split('.');
+        const signature = parts[2] ?? '';
+        // Include signature in key derivation for additional entropy
+        const ikm = Buffer.concat([
+            Buffer.from(claims.jti, 'utf8'),
+            Buffer.from(claims.vaultKey ?? '', 'utf8'),
+            Buffer.from(claims.sub, 'utf8'),
+            Buffer.from(claims.iat.toString(), 'utf8'),
+            Buffer.from(signature, 'utf8'),
+            this.pepper,
+        ]);
+        const prk = (0, node_crypto_1.createHmac)('sha256', this.hkdfInfo).update(ikm).digest();
+        const okm = (0, node_crypto_1.createHmac)('sha256', prk)
+            .update(Buffer.concat([this.hkdfInfo, Buffer.from([0x01])]))
+            .digest();
+        return okm;
+    }
+    /**
+     * Encrypt plaintext data using AES-256-GCM
+     *
+     * @param plaintext - Data to encrypt (typically JSON string)
+     * @param key - 32-byte encryption key from deriveKey()
+     * @returns Encrypted data object (safe to store in Redis)
+     */
+    encrypt(plaintext, key) {
+        if (key.length !== 32) {
+            throw new Error('Encryption key must be 32 bytes');
+        }
+        // Generate random 12-byte IV (recommended for GCM)
+        const iv = (0, node_crypto_1.randomBytes)(12);
+        // Create cipher
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+        // Encrypt
+        const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        // Get authentication tag
+        const tag = cipher.getAuthTag();
+        return {
+            v: 1,
+            alg: 'aes-256-gcm',
+            iv: iv.toString('base64'),
+            ct: ciphertext.toString('base64'),
+            tag: tag.toString('base64'),
+        };
+    }
+    /**
+     * Decrypt encrypted data using AES-256-GCM
+     *
+     * @param encrypted - Encrypted data object from encrypt()
+     * @param key - 32-byte encryption key from deriveKey()
+     * @returns Decrypted plaintext
+     * @throws Error if decryption fails (wrong key, tampered data, etc.)
+     */
+    decrypt(encrypted, key) {
+        if (key.length !== 32) {
+            throw new Error('Encryption key must be 32 bytes');
+        }
+        // Validate encrypted data format
+        const parsed = exports.encryptedDataSchema.safeParse(encrypted);
+        if (!parsed.success) {
+            throw new Error('Invalid encrypted data format');
+        }
+        const { iv, ct, tag } = parsed.data;
+        // Decode from base64
+        const ivBuffer = Buffer.from(iv, 'base64');
+        const ciphertext = Buffer.from(ct, 'base64');
+        const tagBuffer = Buffer.from(tag, 'base64');
+        // Create decipher
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, ivBuffer);
+        decipher.setAuthTag(tagBuffer);
+        // Decrypt
+        try {
+            const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+            return plaintext.toString('utf8');
+        }
+        catch (error) {
+            // GCM authentication failed - wrong key or tampered data
+            throw new Error('Decryption failed: invalid key or corrupted data');
+        }
+    }
+    /**
+     * Encrypt a JavaScript object (serializes to JSON first)
+     *
+     * @param data - Object to encrypt
+     * @param key - Encryption key
+     * @returns Encrypted data
+     */
+    encryptObject(data, key) {
+        return this.encrypt(JSON.stringify(data), key);
+    }
+    /**
+     * Decrypt and parse a JavaScript object
+     *
+     * @param encrypted - Encrypted data
+     * @param key - Encryption key
+     * @returns Decrypted and parsed object
+     */
+    decryptObject(encrypted, key) {
+        const plaintext = this.decrypt(encrypted, key);
+        return JSON.parse(plaintext);
+    }
+    /**
+     * Check if data is in encrypted format
+     *
+     * @param data - Data to check
+     * @returns True if data appears to be encrypted
+     */
+    isEncrypted(data) {
+        return exports.encryptedDataSchema.safeParse(data).success;
+    }
+}
+exports.VaultEncryption = VaultEncryption;
+// ============================================
+// Encrypted Vault Entry Schema
+// ============================================
+/**
+ * Vault entry with encrypted credentials
+ *
+ * The structure separates:
+ * - Metadata (unencrypted): id, userSub, timestamps, app lists
+ * - Sensitive data (encrypted): provider tokens, app credentials
+ */
+exports.encryptedVaultEntrySchema = zod_1.z.object({
+    /** Vault ID (maps to JWT jti claim) */
+    id: zod_1.z.string(),
+    /** User subject identifier */
+    userSub: zod_1.z.string(),
+    /** User email (unencrypted for display) */
+    userEmail: zod_1.z.string().optional(),
+    /** User name (unencrypted for display) */
+    userName: zod_1.z.string().optional(),
+    /** Client ID that created this session */
+    clientId: zod_1.z.string(),
+    /** Creation timestamp */
+    createdAt: zod_1.z.number(),
+    /** Last access timestamp */
+    lastAccessAt: zod_1.z.number(),
+    /** Encrypted sensitive data (provider tokens, credentials, consent) */
+    encryptedData: exports.encryptedDataSchema,
+    /** Apps that are fully authorized (unencrypted for quick lookup) */
+    authorizedAppIds: zod_1.z.array(zod_1.z.string()),
+    /** Apps that were skipped (unencrypted for quick lookup) */
+    skippedAppIds: zod_1.z.array(zod_1.z.string()),
+    /** Pending auth IDs (unencrypted for lookup, actual URLs encrypted) */
+    pendingAuthIds: zod_1.z.array(zod_1.z.string()).default([]),
+});
+//# sourceMappingURL=vault-encryption.js.map

package/src/auth/session/vault-encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-encryption.js","sourceRoot":"","sources":["../../../../src/auth/session/vault-encryption.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Vault Encryption\n *\n * Client-side key derivation for zero-knowledge credential storage.\n *\n * Security Model:\n * - The JWT authorization token contains a unique `jti` (JWT ID) claim\n * - A secret portion of the token (or a derived key) is used as the encryption key\n * - The server stores encrypted blobs in Redis but CANNOT decrypt them\n * - Only the client presenting the valid JWT can decrypt their vault\n *\n * Key Derivation:\n * - Input: JWT token (after signature verification)\n * - Extract: jti + a secret claim (e.g., `vaultKey` or derived from signature)\n * - Derive: HKDF-SHA256 to produce AES-256 key\n *\n * Encryption:\n * - Algorithm: AES-256-GCM (authenticated encryption)\n * - IV: Random 12 bytes per encryption (stored with ciphertext)\n * - Auth Tag: 16 bytes (ensures integrity)\n */\n\nimport { createCipheriv, createDecipheriv, randomBytes, createHmac } from 'node:crypto';\nimport { z } from 'zod';\n\n// ============================================\n// Types and Schemas\n// ============================================\n\n/**\n * Encrypted data format stored in Redis\n */\nexport const encryptedDataSchema = z.object({\n  /** Version for future algorithm changes */\n  v: z.literal(1),\n  /** Algorithm identifier */\n  alg: z.literal('aes-256-gcm'),\n  /** Initialization vector (base64) */\n  iv: z.string(),\n  /** Ciphertext (base64) */\n  ct: z.string(),\n  /** Authentication tag (base64) */\n  tag: z.string(),\n});\n\nexport type EncryptedData = z.infer<typeof encryptedDataSchema>;\n\n/**\n * JWT claims required for key derivation\n */\nexport interface VaultKeyDerivationClaims {\n  /** JWT ID - unique identifier for this token/vault */\n  jti: string;\n  /** Vault key material - secret claim added during token generation */\n  vaultKey?: string;\n  /** Subject - user identifier */\n  sub: string;\n  /** Issued at timestamp */\n  iat: number;\n}\n\n/**\n * Vault encryption configuration\n */\nexport interface VaultEncryptionConfig {\n  /**\n   * Server-side pepper added to key derivation\n   * This adds defense-in-depth: even with a stolen JWT,\n   * attacker needs the pepper to derive the key\n   */\n  pepper?: string;\n  /**\n   * Key derivation info string for HKDF\n   * Allows domain separation between different uses\n   */\n  hkdfInfo?: string;\n}\n\n// ============================================\n// Vault Encryption Class\n// ============================================\n\n/**\n * VaultEncryption handles encryption/decryption of vault credentials\n * using keys derived from the client's JWT authorization token.\n *\n * @example\n * ```typescript\n * const encryption = new VaultEncryption({ pepper: process.env.VAULT_PEPPER });\n *\n * // After JWT verification, derive the encryption key\n * const key = encryption.deriveKey(jwtClaims);\n *\n * // Encrypt credentials before storing\n * const encrypted = encryption.encrypt(JSON.stringify(credentials), key);\n *\n * // Decrypt when reading\n * const decrypted = encryption.decrypt(encrypted, key);\n * const credentials = JSON.parse(decrypted);\n * ```\n */\nexport class VaultEncryption {\n  private readonly pepper: Buffer;\n  private readonly hkdfInfo: Buffer;\n\n  constructor(config: VaultEncryptionConfig = {}) {\n    // Convert pepper to buffer, use empty if not provided\n    this.pepper = Buffer.from(config.pepper ?? '', 'utf8');\n    this.hkdfInfo = Buffer.from(config.hkdfInfo ?? 'frontmcp-vault-v1', 'utf8');\n  }\n\n  /**\n   * Derive an encryption key from JWT claims\n   *\n   * The key derivation uses HKDF-like construction:\n   * 1. Combine jti + vaultKey + sub + iat + pepper\n   * 2. Apply HMAC-SHA256 to derive a 256-bit key\n   *\n   * @param claims - JWT claims containing key material\n   * @returns 32-byte encryption key\n   */\n  deriveKey(claims: VaultKeyDerivationClaims): Buffer {\n    // Build the input key material (IKM)\n    // Using multiple claims ensures the key is unique per token\n    const ikm = Buffer.concat([\n      Buffer.from(claims.jti, 'utf8'),\n      Buffer.from(claims.vaultKey ?? '', 'utf8'),\n      Buffer.from(claims.sub, 'utf8'),\n      Buffer.from(claims.iat.toString(), 'utf8'),\n      this.pepper,\n    ]);\n\n    // HKDF-Extract: PRK = HMAC-SHA256(salt, IKM)\n    // Using hkdfInfo as salt for domain separation\n    const prk = createHmac('sha256', this.hkdfInfo).update(ikm).digest();\n\n    // HKDF-Expand: OKM = HMAC-SHA256(PRK, info || 0x01)\n    // We only need 32 bytes, so single iteration is sufficient\n    const okm = createHmac('sha256', prk)\n      .update(Buffer.concat([this.hkdfInfo, Buffer.from([0x01])]))\n      .digest();\n\n    return okm;\n  }\n\n  /**\n   * Derive a key directly from the raw JWT token string\n   *\n   * This is useful when you want to derive the key from the token\n   * before or without fully parsing the claims. Uses the token's\n   * signature portion as additional entropy.\n   *\n   * @param token - The raw JWT token string\n   * @param claims - Parsed JWT claims\n   * @returns 32-byte encryption key\n   */\n  deriveKeyFromToken(token: string, claims: VaultKeyDerivationClaims): Buffer {\n    // Extract signature from JWT (last part after final dot)\n    const parts = token.split('.');\n    const signature = parts[2] ?? '';\n\n    // Include signature in key derivation for additional entropy\n    const ikm = Buffer.concat([\n      Buffer.from(claims.jti, 'utf8'),\n      Buffer.from(claims.vaultKey ?? '', 'utf8'),\n      Buffer.from(claims.sub, 'utf8'),\n      Buffer.from(claims.iat.toString(), 'utf8'),\n      Buffer.from(signature, 'utf8'),\n      this.pepper,\n    ]);\n\n    const prk = createHmac('sha256', this.hkdfInfo).update(ikm).digest();\n    const okm = createHmac('sha256', prk)\n      .update(Buffer.concat([this.hkdfInfo, Buffer.from([0x01])]))\n      .digest();\n\n    return okm;\n  }\n\n  /**\n   * Encrypt plaintext data using AES-256-GCM\n   *\n   * @param plaintext - Data to encrypt (typically JSON string)\n   * @param key - 32-byte encryption key from deriveKey()\n   * @returns Encrypted data object (safe to store in Redis)\n   */\n  encrypt(plaintext: string, key: Buffer): EncryptedData {\n    if (key.length !== 32) {\n      throw new Error('Encryption key must be 32 bytes');\n    }\n\n    // Generate random 12-byte IV (recommended for GCM)\n    const iv = randomBytes(12);\n\n    // Create cipher\n    const cipher = createCipheriv('aes-256-gcm', key, iv);\n\n    // Encrypt\n    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);\n\n    // Get authentication tag\n    const tag = cipher.getAuthTag();\n\n    return {\n      v: 1,\n      alg: 'aes-256-gcm',\n      iv: iv.toString('base64'),\n      ct: ciphertext.toString('base64'),\n      tag: tag.toString('base64'),\n    };\n  }\n\n  /**\n   * Decrypt encrypted data using AES-256-GCM\n   *\n   * @param encrypted - Encrypted data object from encrypt()\n   * @param key - 32-byte encryption key from deriveKey()\n   * @returns Decrypted plaintext\n   * @throws Error if decryption fails (wrong key, tampered data, etc.)\n   */\n  decrypt(encrypted: EncryptedData, key: Buffer): string {\n    if (key.length !== 32) {\n      throw new Error('Encryption key must be 32 bytes');\n    }\n\n    // Validate encrypted data format\n    const parsed = encryptedDataSchema.safeParse(encrypted);\n    if (!parsed.success) {\n      throw new Error('Invalid encrypted data format');\n    }\n\n    const { iv, ct, tag } = parsed.data;\n\n    // Decode from base64\n    const ivBuffer = Buffer.from(iv, 'base64');\n    const ciphertext = Buffer.from(ct, 'base64');\n    const tagBuffer = Buffer.from(tag, 'base64');\n\n    // Create decipher\n    const decipher = createDecipheriv('aes-256-gcm', key, ivBuffer);\n    decipher.setAuthTag(tagBuffer);\n\n    // Decrypt\n    try {\n      const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);\n\n      return plaintext.toString('utf8');\n    } catch (error) {\n      // GCM authentication failed - wrong key or tampered data\n      throw new Error('Decryption failed: invalid key or corrupted data');\n    }\n  }\n\n  /**\n   * Encrypt a JavaScript object (serializes to JSON first)\n   *\n   * @param data - Object to encrypt\n   * @param key - Encryption key\n   * @returns Encrypted data\n   */\n  encryptObject<T>(data: T, key: Buffer): EncryptedData {\n    return this.encrypt(JSON.stringify(data), key);\n  }\n\n  /**\n   * Decrypt and parse a JavaScript object\n   *\n   * @param encrypted - Encrypted data\n   * @param key - Encryption key\n   * @returns Decrypted and parsed object\n   */\n  decryptObject<T>(encrypted: EncryptedData, key: Buffer): T {\n    const plaintext = this.decrypt(encrypted, key);\n    return JSON.parse(plaintext) as T;\n  }\n\n  /**\n   * Check if data is in encrypted format\n   *\n   * @param data - Data to check\n   * @returns True if data appears to be encrypted\n   */\n  isEncrypted(data: unknown): data is EncryptedData {\n    return encryptedDataSchema.safeParse(data).success;\n  }\n}\n\n// ============================================\n// Encrypted Vault Entry Schema\n// ============================================\n\n/**\n * Vault entry with encrypted credentials\n *\n * The structure separates:\n * - Metadata (unencrypted): id, userSub, timestamps, app lists\n * - Sensitive data (encrypted): provider tokens, app credentials\n */\nexport const encryptedVaultEntrySchema = z.object({\n  /** Vault ID (maps to JWT jti claim) */\n  id: z.string(),\n  /** User subject identifier */\n  userSub: z.string(),\n  /** User email (unencrypted for display) */\n  userEmail: z.string().optional(),\n  /** User name (unencrypted for display) */\n  userName: z.string().optional(),\n  /** Client ID that created this session */\n  clientId: z.string(),\n  /** Creation timestamp */\n  createdAt: z.number(),\n  /** Last access timestamp */\n  lastAccessAt: z.number(),\n  /** Encrypted sensitive data (provider tokens, credentials, consent) */\n  encryptedData: encryptedDataSchema,\n  /** Apps that are fully authorized (unencrypted for quick lookup) */\n  authorizedAppIds: z.array(z.string()),\n  /** Apps that were skipped (unencrypted for quick lookup) */\n  skippedAppIds: z.array(z.string()),\n  /** Pending auth IDs (unencrypted for lookup, actual URLs encrypted) */\n  pendingAuthIds: z.array(z.string()).default([]),\n});\n\nexport type EncryptedVaultEntry = z.infer<typeof encryptedVaultEntrySchema>;\n\n/**\n * Sensitive data that gets encrypted\n */\nexport interface VaultSensitiveData {\n  /** App credentials */\n  appCredentials: Record<string, unknown>;\n  /** Consent record */\n  consent?: unknown;\n  /** Federated login record */\n  federated?: unknown;\n  /** Pending auth details (URLs, scopes, etc.) */\n  pendingAuths: unknown[];\n}\n"]}