@4da/mcp-server 5.0.0 → 5.0.1

package/README.md

@@ -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/http-transport.d.ts

@@ -9,21 +9,79 @@
  * no express or other framework needed.
  *
  * Security:
- * - Binds to 127.0.0.1 only (localhost)
- * - DNS rebinding protection via Origin header check
+ * - Binds to 127.0.0.1 by default. `--host` can widen that; a non-loopback
+ *   bind is refused unless a shared auth secret is configured, and forces
+ *   authentication on for every request.
+ * - DNS rebinding protection via a `Host` header allowlist, applied to EVERY
+ *   request. This is the primary guard: a rebinding attack necessarily
+ *   presents the attacker's hostname in `Host`, and unlike `Origin` the header
+ *   is mandatory, so a request cannot skip the check by omitting it.
+ * - `Origin`, when present, must also be localhost-class. A missing `Origin`
+ *   is not a pass — it is simply not additional evidence, so such requests are
+ *   admitted only on the strength of the `Host` check above, and only ever
+ *   without credentials on a loopback bind.
+ * - Bearer tokens are HMAC-SHA256 verified (see auth.ts) before any claim is
+ *   read, and the verified role is enforced on tool dispatch.
  * - Stateless (no session tracking)
  */
+import { type Server as HttpServer } from "node:http";
 import { type Server } from "@modelcontextprotocol/server";
 export interface HttpServerOptions {
     port: number;
     host: string;
 }
+/** Handle for a running HTTP transport, so callers (and tests) can shut it down. */
+export interface HttpServerHandle {
+    server: HttpServer;
+    close(): Promise<void>;
+}
+/** Security posture derived from the bind address plus environment config. */
+export interface HttpSecurityPolicy {
+    /** True when the server is bound to a loopback address only. */
+    loopback: boolean;
+    /** True when every non-health request must carry a verified Bearer token. */
+    authRequired: boolean;
+    /** Hostnames accepted in the `Host` header (port-agnostic). */
+    allowedHostnames: string[];
+    /** Hostnames accepted in the `Origin` header, when one is sent. */
+    allowedOrigins: string[];
+}
+/** Loopback bind addresses — everything else reaches the network. */
+export declare function isLoopbackBind(host: string): boolean;
+/**
+ * Resolve the security policy for a bind address.
+ *
+ * A loopback bind keeps the historical behaviour: auth is opt-in via
+ * `MCP_AUTH_REQUIRED`. Any other bind is network-exposed, so authentication is
+ * mandatory regardless of that variable.
+ */
+export declare function resolveSecurityPolicy(host: string): HttpSecurityPolicy;
+export interface GuardRejection {
+    status: number;
+    error: string;
+}
+/**
+ * DNS rebinding guard. Runs on every request, before routing and before auth.
+ *
+ * Returns null when the request may proceed, or the rejection to send.
+ */
+export declare function evaluateRequestGuard(headers: {
+    host?: string | string[];
+    origin?: string | string[];
+}, policy: HttpSecurityPolicy): GuardRejection | null;
+/**
+ * Refuse to start a network-exposed server that cannot authenticate anyone,
+ * and make a non-loopback bind impossible to do accidentally.
+ */
+export declare function enforceBindPolicy(host: string, policy: HttpSecurityPolicy): void;
 /**
  * Start a Streamable HTTP server for the MCP protocol.
  *
  * Takes a server factory: `createMcpHandler` builds a fresh instance per
  * request (stateless — compatible with serverless environments and simple
  * round-robin load balancing).
+ *
+ * Resolves once the server is accepting connections.
  */
-export declare function startHttpServer(factory: () => Server, options?: HttpServerOptions): Promise<void>;
+export declare function startHttpServer(factory: () => Server, options?: HttpServerOptions): Promise<HttpServerHandle>;
 //# sourceMappingURL=http-transport.d.ts.map

package/dist/http-transport.js

@@ -10,30 +10,145 @@
  * no express or other framework needed.
  *
  * Security:
- * - Binds to 127.0.0.1 only (localhost)
- * - DNS rebinding protection via Origin header check
+ * - Binds to 127.0.0.1 by default. `--host` can widen that; a non-loopback
+ *   bind is refused unless a shared auth secret is configured, and forces
+ *   authentication on for every request.
+ * - DNS rebinding protection via a `Host` header allowlist, applied to EVERY
+ *   request. This is the primary guard: a rebinding attack necessarily
+ *   presents the attacker's hostname in `Host`, and unlike `Origin` the header
+ *   is mandatory, so a request cannot skip the check by omitting it.
+ * - `Origin`, when present, must also be localhost-class. A missing `Origin`
+ *   is not a pass — it is simply not additional evidence, so such requests are
+ *   admitted only on the strength of the `Host` check above, and only ever
+ *   without credentials on a loopback bind.
+ * - Bearer tokens are HMAC-SHA256 verified (see auth.ts) before any claim is
+ *   read, and the verified role is enforced on tool dispatch.
  * - Stateless (no session tracking)
  */
 import { createServer } from "node:http";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createMcpHandler } from "@modelcontextprotocol/server";
+import { createMcpHandler, localhostAllowedHostnames, localhostAllowedOrigins, validateHostHeader, validateOriginHeader, } from "@modelcontextprotocol/server";
 import { toNodeHandler } from "@modelcontextprotocol/node";
-import { extractAuthClaims } from "./auth.js";
+import { extractAuthClaims, getAuthSecret } from "./auth.js";
+import { runWithAuthContext } from "./auth-context.js";
 const DEFAULT_PORT = 4840;
 const DEFAULT_HOST = "127.0.0.1";
 const __ht_dirname = dirname(fileURLToPath(import.meta.url));
 const SERVER_VERSION = JSON.parse(readFileSync(join(__ht_dirname, "..", "package.json"), "utf-8")).version;
+/** Strip IPv6 brackets and zone id so "[::1]" and "::1" compare equal. */
+function normalizeHostname(host) {
+    return host.trim().replace(/^\[|\]$/g, "").split("%")[0].toLowerCase();
+}
+/** Loopback bind addresses — everything else reaches the network. */
+export function isLoopbackBind(host) {
+    const h = normalizeHostname(host);
+    return h === "localhost" || h === "::1" || /^127\./.test(h);
+}
+/**
+ * Extra hostnames accepted in `Host`/`Origin`, from `MCP_ALLOWED_HOSTS`
+ * (comma-separated). Needed when binding to `0.0.0.0`, where the hostname
+ * legitimate clients use is not knowable from the bind address.
+ */
+function configuredExtraHosts() {
+    return (process.env.MCP_ALLOWED_HOSTS ?? "")
+        .split(",")
+        .map((h) => normalizeHostname(h))
+        .filter((h) => h.length > 0);
+}
+/**
+ * Resolve the security policy for a bind address.
+ *
+ * A loopback bind keeps the historical behaviour: auth is opt-in via
+ * `MCP_AUTH_REQUIRED`. Any other bind is network-exposed, so authentication is
+ * mandatory regardless of that variable.
+ */
+export function resolveSecurityPolicy(host) {
+    const loopback = isLoopbackBind(host);
+    const extras = configuredExtraHosts();
+    // A concrete non-loopback bind address is itself a legitimate Host value;
+    // wildcards (0.0.0.0 / ::) name no reachable host, so they add nothing.
+    const bindHostname = normalizeHostname(host);
+    const isWildcard = bindHostname === "0.0.0.0" || bindHostname === "::" || bindHostname === "";
+    const bindExtras = loopback || isWildcard ? [] : [bindHostname];
+    return {
+        loopback,
+        authRequired: loopback ? process.env.MCP_AUTH_REQUIRED === "true" : true,
+        allowedHostnames: [...localhostAllowedHostnames(), ...bindExtras, ...extras],
+        allowedOrigins: [...localhostAllowedOrigins(), ...bindExtras, ...extras],
+    };
+}
+/**
+ * DNS rebinding guard. Runs on every request, before routing and before auth.
+ *
+ * Returns null when the request may proceed, or the rejection to send.
+ */
+export function evaluateRequestGuard(headers, policy) {
+    const pick = (v) => Array.isArray(v) ? v[0] : v;
+    // `Host` is mandatory in HTTP/1.1 and always present in HTTP/2 (as
+    // :authority, which Node surfaces here). Missing means malformed, not
+    // trusted — validateHostHeader rejects it.
+    const hostResult = validateHostHeader(pick(headers.host), policy.allowedHostnames);
+    if (!hostResult.ok) {
+        return { status: 403, error: `Forbidden: DNS rebinding protection (${hostResult.errorCode})` };
+    }
+    // `Origin` is only sent by browsers. A present-but-foreign value is a
+    // cross-origin browser request and is refused; an absent value adds no
+    // evidence either way, and the Host check above has already run.
+    const originResult = validateOriginHeader(pick(headers.origin), policy.allowedOrigins);
+    if (!originResult.ok) {
+        return { status: 403, error: `Forbidden: ${originResult.errorCode}` };
+    }
+    return null;
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+/**
+ * Refuse to start a network-exposed server that cannot authenticate anyone,
+ * and make a non-loopback bind impossible to do accidentally.
+ */
+export function enforceBindPolicy(host, policy) {
+    if (policy.loopback)
+        return;
+    if (!getAuthSecret()) {
+        throw new Error(`Refusing to bind the MCP HTTP transport to a non-loopback address (${host}) with no auth secret.\n` +
+            `  Every 4DA tool (dependency inventory, decisions, agent memory, Developer DNA) would be\n` +
+            `  readable and writable by anyone who can reach this port.\n` +
+            `  Set MCP_AUTH_SECRET (the same value as the relay's JWT_SECRET) to enable token verification,\n` +
+            `  or drop --host and serve on 127.0.0.1.`);
+    }
+    console.error("");
+    console.error("  ############################################################");
+    console.error(`  # WARNING: MCP HTTP transport is bound to ${host}`);
+    console.error("  # This exposes 4DA tools beyond this machine.");
+    console.error("  # Authentication is REQUIRED for every request on this bind.");
+    console.error("  # Put it behind TLS and a trusted network boundary.");
+    console.error("  ############################################################");
+    console.error("");
+    const extras = configuredExtraHosts();
+    const bindHostname = normalizeHostname(host);
+    if ((bindHostname === "0.0.0.0" || bindHostname === "::") && extras.length === 0) {
+        console.error("  NOTE: MCP_ALLOWED_HOSTS is unset, so only localhost-class Host headers are accepted.");
+        console.error("        Set MCP_ALLOWED_HOSTS=<hostname-or-ip[,...]> to the address clients actually use.");
+        console.error("");
+    }
+}
 /**
  * Start a Streamable HTTP server for the MCP protocol.
  *
  * Takes a server factory: `createMcpHandler` builds a fresh instance per
  * request (stateless — compatible with serverless environments and simple
  * round-robin load balancing).
+ *
+ * Resolves once the server is accepting connections.
  */
 export async function startHttpServer(factory, options = { port: DEFAULT_PORT, host: DEFAULT_HOST }) {
     const { port, host } = options;
+    const policy = resolveSecurityPolicy(host);
+    enforceBindPolicy(host, policy);
     const mcpHandler = createMcpHandler(factory);
     const handleMcpRequest = toNodeHandler(mcpHandler, {
         onerror: (err) => {
@@ -41,73 +156,68 @@ export async function startHttpServer(factory, options = { port: DEFAULT_PORT, h
         },
     });
     const httpServer = createServer(async (req, res) => {
-        // DNS rebinding protection: reject cross-origin requests from non-local origins
-        const origin = req.headers.origin;
-        if (origin) {
-            try {
-                const url = new URL(origin);
-                if (url.hostname !== "localhost" && url.hostname !== "127.0.0.1" && url.hostname !== "::1" && url.hostname !== "[::1]") {
-                    res.writeHead(403, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Forbidden: DNS rebinding protection" }));
-                    return;
-                }
-            }
-            catch {
-                res.writeHead(403, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: "Forbidden: invalid Origin header" }));
-                return;
-            }
+        // DNS rebinding protection — every request, before routing or auth.
+        const rejection = evaluateRequestGuard(req.headers, policy);
+        if (rejection) {
+            sendJson(res, rejection.status, { error: rejection.error });
+            return;
         }
-        // Auth check: if MCP_AUTH_REQUIRED env var is set, validate JWT
-        const authRequired = process.env.MCP_AUTH_REQUIRED === "true";
+        const pathname = new URL(req.url || "/", `http://${host}:${port}`).pathname;
+        // Auth gate. Unauthenticated health checks on "/" stay open so liveness
+        // probes work; the endpoint reveals only name, version and status.
         let claims = null;
-        if (authRequired) {
-            // Allow unauthenticated health checks on root
-            const checkPath = new URL(req.url || "/", `http://${host}:${port}`).pathname;
-            if (checkPath !== "/") {
-                claims = extractAuthClaims(req);
-                if (!claims) {
-                    res.writeHead(401, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Authentication required" }));
-                    return;
-                }
+        if (policy.authRequired && pathname !== "/") {
+            claims = extractAuthClaims(req);
+            if (!claims) {
+                res.writeHead(401, {
+                    "Content-Type": "application/json",
+                    "WWW-Authenticate": 'Bearer realm="4da-mcp"',
+                });
+                res.end(JSON.stringify({ error: "Authentication required" }));
+                return;
             }
         }
-        // Route requests
-        const pathname = new URL(req.url || "/", `http://${host}:${port}`).pathname;
         // Health check endpoint
         if (pathname === "/" && req.method === "GET") {
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
+            sendJson(res, 200, {
                 name: "4da-mcp",
                 version: SERVER_VERSION,
                 transport: "streamable-http",
                 status: "ok",
-            }));
+            });
             return;
         }
         // Only handle /mcp endpoint
         if (pathname !== "/mcp") {
-            res.writeHead(404, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "Not Found" }));
+            sendJson(res, 404, { error: "Not Found" });
             return;
         }
         // Hand off to the MCP handler — body parsing, era classification, and
-        // per-request instance construction happen inside the entry.
-        await handleMcpRequest(req, res);
+        // per-request instance construction happen inside the entry. The auth
+        // context rides along so tool dispatch can enforce the verified role.
+        await runWithAuthContext({ claims, enforced: policy.authRequired }, () => handleMcpRequest(req, res));
     });
-    httpServer.listen(port, host, () => {
-        console.error(`4DA MCP Server v${SERVER_VERSION} (Streamable HTTP) listening on http://${host}:${port}/mcp`);
-        console.error(`Health check: http://${host}:${port}/`);
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(port, host, () => {
+            httpServer.removeListener("error", reject);
+            resolve();
+        });
     });
+    console.error(`4DA MCP Server v${SERVER_VERSION} (Streamable HTTP) listening on http://${host}:${port}/mcp`);
+    console.error(`Health check: http://${host}:${port}/`);
+    console.error(`Authentication: ${policy.authRequired ? "required (HMAC-SHA256 verified Bearer tokens)" : "disabled (loopback only)"}`);
+    const close = async () => {
+        await mcpHandler.close();
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+    };
     // Graceful shutdown
     const shutdown = () => {
         console.error("Shutting down HTTP server...");
-        void mcpHandler.close();
-        httpServer.close();
-        process.exit(0);
+        void close().finally(() => process.exit(0));
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    return { server: httpServer, close };
 }
 //# sourceMappingURL=http-transport.js.map

package/dist/index.js

@@ -8,9 +8,12 @@
  * Claude Desktop, and other MCP hosts. Runs locally; the only data leaving the
  * machine is public package names/versions sent to registries (OSV, npm, etc.).
  *
- * SECURITY: the server trusts its local environment and does NOT implement
- * authentication. The optional --http transport is intended for localhost use;
- * do NOT expose it over a network without putting your own auth in front.
+ * SECURITY: stdio serving is unauthenticated by design — the MCP host launches
+ * this process and already holds local process rights. The optional --http
+ * transport defaults to 127.0.0.1 and applies a Host-header DNS rebinding
+ * guard to every request. Binding it anywhere else requires a shared auth
+ * secret (MCP_AUTH_SECRET) and then verifies an HMAC-SHA256-signed Bearer
+ * token on every request, enforcing the token's role at tool dispatch.
  *
  * 14 tools across 5 categories. Live vulnerability scanning (OSV.dev),
  * ecosystem news, persistent memory, and tech stack awareness for any MCP host.
@@ -338,13 +341,23 @@ async function main() {
   Options:
     --http              Use Streamable HTTP instead of stdio
     --port <number>     HTTP port (default: 4840)
-    --host <address>    HTTP bind address (default: 127.0.0.1)
+    --host <address>    HTTP bind address (default: 127.0.0.1). A non-loopback
+                        address exposes every tool to the network and is
+                        refused unless MCP_AUTH_SECRET is set; authentication
+                        is then mandatory for every request.
     --setup             Detect editors and write MCP config
     --doctor            Validate database, bindings, and LLM providers
 
   Environment:
     FOURDA_DB_PATH      Path to 4DA's SQLite database (auto-detected if omitted)
     FOURDA_OFFLINE      Set to "true" to disable all network calls (OSV.dev, HN)
+    MCP_AUTH_SECRET     Shared secret for verifying relay-issued Bearer tokens
+                        (HMAC-SHA256). Falls back to JWT_SECRET. Without it, no
+                        token is accepted.
+    MCP_AUTH_REQUIRED   Set to "true" to require auth on a loopback --http bind
+                        (always required on a non-loopback bind)
+    MCP_ALLOWED_HOSTS   Extra comma-separated hostnames accepted in the Host /
+                        Origin headers (needed when binding to 0.0.0.0)
 
   Works standalone (scans your project on startup) or with the full
   4DA desktop app for content scoring, source monitoring, and more.
@@ -365,10 +378,35 @@ async function main() {
     }
     // HTTP transport mode
     if (args.includes("--http")) {
-        const portIndex = args.indexOf("--port");
-        const port = portIndex !== -1 ? parseInt(args[portIndex + 1], 10) : 4840;
-        const host = args.includes("--host") ? args[args.indexOf("--host") + 1] : "127.0.0.1";
-        await startHttpServer(buildServer, { port, host });
+        const flagValue = (flag) => {
+            const i = args.indexOf(flag);
+            if (i === -1)
+                return undefined;
+            const value = args[i + 1];
+            // A flag with no value (or followed by another flag) is a typo, not a
+            // request to bind everywhere — refuse rather than guess.
+            if (value === undefined || value.startsWith("-")) {
+                console.error(`[4DA] ${flag} requires a value`);
+                process.exit(1);
+            }
+            return value;
+        };
+        const rawPort = flagValue("--port");
+        const port = rawPort === undefined ? 4840 : Number.parseInt(rawPort, 10);
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            console.error(`[4DA] Invalid --port value: ${rawPort}`);
+            process.exit(1);
+        }
+        const host = flagValue("--host") ?? "127.0.0.1";
+        try {
+            await startHttpServer(buildServer, { port, host });
+        }
+        catch (error) {
+            // Bind-policy refusals carry an actionable message; print it plainly
+            // rather than as an unhandled stack trace.
+            console.error(`[4DA] ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
         return;
     }
     // -------------------------------------------------------------------------

package/dist/tool-dispatch.d.ts

@@ -14,6 +14,10 @@ export type ToolExecutor = (db: FourDADatabase, params: any) => unknown | Promis
 /**
  * Dispatch a tool call by name. Awaits uniformly (no-op for sync executors).
  * Returns MCP-formatted response with JSON-serialized result.
+ *
+ * Authenticated HTTP callers are role-checked here — the single choke point
+ * every tool call passes through. Stdio callers are unaffected (no auth
+ * context; the host already owns the process).
  */
 export declare function dispatchTool(name: string, db: FourDADatabase, args: Record<string, unknown> | undefined): Promise<CallToolResult>;
 /** Check if a tool exists in the dispatch map */

package/dist/tool-dispatch.js

@@ -5,6 +5,7 @@
  * Map-based dispatch for the 14 active tools.
  * Adding a new tool = add to this map + schema-registry + barrel export.
  */
+import { assertToolPermission } from "./auth-context.js";
 import { executeGetRelevantContent, executeGetContext, executeRecordFeedback, executeGetActionableSignals, executeKnowledgeGaps, executeDecisionMemory, executeCheckDecisionAlignment, executeAgentMemory, executeDeveloperDna, executeWhatShouldIKnow, executeVulnerabilityScan, executeEcosystemPulse, executeDependencyHealth, executeUpgradePlanner, } from "./tools/index.js";
 import { getLiveIntelligence } from "./live-singleton.js";
 /**
@@ -46,12 +47,17 @@ const FRESHNESS_TOOLS = new Set([
 /**
  * Dispatch a tool call by name. Awaits uniformly (no-op for sync executors).
  * Returns MCP-formatted response with JSON-serialized result.
+ *
+ * Authenticated HTTP callers are role-checked here — the single choke point
+ * every tool call passes through. Stdio callers are unaffected (no auth
+ * context; the host already owns the process).
  */
 export async function dispatchTool(name, db, args) {
     const executor = DISPATCH_MAP[name];
     if (!executor) {
         throw new Error(`Unknown tool: ${name}`);
     }
+    assertToolPermission(name);
     const result = await executor(db, (args || {}));
     const payload = FRESHNESS_TOOLS.has(name) ? attachFreshness(db, result) : result;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4da/mcp-server",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "mcpName": "io.github.4DA-Systems/4da-mcp-server",
   "description": "Dependency intelligence for AI coding agents. Live CVE scanning, dependency health, upgrade planning, ecosystem news, decision memory — zero config, privacy-first. 9 tools standalone, 14 total with desktop app.",
   "type": "module",
@@ -82,7 +82,8 @@
   "dependencies": {
     "better-sqlite3": "^12.9.0",
     "@modelcontextprotocol/node": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0"
+    "@modelcontextprotocol/server": "^2.0.0",
+    "hono": "^4.12.34"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
@@ -103,7 +104,9 @@
       "fast-uri": ">=3.1.2",
       "ip-address": "^10.1.1",
       "vite": ">=7.3.5 <8",
-      "esbuild": ">=0.28.1"
+      "esbuild": ">=0.28.1",
+      "hono": ">=4.12.34 <5",
+      "@hono/node-server": ">=2.0.5 <3"
     }
   }
 }