@4da/mcp-server 5.0.0 → 5.0.2

package/README.md

@@ -172,7 +172,7 @@ The MCP server works without the desktop app. On first run it creates a local da
 | Agent memory (cross-session) | Yes | Yes |
 | Scored content feed (20+ sources) | -- | Yes |
 | Actionable signals + knowledge gaps | -- | Yes |
-| Compound intelligence (learns over time) | -- | Yes |
+| The analysis layer (Signal Chains, Knowledge Gaps, temporal analysis) | -- | Yes |
 
 > **[Download 4DA](https://github.com/4DA-Systems/4DA/releases/latest)** for the full experience.
 
@@ -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
 
@@ -211,7 +229,7 @@ npx @4da/mcp-server --version    # Print version
 No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy) and generic tech keywords to [HN Algolia](https://hn.algolia.com/api). The same public data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
 
 **Do I need the 4DA desktop app?**
-No. 9 tools work standalone: vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds scored content from 20+ sources that compounds over time.
+No. 9 tools work standalone: vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds a scored content feed from 20+ sources, graded against your actual stack.
 
 **Which AI tools does this work with?**
 Any tool that supports [MCP](https://modelcontextprotocol.io): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), and any custom MCP client.

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