@4da/mcp-server 4.6.6 → 5.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@4da/mcp-server?color=gold)](https://www.npmjs.com/package/@4da/mcp-server)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D20-brightgreen)](https://nodejs.org/)
 [![smithery badge](https://smithery.ai/badge/@4da/mcp-server)](https://smithery.ai/server/@4da/mcp-server)
 
 **Dependency intelligence for AI coding agents.** Live CVE scanning, dependency health checks, upgrade planning, ecosystem news, and persistent decision memory. Zero config, privacy-first.
@@ -188,6 +188,21 @@ npx @4da/mcp-server
 npx @4da/mcp-server --http --port 4840
 ```
 
+The HTTP transport binds to `127.0.0.1` by default and applies a `Host`-header
+DNS rebinding guard to every request. Exposing it beyond this machine requires
+a shared secret:
+
+```bash
+MCP_AUTH_SECRET=<same value as the relay's JWT_SECRET> \
+MCP_ALLOWED_HOSTS=mcp.internal \
+  npx @4da/mcp-server --http --host 0.0.0.0
+```
+
+Without `MCP_AUTH_SECRET` a non-loopback bind is refused at startup. With it,
+every request must carry a Bearer token whose HMAC-SHA256 signature verifies
+against that secret, and the token's role is enforced per tool (`viewer` is
+read-only; `member` and `admin` may write). Put TLS in front of it.
+
 ## CLI Reference
 
 ```
@@ -204,6 +219,9 @@ npx @4da/mcp-server --version    # Print version
 |----------|-------------|---------|
 | `FOURDA_DB_PATH` | Path to 4DA's SQLite database | Auto-detected |
 | `FOURDA_OFFLINE` | Disable all network calls | `false` |
+| `MCP_AUTH_SECRET` | Shared secret for verifying Bearer tokens on `--http` (HMAC-SHA256). Falls back to `JWT_SECRET`. Unset means no token is accepted. | Unset |
+| `MCP_AUTH_REQUIRED` | Require auth on a **loopback** `--http` bind. Always required on a non-loopback bind. | `false` |
+| `MCP_ALLOWED_HOSTS` | Extra comma-separated hostnames accepted in `Host`/`Origin` (needed when binding to `0.0.0.0`). | localhost only |
 
 ## FAQ
 

package/dist/auth-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-request authorization context.
+ *
+ * The MCP v2 serving entries build a fresh `Server` per request from a
+ * zero-argument factory, so verified claims cannot be threaded through as a
+ * constructor argument. `AsyncLocalStorage` carries them from the HTTP
+ * transport (where the token is verified) to the tool-dispatch path (where the
+ * role is enforced) without touching every handler signature.
+ *
+ * Trust model:
+ *   - stdio        → no context at all. The host launched this process; it
+ *                    already has local process rights. Nothing to enforce.
+ *   - HTTP, no auth→ context with `claims: null, enforced: false`. Only
+ *                    reachable when bound to loopback with auth disabled, i.e.
+ *                    the same trust boundary as stdio.
+ *   - HTTP, auth   → context with verified claims. Roles are enforced.
+ */
+import { type TeamClaims } from "./auth.js";
+export interface RequestAuthContext {
+    /** Claims verified by `extractAuthClaims`, or null when auth was not required. */
+    claims: TeamClaims | null;
+    /** True when the transport required authentication for this request. */
+    enforced: boolean;
+}
+/** Run `fn` (and everything it awaits) with the given auth context attached. */
+export declare function runWithAuthContext<T>(ctx: RequestAuthContext, fn: () => T): T;
+/** The current request's auth context, or undefined on the stdio path. */
+export declare function getAuthContext(): RequestAuthContext | undefined;
+/** Thrown when an authenticated caller's role does not permit a tool call. */
+export declare class AuthorizationError extends Error {
+    constructor(message: string);
+}
+/**
+ * The operation a tool performs, derived from the registry annotation that
+ * already declares it. `readOnlyHint: true` means the tool cannot mutate
+ * state; everything else is treated as a write.
+ *
+ * Deliberately coarse: `decision_memory` and `agent_memory` have read-shaped
+ * actions too, but they are dispatched through a tool that CAN write, so a
+ * viewer is denied the whole tool rather than trusting an `action` argument to
+ * decide. Unknown tools fail closed as writes.
+ */
+export declare function requiredOperation(toolName: string): "read" | "write";
+/**
+ * Enforce the caller's role against the tool being invoked.
+ * Throws `AuthorizationError` when the role is insufficient.
+ */
+export declare function assertToolPermission(toolName: string): void;
+//# sourceMappingURL=auth-context.d.ts.map

package/dist/auth-context.js

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-request authorization context.
+ *
+ * The MCP v2 serving entries build a fresh `Server` per request from a
+ * zero-argument factory, so verified claims cannot be threaded through as a
+ * constructor argument. `AsyncLocalStorage` carries them from the HTTP
+ * transport (where the token is verified) to the tool-dispatch path (where the
+ * role is enforced) without touching every handler signature.
+ *
+ * Trust model:
+ *   - stdio        → no context at all. The host launched this process; it
+ *                    already has local process rights. Nothing to enforce.
+ *   - HTTP, no auth→ context with `claims: null, enforced: false`. Only
+ *                    reachable when bound to loopback with auth disabled, i.e.
+ *                    the same trust boundary as stdio.
+ *   - HTTP, auth   → context with verified claims. Roles are enforced.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { hasPermission } from "./auth.js";
+import { TOOL_REGISTRY } from "./schema-registry.js";
+const storage = new AsyncLocalStorage();
+/** Run `fn` (and everything it awaits) with the given auth context attached. */
+export function runWithAuthContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+/** The current request's auth context, or undefined on the stdio path. */
+export function getAuthContext() {
+    return storage.getStore();
+}
+/** Thrown when an authenticated caller's role does not permit a tool call. */
+export class AuthorizationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthorizationError";
+    }
+}
+/**
+ * The operation a tool performs, derived from the registry annotation that
+ * already declares it. `readOnlyHint: true` means the tool cannot mutate
+ * state; everything else is treated as a write.
+ *
+ * Deliberately coarse: `decision_memory` and `agent_memory` have read-shaped
+ * actions too, but they are dispatched through a tool that CAN write, so a
+ * viewer is denied the whole tool rather than trusting an `action` argument to
+ * decide. Unknown tools fail closed as writes.
+ */
+export function requiredOperation(toolName) {
+    return TOOL_REGISTRY[toolName]?.annotations.readOnlyHint ? "read" : "write";
+}
+/**
+ * Enforce the caller's role against the tool being invoked.
+ * Throws `AuthorizationError` when the role is insufficient.
+ */
+export function assertToolPermission(toolName) {
+    const ctx = storage.getStore();
+    if (!ctx)
+        return; // stdio — local process, no network identity to enforce
+    const operation = requiredOperation(toolName);
+    if (!ctx.claims) {
+        if (ctx.enforced) {
+            // Defensive: the transport rejects unauthenticated requests with 401
+            // before dispatch, so reaching here means the gate was bypassed.
+            throw new AuthorizationError(`Authentication required for '${toolName}' but no verified claims are present`);
+        }
+        return; // loopback HTTP with auth disabled — same trust boundary as stdio
+    }
+    if (!hasPermission(ctx.claims.role, operation)) {
+        throw new AuthorizationError(`Role '${ctx.claims.role}' is not permitted to perform '${operation}' operations (tool: ${toolName})`);
+    }
+}
+//# sourceMappingURL=auth-context.js.map

package/dist/auth.d.ts

@@ -1,36 +1,63 @@
 /**
- * MCP Authentication Middleware
+ * MCP Authentication — Bearer token verification for the HTTP transport.
  *
- * Validates JWT tokens from the Team Relay for network-exposed MCP access.
- * Stdio transport (local) remains unauthenticated.
- * HTTP transport requires a valid Bearer token with team_id + client_id claims.
+ * Stdio transport (one server process per host, launched by the host itself)
+ * is unauthenticated by design: the caller already has local process rights.
+ * The HTTP transport verifies every token cryptographically before a single
+ * claim is trusted.
+ *
+ * Verification is HMAC-SHA256 over `base64url(header) + "." + base64url(payload)`
+ * compared in constant time against the shared relay secret, followed by
+ * expiry, not-before, and role checks. Tokens are issued by the 4DA Team Relay
+ * (`relay/src/auth.rs`: `jsonwebtoken` v9, `Header::default()` = HS256,
+ * `Validation::default()` = HS256 + mandatory `exp` + 60s leeway) — the
+ * parameters below mirror that issuer exactly.
+ *
+ * FAIL CLOSED: when no shared secret is configured, every token is rejected.
+ * A server that cannot verify a signature must never accept the claims inside
+ * it — the payload of an unverified JWT is attacker-controlled plaintext.
  */
 import { IncomingMessage } from "node:http";
+/** Roles the relay issues. Anything else is rejected. */
+export declare const KNOWN_ROLES: readonly ["admin", "member", "viewer"];
+export type TeamRole = (typeof KNOWN_ROLES)[number];
 export interface TeamClaims {
     team_id: string;
     client_id: string;
-    role: string;
+    role: TeamRole;
     exp: number;
 }
 /**
- * Extract and validate a JWT token from an HTTP request.
+ * The shared secret used to verify relay-issued tokens.
  *
- * Returns the decoded claims if valid, null if no token or invalid.
- * Uses HMAC-SHA256 verification against the shared relay secret.
+ * `MCP_AUTH_SECRET` is the name to use when the MCP server is deployed on its
+ * own; `JWT_SECRET` is accepted as a fallback so a server co-deployed with the
+ * relay (which reads `JWT_SECRET`) inherits the same value without duplicating
+ * the config. Whitespace-only values count as unset.
+ */
+export declare function getAuthSecret(): string | undefined;
+/**
+ * Verify a JWT's signature and claims. Returns the claims only when the
+ * signature checks out against the configured secret AND the claims are valid.
  *
- * NOTE: This is a lightweight validator that checks structure and expiry.
- * Full JWT signature verification requires the `jsonwebtoken` package.
- * For launch, we validate structure + expiry. Post-launch, add signature verification.
+ * @param token   The raw JWT (no "Bearer " prefix).
+ * @param nowMs   Current time in epoch milliseconds (injectable for tests).
  */
-export declare function extractAuthClaims(req: IncomingMessage): TeamClaims | null;
+export declare function verifyToken(token: string, nowMs?: number): TeamClaims | null;
 /**
- * Check if a license tier allows network MCP access.
- * Only "team" and "enterprise" tiers can use HTTP transport.
+ * Extract and verify the Bearer token on an HTTP request.
+ *
+ * Returns the verified claims, or null when the request carries no token, a
+ * malformed token, a forged/tampered token, or an expired one.
  */
-export declare function isNetworkTierAllowed(tier: string | undefined): boolean;
+export declare function extractAuthClaims(req: IncomingMessage): TeamClaims | null;
 /**
  * Check if a role has permission for a specific operation.
  * Viewers can read, members can read+write, admins can do everything.
+ *
+ * Enforced on the tool-dispatch path — see `assertToolPermission` in
+ * `auth-context.ts`, which maps each tool to an operation via its
+ * `readOnlyHint` annotation.
  */
 export declare function hasPermission(role: string, operation: "read" | "write" | "admin"): boolean;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -1,76 +1,187 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * MCP Authentication Middleware
+ * MCP Authentication — Bearer token verification for the HTTP transport.
  *
- * Validates JWT tokens from the Team Relay for network-exposed MCP access.
- * Stdio transport (local) remains unauthenticated.
- * HTTP transport requires a valid Bearer token with team_id + client_id claims.
+ * Stdio transport (one server process per host, launched by the host itself)
+ * is unauthenticated by design: the caller already has local process rights.
+ * The HTTP transport verifies every token cryptographically before a single
+ * claim is trusted.
+ *
+ * Verification is HMAC-SHA256 over `base64url(header) + "." + base64url(payload)`
+ * compared in constant time against the shared relay secret, followed by
+ * expiry, not-before, and role checks. Tokens are issued by the 4DA Team Relay
+ * (`relay/src/auth.rs`: `jsonwebtoken` v9, `Header::default()` = HS256,
+ * `Validation::default()` = HS256 + mandatory `exp` + 60s leeway) — the
+ * parameters below mirror that issuer exactly.
+ *
+ * FAIL CLOSED: when no shared secret is configured, every token is rejected.
+ * A server that cannot verify a signature must never accept the claims inside
+ * it — the payload of an unverified JWT is attacker-controlled plaintext.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Roles the relay issues. Anything else is rejected. */
+export const KNOWN_ROLES = ["admin", "member", "viewer"];
+/**
+ * The only accepted signing algorithm. Pinning a single algorithm is what
+ * closes algorithm-confusion attacks: `alg: none` (no signature at all) and
+ * asymmetric algorithms (where a public key can be replayed as the HMAC key)
+ * are rejected before any HMAC is computed.
  */
+const ACCEPTED_ALG = "HS256";
+/** Clock skew tolerance, matching `jsonwebtoken`'s default `leeway` on the issuer. */
+const CLOCK_SKEW_SECONDS = 60;
 /**
- * Extract and validate a JWT token from an HTTP request.
+ * The shared secret used to verify relay-issued tokens.
  *
- * Returns the decoded claims if valid, null if no token or invalid.
- * Uses HMAC-SHA256 verification against the shared relay secret.
+ * `MCP_AUTH_SECRET` is the name to use when the MCP server is deployed on its
+ * own; `JWT_SECRET` is accepted as a fallback so a server co-deployed with the
+ * relay (which reads `JWT_SECRET`) inherits the same value without duplicating
+ * the config. Whitespace-only values count as unset.
+ */
+export function getAuthSecret() {
+    const secret = process.env.MCP_AUTH_SECRET?.trim() || process.env.JWT_SECRET?.trim();
+    return secret ? secret : undefined;
+}
+/** Constant-time buffer comparison that tolerates length mismatch. */
+function constantTimeEquals(a, b) {
+    // timingSafeEqual throws on differing lengths. A wrong-length signature is
+    // unconditionally invalid, so returning early leaks nothing an attacker
+    // cannot already compute (HS256 signatures are always 32 bytes).
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+function decodeSegment(segment) {
+    const json = Buffer.from(segment, "base64url").toString("utf-8");
+    return JSON.parse(json);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** Reject anything that is not a finite number (NaN, Infinity, strings, null). */
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function reject(reason) {
+    // console.warn writes to stderr, which is the only stream an MCP stdio
+    // server may write diagnostics to. Never log the token itself.
+    console.warn(`[4DA MCP Auth] Token rejected: ${reason}`);
+    return null;
+}
+/**
+ * Verify a JWT's signature and claims. Returns the claims only when the
+ * signature checks out against the configured secret AND the claims are valid.
  *
- * NOTE: This is a lightweight validator that checks structure and expiry.
- * Full JWT signature verification requires the `jsonwebtoken` package.
- * For launch, we validate structure + expiry. Post-launch, add signature verification.
+ * @param token   The raw JWT (no "Bearer " prefix).
+ * @param nowMs   Current time in epoch milliseconds (injectable for tests).
  */
-export function extractAuthClaims(req) {
-    const auth = req.headers["authorization"];
-    if (!auth || !auth.startsWith("Bearer ")) {
-        return null;
+export function verifyToken(token, nowMs = Date.now()) {
+    const secret = getAuthSecret();
+    if (!secret) {
+        // Fail closed. Without a secret there is nothing to verify against, so no
+        // token can be trusted — including one that is perfectly well-formed.
+        return reject("no shared secret configured (set MCP_AUTH_SECRET). Refusing to trust unverifiable tokens");
     }
-    const token = auth.slice(7).trim();
-    if (!token)
-        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some((p) => p.length === 0)) {
+        return reject("malformed token (expected three non-empty segments)");
+    }
+    const [encodedHeader, encodedPayload, encodedSignature] = parts;
+    // --- 1. Header: pin the algorithm BEFORE doing any crypto ---------------
+    let header;
     try {
-        // JWT is base64url(header).base64url(payload).signature
-        const parts = token.split(".");
-        if (parts.length !== 3)
-            return null;
-        // Decode payload (middle part)
-        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
-        // Validate required fields
-        if (!payload.team_id || !payload.client_id || !payload.role) {
-            return null;
-        }
-        // Check expiry
-        if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
-            console.warn(`[4DA MCP Auth] Token expired for team ${payload.team_id}`);
-            return null;
-        }
-        // Validate role is known
-        if (!["admin", "member", "viewer"].includes(payload.role)) {
-            return null;
-        }
-        return {
-            team_id: payload.team_id,
-            client_id: payload.client_id,
-            role: payload.role,
-            exp: payload.exp || 0,
-        };
+        header = decodeSegment(encodedHeader);
     }
     catch {
-        console.warn("[4DA MCP Auth] Failed to parse JWT token");
-        return null;
+        return reject("undecodable header segment");
     }
+    if (!isPlainObject(header))
+        return reject("header is not a JSON object");
+    if (header.alg !== ACCEPTED_ALG) {
+        return reject(`unsupported alg '${String(header.alg)}' (only ${ACCEPTED_ALG} is accepted)`);
+    }
+    if (header.typ !== undefined && header.typ !== "JWT") {
+        return reject(`unsupported typ '${String(header.typ)}'`);
+    }
+    if (header.crit !== undefined) {
+        // `crit` marks header params a verifier MUST understand. We understand
+        // none of them, so the only spec-correct response is to refuse.
+        return reject("token declares critical header params this verifier does not implement");
+    }
+    // --- 2. Signature: constant-time HMAC-SHA256 over header.payload -------
+    const signingInput = `${encodedHeader}.${encodedPayload}`;
+    const expected = createHmac("sha256", secret).update(signingInput).digest();
+    const provided = Buffer.from(encodedSignature, "base64url");
+    if (!constantTimeEquals(expected, provided)) {
+        return reject("signature verification failed");
+    }
+    // --- 3. Claims: only now is the payload trustworthy --------------------
+    let payload;
+    try {
+        payload = decodeSegment(encodedPayload);
+    }
+    catch {
+        return reject("undecodable payload segment");
+    }
+    if (!isPlainObject(payload))
+        return reject("payload is not a JSON object");
+    const { team_id, client_id, role, exp, nbf } = payload;
+    if (!isNonEmptyString(team_id))
+        return reject("missing or invalid team_id");
+    if (!isNonEmptyString(client_id))
+        return reject("missing or invalid client_id");
+    if (!isNonEmptyString(role))
+        return reject("missing or invalid role");
+    if (!KNOWN_ROLES.includes(role)) {
+        return reject(`unknown role '${role}'`);
+    }
+    // `exp` is mandatory: a signed token with no expiry is a permanent
+    // credential, and the issuer always sets one.
+    if (!isFiniteNumber(exp))
+        return reject("missing or invalid exp claim");
+    const nowSeconds = Math.floor(nowMs / 1000);
+    if (exp + CLOCK_SKEW_SECONDS < nowSeconds) {
+        return reject(`token expired for team ${team_id}`);
+    }
+    if (nbf !== undefined) {
+        if (!isFiniteNumber(nbf))
+            return reject("invalid nbf claim");
+        if (nbf - CLOCK_SKEW_SECONDS > nowSeconds)
+            return reject("token not yet valid (nbf)");
+    }
+    return { team_id, client_id, role: role, exp };
 }
 /**
- * Check if a license tier allows network MCP access.
- * Only "team" and "enterprise" tiers can use HTTP transport.
+ * Extract and verify the Bearer token on an HTTP request.
+ *
+ * Returns the verified claims, or null when the request carries no token, a
+ * malformed token, a forged/tampered token, or an expired one.
  */
-export function isNetworkTierAllowed(tier) {
-    return tier === "team" || tier === "enterprise";
+export function extractAuthClaims(req) {
+    const auth = req.headers["authorization"];
+    if (typeof auth !== "string" || !auth.startsWith("Bearer ")) {
+        return null;
+    }
+    const token = auth.slice(7).trim();
+    if (!token)
+        return null;
+    return verifyToken(token);
 }
 /**
  * Check if a role has permission for a specific operation.
  * Viewers can read, members can read+write, admins can do everything.
+ *
+ * Enforced on the tool-dispatch path — see `assertToolPermission` in
+ * `auth-context.ts`, which maps each tool to an operation via its
+ * `readOnlyHint` annotation.
  */
 export function hasPermission(role, operation) {
     switch (operation) {
         case "read":
-            return true; // All roles can read
+            return KNOWN_ROLES.includes(role);
         case "write":
             return role === "member" || role === "admin";
         case "admin":

package/dist/db.d.ts

@@ -107,7 +107,7 @@ export declare class FourDADatabase {
      * Get relevant content items scored by the Rust pipeline (preferred) or
      * TypeScript fallback scoring when Rust scores are unavailable.
      */
-    getRelevantContent(minScore?: number, sourceType?: string, limit?: number, sinceHours?: number): RelevantItem[];
+    getRelevantContent(minScore?: number, sourceType?: string, limit?: number, sinceHours?: number, requireCurrentVersion?: boolean): RelevantItem[];
     /**
      * Read the live freshness state of the feed database. Answered from ground truth, not from any
      * claim that a refresh ran — so DB-backed tools can tell the caller whether the curated feed is