🔒 URL Verifier + Form Gate

Secure URL generation with Turnstile + fingerprinting + ban checks, plus a session-gated /form/* proxy.

Behavior for banned users: they can complete Turnstile but will remain stuck in a “Performing additional security checks…” loop.

Environment

URL_METADATA KV (required)
BANNED_LIST KV (required)
FORM_DATA KV (optional)
API_KEY, ADMIN_API_KEY (required)
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY (required)
ORIGIN_BASE (required) — e.g. https://chat.example.com
FINGERPRINT_PUBLIC_KEY (optional)
ALLOWED_ORIGINS (optional) — affects API endpoints only
FORM_REQUIRE_SESSION (optional) default true
FORM_SESSION_TTL_SECONDS (optional) default 600
FORM_SESSION_BIND_IP (optional) default true

Endpoints

POST /generate

Create a secure URL /r/:token. Usually set destinationUrl to your worker’s /form/... path.

Headers:
  X-API-Key: <API_KEY>
  Content-Type: application/json

Body:
{
  "userId": "user123",
  "destinationUrl": "https://YOUR_WORKER_DOMAIN/form/register",
  "expiresIn": 300,
  "oneTimeUse": false
}

GET /r/:token

Turnstile challenge page. On success calls POST /verify.

POST /verify

Validates Turnstile, checks bans, mints sess and returns destination URL (with sess appended).

/form/*

Session-gated proxy. Requires ?sess=... by default; banned users never reach origin.

Admin API

POST /api/ban

Headers:
  X-API-Key: <ADMIN_API_KEY>
  Content-Type: application/json

Body:
{
  "type": "ip|user|visitor",
  "value": "1.2.3.4",
  "reason": "Suspicious activity"
}

POST /api/unban

Headers:
  X-API-Key: <ADMIN_API_KEY>
  Content-Type: application/json

Body:
{
  "type": "ip|user|visitor",
  "value": "1.2.3.4"
}

GET /api/bans

Headers:
  X-API-Key: <ADMIN_API_KEY>

Optional:
  /api/bans?type=ip
  /api/bans?type=ip&id=1.2.3.4

GET /api/metrics

Headers:
  X-API-Key: <ADMIN_API_KEY>

Optional:
  /api/metrics?type=success

GET /api/link-status

Headers:
  X-API-Key: <ADMIN_API_KEY>

Query:
  /api/link-status?token=abc123

Notes

For Rocket.Chat registration, set ORIGIN_BASE to the Rocket.Chat origin and point destinationUrl to /form/<registration-path>.
Keep FORM_REQUIRE_SESSION enabled unless you explicitly want /form/* to be publicly accessible.