npm - @casys/mcp-server - Versions diffs - 0.2.1 - Mend

@casys/mcp-server 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/README.md +417 -0
package/mod.ts +161 -0
package/package.json +32 -0
package/src/auth/config.ts +229 -0
package/src/auth/jwt-provider.ts +175 -0
package/src/auth/middleware.ts +170 -0
package/src/auth/mod.ts +44 -0
package/src/auth/presets.ts +129 -0
package/src/auth/provider.ts +47 -0
package/src/auth/scope-middleware.ts +59 -0
package/src/auth/types.ts +69 -0
package/src/concurrency/rate-limiter.ts +190 -0
package/src/concurrency/request-queue.ts +140 -0
package/src/concurrent-server.ts +1899 -0
package/src/middleware/backpressure.ts +36 -0
package/src/middleware/mod.ts +21 -0
package/src/middleware/rate-limit.ts +45 -0
package/src/middleware/runner.ts +63 -0
package/src/middleware/types.ts +60 -0
package/src/middleware/validation.ts +28 -0
package/src/observability/metrics.ts +378 -0
package/src/observability/mod.ts +20 -0
package/src/observability/otel.ts +109 -0
package/src/runtime/runtime.ts +220 -0
package/src/runtime/types.ts +90 -0
package/src/sampling/sampling-bridge.ts +191 -0
package/src/security/channel-hmac.ts +140 -0
package/src/security/csp.ts +87 -0
package/src/security/message-signer.ts +223 -0
package/src/types.ts +478 -0
package/src/validation/schema-validator.ts +238 -0

package/src/security/channel-hmac.ts ADDED Viewed

@@ -0,0 +1,140 @@
+/**
+ * HMAC Channel Authentication — Inline Script for PostMessage (MCP Apps)
+ *
+ * Generates an inline `<script>` that signs outgoing JSON-RPC messages
+ * from an iframe to its parent via PostMessage (HMAC-SHA256 + anti-replay).
+ *
+ * The HOST side is responsible for verifying incoming messages using
+ * `MessageSigner.verify()`. This script only handles the IFRAME side
+ * (signing outgoing).
+ *
+ * Part of @casys/mcp-server security module. See also:
+ * - message-signer.ts (MessageSigner class, HMAC sign/verify)
+ *
+ * @module server/security/channel-hmac
+ */
+// ---------------------------------------------------------------------------
+// Inline HMAC Script
+// ---------------------------------------------------------------------------
+/**
+ * Generate the inline `<script>` tag for iframe HMAC signing.
+ *
+ * The script:
+ * 1. Embeds the channel secret (invisible to other iframes due to cross-origin)
+ * 2. Monkey-patches `window.parent.postMessage` to sign outgoing JSON-RPC
+ *
+ * Verification of incoming messages is the HOST's responsibility
+ * (via `MessageSigner.verify()`), not the iframe's.
+ *
+ * @param secret - 64-char hex secret from MessageSigner.generateSecret()
+ * @returns HTML `<script>` string ready for injection into `<head>`
+ */
+export function generateHmacScript(secret: string): string {
+  return `
+<script data-mcp-channel-auth>
+(function() {
+  'use strict';
+  var SECRET_HEX = '${secret}';
+  var sendSeq = 0;
+  var cryptoKeyPromise = null;
+  function hexToBytes(hex) {
+    var bytes = new Uint8Array(hex.length / 2);
+    for (var i = 0; i < hex.length; i += 2) {
+      bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+  }
+  function bytesToHex(bytes) {
+    var hex = '';
+    for (var i = 0; i < bytes.length; i++) {
+      hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+  }
+  function initKey() {
+    if (cryptoKeyPromise) return cryptoKeyPromise;
+    cryptoKeyPromise = crypto.subtle.importKey(
+      'raw', hexToBytes(SECRET_HEX),
+      { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+    );
+    return cryptoKeyPromise;
+  }
+  function buildPayload(msg, seq) {
+    var id = msg.id != null ? msg.id : '';
+    var method = msg.method || '';
+    var body;
+    if (msg.params !== undefined) body = JSON.stringify(msg.params);
+    else if (msg.result !== undefined) body = JSON.stringify(msg.result);
+    else if (msg.error !== undefined) body = JSON.stringify(msg.error);
+    else body = '{}';
+    return seq + ':' + id + ':' + method + ':' + body;
+  }
+  function signMessage(msg) {
+    var seq = sendSeq++;
+    var payload = buildPayload(msg, seq);
+    return initKey().then(function(key) {
+      return crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload));
+    }).then(function(sig) {
+      var signed = {};
+      for (var k in msg) {
+        if (Object.prototype.hasOwnProperty.call(msg, k)) signed[k] = msg[k];
+      }
+      signed._seq = seq;
+      signed._hmac = bytesToHex(new Uint8Array(sig));
+      return signed;
+    });
+  }
+  // Monkey-patch outgoing postMessage (iframe -> parent)
+  var realPostMessage = window.parent.postMessage.bind(window.parent);
+  window.parent.postMessage = function(message, targetOrigin, transfer) {
+    if (message && typeof message === 'object' && message.jsonrpc === '2.0') {
+      signMessage(message).then(function(signed) {
+        realPostMessage(signed, targetOrigin, transfer);
+      }).catch(function(err) {
+        console.error('[mcp-channel-auth] Sign error:', err);
+      });
+    } else {
+      realPostMessage(message, targetOrigin, transfer);
+    }
+  };
+  initKey();
+})();
+</script>
+`;
+}
+/**
+ * Inject channel authentication script into HTML content.
+ *
+ * Inserts the HMAC signing script before `</head>` (preferred) or at the start.
+ * The injected script signs all outgoing JSON-RPC postMessages from the iframe.
+ * The HOST must verify these signatures using `MessageSigner.verify()`.
+ *
+ * @param html - HTML content to inject into
+ * @param secret - 64-char hex secret from MessageSigner.generateSecret()
+ * @returns Modified HTML with HMAC signing script injected
+ * @throws {Error} If secret is not a valid 64-char hex string
+ */
+export function injectChannelAuth(html: string, secret: string): string {
+  if (!/^[0-9a-f]{64}$/.test(secret)) {
+    throw new Error(
+      "[injectChannelAuth] Invalid secret: expected 64-char lowercase hex string. " +
+        "Use MessageSigner.generateSecret() to create one.",
+    );
+  }
+  const script = generateHmacScript(secret);
+  if (html.includes("</head>")) {
+    return html.replace("</head>", script + "</head>");
+  }
+  return script + html;
+}

package/src/security/csp.ts ADDED Viewed

@@ -0,0 +1,87 @@
+/**
+ * Content Security Policy helpers for MCP Apps HTML resources.
+ *
+ * Provides CSP header generation and HTML meta tag injection to protect
+ * against XSS and unauthorized resource loading in MCP App iframes.
+ *
+ * @module lib/server/security/csp
+ */
+/** Options for generating a CSP header value. */
+export interface CspOptions {
+  /** Additional allowed script sources (e.g. CDN URLs). */
+  readonly scriptSources?: readonly string[];
+  /** Additional allowed connect sources (e.g. WebSocket endpoints). */
+  readonly connectSources?: readonly string[];
+  /** Additional allowed frame ancestors. */
+  readonly frameAncestors?: readonly string[];
+  /**
+   * Allow `'unsafe-inline'` for scripts and styles (default: true).
+   * MCP Apps typically need inline scripts/styles for single-file HTML UIs.
+   */
+  readonly allowInline?: boolean;
+}
+/**
+ * Build a Content-Security-Policy header value.
+ *
+ * Uses `default-src 'none'` as the baseline (deny-all), then explicitly allows
+ * only what MCP App UIs need. Inline scripts/styles are allowed by default
+ * since MCP Apps are typically single-file HTML with inline code.
+ *
+ * @param options - CSP configuration
+ * @returns CSP header value string
+ */
+export function buildCspHeader(options: CspOptions = {}): string {
+  const allowInline = options.allowInline !== false;
+  const inlineDirective = allowInline ? " 'unsafe-inline'" : "";
+  const scriptSrc = [
+    `'self'${inlineDirective}`,
+    ...(options.scriptSources ?? []),
+  ].join(" ");
+  const connectSrc = ["'self'", ...(options.connectSources ?? [])].join(" ");
+  const frameAncestors = ["'self'", ...(options.frameAncestors ?? [])].join(
+    " ",
+  );
+  return [
+    `default-src 'none'`,
+    `script-src ${scriptSrc}`,
+    `style-src 'self'${inlineDirective}`,
+    `img-src 'self' data:`,
+    `font-src 'self'`,
+    `connect-src ${connectSrc}`,
+    `frame-ancestors ${frameAncestors}`,
+    `base-uri 'self'`,
+  ].join("; ");
+}
+/**
+ * Inject a CSP meta tag into HTML content.
+ *
+ * Inserts `<meta http-equiv="Content-Security-Policy" content="...">` right
+ * after the opening `<head>` tag. If no `<head>` tag exists, prepends to content.
+ *
+ * This provides CSP enforcement even when HTTP headers are unavailable
+ * (e.g. STDIO transport where there are no HTTP response headers).
+ *
+ * @param html - Original HTML content
+ * @param cspValue - CSP header value (from buildCspHeader)
+ * @returns HTML with injected CSP meta tag
+ */
+export function injectCspMetaTag(html: string, cspValue: string): string {
+  const escaped = cspValue.replace(/"/g, "&quot;");
+  const metaTag =
+    `<meta http-equiv="Content-Security-Policy" content="${escaped}">`;
+  // Inject right after <head> (case-insensitive, handles attributes)
+  const headMatch = html.match(/<head[^>]*>/i);
+  if (headMatch && headMatch.index !== undefined) {
+    const insertPos = headMatch.index + headMatch[0].length;
+    return html.slice(0, insertPos) + metaTag + html.slice(insertPos);
+  }
+  // Fallback: prepend to content
+  return metaTag + html;
+}

package/src/security/message-signer.ts ADDED Viewed

@@ -0,0 +1,223 @@
+/**
+ * HMAC-SHA256 Message Signer for PostMessage Channels
+ *
+ * Signs and verifies JSON-RPC messages exchanged via PostMessage.
+ * Each message gains `_hmac` (signature) and `_seq` (monotonic counter)
+ * fields for authentication and anti-replay protection.
+ *
+ * HMAC payload: `"${_seq}:${id}:${method}:${JSON.stringify(params|result|error)}"`
+ *
+ * Uses the Web Crypto API exclusively (Deno, Node.js 18+, browsers).
+ *
+ * @module server/security/message-signer
+ */
+// ---------------------------------------------------------------------------
+// Hex utilities
+// ---------------------------------------------------------------------------
+/** Convert a Uint8Array to a lowercase hex string. */
+export function bytesToHex(bytes: Uint8Array): string {
+  const out: string[] = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    out[i] = bytes[i].toString(16).padStart(2, "0");
+  }
+  return out.join("");
+}
+/** Convert a hex string to a Uint8Array. Returns null if invalid hex. */
+export function hexToBytes(hex: string): Uint8Array | null {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) return null;
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** A JSON-RPC message with optional HMAC signature fields. */
+export interface SignedMessage {
+  jsonrpc: "2.0";
+  id?: string | number;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: unknown;
+  _hmac?: string;
+  _seq?: number;
+  [key: string]: unknown;
+}
+/** Result of verifying a signed message. */
+export interface VerifyResult {
+  /** Whether the signature is valid. */
+  valid: boolean;
+  /** The message with `_hmac` and `_seq` stripped. */
+  message: SignedMessage;
+  /** Error description when valid is false. */
+  error?: string;
+}
+// ---------------------------------------------------------------------------
+// HMAC Payload
+// ---------------------------------------------------------------------------
+/**
+ * Build the canonical HMAC payload string.
+ *
+ * Format: `"${seq}:${id}:${method}:${body}"`
+ */
+export function buildHmacPayload(message: SignedMessage, seq: number): string {
+  const id = message.id ?? "";
+  const method = message.method ?? "";
+  let body: string;
+  if (message.params !== undefined) body = JSON.stringify(message.params);
+  else if (message.result !== undefined) body = JSON.stringify(message.result);
+  else if (message.error !== undefined) body = JSON.stringify(message.error);
+  else body = "{}";
+  return `${seq}:${id}:${method}:${body}`;
+}
+// ---------------------------------------------------------------------------
+// MessageSigner
+// ---------------------------------------------------------------------------
+/**
+ * HMAC-SHA256 message signer/verifier for a single PostMessage channel.
+ *
+ * Maintains separate sequence counters for send and receive directions.
+ *
+ * @example
+ * ```ts
+ * const signer = new MessageSigner(secretHex);
+ * await signer.init();
+ *
+ * const signed = await signer.sign({ jsonrpc: '2.0', method: 'tools/call', params: {} });
+ * const result = await signer.verify(signed);
+ * ```
+ */
+export class MessageSigner {
+  private cryptoKey: CryptoKey | null = null;
+  private sendSeq = 0;
+  private lastRecvSeq = -1;
+  private readonly secretHex: string;
+  /**
+   * Generate a 32-byte (256-bit) random hex secret for channel authentication.
+   * Uses `crypto.getRandomValues()` for cryptographic randomness.
+   *
+   * @returns 64-character lowercase hex string (32 bytes)
+   */
+  static generateSecret(): string {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+  }
+  constructor(secretHex: string) {
+    this.secretHex = secretHex;
+  }
+  /**
+   * Initialize the CryptoKey. Must be called before sign()/verify().
+   * Idempotent.
+   */
+  async init(): Promise<void> {
+    if (this.cryptoKey) return;
+    const keyBytes = hexToBytes(this.secretHex);
+    if (!keyBytes) {
+      throw new Error(
+        "[MessageSigner] Invalid secret: must be a valid hex string. " +
+          "Use MessageSigner.generateSecret() to create one.",
+      );
+    }
+    this.cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      keyBytes.buffer as ArrayBuffer,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign", "verify"],
+    );
+  }
+  /** Sign a JSON-RPC message by adding `_hmac` and `_seq` fields. */
+  async sign(message: SignedMessage): Promise<SignedMessage> {
+    if (!this.cryptoKey) {
+      throw new Error(
+        "[MessageSigner] Not initialized. Call init() before sign().",
+      );
+    }
+    const seq = this.sendSeq++;
+    const payload = buildHmacPayload(message, seq);
+    const sig = await crypto.subtle.sign(
+      "HMAC",
+      this.cryptoKey,
+      new TextEncoder().encode(payload),
+    );
+    return { ...message, _seq: seq, _hmac: bytesToHex(new Uint8Array(sig)) };
+  }
+  /**
+   * Verify a signed message and strip `_hmac`/`_seq` fields.
+   *
+   * Rejects if: missing fields, replay (seq <= lastSeen), HMAC mismatch.
+   */
+  async verify(message: SignedMessage): Promise<VerifyResult> {
+    if (!this.cryptoKey) {
+      throw new Error(
+        "[MessageSigner] Not initialized. Call init() before verify().",
+      );
+    }
+    const { _hmac, _seq, ...clean } = message;
+    if (_hmac === undefined || _seq === undefined) {
+      return {
+        valid: false,
+        message: clean as SignedMessage,
+        error: "Missing _hmac or _seq field",
+      };
+    }
+    if (typeof _seq !== "number" || _seq <= this.lastRecvSeq) {
+      return {
+        valid: false,
+        message: clean as SignedMessage,
+        error:
+          `Replay detected: _seq=${_seq} <= lastRecvSeq=${this.lastRecvSeq}`,
+      };
+    }
+    const hmacBytes = hexToBytes(_hmac);
+    if (!hmacBytes) {
+      return {
+        valid: false,
+        message: clean as SignedMessage,
+        error: "Invalid _hmac: not valid hex",
+      };
+    }
+    const payload = buildHmacPayload(clean as SignedMessage, _seq);
+    const isValid = await crypto.subtle.verify(
+      "HMAC",
+      this.cryptoKey,
+      hmacBytes.buffer as ArrayBuffer,
+      new TextEncoder().encode(payload),
+    );
+    if (!isValid) {
+      return {
+        valid: false,
+        message: clean as SignedMessage,
+        error: "HMAC signature mismatch",
+      };
+    }
+    this.lastRecvSeq = _seq;
+    return { valid: true, message: clean as SignedMessage };
+  }
+  /** Reset sequence counters (for testing). */
+  reset(): void {
+    this.sendSeq = 0;
+    this.lastRecvSeq = -1;
+  }
+}