@frontmcp/utils 1.10.16 → 1.11.0-rc.1

package/browser/crypto/index.mjs

@@ -0,0 +1,281 @@
+// libs/utils/src/crypto/index.ts
+import * as platformCrypto from "./browser.mjs";
+import { isNode } from "./runtime.mjs";
+import { rsaVerifyBrowser } from "./web-rsa.mjs";
+import { isRsaPssAlg, jwtAlgToNodeAlg, jwtAlgToWebCryptoAlg } from "./jwt-alg.mjs";
+import { isNode as isNode2, isBrowser, assertNode } from "./runtime.mjs";
+import {
+  EncryptedBlobError,
+  encryptValue,
+  decryptValue,
+  tryDecryptValue,
+  serializeBlob,
+  deserializeBlob,
+  tryDeserializeBlob,
+  isValidEncryptedBlob,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  tryDeserializeAndDecrypt
+} from "./encrypted-blob.mjs";
+import {
+  MIN_CODE_VERIFIER_LENGTH,
+  MAX_CODE_VERIFIER_LENGTH,
+  DEFAULT_CODE_VERIFIER_LENGTH,
+  PkceError,
+  generateCodeVerifier,
+  generateCodeChallenge,
+  verifyCodeChallenge,
+  generatePkcePair,
+  isValidCodeVerifier,
+  isValidCodeChallenge
+} from "./pkce/index.mjs";
+import {
+  secretDataSchema,
+  validateSecretData,
+  parseSecretData,
+  isSecretPersistenceEnabled,
+  resolveSecretPath,
+  loadSecret,
+  saveSecret,
+  deleteSecret,
+  generateSecret,
+  createSecretData,
+  getOrCreateSecret,
+  clearCachedSecret,
+  isSecretCached
+} from "./secret-persistence/index.mjs";
+import {
+  signData,
+  verifyData,
+  isSignedData,
+  verifyOrParseData
+} from "./hmac-signing.mjs";
+import {
+  asymmetricAlgSchema,
+  secretKeyDataSchema,
+  asymmetricKeyDataSchema,
+  anyKeyDataSchema,
+  validateKeyData,
+  parseKeyData,
+  isSecretKeyData,
+  isAsymmetricKeyData,
+  KeyPersistence,
+  createKeyPersistence,
+  createKeyPersistenceWithStorage
+} from "./key-persistence/index.mjs";
+function getCrypto() {
+  return platformCrypto.cryptoProvider;
+}
+function rsaVerify2(jwtAlg, data, publicJwk, signature) {
+  if (isNode()) {
+    return Promise.resolve(platformCrypto.rsaVerify(jwtAlg, data, publicJwk, signature));
+  }
+  return rsaVerifyBrowser(jwtAlg, data, publicJwk, signature);
+}
+function rsaSignBase64Url2(jwtAlg, data, privateJwk) {
+  if (!isNode()) {
+    throw new Error("rsaSignBase64Url is only available in Node.js runtimes");
+  }
+  return platformCrypto.rsaSignBase64Url(jwtAlg, data, privateJwk);
+}
+function rsaVerifySync2(jwtAlg, data, publicJwk, signature) {
+  if (!isNode()) {
+    throw new Error("rsaVerifySync is only available in Node.js runtimes; use the async rsaVerify in browsers");
+  }
+  return platformCrypto.rsaVerifySync(jwtAlg, data, publicJwk, signature);
+}
+function pemToPublicJwk2(pem) {
+  if (!isNode()) {
+    throw new Error("pemToPublicJwk is only available in Node.js runtimes");
+  }
+  return platformCrypto.pemToPublicJwk(pem);
+}
+function generateRsaKeyPair2(modulusLength, alg) {
+  if (!isNode()) {
+    throw new Error("generateRsaKeyPair is only available in Node.js runtimes");
+  }
+  return platformCrypto.generateRsaKeyPair(modulusLength, alg);
+}
+function randomUUID() {
+  return getCrypto().randomUUID();
+}
+function randomBytes(length) {
+  if (!Number.isInteger(length) || length <= 0) {
+    throw new Error(`randomBytes length must be a positive integer, got ${length}`);
+  }
+  return getCrypto().randomBytes(length);
+}
+function sha256(data) {
+  return getCrypto().sha256(data);
+}
+function sha256Hex(data) {
+  return getCrypto().sha256Hex(data);
+}
+function hmacSha256(key, data) {
+  return getCrypto().hmacSha256(key, data);
+}
+var HKDF_SHA256_MAX_LENGTH = 255 * 32;
+function hkdfSha256(ikm, salt, info, length) {
+  if (!Number.isInteger(length) || length <= 0) {
+    throw new Error(`HKDF length must be a positive integer, got ${length}`);
+  }
+  if (length > HKDF_SHA256_MAX_LENGTH) {
+    throw new Error(`HKDF-SHA256 length cannot exceed ${HKDF_SHA256_MAX_LENGTH} bytes, got ${length}`);
+  }
+  return getCrypto().hkdfSha256(ikm, salt, info, length);
+}
+function encryptAesGcm(key, plaintext, iv) {
+  if (key.length !== 32) {
+    throw new Error(`AES-256-GCM requires a 32-byte key, got ${key.length} bytes`);
+  }
+  if (iv.length !== 12) {
+    throw new Error(`AES-GCM requires a 12-byte IV, got ${iv.length} bytes`);
+  }
+  return getCrypto().encryptAesGcm(key, plaintext, iv);
+}
+function decryptAesGcm(key, ciphertext, iv, tag) {
+  if (key.length !== 32) {
+    throw new Error(`AES-256-GCM requires a 32-byte key, got ${key.length} bytes`);
+  }
+  if (iv.length !== 12) {
+    throw new Error(`AES-GCM requires a 12-byte IV, got ${iv.length} bytes`);
+  }
+  if (tag.length !== 16) {
+    throw new Error(`AES-GCM requires a 16-byte authentication tag, got ${tag.length} bytes`);
+  }
+  return getCrypto().decryptAesGcm(key, ciphertext, iv, tag);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`timingSafeEqual requires equal-length arrays, got ${a.length} and ${b.length} bytes`);
+  }
+  return getCrypto().timingSafeEqual(a, b);
+}
+function bytesToHex(data) {
+  return Array.from(data).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function base64urlEncode(data) {
+  let base64;
+  if (typeof Buffer !== "undefined") {
+    base64 = Buffer.from(data).toString("base64");
+  } else {
+    const binString = Array.from(data, (byte) => String.fromCodePoint(byte)).join("");
+    base64 = btoa(binString);
+  }
+  const result = base64.replace(/\+/g, "-").replace(/\//g, "_");
+  let end = result.length;
+  while (end > 0 && result[end - 1] === "=") {
+    end--;
+  }
+  return result.slice(0, end);
+}
+function base64urlDecode(data) {
+  let base64 = data.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = base64.length % 4;
+  if (pad) {
+    base64 += "=".repeat(4 - pad);
+  }
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(base64, "base64"));
+  } else {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, (c) => c.codePointAt(0) ?? 0);
+  }
+}
+function base64Encode(data) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(data).toString("base64");
+  } else {
+    const binString = Array.from(data, (byte) => String.fromCodePoint(byte)).join("");
+    return btoa(binString);
+  }
+}
+function base64Decode(data) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(data, "base64"));
+  } else {
+    const binString = atob(data);
+    return Uint8Array.from(binString, (c) => c.codePointAt(0) ?? 0);
+  }
+}
+function sha256Base64url(data) {
+  return base64urlEncode(sha256(data));
+}
+export {
+  DEFAULT_CODE_VERIFIER_LENGTH,
+  EncryptedBlobError,
+  KeyPersistence,
+  MAX_CODE_VERIFIER_LENGTH,
+  MIN_CODE_VERIFIER_LENGTH,
+  PkceError,
+  anyKeyDataSchema,
+  assertNode,
+  asymmetricAlgSchema,
+  asymmetricKeyDataSchema,
+  base64Decode,
+  base64Encode,
+  base64urlDecode,
+  base64urlEncode,
+  bytesToHex,
+  clearCachedSecret,
+  createKeyPersistence,
+  createKeyPersistenceWithStorage,
+  createSecretData,
+  decryptAesGcm,
+  decryptValue,
+  deleteSecret,
+  deserializeAndDecrypt,
+  deserializeBlob,
+  encryptAesGcm,
+  encryptAndSerialize,
+  encryptValue,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generatePkcePair,
+  generateRsaKeyPair2 as generateRsaKeyPair,
+  generateSecret,
+  getCrypto,
+  getOrCreateSecret,
+  hkdfSha256,
+  hmacSha256,
+  isAsymmetricKeyData,
+  isBrowser,
+  isNode2 as isNode,
+  isRsaPssAlg,
+  isSecretCached,
+  isSecretKeyData,
+  isSecretPersistenceEnabled,
+  isSignedData,
+  isValidCodeChallenge,
+  isValidCodeVerifier,
+  isValidEncryptedBlob,
+  jwtAlgToNodeAlg,
+  jwtAlgToWebCryptoAlg,
+  loadSecret,
+  parseKeyData,
+  parseSecretData,
+  pemToPublicJwk2 as pemToPublicJwk,
+  randomBytes,
+  randomUUID,
+  resolveSecretPath,
+  rsaSignBase64Url2 as rsaSignBase64Url,
+  rsaVerify2 as rsaVerify,
+  rsaVerifySync2 as rsaVerifySync,
+  saveSecret,
+  secretDataSchema,
+  secretKeyDataSchema,
+  serializeBlob,
+  sha256,
+  sha256Base64url,
+  sha256Hex,
+  signData,
+  timingSafeEqual,
+  tryDecryptValue,
+  tryDeserializeAndDecrypt,
+  tryDeserializeBlob,
+  validateKeyData,
+  validateSecretData,
+  verifyCodeChallenge,
+  verifyData,
+  verifyOrParseData
+};

package/browser/crypto/jwt-alg.mjs

@@ -0,0 +1,40 @@
+// libs/utils/src/crypto/jwt-alg.ts
+var JWT_ALG_TO_NODE_DIGEST = {
+  RS256: "RSA-SHA256",
+  RS384: "RSA-SHA384",
+  RS512: "RSA-SHA512",
+  // For RSA-PSS, Node's crypto.sign/verify uses the digest algorithm + explicit PSS padding options.
+  PS256: "RSA-SHA256",
+  PS384: "RSA-SHA384",
+  PS512: "RSA-SHA512"
+};
+function jwtAlgToNodeAlg(jwtAlg) {
+  const nodeAlg = JWT_ALG_TO_NODE_DIGEST[jwtAlg];
+  if (!nodeAlg) {
+    throw new Error(`Unsupported JWT algorithm: ${jwtAlg}`);
+  }
+  return nodeAlg;
+}
+function isRsaPssAlg(jwtAlg) {
+  return jwtAlg.startsWith("PS");
+}
+var JWT_ALG_TO_WEB_CRYPTO = {
+  RS256: "SHA-256",
+  RS384: "SHA-384",
+  RS512: "SHA-512",
+  PS256: "SHA-256",
+  PS384: "SHA-384",
+  PS512: "SHA-512"
+};
+function jwtAlgToWebCryptoAlg(jwtAlg) {
+  const webAlg = JWT_ALG_TO_WEB_CRYPTO[jwtAlg];
+  if (!webAlg) {
+    throw new Error(`Unsupported JWT algorithm for WebCrypto: ${jwtAlg}`);
+  }
+  return webAlg;
+}
+export {
+  isRsaPssAlg,
+  jwtAlgToNodeAlg,
+  jwtAlgToWebCryptoAlg
+};

package/browser/crypto/key-persistence/factory.mjs

@@ -0,0 +1,134 @@
+// libs/utils/src/crypto/key-persistence/factory.ts
+import { isNode, isBrowser } from "../runtime.mjs";
+import { cryptoProvider } from "../browser.mjs";
+import { MemoryStorageAdapter } from "../../storage/adapters/memory.mjs";
+import { KeyPersistence } from "./key-persistence.mjs";
+import { randomBytes, base64urlEncode, base64urlDecode } from "../index.mjs";
+var DEFAULT_BASE_DIR = ".frontmcp/keys";
+var LS_HKDF_IKM = new TextEncoder().encode("frontmcp:localstorage:v1");
+var INSTALL_SALT_KEY = "__frontmcp_internal__:install_salt";
+var LEGACY_SALT_KEY = "frontmcp:_install_salt";
+function getOrCreateInstallationSalt() {
+  if (typeof localStorage === "undefined") {
+    throw new Error("localStorage unavailable: cannot derive installation salt");
+  }
+  const existing = localStorage.getItem(INSTALL_SALT_KEY);
+  if (existing) {
+    try {
+      return base64urlDecode(existing);
+    } catch {
+    }
+  }
+  const legacy = localStorage.getItem(LEGACY_SALT_KEY);
+  if (legacy) {
+    try {
+      const salt2 = base64urlDecode(legacy);
+      localStorage.setItem(INSTALL_SALT_KEY, base64urlEncode(salt2));
+      localStorage.removeItem(LEGACY_SALT_KEY);
+      return salt2;
+    } catch {
+      localStorage.removeItem(LEGACY_SALT_KEY);
+    }
+  }
+  const salt = randomBytes(32);
+  localStorage.setItem(INSTALL_SALT_KEY, base64urlEncode(salt));
+  return salt;
+}
+function deriveLocalStorageKey(userKey) {
+  if (userKey) return userKey;
+  const salt = getOrCreateInstallationSalt();
+  const origin = typeof location !== "undefined" ? location.origin : "unknown";
+  const info = new TextEncoder().encode(origin);
+  return cryptoProvider.hkdfSha256(LS_HKDF_IKM, salt, info, 32);
+}
+async function createKeyPersistence(options) {
+  const type = options?.type ?? "auto";
+  const baseDir = options?.baseDir ?? DEFAULT_BASE_DIR;
+  let adapter;
+  if (type === "memory") {
+    adapter = new MemoryStorageAdapter();
+  } else if (type === "filesystem") {
+    const { FileSystemStorageAdapter } = await import("../../storage/adapters/filesystem.mjs");
+    adapter = new FileSystemStorageAdapter({ baseDir });
+  } else if (type === "indexeddb") {
+    const { IndexedDBStorageAdapter } = await import("../../storage/adapters/indexeddb.mjs");
+    adapter = new IndexedDBStorageAdapter({ prefix: "frontmcp:keys:" });
+  } else if (type === "localstorage") {
+    const { LocalStorageAdapter } = await import("../../storage/adapters/localstorage.mjs");
+    adapter = new LocalStorageAdapter({
+      prefix: "frontmcp:keys:",
+      encryptionKey: deriveLocalStorageKey(options?.encryptionKey)
+    });
+  } else {
+    let connected = false;
+    if (isNode()) {
+      try {
+        const { FileSystemStorageAdapter } = await import("../../storage/adapters/filesystem.mjs");
+        adapter = new FileSystemStorageAdapter({ baseDir });
+        await adapter.connect();
+        connected = true;
+      } catch {
+        adapter = new MemoryStorageAdapter();
+      }
+    } else if (isBrowser() && typeof indexedDB !== "undefined") {
+      try {
+        const { IndexedDBStorageAdapter } = await import("../../storage/adapters/indexeddb.mjs");
+        adapter = new IndexedDBStorageAdapter({ prefix: "frontmcp:keys:" });
+        await adapter.connect();
+        connected = true;
+      } catch {
+        if (typeof localStorage !== "undefined") {
+          try {
+            const { LocalStorageAdapter } = await import("../../storage/adapters/localstorage.mjs");
+            adapter = new LocalStorageAdapter({
+              prefix: "frontmcp:keys:",
+              encryptionKey: deriveLocalStorageKey(options?.encryptionKey)
+            });
+            await adapter.connect();
+            connected = true;
+          } catch {
+            adapter = new MemoryStorageAdapter();
+          }
+        } else {
+          adapter = new MemoryStorageAdapter();
+        }
+      }
+    } else if (isBrowser() && typeof localStorage !== "undefined") {
+      try {
+        const { LocalStorageAdapter } = await import("../../storage/adapters/localstorage.mjs");
+        adapter = new LocalStorageAdapter({
+          prefix: "frontmcp:keys:",
+          encryptionKey: deriveLocalStorageKey(options?.encryptionKey)
+        });
+        await adapter.connect();
+        connected = true;
+      } catch {
+        adapter = new MemoryStorageAdapter();
+      }
+    } else {
+      adapter = new MemoryStorageAdapter();
+    }
+    if (!connected) {
+      await adapter.connect();
+    }
+  }
+  if (type !== "auto") {
+    await adapter.connect();
+  }
+  return new KeyPersistence({
+    storage: adapter,
+    throwOnInvalid: options?.throwOnInvalid ?? false,
+    enableCache: options?.enableCache ?? true
+  });
+}
+function createKeyPersistenceWithStorage(storage, options) {
+  return new KeyPersistence({
+    storage,
+    throwOnInvalid: options?.throwOnInvalid ?? false,
+    enableCache: options?.enableCache ?? true
+  });
+}
+export {
+  createKeyPersistence,
+  createKeyPersistenceWithStorage
+};

package/browser/crypto/key-persistence/index.mjs

@@ -0,0 +1,26 @@
+// libs/utils/src/crypto/key-persistence/index.ts
+import {
+  asymmetricAlgSchema,
+  secretKeyDataSchema,
+  asymmetricKeyDataSchema,
+  anyKeyDataSchema,
+  validateKeyData,
+  parseKeyData,
+  isSecretKeyData,
+  isAsymmetricKeyData
+} from "./schemas.mjs";
+import { KeyPersistence } from "./key-persistence.mjs";
+import { createKeyPersistence, createKeyPersistenceWithStorage } from "./factory.mjs";
+export {
+  KeyPersistence,
+  anyKeyDataSchema,
+  asymmetricAlgSchema,
+  asymmetricKeyDataSchema,
+  createKeyPersistence,
+  createKeyPersistenceWithStorage,
+  isAsymmetricKeyData,
+  isSecretKeyData,
+  parseKeyData,
+  secretKeyDataSchema,
+  validateKeyData
+};

package/browser/crypto/key-persistence/key-persistence.mjs

@@ -0,0 +1,185 @@
+// libs/utils/src/crypto/key-persistence/key-persistence.ts
+import { randomBytes, base64urlEncode } from "../index.mjs";
+import { validateKeyData, isSecretKeyData, isAsymmetricKeyData } from "./schemas.mjs";
+var KeyPersistence = class {
+  storage;
+  cache = /* @__PURE__ */ new Map();
+  enableCache;
+  throwOnInvalid;
+  constructor(options) {
+    this.storage = options.storage;
+    this.enableCache = options.enableCache ?? true;
+    this.throwOnInvalid = options.throwOnInvalid ?? false;
+  }
+  /**
+   * Get a key by ID.
+   *
+   * @param kid - Key identifier
+   * @returns Key data or null if not found
+   */
+  async get(kid) {
+    if (this.enableCache) {
+      const cached = this.cache.get(kid);
+      if (cached) return cached;
+    }
+    const raw = await this.storage.get(kid);
+    if (!raw) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      if (this.throwOnInvalid) {
+        throw new Error(`Invalid JSON for key "${kid}"`);
+      }
+      return null;
+    }
+    const validation = validateKeyData(parsed);
+    if (!validation.valid) {
+      if (this.throwOnInvalid) {
+        throw new Error(`Invalid key data for "${kid}": ${validation.error}`);
+      }
+      return null;
+    }
+    const key = validation.data;
+    if (this.enableCache) {
+      this.cache.set(kid, key);
+    }
+    return key;
+  }
+  /**
+   * Get a secret key by ID.
+   *
+   * @param kid - Key identifier
+   * @returns Secret key data or null if not found or wrong type
+   */
+  async getSecret(kid) {
+    const key = await this.get(kid);
+    if (!key || !isSecretKeyData(key)) return null;
+    return key;
+  }
+  /**
+   * Get an asymmetric key by ID.
+   *
+   * @param kid - Key identifier
+   * @returns Asymmetric key data or null if not found or wrong type
+   */
+  async getAsymmetric(kid) {
+    const key = await this.get(kid);
+    if (!key || !isAsymmetricKeyData(key)) return null;
+    return key;
+  }
+  /**
+   * Store a key.
+   *
+   * @param key - Key data to store
+   */
+  async set(key) {
+    const validation = validateKeyData(key);
+    if (!validation.valid) {
+      throw new Error(`Invalid key data: ${validation.error}`);
+    }
+    await this.storage.set(key.kid, JSON.stringify(key, null, 2));
+    if (this.enableCache) {
+      this.cache.set(key.kid, key);
+    }
+  }
+  /**
+   * Delete a key.
+   *
+   * @param kid - Key identifier
+   * @returns true if key existed and was deleted
+   */
+  async delete(kid) {
+    this.cache.delete(kid);
+    return this.storage.delete(kid);
+  }
+  /**
+   * Check if a key exists.
+   *
+   * @param kid - Key identifier
+   * @returns true if key exists
+   */
+  async has(kid) {
+    if (this.enableCache && this.cache.has(kid)) {
+      return true;
+    }
+    return this.storage.exists(kid);
+  }
+  /**
+   * List all key IDs.
+   *
+   * @returns Array of key identifiers
+   */
+  async list() {
+    return this.storage.keys();
+  }
+  /**
+   * Get or create a secret key.
+   *
+   * If a key with the given ID exists and is a valid secret key,
+   * it is returned. Otherwise, a new secret key is generated.
+   *
+   * @param kid - Key identifier
+   * @param options - Options for key creation
+   * @returns Secret key data
+   *
+   * @example
+   * ```typescript
+   * const secret = await keys.getOrCreateSecret('encryption-key');
+   * const bytes = base64urlDecode(secret.secret);
+   * ```
+   */
+  async getOrCreateSecret(kid, options) {
+    const existing = await this.getSecret(kid);
+    if (existing) {
+      return existing;
+    }
+    const bytes = options?.bytes ?? 32;
+    const secret = {
+      type: "secret",
+      kid,
+      secret: base64urlEncode(randomBytes(bytes)),
+      bytes,
+      createdAt: Date.now(),
+      version: 1
+    };
+    await this.set(secret);
+    return secret;
+  }
+  /**
+   * Clear the in-memory cache.
+   *
+   * Useful when you want to force a reload from storage.
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Clear cache for a specific key.
+   *
+   * @param kid - Key identifier
+   */
+  clearCacheFor(kid) {
+    this.cache.delete(kid);
+  }
+  /**
+   * Check if a key is in the cache.
+   *
+   * @param kid - Key identifier
+   * @returns true if key is cached
+   */
+  isCached(kid) {
+    return this.cache.has(kid);
+  }
+  /**
+   * Get the underlying storage adapter.
+   *
+   * Use with caution - direct storage access bypasses validation.
+   */
+  getAdapter() {
+    return this.storage;
+  }
+};
+export {
+  KeyPersistence
+};