docs: document mTLS & HMAC request signing env vars across developer-facing references

AGENTS.md

@@ -395,6 +395,10 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER` - AllowOnly owner scope value (sets default for `--allowonly-scope-owner`)
 - `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO` - AllowOnly repo name, requires owner (sets default for `--allowonly-scope-repo`)
 - `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY` - AllowOnly integrity level: `none`, `unapproved`, `approved`, `merged` (sets default for `--allowonly-min-integrity`)
+- `MCP_GATEWAY_TLS_CERT` - Path to TLS server certificate PEM file; enables HTTPS when set together with `MCP_GATEWAY_TLS_KEY` (sets default for `--tls-cert`)
+- `MCP_GATEWAY_TLS_KEY` - Path to TLS server private key PEM file; required when `MCP_GATEWAY_TLS_CERT` is set (sets default for `--tls-key`)
+- `MCP_GATEWAY_CA_CERT` - Path to CA certificate PEM file for client certificate verification; enables mutual TLS (mTLS) when set alongside `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY` (sets default for `--tls-ca`)
+- `MCP_GATEWAY_HMAC_SECRET` - Shared HMAC-SHA256 secret for request signing and replay protection; when set, requests to MCP handlers must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers (sets default for `--hmac-secret`)
 - `RUNNING_IN_CONTAINER` - Set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable
 
 **Note:** `PORT`, `HOST`, and `MODE` are not read by the `awmg` binary directly. However, `run.sh` does use `HOST` (default: `0.0.0.0`) and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly.
@@ -471,6 +475,8 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - **Auth**: `Authorization: <apiKey>` header (plain API key per spec 7.1, NOT Bearer scheme)
 - **Sessions**: Session ID extracted from Authorization header value
 - **Stdio servers**: Containerized execution only (no direct command support)
+- **mTLS**: Mutual TLS can be enabled with `--tls-cert`, `--tls-key`, and `--tls-ca` flags (or corresponding env vars) to require client certificates for all connections
+- **HMAC request signing**: Set `--hmac-secret` (or `MCP_GATEWAY_HMAC_SECRET`) to require HMAC-SHA256 signed requests; protects against replay attacks using `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers
 
 ## Resources
 

config.example.toml

@@ -176,6 +176,39 @@ args = [
 # Useful when servers have ordering dependencies or for debugging startup issues
 # sequential_launch = false
 
+# ============================================================================
+# Security: mTLS & HMAC Request Signing
+# ============================================================================
+# These options are configured via CLI flags or environment variables, NOT
+# directly in the TOML file. They are documented here for reference.
+#
+# TLS (one-way or mutual):
+#   --tls-cert <path>   Path to TLS server certificate PEM file (enables HTTPS)
+#                       Env: MCP_GATEWAY_TLS_CERT
+#   --tls-key <path>    Path to TLS server private key PEM file (required with --tls-cert)
+#                       Env: MCP_GATEWAY_TLS_KEY
+#   --tls-ca <path>     Path to CA certificate PEM file for client certificate
+#                       verification — enables mutual TLS (mTLS)
+#                       Env: MCP_GATEWAY_CA_CERT
+#
+# HMAC request signing:
+#   --hmac-secret <s>   Shared HMAC-SHA256 secret for request signing and replay
+#                       protection. When set, requests to HMAC-protected MCP
+#                       handler routes must include:
+#                         X-MCP-Timestamp  — Unix-second timestamp
+#                         X-MCP-Nonce      — unique per-request random nonce
+#                         X-MCP-Signature  — hex-encoded HMAC-SHA256 signature
+#                       Common operational endpoints such as /health and
+#                       /close are intentionally not HMAC-protected.
+#                       Env: MCP_GATEWAY_HMAC_SECRET
+#
+# Example (run command):
+#   ./awmg --config config.toml \
+#     --tls-cert /path/to/server.crt \
+#     --tls-key  /path/to/server.key \
+#     --tls-ca   /path/to/ca.crt \
+#     --hmac-secret "$(openssl rand -hex 32)"
+
 # ============================================================================
 # Notes
 # ============================================================================

docs/ENVIRONMENT_VARIABLES.md

@@ -29,6 +29,10 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 | `MCP_GATEWAY_WASM_GUARDS_DIR` | Root directory for per-server WASM guards (`<root>/<serverID>/*.wasm`, first match is loaded) | (disabled) |
 | `MCP_GATEWAY_GUARDS_MODE` | Guards enforcement mode: `strict` (deny violations), `filter` (remove denied tools), `propagate` (auto-adjust agent labels) (sets default for `--guards-mode`) | `strict` |
 | `MCP_GATEWAY_GUARDS_SINK_SERVER_IDS` | Comma-separated sink server IDs for JSONL guards tag enrichment (sets default for `--guards-sink-server-ids`) | (disabled) |
+| `MCP_GATEWAY_TLS_CERT` | Path to TLS server certificate PEM file. When set together with `MCP_GATEWAY_TLS_KEY`, enables HTTPS. Sets default for `--tls-cert`. | (disabled) |
+| `MCP_GATEWAY_TLS_KEY` | Path to TLS server private key PEM file. Required when `MCP_GATEWAY_TLS_CERT` is set. Sets default for `--tls-key`. | (disabled) |
+| `MCP_GATEWAY_CA_CERT` | Path to CA certificate PEM file for client certificate verification. When set (requires `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY`), enables mutual TLS (mTLS). Sets default for `--tls-ca`. | (disabled) |
+| `MCP_GATEWAY_HMAC_SECRET` | Shared HMAC-SHA256 secret for request signing and replay protection on MCP request endpoints (for example, `/mcp` and `/mcp/<server>`). When set, those MCP requests must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers. Sets default for `--hmac-secret`. | (disabled) |
 | `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*,launcher:*`) | (disabled) |
 | `DEBUG_COLORS` | Control colored debug output (0 to disable, auto-disabled when piping) | Auto-detect |
 | `RUNNING_IN_CONTAINER` | Manual override; set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable | (unset) |