Rules at the edge.

Example: hide /admin from the world

curl -X PUT -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{"actions":[{"kind":"deny","path_prefix":"/admin"}]}' \
    https://login.21tunnel.com/api/tunnels/$TID/policy

What public requests see:

$ curl -i https://myapp.21tunnel.com/admin/users
HTTP/1.1 403 Forbidden
Content-Type: text/plain

forbidden by traffic policy

Prefix matching, not glob. /admin denies /admin, /admin/users, and /administrator. If you want stricter, use a more specific prefix (/admin/ with the trailing slash).

Why denies don't consume rate-limit budget

A path you explicitly denied is not "legitimate traffic" — it's noise. Counting it against the per-minute budget would mean an attacker hammering /admin could exhaust the budget and rate-limit your real users. The evaluator short-circuits deny before rate_limit so this can't happen.

Example: 60 / minute

curl -X PUT -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{"actions":[{"kind":"rate_limit","requests_per_minute":60}]}' \
    https://login.21tunnel.com/api/tunnels/$TID/policy

What public clients see at the cap:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: text/plain

rate limit exceeded by traffic policy

Per-tunnel, not per-IP

The bucket is keyed on tunnel ID. 60 / min means 60 requests across all public clients hitting that tunnel — not 60 per source IP. For per-IP rate-limiting inside your app, your own framework still has to do that work; the edge policy is for catching runaway scripts and obvious abuse.

Why fixed-window, not sliding

The window resets at the 60-second boundary. That means a burst of 2× the cap is possible right at the rollover (last request of window N + first of N+1 in < 1 ms). We chose fixed-window because:

• Trivially correct under concurrent access via CAS — no lock, no clock-coordination on the hot path.
• Smoother sliding-window is upgradeable later without a wire-format change.
• The burst-at-boundary case is essentially irrelevant for the rate-limit's purpose (catch a buggy script burning hundreds of requests per second).

Limits

• Max: requests_per_minute capped at 60,000 (≈ 1,000 req/s).
• Min: 1.
• At most one rate_limit action per policy.
• State is in-memory. If the tunnel server restarts, the bucket resets — accepted because the 60-second window is short.

jwt_validation — verify a bearer token at the edge

Requests without a valid Authorization: Bearer token get a 401 from us; your service never sees them. Optional issuer and audience allow-lists narrow it further. Expiry is always enforced.

Point it at your issuer's JWKS endpoint and key rotation takes care of itself — this is what you want with Auth0, Cognito, Firebase, or anything else that publishes a JWKS:

{
  "actions": [
    { "kind": "jwt_validation",
      "algorithm": "RS256",
      "jwks_url": "https://your-tenant.auth0.com/.well-known/jwks.json",
      "allowed_issuers":   ["https://your-tenant.auth0.com/"],
      "allowed_audiences": ["my-api"] }
  ]
}

Keys are fetched in the background and cached, never during your request. If your issuer is briefly unreachable the cached keys keep working for a grace period; once that expires requests are rejected rather than let through unverified. Add "jwks_cache_ttl_secs" (60–86400) to control how long keys are trusted before a refresh — a rotation is picked up within about half a minute of that expiring, and sooner if a token arrives signed by a key we have not seen.

A shared secret works too, and so does a pasted public key — though with the latter you have to paste it again on every rotation:

{ "kind": "jwt_validation",
  "algorithm": "HS256",
  "key": "your-shared-secret" }

Set exactly one of key or jwks_url. jwks_url must be https and requires "algorithm": "RS256" — a JWKS publishes public keys, so there is nothing for HS256 to fetch.

Read

curl -H "Authorization: Bearer $JWT" \
    https://login.21tunnel.com/api/tunnels/$TID/policy

{
  "id": "3a1b2c3d-...",
  "policy": {
    "actions": [
      { "kind": "deny", "path_prefix": "/admin" }
    ]
  }
}

Bad shapes return 400

Validation runs before persistence. Common errors:

HTTP/1.1 400 Bad Request

{ "error": "bad_policy",
  "message": "action[0] header_set: value must not contain CR or LF" }

Other rejected inputs: too many actions (max 16), bad rate-limit values, missing leading / on path_prefix, second rate_limit action.