> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Transport Security

> Configure CORS, bind address, DNS rebinding protection, and host validation for production deployments

FrontMCP provides transport-level security controls for CORS, network binding, DNS rebinding protection, and host header validation. In development, defaults are permissive for ease of use. In production, FrontMCP logs security warnings and offers a **strict mode** that enables all protections at once.

## Quick Start

Enable strict security mode for production:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  http: {
    port: 3000,
    cors: {
      origin: ['https://app.example.com'],
      credentials: false,
    },
    security: {
      strict: true,
      dnsRebindingProtection: {
        enabled: true,
        allowedHosts: ['api.example.com', 'api.example.com:3000'],
        allowedOrigins: ['https://app.example.com'],
      },
    },
  },
})
```

## Security Options

| Field                                            | Type                              | Default     | Description                          |
| ------------------------------------------------ | --------------------------------- | ----------- | ------------------------------------ |
| `security.strict`                                | boolean                           | `false`     | Enable all security features at once |
| `security.bindAddress`                           | `'loopback'` \| `'all'` \| string | `'0.0.0.0'` | Network bind address                 |
| `security.dnsRebindingProtection.enabled`        | boolean                           | `false`     | Validate Host and Origin headers     |
| `security.dnsRebindingProtection.allowedHosts`   | string\[]                         | ---         | Allowed Host header values           |
| `security.dnsRebindingProtection.allowedOrigins` | string\[]                         | ---         | Allowed Origin header values         |

## CORS Configuration

By default, FrontMCP uses permissive CORS (`origin: true`) for development convenience. In production, you should restrict origins explicitly:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  http: {
    cors: {
      origin: ['https://app.example.com', 'https://admin.example.com'],
      credentials: false,
      maxAge: 600,
    },
  },
})
```

To disable CORS entirely (same-origin only):

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  http: {
    cors: false,
  },
})
```

<Warning>
  `origin: true` reflects the request origin header, effectively allowing **any** website to make cross-origin requests. This is safe for local development but should never be used in production.
</Warning>

## Bind Address

Controls which network interface the server listens on:

| Value        | Binds To    | Use Case                                         |
| ------------ | ----------- | ------------------------------------------------ |
| `'loopback'` | `127.0.0.1` | Local-only access (development, reverse proxy)   |
| `'all'`      | `0.0.0.0`   | All interfaces (distributed pods, direct access) |
| IP string    | Specific IP | Custom network binding                           |

### Strict Mode Behavior

When `security.strict: true`:

* **Standalone mode**: binds to `127.0.0.1` (loopback only)
* **Distributed mode**: binds to `0.0.0.0` (pods need external access)

### Explicit Override

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
security: {
  bindAddress: 'loopback', // Always 127.0.0.1, regardless of deployment mode
}
```

<Tip>
  When running behind a reverse proxy (NGINX, Traefik, Envoy), bind to loopback and let the proxy handle external traffic.
</Tip>

## DNS Rebinding Protection

Validates the HTTP `Host` and `Origin` headers against an allowlist. When a request arrives with an unrecognized host, the server responds with `403 Forbidden`.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
security: {
  dnsRebindingProtection: {
    enabled: true,
    allowedHosts: ['localhost:3000', 'api.example.com'],
    allowedOrigins: ['https://app.example.com'],
  },
}
```

* **`allowedHosts`**: Matches the `Host` header exactly (include port if non-standard)
* **`allowedOrigins`**: Matches the `Origin` header exactly (include scheme)
* If `allowedOrigins` is set, requests **without** an `Origin` header are allowed through (non-browser clients)

<Note>
  DNS rebinding attacks use a malicious domain that resolves to `127.0.0.1`, tricking a browser into making requests to your local server. Host validation blocks these requests.
</Note>

## Request Body Limits

FrontMCP's Express host applies a default request body limit of `'4mb'` to
both `express.json()` and `express.urlencoded()` — lifting body-parser's
silent 100KB default, which routinely rejected base64-encoded blobs (PDFs,
DOCXes, large HTML inputs) before they reached MCP tool handlers (issue
\#410). Override the limits via the `http` block on `@FrontMcp`:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  http: {
    bodyLimit: '500kb',       // tighten for public-facing deployments
    urlencodedLimit: '100kb', // optional — falls back to bodyLimit when omitted
  },
})
class Server {}
```

| Option            | Type               | Default                   | Notes                                                                           |
| ----------------- | ------------------ | ------------------------- | ------------------------------------------------------------------------------- |
| `bodyLimit`       | `number \| string` | `'4mb'`                   | Accepts bytes (number) or body-parser strings (`'4mb'`, `'500kb'`, `'2gb'`, …). |
| `urlencodedLimit` | `number \| string` | falls back to `bodyLimit` | Independent override for `application/x-www-form-urlencoded` bodies.            |

When a request exceeds the configured limit, the adapter returns HTTP 413
with a structured JSON-RPC envelope:

```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Payload Too Large",
    "data": { "limit": 102400, "length": 204800 }
  }
}
```

<Warning>
  **Security trade-off.** Body-parser buffers the full request body in
  memory before parsing, so raising `bodyLimit` scales per-request memory
  with concurrency. Deployments exposed to untrusted networks should set an
  explicit lower bound (e.g. `'500kb'` or `'1mb'`) sized for the largest
  legitimate payload. The 100KB → 4MB default change in this release is a
  liberalization — every request that succeeded before still succeeds, but
  the implicit DoS guard is gone unless you set the option yourself.
</Warning>

Custom `hostFactory` users build their own Express app and are
**not affected** by `bodyLimit`/`urlencodedLimit` — those options are
consumed only by the built-in `ExpressHostAdapter`. Custom-host
deployments must configure their own body limits.

## Security Audit Warnings

In production (`NODE_ENV=production`) or distributed mode, FrontMCP logs security warnings at startup:

```
[Security] CORS_PERMISSIVE_DEFAULT: CORS is using the permissive default (origin: true).
[Security] BIND_ALL_INTERFACES: Server bound to 0.0.0.0 — accessible from all network interfaces.
[Security] DNS_REBINDING_UNPROTECTED: DNS rebinding protection is disabled.
[Security] STRICT_MODE_HINT: To enable strict security defaults, set security.strict = true.
```

These are warnings only — no defaults are changed. Use them to audit your configuration before going to production.

## Production Checklist

* [ ] Set explicit `cors.origin` (not `true`)
* [ ] Enable `security.dnsRebindingProtection` with `allowedHosts`
* [ ] Set `security.bindAddress` to `'loopback'` if behind a reverse proxy
* [ ] Configure TLS termination at the reverse proxy layer
* [ ] Set `NODE_ENV=production` for security audit warnings
* [ ] Review startup logs for `[Security]` warnings
* [ ] Tune `http.bodyLimit` to your largest legitimate payload

## Example: Full Production Config

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
  http: {
    port: 3000,
    cors: {
      origin: ['https://app.example.com'],
      credentials: false,
      maxAge: 600,
    },
    security: {
      strict: true,
      bindAddress: 'loopback',
      dnsRebindingProtection: {
        enabled: true,
        allowedHosts: ['localhost:3000'],
        allowedOrigins: ['https://app.example.com'],
      },
    },
  },
  redis: { provider: 'redis', host: 'redis', port: 6379 },
  transport: {
    protocol: 'modern',
    persistence: {
      redis: { provider: 'redis', host: 'redis', port: 6379 },
    },
  },
})
```

## Related

<CardGroup cols={2}>
  <Card title="Security Headers & CSP" icon="shield-halved" href="/frontmcp/deployment/security-headers">
    Content Security Policy, HSTS, and X-Frame-Options
  </Card>

  <Card title="High Availability" icon="server" href="/frontmcp/deployment/high-availability">
    Distributed sessions, heartbeat, and session takeover
  </Card>

  <Card title="Redis Setup" icon="database" href="/frontmcp/deployment/redis-setup">
    Redis connection and session store configuration
  </Card>

  <Card title="Production Build" icon="rocket" href="/frontmcp/deployment/production-build">
    Build and deploy for production
  </Card>
</CardGroup>