@frontmcp/utils 1.9.2 → 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/crypto/browser.d.ts

@@ -11,6 +11,11 @@ import type { CryptoProvider } from './types';
 export declare const browserCrypto: CryptoProvider;
 /** Alias for conditional import resolution via `#crypto-provider`. */
 export { browserCrypto as cryptoProvider };
+export declare function rsaVerify(): boolean;
+export declare function rsaSignBase64Url(): string;
+export declare function rsaVerifySync(): boolean;
+export declare function pemToPublicJwk(): JsonWebKey;
+export declare function generateRsaKeyPair(): never;
 export { isRsaPssAlg, jwtAlgToWebCryptoAlg } from './jwt-alg';
 /**
  * Verify an RSA signature using WebCrypto.

package/crypto/browser.js

@@ -22,16 +22,21 @@ var browser_exports = {};
 __export(browser_exports, {
   browserCrypto: () => browserCrypto,
   cryptoProvider: () => browserCrypto,
+  generateRsaKeyPair: () => generateRsaKeyPair,
   isRsaPssAlg: () => isRsaPssAlg,
   jwtAlgToWebCryptoAlg: () => jwtAlgToWebCryptoAlg,
-  rsaVerifyBrowser: () => rsaVerifyBrowser
+  pemToPublicJwk: () => pemToPublicJwk,
+  rsaSignBase64Url: () => rsaSignBase64Url,
+  rsaVerify: () => rsaVerify,
+  rsaVerifyBrowser: () => rsaVerifyBrowser,
+  rsaVerifySync: () => rsaVerifySync
 });
 module.exports = __toCommonJS(browser_exports);
-var import_sha2 = require("@noble/hashes/sha2.js");
-var import_hmac = require("@noble/hashes/hmac.js");
+var import_aes = require("@noble/ciphers/aes.js");
 var import_hkdf = require("@noble/hashes/hkdf.js");
+var import_hmac = require("@noble/hashes/hmac.js");
+var import_sha2 = require("@noble/hashes/sha2.js");
 var import_utils = require("@noble/hashes/utils.js");
-var import_aes = require("@noble/ciphers/aes.js");
 
 // libs/utils/src/crypto/jwt-alg.ts
 function isRsaPssAlg(jwtAlg) {
@@ -119,6 +124,24 @@ var browserCrypto = {
     return constantTimeEqual(a, b);
   }
 };
+function nodeOnly(name) {
+  throw new Error(`${name} is only available in Node.js runtimes`);
+}
+function rsaVerify() {
+  return nodeOnly("rsaVerify");
+}
+function rsaSignBase64Url() {
+  return nodeOnly("rsaSignBase64Url");
+}
+function rsaVerifySync() {
+  return nodeOnly("rsaVerifySync");
+}
+function pemToPublicJwk() {
+  return nodeOnly("pemToPublicJwk");
+}
+function generateRsaKeyPair() {
+  return nodeOnly("generateRsaKeyPair");
+}
 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");
@@ -154,7 +177,12 @@ function getSaltLength(jwtAlg) {
 0 && (module.exports = {
   browserCrypto,
   cryptoProvider,
+  generateRsaKeyPair,
   isRsaPssAlg,
   jwtAlgToWebCryptoAlg,
-  rsaVerifyBrowser
+  pemToPublicJwk,
+  rsaSignBase64Url,
+  rsaVerify,
+  rsaVerifyBrowser,
+  rsaVerifySync
 });

package/crypto/node.d.ts

@@ -48,7 +48,7 @@ export declare function generateRsaKeyPair(modulusLength?: number, alg?: string)
  * For RSA-PSS (PS256/PS384/PS512), callers must pass appropriate padding/saltLength options.
  */
 export declare function rsaSign(algorithm: string, data: Buffer, privateKey: crypto.KeyObject, options?: Omit<crypto.SignKeyObjectInput, 'key'>): Buffer;
-export declare function rsaVerify(jwtAlg: string, data: Buffer, publicJwk: JsonWebKey, signature: Buffer): boolean;
+export declare function rsaVerify(jwtAlg: string, data: Buffer | Uint8Array, publicJwk: JsonWebKey, signature: Buffer | Uint8Array): boolean;
 /**
  * Sign data with an RSA private JWK and return a base64url-encoded signature.
  *

package/esm/crypto/browser.mjs

@@ -2,11 +2,11 @@ var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuilt
 const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
 // __frontmcpCreateRequire
 // libs/utils/src/crypto/browser.ts
-import { sha256 as sha256Hash } from "@noble/hashes/sha2.js";
-import { hmac } from "@noble/hashes/hmac.js";
+import { gcm } from "@noble/ciphers/aes.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 as sha256Hash } from "@noble/hashes/sha2.js";
 import { randomBytes as nobleRandomBytes } from "@noble/hashes/utils.js";
-import { gcm } from "@noble/ciphers/aes.js";
 
 // libs/utils/src/crypto/jwt-alg.ts
 function isRsaPssAlg(jwtAlg) {
@@ -94,6 +94,24 @@ var browserCrypto = {
     return constantTimeEqual(a, b);
   }
 };
+function nodeOnly(name) {
+  throw new Error(`${name} is only available in Node.js runtimes`);
+}
+function rsaVerify() {
+  return nodeOnly("rsaVerify");
+}
+function rsaSignBase64Url() {
+  return nodeOnly("rsaSignBase64Url");
+}
+function rsaVerifySync() {
+  return nodeOnly("rsaVerifySync");
+}
+function pemToPublicJwk() {
+  return nodeOnly("pemToPublicJwk");
+}
+function generateRsaKeyPair() {
+  return nodeOnly("generateRsaKeyPair");
+}
 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");
@@ -128,7 +146,12 @@ function getSaltLength(jwtAlg) {
 export {
   browserCrypto,
   browserCrypto as cryptoProvider,
+  generateRsaKeyPair,
   isRsaPssAlg,
   jwtAlgToWebCryptoAlg,
-  rsaVerifyBrowser
+  pemToPublicJwk,
+  rsaSignBase64Url,
+  rsaVerify,
+  rsaVerifyBrowser,
+  rsaVerifySync
 };