- Trusted Proxy Hops — how many X-Forwarded-For hops you trust (e.g., Cloudflare + Nginx = 2)
- Max Body (bytes) — reject large payloads early (default 1 MB)
- Allowed Content-Types — comma-separated allowlist (default: application/json,application/x-www-form-urlencoded)
- Rate Limit / Minute (per IP) — default 120. With Redis it’s cluster-wide; otherwise per process

---

$3

- Timestamp Header (x-timestamp) — UNIX seconds, 10 digits
- Nonce Header (x-nonce) — unique per request (UUID v4 or 16–32B hex)
- Max Skew (sec) — default 300; tune based on client/server time sync

---

$3

- HMAC Signature Header (x-signature) → value like sha256=
- HMAC Algorithm — sha256 (default) or sha512

Signature Mode
- body — sign raw body with HMAC (compatibility)
- extended — method + path + canonical query + timestamp + nonce + bodyhash (strongest)

Dual-Key Rotation
- Previous Secret — optional, for rolling changes
- Dual-Key Window (min) — accept previous secret briefly during rotation

---

$3

- IP Allow (CIDR) — only allow these ranges
- IP Deny (CIDR) — block these ranges first (deny takes precedence)

---

$3

- JWT Issuer (iss) — optional but recommended
- JWT Audience (aud) — optional but recommended
- JWKS Cooldown (ms) — min interval between JWKS fetches (default 60s)
- JWKS Fetch Timeout (ms) — network timeout (default 3s)

---

$3

- Require mTLS Header — expect proof from your proxy (e.g., x-ssl-client-verify: SUCCESS)
- Verify Header — default x-ssl-client-verify
- Subject Header — default x-ssl-client-dn
- Subject Allow Regex — optional (^CN=partner\.), fail-closed on bad regex

---

$3

- Audit Export — none or https
- Audit Endpoint URL — HTTPS receiver of compact JSON events
- Audit Bearer Token — optional Authorization: Bearer

🔐 Client Integration Scenarios

$3

Server:
- Create credentials hmacSharedSecretApi with your shared secret.
- Profile: Empfohlen (HMAC).
- Keep default timestamp/nonce headers unless you need custom names.

Client (Node.js, extended mode):
`js
import crypto from 'node:crypto';

const url = 'https://your-n8n.example/secure?foo=bar';
const body = JSON.stringify({ hello: 'world' });
const ts = Math.floor(Date.now()/1000).toString();
const nonce = crypto.randomUUID();
const algo = 'sha256';

// body hash
const bodyHash = crypto.createHash(algo).update(Buffer.from(body)).digest('hex');

// canonicalize query
const { URL } = await import('node:url');
const u = new URL(url);
const query = [...u.searchParams.entries()]
.sort(([a],[b]) => a.localeCompare(b))
.map(([k,v]) => ${encodeURIComponent(k)}=${encodeURIComponent(v)})
.join('&');

// base string
const base = ['POST', u.pathname, query, ts, nonce, bodyHash].join('\n');

// hmac
const signatureHex = crypto.createHmac(algo, process.env.WEBHOOK_SECRET).update(base).digest('hex');

const resp = await fetch(url, {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-timestamp': ts,
'x-nonce': nonce,
'x-signature': ${algo}=${signatureHex},
},
body,
});
console.log(resp.status, await resp.text());
`

curl (body mode):
`bash
TS=$(date +%s)
NONCE=$(uuidgen)
BODY='{"hello":"world"}'
SIG_HEX=$(printf %s "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary | xxd -p -c 256)

curl -X POST "https://your-n8n.example/secure" \
-H "content-type: application/json" \
-H "x-timestamp: $TS" \
-H "x-nonce: $NONCE" \
-H "x-signature: sha256=$SIG_HEX" \
--data "$BODY"
`

---

$3

#### Server:
- Create credentials jwtJwksApi with your JWKS URL.
- Profile: JWT (JWKS). Optionally set jwtIss/jwtAud.

#### Client:
`bash
curl -X POST "https://your-n8n.example/secure" \
-H "content-type: application/json" \
-H "authorization: Bearer $JWT" \
--data '{"ok":true}'
`

---

$3

Server:
- Create credentials apiKeyHeaderApi with:
- headerName: e.g., x-api-key
- value: your static secret
- Profile: Einfacher API Key.

#### Client:
`bash
curl -X POST "https://your-n8n.example/secure" \
-H "content-type: application/json" \
-H "x-api-key: YOUR_SECRET" \
--data '{"ok":true}'
`

---

$3

Server:
- Profile: Kombiniert.
- Configure HMAC and IP Allow/Deny CIDRs.

Client: Same as HMAC, but requests must originate from allowed networks.

---

$3

1. Set Previous Secret = current secret; deploy the node with a Dual-Key Window (e.g., 60 min).
2. Distribute the new secret to clients and switch their signing key.
3. After the window elapses and traffic is fully migrated, clear Previous Secret.

🧭 Reverse Proxy (mTLS Header) Example

Nginx:
`nginx
ssl_verify_client on; # request client cert
ssl_client_certificate /etc/nginx/ca_chain.pem;

location /secure {
proxy_pass http://n8n:5678/secure;
proxy_set_header x-ssl-client-verify $ssl_client_verify; # "SUCCESS" on pass
proxy_set_header x-ssl-client-dn $ssl_client_s_dn;
}
`

$3

Fields
- Rate Limit / Minute (per IP): max hits per 60s
- Redis aktivieren / URL / Namespace: shared state across nodes
- Returns 429 with Retry-After when exceeded

---

$3

- ✅ Valid Content-Type and within Max Body
- ✅ Include x-timestamp (10-digit seconds) within Max Skew
- ✅ Include x-nonce (unique per request)
- ✅ HMAC: correct signature (body/extended mode)
- ✅ JWT: valid token & reachable JWKS; iss/aud match if configured
- ✅ Rate limiting: send > rateMax/min to observe 429 + Retry-After
- ✅ IP policy behavior (allow/deny)
- ✅ (Optional) mTLS headers forwarding via proxy
- ✅ Observe x-request-id and audit events

---

$3

- 415 unsupported_content_type → Add client’s type to Allowed Content-Types
- 413 payload_too_large → Increase Max Body or shrink payload
- 401 bad_or_missing_timestamp → Ensure x-timestamp within Max Skew
- 401 replay_detected → Use a fresh x-nonce for every request
- 401 bad_signature / bad_signature_algo → Check algorithm/header and base string mode
- 401 invalid_token / missing_bearer → Send Authorization: Bearer ; verify IdP/JWKS
- 401 mtls_* → Confirm proxy sets verification headers
- 403 ip_denied / ip_not_allowed → Adjust IP Deny/Allow CIDRs
- 429 rate_limited → Decrease traffic, raise threshold, or enable Redis

---

$3

- Prefer HMAC extended mode for public endpoints.
- Keep Max Skew low (120–300s) and ensure NTP on all systems.
- Rotate HMAC secrets regularly; use Dual-Key Window during rollouts.
- For HA/Cluster, enable Redis (protect with TLS/network policy).
- Terminate TLS at the edge; add mTLS for partner integrations.
- Use precise CIDRs in IP allow lists (avoid wildcards).
- Log/trace with x-request-id end-to-end.

🙌 Contributing

PRs welcome!
`bash
npm ci
npm run build
``

Open a PR with what changed and how to test it.

📄 License

© 2025 prokodo.
Visit us at prokodo.com.