@frontmcp/utils 1.9.3 → 1.9.4

package/class-brand/class-brand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Class identity shared by every copy of a package loaded in one process.
+ *
+ * A process can hold two copies of a FrontMCP package: in an ES-module project `@frontmcp/sdk`'s ESM
+ * build loads `@frontmcp/observability` with `require()`, which resolves observability's CommonJS
+ * build, which in turn loads the CommonJS builds of the SDK and of its dependencies. Each copy has its
+ * own classes, so a plain `instanceof` in one copy does not recognise an instance made by the other:
+ * an error the client was answered with as a `PublicMcpError` was recorded as an internal error with
+ * a new id (#802).
+ *
+ * A branded class answers `instanceof` for its own instances as usual, and also for an instance of
+ * the class with the same brand from another copy. The brand is an own property of the class, so a
+ * subclass is recognised only through a brand of its own: an unbranded subclass keeps the plain
+ * check, and never matches a different subclass that happens to share a branded parent.
+ *
+ * @example
+ * ```ts
+ * export class GuardError extends Error {
+ *   static override [Symbol.hasInstance](value: unknown): boolean {
+ *     return isBrandedInstance(this, value);
+ *   }
+ * }
+ * brandClass(GuardError, '@frontmcp/guard:GuardError');
+ * ```
+ */
+/**
+ * Give `klass` a process-wide brand. The same class in another copy of its package carries the same
+ * brand, so each recognises the other's instances through {@link isBrandedInstance}. Namespace the
+ * brand with the package name (`'@frontmcp/sdk:McpError'`).
+ */
+export declare function brandClass(klass: object, brand: string): void;
+/**
+ * `value instanceof klass`, also true when `value` is an instance of the class that carries `klass`'s
+ * own brand in another copy of the package. Meant as the `static [Symbol.hasInstance]` of a branded
+ * class (subclasses inherit it, and match through their own brand or the plain check).
+ */
+export declare function isBrandedInstance(klass: object, value: unknown): boolean;

package/class-brand/index.d.ts

@@ -0,0 +1 @@
+export { brandClass, isBrandedInstance } from './class-brand';

package/esm/index.mjs

@@ -117,6 +117,9 @@ async function fileExists(p) {
     return false;
   }
 }
+function fileExistsSync(p) {
+  return getFs().existsSync(p);
+}
 async function readJSON(jsonPath) {
   try {
     const fsp = getFsp();
@@ -4883,6 +4886,30 @@ function safeJsonForScript(value) {
   }
 }
 
+// libs/utils/src/class-brand/class-brand.ts
+var CLASS_BRAND = /* @__PURE__ */ Symbol.for("@frontmcp/class-brand");
+var ordinaryHasInstance = Function.prototype[Symbol.hasInstance];
+function ownBrandOf(klass) {
+  if (typeof klass !== "function" || !Object.prototype.hasOwnProperty.call(klass, CLASS_BRAND)) return void 0;
+  return klass[CLASS_BRAND];
+}
+function classOfPrototype(proto) {
+  return Object.getOwnPropertyDescriptor(proto, "constructor")?.value;
+}
+function brandClass(klass, brand) {
+  Object.defineProperty(klass, CLASS_BRAND, { value: brand, enumerable: false, writable: false, configurable: false });
+}
+function isBrandedInstance(klass, value) {
+  if (ordinaryHasInstance.call(klass, value)) return true;
+  if (typeof value !== "object" || value === null) return false;
+  const brand = ownBrandOf(klass);
+  if (brand === void 0) return false;
+  for (let proto = Object.getPrototypeOf(value); proto !== null; proto = Object.getPrototypeOf(proto)) {
+    if (ownBrandOf(classOfPrototype(proto)) === brand) return true;
+  }
+  return false;
+}
+
 // libs/utils/src/serialization/serialization.ts
 function safeStringify(value, space) {
   const seen = /* @__PURE__ */ new WeakSet();
@@ -5907,6 +5934,7 @@ export {
   base64urlDecode,
   base64urlEncode,
   basename,
+  brandClass,
   buildPrefix,
   buildSetCookie,
   bytesToHex,
@@ -5957,6 +5985,7 @@ export {
   extractTemplateParams,
   extractUriScheme,
   fileExists,
+  fileExistsSync,
   findNonFiniteNumber,
   generateCodeChallenge,
   generateCodeVerifier,
@@ -5983,6 +6012,7 @@ export {
   inferMimeType,
   isAbsolute,
   isAsymmetricKeyData,
+  isBrandedInstance,
   isBrowser,
   isDebug,
   isDevelopment,

package/fs/fs.d.ts

@@ -137,6 +137,21 @@ export declare function unlink(p: string): Promise<void>;
  * await fileExists('/path/to/file.txt') // true or false
  */
 export declare function fileExists(p: string): Promise<boolean>;
+/**
+ * Check whether a file or directory exists, synchronously.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * Use this only where async is not possible (e.g. resolving a command line
+ * before a synchronous `spawn`). Prefer {@link fileExists} otherwise.
+ *
+ * @param p - Path to check
+ * @returns true if the path exists, false otherwise
+ *
+ * @example
+ * fileExistsSync('/path/to/file.txt') // true or false
+ */
+export declare function fileExistsSync(p: string): boolean;
 /**
  * Read and parse a JSON file.
  *
@@ -343,6 +358,11 @@ export declare function access(p: string, mode?: number): Promise<void>;
 export declare function runCmd(cmd: string, args: string[], opts?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Pass `args` to the child unquoted (Windows only). Set it when the arguments
+     * are already quoted for `cmd.exe /d /s /c`; ignored on other platforms.
+     */
+    windowsVerbatimArguments?: boolean;
 }): Promise<void>;
 /**
  * Handle returned by {@link watchFile}. `close()` stops the watch and is safe

package/fs/index.d.ts

@@ -1,2 +1,2 @@
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, fileExistsSync, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
 export type { FileWatcherHandle, SymlinkType } from './fs';

package/index.d.ts

@@ -15,9 +15,10 @@ export { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost,
 export type { CookieOptions, SecureDetectionRequest } from './http';
 export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4, isRedirectResponse } from './net';
 export type { IpAddressClassification, IpAddressRange, SpecialPurposeIpRange, RedirectCandidate } from './net';
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, fileExistsSync, readJSON, writeJSON, ensureDir, ensureDirSync, isDirEmpty, runCmd, watchFile, getSpawnFn, } from './fs';
 export type { FileWatcherHandle } from './fs';
 export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';
+export { brandClass, isBrandedInstance } from './class-brand';
 export { safeStringify } from './serialization';
 export { getCrypto, rsaVerify, rsaVerifySync, pemToPublicJwk, generateRsaKeyPair, rsaSignBase64Url, type RsaJwk, type RsaKeyPair, jwtAlgToNodeAlg, isRsaPssAlg, randomUUID, randomBytes, sha256, sha256Hex, sha256Base64url, hmacSha256, hkdfSha256, encryptAesGcm, decryptAesGcm, timingSafeEqual, bytesToHex, base64urlEncode, base64urlDecode, base64Encode, base64Decode, isNode, isBrowser, assertNode, EncryptedBlobError, encryptValue, decryptValue, tryDecryptValue, serializeBlob, deserializeBlob, tryDeserializeBlob, isValidEncryptedBlob, encryptAndSerialize, deserializeAndDecrypt, tryDeserializeAndDecrypt, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, type PkcePair, type SecretData, type SecretPersistenceOptions, type SecretValidationResult, secretDataSchema, validateSecretData, parseSecretData, isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, type SignedData, type HmacSigningConfig, signData, verifyData, isSignedData, verifyOrParseData, type BaseKeyData, type SecretKeyData, type AsymmetricKeyData, type AnyKeyData, type KeyPersistenceOptions, type CreateKeyPersistenceOptions, type CreateSecretOptions, type CreateAsymmetricOptions, type KeyValidationResult, asymmetricAlgSchema, secretKeyDataSchema, asymmetricKeyDataSchema, anyKeyDataSchema, validateKeyData, parseKeyData, isSecretKeyData, isAsymmetricKeyData, KeyPersistence, createKeyPersistence, createKeyPersistenceWithStorage, } from './crypto';
 export type { CryptoProvider, EncBlob, EncryptedBlob } from './crypto';

package/index.js

@@ -119,6 +119,9 @@ async function fileExists(p) {
     return false;
   }
 }
+function fileExistsSync(p) {
+  return getFs().existsSync(p);
+}
 async function readJSON(jsonPath) {
   try {
     const fsp = getFsp();
@@ -4134,6 +4137,7 @@ __export(index_exports, {
   base64urlDecode: () => base64urlDecode,
   base64urlEncode: () => base64urlEncode,
   basename: () => import_path2.basename,
+  brandClass: () => brandClass,
   buildPrefix: () => buildPrefix,
   buildSetCookie: () => buildSetCookie,
   bytesToHex: () => bytesToHex,
@@ -4184,6 +4188,7 @@ __export(index_exports, {
   extractTemplateParams: () => extractTemplateParams,
   extractUriScheme: () => extractUriScheme,
   fileExists: () => fileExists,
+  fileExistsSync: () => fileExistsSync,
   findNonFiniteNumber: () => findNonFiniteNumber,
   generateCodeChallenge: () => generateCodeChallenge,
   generateCodeVerifier: () => generateCodeVerifier,
@@ -4210,6 +4215,7 @@ __export(index_exports, {
   inferMimeType: () => inferMimeType,
   isAbsolute: () => import_path2.isAbsolute,
   isAsymmetricKeyData: () => isAsymmetricKeyData,
+  isBrandedInstance: () => isBrandedInstance,
   isBrowser: () => isBrowser,
   isDebug: () => import_env2.isDebug,
   isDevelopment: () => import_env2.isDevelopment,
@@ -5114,6 +5120,30 @@ function safeJsonForScript(value) {
   }
 }
 
+// libs/utils/src/class-brand/class-brand.ts
+var CLASS_BRAND = /* @__PURE__ */ Symbol.for("@frontmcp/class-brand");
+var ordinaryHasInstance = Function.prototype[Symbol.hasInstance];
+function ownBrandOf(klass) {
+  if (typeof klass !== "function" || !Object.prototype.hasOwnProperty.call(klass, CLASS_BRAND)) return void 0;
+  return klass[CLASS_BRAND];
+}
+function classOfPrototype(proto) {
+  return Object.getOwnPropertyDescriptor(proto, "constructor")?.value;
+}
+function brandClass(klass, brand) {
+  Object.defineProperty(klass, CLASS_BRAND, { value: brand, enumerable: false, writable: false, configurable: false });
+}
+function isBrandedInstance(klass, value) {
+  if (ordinaryHasInstance.call(klass, value)) return true;
+  if (typeof value !== "object" || value === null) return false;
+  const brand = ownBrandOf(klass);
+  if (brand === void 0) return false;
+  for (let proto = Object.getPrototypeOf(value); proto !== null; proto = Object.getPrototypeOf(proto)) {
+    if (ownBrandOf(classOfPrototype(proto)) === brand) return true;
+  }
+  return false;
+}
+
 // libs/utils/src/serialization/serialization.ts
 function safeStringify(value, space) {
   const seen = /* @__PURE__ */ new WeakSet();
@@ -6114,6 +6144,7 @@ function setMachineIdOverride(id) {
   base64urlDecode,
   base64urlEncode,
   basename,
+  brandClass,
   buildPrefix,
   buildSetCookie,
   bytesToHex,
@@ -6164,6 +6195,7 @@ function setMachineIdOverride(id) {
   extractTemplateParams,
   extractUriScheme,
   fileExists,
+  fileExistsSync,
   findNonFiniteNumber,
   generateCodeChallenge,
   generateCodeVerifier,
@@ -6190,6 +6222,7 @@ function setMachineIdOverride(id) {
   inferMimeType,
   isAbsolute,
   isAsymmetricKeyData,
+  isBrandedInstance,
   isBrowser,
   isDebug,
   isDevelopment,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.9.3",
+    "@frontmcp/lazy-zod": "1.9.4",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"