@frontmcp/utils 1.10.16 → 1.11.0-rc.1

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

@@ -0,0 +1,82 @@
+// libs/utils/src/crypto/key-persistence/schemas.ts
+import { internalZ as z } from "@frontmcp/lazy-zod";
+var MAX_CLOCK_DRIFT_MS = 6e4;
+var MAX_KEY_AGE_MS = 100 * 365 * 24 * 60 * 60 * 1e3;
+var asymmetricAlgSchema = z.enum(["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"]);
+var baseKeyDataSchema = z.object({
+  kid: z.string().min(1),
+  createdAt: z.number().positive().int(),
+  version: z.number().positive().int()
+});
+var jsonWebKeySchema = z.object({
+  kty: z.string().optional(),
+  use: z.string().optional(),
+  alg: z.string().optional(),
+  kid: z.string().optional(),
+  n: z.string().optional(),
+  e: z.string().optional(),
+  d: z.string().optional(),
+  p: z.string().optional(),
+  q: z.string().optional(),
+  dp: z.string().optional(),
+  dq: z.string().optional(),
+  qi: z.string().optional(),
+  x: z.string().optional(),
+  y: z.string().optional(),
+  crv: z.string().optional()
+}).passthrough();
+var secretKeyDataSchema = baseKeyDataSchema.extend({
+  type: z.literal("secret"),
+  secret: z.string().min(1),
+  bytes: z.number().positive().int()
+});
+var asymmetricKeyDataSchema = baseKeyDataSchema.extend({
+  type: z.literal("asymmetric"),
+  alg: asymmetricAlgSchema,
+  privateKey: jsonWebKeySchema,
+  publicJwk: z.object({
+    keys: z.array(jsonWebKeySchema).min(1)
+  })
+});
+var anyKeyDataSchema = z.discriminatedUnion("type", [secretKeyDataSchema, asymmetricKeyDataSchema]);
+function validateKeyData(data) {
+  const result = anyKeyDataSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      valid: false,
+      error: result.error.issues[0]?.message ?? "Invalid key structure"
+    };
+  }
+  const parsed = result.data;
+  const now = Date.now();
+  if (parsed.createdAt > now + MAX_CLOCK_DRIFT_MS) {
+    return { valid: false, error: "createdAt is in the future" };
+  }
+  if (parsed.createdAt < now - MAX_KEY_AGE_MS) {
+    return { valid: false, error: "createdAt is too old" };
+  }
+  return { valid: true, data: parsed };
+}
+function parseKeyData(data) {
+  const validation = validateKeyData(data);
+  if (!validation.valid) {
+    return null;
+  }
+  return validation.data;
+}
+function isSecretKeyData(data) {
+  return data.type === "secret";
+}
+function isAsymmetricKeyData(data) {
+  return data.type === "asymmetric";
+}
+export {
+  anyKeyDataSchema,
+  asymmetricAlgSchema,
+  asymmetricKeyDataSchema,
+  isAsymmetricKeyData,
+  isSecretKeyData,
+  parseKeyData,
+  secretKeyDataSchema,
+  validateKeyData
+};

package/browser/crypto/pkce/index.mjs

@@ -0,0 +1,25 @@
+// libs/utils/src/crypto/pkce/index.ts
+import {
+  MIN_CODE_VERIFIER_LENGTH,
+  MAX_CODE_VERIFIER_LENGTH,
+  DEFAULT_CODE_VERIFIER_LENGTH,
+  PkceError,
+  generateCodeVerifier,
+  generateCodeChallenge,
+  verifyCodeChallenge,
+  generatePkcePair,
+  isValidCodeVerifier,
+  isValidCodeChallenge
+} from "./pkce.mjs";
+export {
+  DEFAULT_CODE_VERIFIER_LENGTH,
+  MAX_CODE_VERIFIER_LENGTH,
+  MIN_CODE_VERIFIER_LENGTH,
+  PkceError,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generatePkcePair,
+  isValidCodeChallenge,
+  isValidCodeVerifier,
+  verifyCodeChallenge
+};

package/browser/crypto/pkce/pkce.mjs

@@ -0,0 +1,59 @@
+// libs/utils/src/crypto/pkce/pkce.ts
+import { randomBytes, sha256, base64urlEncode } from "../index.mjs";
+var MIN_CODE_VERIFIER_LENGTH = 43;
+var MAX_CODE_VERIFIER_LENGTH = 128;
+var DEFAULT_CODE_VERIFIER_LENGTH = 64;
+var PkceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PkceError";
+  }
+};
+function generateCodeVerifier(length = DEFAULT_CODE_VERIFIER_LENGTH) {
+  if (length < MIN_CODE_VERIFIER_LENGTH || length > MAX_CODE_VERIFIER_LENGTH) {
+    throw new PkceError(
+      `Code verifier length must be between ${MIN_CODE_VERIFIER_LENGTH} and ${MAX_CODE_VERIFIER_LENGTH} characters (got ${length})`
+    );
+  }
+  const bytesNeeded = Math.ceil(length * 6 / 8);
+  const bytes = randomBytes(bytesNeeded);
+  return base64urlEncode(bytes).slice(0, length);
+}
+function generateCodeChallenge(codeVerifier) {
+  const verifierBytes = new TextEncoder().encode(codeVerifier);
+  const hash = sha256(verifierBytes);
+  return base64urlEncode(hash);
+}
+function verifyCodeChallenge(codeVerifier, codeChallenge) {
+  const computedChallenge = generateCodeChallenge(codeVerifier);
+  return computedChallenge === codeChallenge;
+}
+function generatePkcePair(length = DEFAULT_CODE_VERIFIER_LENGTH) {
+  const codeVerifier = generateCodeVerifier(length);
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+  return { codeVerifier, codeChallenge };
+}
+function isValidCodeVerifier(value) {
+  if (value.length < MIN_CODE_VERIFIER_LENGTH || value.length > MAX_CODE_VERIFIER_LENGTH) {
+    return false;
+  }
+  return /^[A-Za-z0-9\-._~]+$/.test(value);
+}
+function isValidCodeChallenge(value) {
+  if (value.length !== 43) {
+    return false;
+  }
+  return /^[A-Za-z0-9\-_]+$/.test(value);
+}
+export {
+  DEFAULT_CODE_VERIFIER_LENGTH,
+  MAX_CODE_VERIFIER_LENGTH,
+  MIN_CODE_VERIFIER_LENGTH,
+  PkceError,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generatePkcePair,
+  isValidCodeChallenge,
+  isValidCodeVerifier,
+  verifyCodeChallenge
+};

package/browser/crypto/runtime.mjs

@@ -0,0 +1,17 @@
+// libs/utils/src/crypto/runtime.ts
+function isNode() {
+  return typeof process !== "undefined" && !!process.versions?.node;
+}
+function isBrowser() {
+  return typeof globalThis !== "undefined" && typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function";
+}
+function assertNode(feature) {
+  if (!isNode()) {
+    throw new Error(`${feature} is not supported in the browser. Requires Node.js.`);
+  }
+}
+export {
+  assertNode,
+  isBrowser,
+  isNode
+};

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

@@ -0,0 +1,29 @@
+// libs/utils/src/crypto/secret-persistence/index.ts
+import { secretDataSchema, validateSecretData, parseSecretData } from "./schema.mjs";
+import {
+  isSecretPersistenceEnabled,
+  resolveSecretPath,
+  loadSecret,
+  saveSecret,
+  deleteSecret,
+  generateSecret,
+  createSecretData,
+  getOrCreateSecret,
+  clearCachedSecret,
+  isSecretCached
+} from "./persistence.mjs";
+export {
+  clearCachedSecret,
+  createSecretData,
+  deleteSecret,
+  generateSecret,
+  getOrCreateSecret,
+  isSecretCached,
+  isSecretPersistenceEnabled,
+  loadSecret,
+  parseSecretData,
+  resolveSecretPath,
+  saveSecret,
+  secretDataSchema,
+  validateSecretData
+};

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

@@ -0,0 +1,181 @@
+var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("module") : undefined;
+const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
+// __frontmcpCreateRequire
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// libs/utils/src/crypto/secret-persistence/persistence.ts
+import { readFile, writeFile, mkdir, rename, unlink } from "../../fs/index.mjs";
+import { randomBytes, base64urlEncode } from "../index.mjs";
+import { validateSecretData } from "./schema.mjs";
+import { getEnv, getCwd } from "../../env/browser-env.mjs";
+function getPath() {
+  return __require("path");
+}
+var DEFAULT_SECRET_BYTES = 32;
+var DEFAULT_SECRET_DIR = ".frontmcp";
+function isSecretPersistenceEnabled(options) {
+  const isProduction = getEnv("NODE_ENV") === "production";
+  if (isProduction) {
+    return options?.forceEnable === true;
+  }
+  return true;
+}
+function resolveSecretPath(options) {
+  const p = getPath();
+  if (options?.secretPath) {
+    if (p.isAbsolute(options.secretPath)) {
+      return options.secretPath;
+    }
+    return p.resolve(getCwd(), options.secretPath);
+  }
+  const name = options?.name ?? "default";
+  const defaultPath = `${DEFAULT_SECRET_DIR}/${name}-secret.json`;
+  return p.resolve(getCwd(), defaultPath);
+}
+var noop = () => {
+};
+function getLogger(options) {
+  if (options?.enableLogging === false) {
+    return { warn: noop, error: noop };
+  }
+  return options?.logger ?? { warn: console.warn, error: console.error };
+}
+function getLogPrefix(options) {
+  const name = options?.name ?? "Secret";
+  return `[${name}Persistence]`;
+}
+async function loadSecret(options) {
+  if (!isSecretPersistenceEnabled(options)) {
+    return null;
+  }
+  const secretPath = resolveSecretPath(options);
+  const logger = getLogger(options);
+  const prefix = getLogPrefix(options);
+  try {
+    const content = await readFile(secretPath);
+    const data = JSON.parse(content);
+    const validation = validateSecretData(data);
+    if (!validation.valid) {
+      logger.warn(`${prefix} Invalid secret file format at ${secretPath}: ${validation.error}, will regenerate`);
+      return null;
+    }
+    return data;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    logger.warn(`${prefix} Failed to load secret from ${secretPath}: ${error.message}`);
+    return null;
+  }
+}
+async function saveSecret(secretData, options) {
+  if (!isSecretPersistenceEnabled(options)) {
+    return true;
+  }
+  const secretPath = resolveSecretPath(options);
+  const dir = getPath().dirname(secretPath);
+  const tempPath = `${secretPath}.tmp.${Date.now()}.${base64urlEncode(randomBytes(8))}`;
+  const logger = getLogger(options);
+  const prefix = getLogPrefix(options);
+  try {
+    await mkdir(dir, { recursive: true, mode: 448 });
+    const content = JSON.stringify(secretData, null, 2);
+    await writeFile(tempPath, content, { mode: 384 });
+    await rename(tempPath, secretPath);
+    return true;
+  } catch (error) {
+    logger.error(`${prefix} Failed to save secret to ${secretPath}: ${error.message}`);
+    try {
+      await unlink(tempPath);
+    } catch {
+    }
+    return false;
+  }
+}
+async function deleteSecret(options) {
+  const secretPath = resolveSecretPath(options);
+  const logger = getLogger(options);
+  const prefix = getLogPrefix(options);
+  try {
+    await unlink(secretPath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return true;
+    }
+    logger.warn(`${prefix} Failed to delete secret at ${secretPath}: ${error.message}`);
+    return false;
+  }
+}
+function generateSecret(bytes = DEFAULT_SECRET_BYTES) {
+  return base64urlEncode(randomBytes(bytes));
+}
+function createSecretData(options) {
+  const secretBytes = options?.secretBytes ?? DEFAULT_SECRET_BYTES;
+  return {
+    secret: generateSecret(secretBytes),
+    createdAt: Date.now(),
+    version: 1
+  };
+}
+var secretCache = /* @__PURE__ */ new Map();
+var generationPromises = /* @__PURE__ */ new Map();
+async function getOrCreateSecret(options) {
+  const cacheKey = resolveSecretPath(options);
+  const cached = secretCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const existing = generationPromises.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const promise = (async () => {
+    try {
+      const loaded = await loadSecret(options);
+      if (loaded) {
+        secretCache.set(cacheKey, loaded.secret);
+        return loaded.secret;
+      }
+      const secretData = createSecretData(options);
+      if (isSecretPersistenceEnabled(options)) {
+        await saveSecret(secretData, options);
+      }
+      secretCache.set(cacheKey, secretData.secret);
+      return secretData.secret;
+    } finally {
+      generationPromises.delete(cacheKey);
+    }
+  })();
+  generationPromises.set(cacheKey, promise);
+  return promise;
+}
+function clearCachedSecret(options) {
+  if (options) {
+    const cacheKey = resolveSecretPath(options);
+    secretCache.delete(cacheKey);
+  } else {
+    secretCache.clear();
+  }
+}
+function isSecretCached(options) {
+  const cacheKey = resolveSecretPath(options);
+  return secretCache.has(cacheKey);
+}
+export {
+  clearCachedSecret,
+  createSecretData,
+  deleteSecret,
+  generateSecret,
+  getOrCreateSecret,
+  isSecretCached,
+  isSecretPersistenceEnabled,
+  loadSecret,
+  resolveSecretPath,
+  saveSecret
+};

package/browser/crypto/secret-persistence/schema.mjs

@@ -0,0 +1,40 @@
+// libs/utils/src/crypto/secret-persistence/schema.ts
+import { internalZ as z } from "@frontmcp/lazy-zod";
+var secretDataSchema = z.object({
+  secret: z.string().base64url().length(43),
+  // base64url of 32 bytes is exactly 43 chars
+  createdAt: z.number().positive().int(),
+  version: z.number().positive().int()
+}).strict();
+var MAX_CLOCK_DRIFT_MS = 6e4;
+var MAX_SECRET_AGE_MS = 100 * 365 * 24 * 60 * 60 * 1e3;
+function validateSecretData(data) {
+  const result = secretDataSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      valid: false,
+      error: result.error.issues[0]?.message ?? "Invalid secret structure"
+    };
+  }
+  const parsed = result.data;
+  const now = Date.now();
+  if (parsed.createdAt > now + MAX_CLOCK_DRIFT_MS) {
+    return { valid: false, error: "createdAt is in the future" };
+  }
+  if (parsed.createdAt < now - MAX_SECRET_AGE_MS) {
+    return { valid: false, error: "createdAt is too old" };
+  }
+  return { valid: true };
+}
+function parseSecretData(data) {
+  const validation = validateSecretData(data);
+  if (!validation.valid) {
+    return null;
+  }
+  return data;
+}
+export {
+  parseSecretData,
+  secretDataSchema,
+  validateSecretData
+};

package/browser/crypto/web-rsa.mjs

@@ -0,0 +1,36 @@
+// libs/utils/src/crypto/web-rsa.ts
+import { isRsaPssAlg, jwtAlgToWebCryptoAlg } from "./jwt-alg.mjs";
+async function rsaVerifyBrowser(jwtAlg, data, publicJwk, signature) {
+  if (typeof globalThis.crypto?.subtle === "undefined") {
+    throw new Error("WebCrypto API (crypto.subtle) is not available in this environment");
+  }
+  const webAlg = jwtAlgToWebCryptoAlg(jwtAlg);
+  const isPss = isRsaPssAlg(jwtAlg);
+  const algorithm = {
+    name: isPss ? "RSA-PSS" : "RSASSA-PKCS1-v1_5",
+    hash: { name: webAlg }
+  };
+  const key = await globalThis.crypto.subtle.importKey("jwk", publicJwk, algorithm, false, ["verify"]);
+  const verifyAlgorithm = isPss ? { name: "RSA-PSS", saltLength: getSaltLength(jwtAlg) } : { name: "RSASSA-PKCS1-v1_5" };
+  const sigBuf = new Uint8Array(signature).buffer;
+  const dataBuf = new Uint8Array(data).buffer;
+  return globalThis.crypto.subtle.verify(verifyAlgorithm, key, sigBuf, dataBuf);
+}
+function getSaltLength(jwtAlg) {
+  switch (jwtAlg) {
+    case "PS256":
+      return 32;
+    // SHA-256 digest length
+    case "PS384":
+      return 48;
+    // SHA-384 digest length
+    case "PS512":
+      return 64;
+    // SHA-512 digest length
+    default:
+      return 32;
+  }
+}
+export {
+  rsaVerifyBrowser
+};

package/browser/env/browser-env.mjs

@@ -0,0 +1,56 @@
+// libs/utils/src/env/browser-env.ts
+import { hasEdgeGlobalScope } from "./edge-scope.mjs";
+var NODE_ENV_KEY = "NODE_ENV";
+function bundlerDefinedNodeEnv() {
+  try {
+    return process.env["NODE_ENV"] || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getEnv(_key, defaultValue) {
+  return defaultValue;
+}
+function getCwd() {
+  return "/";
+}
+function getNodeEnv() {
+  const shim = globalThis.process;
+  return shim?.env?.[NODE_ENV_KEY] || bundlerDefinedNodeEnv();
+}
+function isProduction() {
+  return getNodeEnv() === "production";
+}
+function isDevelopment() {
+  return getNodeEnv() === "development";
+}
+function getEnvFlag(_key) {
+  return false;
+}
+function isDebug() {
+  return false;
+}
+function setEnv(_key, _value) {
+}
+function isEdgeRuntime() {
+  return hasEdgeGlobalScope();
+}
+function isServerless() {
+  return false;
+}
+function supportsAnsi() {
+  return false;
+}
+export {
+  getCwd,
+  getEnv,
+  getEnvFlag,
+  getNodeEnv,
+  isDebug,
+  isDevelopment,
+  isEdgeRuntime,
+  isProduction,
+  isServerless,
+  setEnv,
+  supportsAnsi
+};

package/browser/env/browser-runtime-context.mjs

@@ -0,0 +1,85 @@
+// libs/utils/src/env/browser-runtime-context.ts
+import { internalZ as z } from "@frontmcp/lazy-zod";
+import { getNodeEnv } from "./browser-env.mjs";
+var entryAvailabilitySchema = z.object({
+  os: z.array(z.string().min(1)).optional(),
+  platform: z.array(z.string().min(1)).optional(),
+  runtime: z.array(z.string().min(1)).optional(),
+  deployment: z.array(z.string().min(1)).optional(),
+  provider: z.array(z.string().min(1)).optional(),
+  target: z.array(z.string().min(1)).optional(),
+  surface: z.array(z.enum(["mcp", "cli", "http-trigger", "job", "agent", "webmcp"])).optional(),
+  env: z.array(z.string().min(1)).optional()
+}).strict();
+var PROCESS_AXES = [
+  { key: "os", ctxKey: "os" },
+  { key: "platform", ctxKey: "platform" },
+  { key: "runtime", ctxKey: "runtime" },
+  { key: "deployment", ctxKey: "deployment" },
+  { key: "provider", ctxKey: "provider" },
+  { key: "target", ctxKey: "target" },
+  { key: "env", ctxKey: "env" }
+];
+function isEntryAvailable(availability, ctx, callCtx) {
+  if (!availability) return true;
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0) return false;
+    if (!allowed.includes(ctx[ctxKey])) return false;
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) return false;
+    if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) return false;
+  }
+  return true;
+}
+function checkEntryAvailability(availability, ctx, callCtx) {
+  if (!availability) return { available: true, missingAxes: [] };
+  const missing = [];
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0 || !allowed.includes(ctx[ctxKey])) missing.push(key);
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) missing.push("surface");
+    else if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) missing.push("surface");
+  }
+  return { available: missing.length === 0, missingAxes: missing };
+}
+function detectRuntimeContext() {
+  return {
+    os: "browser",
+    platform: "browser",
+    runtime: "browser",
+    deployment: "standalone",
+    provider: "bare",
+    target: "browser",
+    env: getNodeEnv() || "development"
+  };
+}
+var cached;
+function getRuntimeContext() {
+  if (!cached) {
+    const detected = detectRuntimeContext();
+    Object.defineProperty(detected, "env", {
+      get: () => getNodeEnv() || "development",
+      enumerable: true,
+      configurable: true
+    });
+    cached = detected;
+  }
+  return cached;
+}
+function resetRuntimeContext() {
+  cached = void 0;
+}
+export {
+  checkEntryAvailability,
+  detectRuntimeContext,
+  entryAvailabilitySchema,
+  getRuntimeContext,
+  isEntryAvailable,
+  resetRuntimeContext
+};

package/browser/env/build-target.mjs

@@ -0,0 +1,25 @@
+// libs/utils/src/env/build-target.ts
+var cached;
+function getBuildTarget() {
+  if (cached) return cached;
+  cached = resolveBuildTarget();
+  return cached;
+}
+function resolveBuildTarget() {
+  const globalAny = globalThis;
+  const fromGlobal = globalAny.FRONTMCP_BUILD_TARGET;
+  if (typeof fromGlobal === "string" && isKnownTarget(fromGlobal)) return fromGlobal;
+  const fromEnv = typeof process !== "undefined" ? process.env?.["FRONTMCP_BUILD_TARGET"] : void 0;
+  if (typeof fromEnv === "string" && isKnownTarget(fromEnv)) return fromEnv;
+  return "unknown";
+}
+function isKnownTarget(value) {
+  return value === "unknown" || value === "node" || value === "distributed" || value === "cli" || value === "vercel" || value === "lambda" || value === "cloudflare" || value === "browser" || value === "sdk" || value === "mcpb";
+}
+function resetBuildTargetCacheForTesting() {
+  cached = void 0;
+}
+export {
+  getBuildTarget,
+  resetBuildTargetCacheForTesting
+};

package/browser/env/edge-scope.mjs

@@ -0,0 +1,17 @@
+// libs/utils/src/env/edge-scope.ts
+function hasEdgeGlobalScope() {
+  if (typeof globalThis === "undefined") return false;
+  if ("EdgeRuntime" in globalThis) return true;
+  if (!("caches" in globalThis) || "window" in globalThis) return false;
+  return !isBrowserWorkerScope();
+}
+function isBrowserWorkerScope() {
+  const userAgent = typeof navigator === "undefined" ? void 0 : navigator.userAgent;
+  if (userAgent === void 0 || userAgent === "Cloudflare-Workers") return false;
+  return ["DedicatedWorkerGlobalScope", "SharedWorkerGlobalScope", "ServiceWorkerGlobalScope"].some(
+    (scopeName) => scopeName in globalThis
+  );
+}
+export {
+  hasEdgeGlobalScope
+};