Presence plugin for Kong Gateway

kong-plugin-presence — CAPTCHA replacement and human presence verification at the API gateway. Gate sensitive routes on a verified Presence session by config rule; no application code changes.

Applications send intent and context. Presence verifies the person. Decionis decides whether execution proceeds.

The plugin is a thin Kong (Lua/OpenResty) adapter of the language-neutral Presence enforcement contract: Kong extracts request context, delegates every decision to the Presence API, and enforces the returned disposition. The rich logic lives remotely; the gateway stays thin and fails closed.

luarocks install kong-plugin-presence

Add presence to Kong's plugins directive (plugins = bundled,presence) and enable it on a service or route:

# Declarative (decK / kong.yml) — gate a checkout route:
plugins:
  - name: presence
    route: checkout-route
    config:
      api_host: https://presence.decionis.com
      api_secret: "{vault://env/presence-api-secret}"
      tenant_id: tn_your_tenant_id # from presence.decionis.com → Developers
      protected_routes: /api/v1/checkout/*

Flow B checks one thing before the token gate: an X-Presence-Proof header carrying a short-lived ES256 enforcement proof. A proof that passes every check — well-formed JWT, ES256, valid claims for this tenant_id, unexpired, and a signature verified against the enforcement JWKS at /.well-known/presence-proof-jwks.json on api_host — forwards upstream as VERIFIED with no /v1/verify round-trip and no token required.

The proof can only speed up a pass, never create one: every failure — malformed header, wrong algorithm, bad claims, unreachable or unparseable JWKS, signature mismatch — falls through to the token gate, which fails closed on its own. Omit the header and behaviour is exactly the documented token flow.

• Verdict verification is cache-first via kong.cache (cluster-aware): a hit resolves without an API call; a miss calls POST /v1/verify under verify_timeout_ms.
• The proof fast path is fail-closed in the same sense: a proof that cannot be fully verified is discarded and the request still has to satisfy the token gate.
• Any verification failure or timeout caches nothing and the gate fails closed (503); missing, invalid, or high-risk tokens are rejected (403).
• Cache keys are the SHA-256 digest of the token — raw tokens never become cache keys; negative verdicts are cached too.
• Risk thresholds (0.75 block / 0.5 challenge) match the Presence API's risk model, so the gateway and the API band identically.
• The tenant credential is referenceable config (use a {vault://…} reference); it is sent only to the Presence API and never reaches the browser.

The plugin is small on purpose — auditable in one sitting:

Requires luacheck + busted on PATH (eval "$(luarocks path --bin)"); the integration suite additionally requires Kong's pongo and a running Docker daemon.

make lint              # luacheck across kong/ and spec/
make test              # busted — pure route-matching + HTML/threshold helpers
make test-integration  # pongo — loads the plugin in a real Kong and gates a route

make lint and make test run without Kong. The integration suite boots a real Kong via pongo and asserts the token-missing gate (403 PRESENCE_TOKEN_MISSING) and untouched pass-through; the mint/verify happy path runs against a mock standing in for the Presence API.

This release ships the CAPTCHA-replacement core: the verify gate (Flow B), session mint (Flow C), and optional widget injection (Flow A). Adaptive step-up relays and additional gateways are planned follow-ons.

• GitHub Issues
• presence.decionis.com/developers/kong
• Security reports: security.txt

Apache-2.0. Use of the hosted Presence service is governed separately.