@frontmcp/auth 1.10.16 → 1.11.0-rc.1

package/browser/session/session-credential-vault.mjs

@@ -0,0 +1,243 @@
+// libs/auth/src/session/session-credential-vault.ts
+import { getEnv, randomUUID } from "@frontmcp/utils";
+import { noopAuthLogger } from "../common/auth-logger.interface.mjs";
+import { VaultEncryption } from "./vault-encryption.mjs";
+var DEFAULT_KEY_PREFIX = "mcp:cred:";
+var DEFAULT_PENDING_TTL_MS = 6e5;
+var SessionCredentialVault = class {
+  storage;
+  encryption;
+  keyPrefix;
+  ttlMs;
+  pendingTtlMs;
+  logger;
+  /** Cache of derived AES keys, keyed by `${sub}:${vaultId}`. */
+  keyCache = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.storage = options.storage;
+    this.keyPrefix = options.keyPrefix ?? DEFAULT_KEY_PREFIX;
+    this.ttlMs = options.ttlMs;
+    this.pendingTtlMs = options.pendingTtlMs ?? DEFAULT_PENDING_TTL_MS;
+    this.logger = options.logger ?? noopAuthLogger;
+    const pepper = options.pepper ?? resolveVaultPepper(this.logger);
+    this.encryption = new VaultEncryption({ pepper, hkdfInfo: "frontmcp-session-credential-vault-v1" });
+  }
+  // ============================================
+  // Storage-key helpers
+  // ============================================
+  /** `cred:idx:<sub>` \u2192 current vaultId (the sub \u2192 vaultId indirection). */
+  indexKey(sub) {
+    return `${this.keyPrefix}idx:${sub}`;
+  }
+  /** `cred:keys:<sub>:<vaultId>` \u2192 JSON array of credential key names (the SET). */
+  keysKey(sub, vaultId) {
+    return `${this.keyPrefix}keys:${sub}:${vaultId}`;
+  }
+  /** `cred:data:<sub>:<vaultId>:<key>` \u2192 encrypted credential record. */
+  dataKey(sub, vaultId, key) {
+    return `${this.keyPrefix}data:${sub}:${vaultId}:${key}`;
+  }
+  /** `cred:pending:<pendingId>` \u2192 encrypted pending-authorize accumulator. */
+  pendingKey(pendingId) {
+    return `${this.keyPrefix}pending:${pendingId}`;
+  }
+  /** Convert the configured `ttlMs` into `SetOptions` (storage uses `ttlSeconds`). */
+  get credentialSetOpts() {
+    return this.ttlMs ? { ttlSeconds: Math.ceil(this.ttlMs / 1e3) } : void 0;
+  }
+  // ============================================
+  // Key derivation
+  // ============================================
+  /**
+   * Derive (and cache) the AES-256 key for a `(sub, vaultId)` pair. The vaultId
+   * acts as the HKDF salt, so rotating it makes prior ciphertext undecryptable.
+   */
+  deriveKey(sub, vaultId) {
+    const cacheKey = `${sub}:${vaultId}`;
+    const cached = this.keyCache.get(cacheKey);
+    if (cached) return cached;
+    const promise = this.encryption.deriveKey({ jti: vaultId, vaultKey: vaultId, sub, iat: 0 });
+    this.keyCache.set(cacheKey, promise);
+    return promise;
+  }
+  // ============================================
+  // vaultId indirection
+  // ============================================
+  /**
+   * Read the current vaultId for a subject, or undefined when the subject has no
+   * live vault (never authorized, or rotated away).
+   */
+  async getVaultId(sub) {
+    const raw = await this.storage.get(this.indexKey(sub));
+    return raw ?? void 0;
+  }
+  /**
+   * Mint a FRESH vaultId for a subject and point the indirection at it. Called
+   * at the start of each authorize so reconnect = empty vault. Returns the new
+   * vaultId. The old vaultId's ciphertext is left in storage but is
+   * unreachable (no index pointer) and undecryptable (different derived key);
+   * it expires via TTL when configured.
+   */
+  async rotateVault(sub) {
+    const vaultId = randomUUID();
+    await this.storage.set(this.indexKey(sub), vaultId, this.credentialSetOpts);
+    return vaultId;
+  }
+  // ============================================
+  // Credential CRUD (committed vault)
+  // ============================================
+  /**
+   * Encrypt + store a single credential into the vault identified by
+   * `(sub, vaultId)` and add its key to the key set. Used both to commit
+   * authorize-time credentials and to additively add a credential mid-session.
+   */
+  async store(sub, vaultId, key, value) {
+    const aesKey = await this.deriveKey(sub, vaultId);
+    const enc = await this.encryption.encryptObject(this.normalize(value), aesKey);
+    const record = { enc };
+    await this.storage.set(this.dataKey(sub, vaultId, key), JSON.stringify(record), this.credentialSetOpts);
+    await this.addKeyToSet(sub, vaultId, key);
+  }
+  /**
+   * Decrypt and return a credential by key for a subject's CURRENT vault.
+   * Returns undefined when there is no live vault or no such key, or when
+   * decryption fails (e.g. a stale pointer to rotated-away ciphertext).
+   */
+  async get(sub, key) {
+    const vaultId = await this.getVaultId(sub);
+    if (!vaultId) return void 0;
+    const raw = await this.storage.get(this.dataKey(sub, vaultId, key));
+    if (!raw) return void 0;
+    try {
+      const record = JSON.parse(raw);
+      const aesKey = await this.deriveKey(sub, vaultId);
+      return await this.encryption.decryptObject(record.enc, aesKey);
+    } catch (err) {
+      this.logger.warn(`SessionCredentialVault: failed to read credential "${key}": ${errMsg(err)}`);
+      return void 0;
+    }
+  }
+  /**
+   * List the credential keys available in a subject's current vault. Returns an
+   * empty array when there is no live vault (e.g. after rotation on reconnect).
+   */
+  async list(sub) {
+    const vaultId = await this.getVaultId(sub);
+    if (!vaultId) return [];
+    return this.readKeySet(sub, vaultId);
+  }
+  /**
+   * Remove a credential by key from a subject's current vault (deletes the
+   * ciphertext and drops the key from the set). No-op when absent.
+   */
+  async remove(sub, key) {
+    const vaultId = await this.getVaultId(sub);
+    if (!vaultId) return;
+    await this.storage.delete(this.dataKey(sub, vaultId, key));
+    const keys = await this.readKeySet(sub, vaultId);
+    const next = keys.filter((k) => k !== key);
+    if (next.length !== keys.length) {
+      await this.writeKeySet(sub, vaultId, next);
+    }
+  }
+  // ============================================
+  // Authorize-time accumulation + commit
+  // ============================================
+  /**
+   * Stage credentials returned by `authenticate()` under a pending id, encrypted
+   * against a freshly-rotated vaultId for `sub`. They are NOT visible to tools
+   * until {@link commit} flushes them \u2014 this lets the authorize flow accumulate
+   * credentials before the subject's identity is final.
+   *
+   * @returns the vaultId the credentials were staged against.
+   */
+  async stage(pendingId, sub, credentials) {
+    const vaultId = await this.rotateVault(sub);
+    const creds = {};
+    for (const cred of credentials) {
+      const aesKey = await this.deriveKey(sub, vaultId);
+      const { key, ...value } = cred;
+      creds[key] = { enc: await this.encryption.encryptObject(this.normalize(value), aesKey) };
+    }
+    const batch = { sub, vaultId, creds };
+    await this.storage.set(this.pendingKey(pendingId), JSON.stringify(batch), {
+      ttlSeconds: Math.ceil(this.pendingTtlMs / 1e3)
+    });
+    return vaultId;
+  }
+  /**
+   * Flush a staged batch into the live vault, binding it to `sub`. The staged
+   * batch's `sub` must equal the supplied `sub` (the one baked into the minted
+   * token) \u2014 a mismatch is refused so credentials can never be committed under a
+   * different identity than the one that will read them.
+   *
+   * @returns true when a batch was committed, false when none was staged.
+   */
+  async commit(pendingId, sub) {
+    const raw = await this.storage.get(this.pendingKey(pendingId));
+    if (!raw) return false;
+    let batch;
+    try {
+      batch = JSON.parse(raw);
+    } catch {
+      await this.storage.delete(this.pendingKey(pendingId));
+      return false;
+    }
+    if (batch.sub !== sub) {
+      this.logger.warn("SessionCredentialVault: pending batch subject mismatch on commit; discarding");
+      await this.storage.delete(this.pendingKey(pendingId));
+      return false;
+    }
+    await this.storage.set(this.indexKey(sub), batch.vaultId, this.credentialSetOpts);
+    const keys = [];
+    for (const [key, record] of Object.entries(batch.creds)) {
+      await this.storage.set(this.dataKey(sub, batch.vaultId, key), JSON.stringify(record), this.credentialSetOpts);
+      keys.push(key);
+    }
+    await this.writeKeySet(sub, batch.vaultId, keys);
+    await this.storage.delete(this.pendingKey(pendingId));
+    return true;
+  }
+  // ============================================
+  // Key-set helpers
+  // ============================================
+  async readKeySet(sub, vaultId) {
+    const raw = await this.storage.get(this.keysKey(sub, vaultId));
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed.filter((k) => typeof k === "string") : [];
+    } catch {
+      return [];
+    }
+  }
+  async writeKeySet(sub, vaultId, keys) {
+    const unique = [...new Set(keys)];
+    await this.storage.set(this.keysKey(sub, vaultId), JSON.stringify(unique), this.credentialSetOpts);
+  }
+  async addKeyToSet(sub, vaultId, key) {
+    const keys = await this.readKeySet(sub, vaultId);
+    if (!keys.includes(key)) {
+      keys.push(key);
+      await this.writeKeySet(sub, vaultId, keys);
+    }
+  }
+  /** Strip undefined metadata so the encrypted JSON stays minimal. */
+  normalize(value) {
+    return value.metadata === void 0 ? { secret: value.secret } : { secret: value.secret, metadata: value.metadata };
+  }
+};
+function resolveVaultPepper(logger) {
+  const fromEnv = getEnv("VAULT_SECRET") ?? getEnv("JWT_SECRET");
+  if (fromEnv && fromEnv.trim().length > 0) return fromEnv;
+  logger.warn(
+    "SessionCredentialVault: neither VAULT_SECRET nor JWT_SECRET is set; using a random per-process pepper. Stored credentials will NOT survive a restart and cannot be shared across instances. Set VAULT_SECRET (or JWT_SECRET) for persistent, multi-instance credential storage."
+  );
+  return randomUUID() + randomUUID();
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+export {
+  SessionCredentialVault
+};

package/browser/session/session-crypto.mjs

@@ -0,0 +1,39 @@
+// libs/auth/src/session/session-crypto.ts
+import {
+  signData,
+  verifyData,
+  isSignedData,
+  verifyOrParseData,
+  getEnv,
+  isProduction
+} from "@frontmcp/utils";
+import { SessionSecretRequiredError } from "../errors/auth-internal.errors.mjs";
+function getSigningSecret(config) {
+  const secret = config?.secret || getEnv("MCP_SESSION_SECRET");
+  if (!secret) {
+    if (isProduction()) {
+      throw new SessionSecretRequiredError("session signing");
+    }
+    console.warn("[SessionCrypto] MCP_SESSION_SECRET not set. Using insecure default for development only.");
+    return "insecure-dev-secret-do-not-use-in-production";
+  }
+  return secret;
+}
+function resolveConfig(config) {
+  return { secret: getSigningSecret(config) };
+}
+function signSession(session, config) {
+  return signData(session, resolveConfig(config));
+}
+function verifySession(signedData, config) {
+  return verifyData(signedData, resolveConfig(config));
+}
+function verifyOrParseSession(data, config) {
+  return verifyOrParseData(data, resolveConfig(config));
+}
+export {
+  isSignedData as isSignedSession,
+  signSession,
+  verifyOrParseSession,
+  verifySession
+};

package/browser/session/session-rate-limiter.mjs

@@ -0,0 +1,126 @@
+// libs/auth/src/session/session-rate-limiter.ts
+var SessionRateLimiter = class {
+  windowMs;
+  maxRequests;
+  requests = /* @__PURE__ */ new Map();
+  cleanupIntervalMs;
+  cleanupTimer = null;
+  constructor(config = {}) {
+    this.windowMs = config.windowMs ?? 6e4;
+    this.maxRequests = config.maxRequests ?? 100;
+    this.cleanupIntervalMs = config.cleanupIntervalMs ?? 6e4;
+  }
+  /**
+   * Start the periodic cleanup timer on first use (idempotent). Deferred out of
+   * the constructor so constructing an instance at module scope has no side
+   * effects \u2014 see the constructor note on V8-isolate global-scope restrictions.
+   */
+  ensureCleanupTimer() {
+    if (this.cleanupTimer || this.cleanupIntervalMs <= 0) return;
+    this.cleanupTimer = setInterval(() => this.cleanup(), this.cleanupIntervalMs);
+    if (typeof this.cleanupTimer.unref === "function") this.cleanupTimer.unref();
+  }
+  /**
+   * Check if a request is allowed for the given key.
+   *
+   * @param key - Identifier for rate limiting (e.g., client IP, session ID prefix)
+   * @returns Rate limit result with allowed status and metadata
+   */
+  check(key) {
+    this.ensureCleanupTimer();
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    let timestamps = this.requests.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.requests.set(key, timestamps);
+    }
+    const validTimestamps = timestamps.filter((t) => t > windowStart);
+    const oldestInWindow = validTimestamps[0] ?? now;
+    const resetAt = oldestInWindow + this.windowMs;
+    if (validTimestamps.length >= this.maxRequests) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetAt,
+        retryAfterMs: resetAt - now
+      };
+    }
+    validTimestamps.push(now);
+    this.requests.set(key, validTimestamps);
+    return {
+      allowed: true,
+      remaining: this.maxRequests - validTimestamps.length,
+      resetAt
+    };
+  }
+  /**
+   * Check if a request would be allowed without recording it.
+   * Useful for pre-checking without consuming quota.
+   *
+   * @param key - Identifier for rate limiting
+   * @returns true if request would be allowed
+   */
+  wouldAllow(key) {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    const timestamps = this.requests.get(key);
+    if (!timestamps) return true;
+    const validCount = timestamps.filter((t) => t > windowStart).length;
+    return validCount < this.maxRequests;
+  }
+  /**
+   * Reset rate limit for a specific key.
+   * Useful for testing or after successful authentication.
+   *
+   * @param key - Identifier to reset
+   */
+  reset(key) {
+    this.requests.delete(key);
+  }
+  /**
+   * Clean up expired entries from all keys.
+   * Called automatically on configured interval, but can be called manually.
+   */
+  cleanup() {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    for (const [key, timestamps] of this.requests.entries()) {
+      const valid = timestamps.filter((t) => t > windowStart);
+      if (valid.length === 0) {
+        this.requests.delete(key);
+      } else if (valid.length < timestamps.length) {
+        this.requests.set(key, valid);
+      }
+    }
+  }
+  /**
+   * Get current statistics for monitoring.
+   */
+  getStats() {
+    let totalRequests = 0;
+    for (const timestamps of this.requests.values()) {
+      totalRequests += timestamps.length;
+    }
+    return {
+      totalKeys: this.requests.size,
+      totalRequests
+    };
+  }
+  /**
+   * Stop the automatic cleanup timer.
+   * Call this when disposing of the rate limiter.
+   */
+  dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.requests.clear();
+  }
+};
+var defaultSessionRateLimiter = new SessionRateLimiter();
+export {
+  SessionRateLimiter,
+  defaultSessionRateLimiter
+};

package/browser/session/session.transport.mjs

@@ -0,0 +1,16 @@
+// libs/auth/src/session/session.transport.ts
+import { randomUUID } from "@frontmcp/utils";
+var TransportIdGenerator = class {
+  /**
+   * Create a transport session ID.
+   * Generates JWT-style IDs for distributed session support.
+   *
+   * @returns A transport session ID (UUID without dashes)
+   */
+  static createId() {
+    return randomUUID().replace(/-/g, "");
+  }
+};
+export {
+  TransportIdGenerator
+};

package/browser/session/signin-binding.mjs

@@ -0,0 +1,30 @@
+// libs/auth/src/session/signin-binding.ts
+import { base64urlEncode, getCookie, randomBytes, sha256Hex, timingSafeEqual } from "@frontmcp/utils";
+var SIGNIN_BINDING_COOKIE_PREFIX = "frontmcp_signin_";
+var SIGNIN_BINDING_SECURE_COOKIE_PREFIX = `__Host-${SIGNIN_BINDING_COOKIE_PREFIX}`;
+var SIGNIN_BINDING_MAX_AGE_SECONDS = 30 * 60;
+function signinBindingCookieName(pendingAuthId, options = {}) {
+  const prefix = options.secure ? SIGNIN_BINDING_SECURE_COOKIE_PREFIX : SIGNIN_BINDING_COOKIE_PREFIX;
+  return `${prefix}${sha256Hex(`signin:${pendingAuthId}`).slice(0, 16)}`;
+}
+function createSigninBinding(pendingAuthId, options = {}) {
+  const value = base64urlEncode(randomBytes(32));
+  return { cookieName: signinBindingCookieName(pendingAuthId, options), value, hash: sha256Hex(value) };
+}
+function signinBindingMatches(cookieHeader, pendingAuthId, expectedHash, options = {}) {
+  if (!expectedHash) return false;
+  const value = getCookie(cookieHeader, signinBindingCookieName(pendingAuthId, options));
+  if (!value) return false;
+  const encoder = new TextEncoder();
+  const actual = encoder.encode(sha256Hex(value));
+  const expected = encoder.encode(expectedHash);
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+export {
+  SIGNIN_BINDING_COOKIE_PREFIX,
+  SIGNIN_BINDING_MAX_AGE_SECONDS,
+  SIGNIN_BINDING_SECURE_COOKIE_PREFIX,
+  createSigninBinding,
+  signinBindingCookieName,
+  signinBindingMatches
+};

package/browser/session/storage/in-memory-authorization-vault.mjs

@@ -0,0 +1,28 @@
+// libs/auth/src/session/storage/in-memory-authorization-vault.ts
+import { MemoryStorageAdapter } from "@frontmcp/utils";
+import { StorageAuthorizationVault } from "./storage-authorization-vault.mjs";
+var InMemoryAuthorizationVault = class extends StorageAuthorizationVault {
+  memoryAdapter;
+  constructor(options = {}) {
+    const memoryAdapter = new MemoryStorageAdapter();
+    super(memoryAdapter, {
+      namespace: options.namespace ?? "vault",
+      pendingAuthTtlMs: options.pendingAuthTtlMs
+    });
+    this.memoryAdapter = memoryAdapter;
+    void this.memoryAdapter.connect();
+  }
+  /**
+   * Clear all stored data.
+   * Useful for testing.
+   */
+  async clear() {
+    const keys = await this.memoryAdapter.keys("*");
+    for (const key of keys) {
+      await this.memoryAdapter.delete(key);
+    }
+  }
+};
+export {
+  InMemoryAuthorizationVault
+};

package/browser/session/storage/index.mjs

@@ -0,0 +1,14 @@
+// libs/auth/src/session/storage/index.ts
+import { TypedStorage } from "@frontmcp/utils";
+import { EncryptedTypedStorage, EncryptedStorageError } from "@frontmcp/utils";
+import { StorageTokenStore } from "./storage-token-store.mjs";
+import { StorageAuthorizationVault } from "./storage-authorization-vault.mjs";
+import { InMemoryAuthorizationVault } from "./in-memory-authorization-vault.mjs";
+export {
+  EncryptedStorageError,
+  EncryptedTypedStorage,
+  InMemoryAuthorizationVault,
+  StorageAuthorizationVault,
+  StorageTokenStore,
+  TypedStorage
+};