Kong plugin - dynamo-gateway-kong
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
A Kong 3.x plugin (Lua, Apache-2.0) implementing the canonical Dynamo plugin contract: allowance credentials verify offline (JWS ES256K against pinned engine signers, recovered on OpenSSL bignums inside the gateway - no per-request network call), denials answer x402-shaped 402s byte-identical to litellm-dynamo, units meter from the response payload and tick to the engine asynchronously, and per-stream caps enforce inline from the local headroom cache. Missing, stale, or revoked-at-last-sync state DENIES - fail closed, never guess. Only canonical encodings verify: a credential with a non-canonical signature or base64url segment is refused.
The plugin is not published; mount it from a clone.
Two surfaces, one guard core
- Guard flow (unpriced routes): the credential rides
Authorization: Bearer; the canonical decision table gates the request; units meter from the response - declared token counts, bytes, or calls, payload-neutral.
- x402 seller flow (priced
resources): 402 challenges with per-request
nonces; X-PAYMENT payments verify offline (streaming allowance + exact receipts) with replay rejection, idempotent consume records, voucher monotonicity, exposure bounds, and finality-aware access. A stream whose metering the engine refused, or whose last sync is older than max_stale_seconds, is refused. An allowance payment is billed only when the upstream answers 2xx; any other answer bills nothing. The meter job is journaled before the serve, so a gateway that dies before the answer settles bills that one request when it restarts. An allowance payment for a stream the gateway has not synced yet (its first payment after a restart) is refused with headroom unknown: stream not yet synced (fail closed) and Retry-After: 1; the same refusal starts that stream's sync at once, off the request path. x402Fetch waits that second and pays once more. If the sync fails, the payment is still refused with the same reason. When the workers' shared lock stays busy for 0.5 seconds, or the full shared dict cannot record a reservation, a request on either flow is refused with headroom unknown: admission lock unavailable (…) (fail closed) or headroom unknown: in-flight units not recorded (…) (fail closed) and Retry-After: 1, with nothing reserved (see known limits). An exact payment the plugin refuses after verifying it, or whose upstream answers other than 2xx, stays redeemable: the same receipt is served once for that resource until it expires, then refused as a replay or as expired.
Every decision lives in kong/plugins/dynamo/core/* - byte-identical to the APISIX vendor copy, enforced by make audit-plugin-core. The handler only moves headers, bodies, and timers.
Config essentials
| Field | Default | Meaning |
|---|---|---|
engine_url | (required) | Engine wire endpoint - the ASYNC leg only (cap sync + meter flush), never the request path |
engine_signers | (required) | Pinned offline trust anchors: the engine signer address set |
max_stale_seconds | 30 | Cache entries older than this DENY (fail closed) |
sync_seconds | 5 | Cap-sync + meter-flush timer period |
units_per_request / units_per_prompt_token / units_per_completion_token / units_per_byte | 0/1/1/0 | Payload-neutral unit metering (digit-string integer math) |
reserved_units_per_response | - | Required on a route with a token price above 0: what one response that declares no usage is billed. The caller's estimate is never billed; the gateway refuses to load such a route without it |
pay_to, asset, resources[{path, price_units}] | - | The x402 seller surface; unpriced routes run the guard flow |
max_unsettled_exposure | - | Seller exposure bound (free pre-check) |
finality_threshold_units | - | Prices above this require a settled voucher frontier |
journal_dir | - | An existing directory, one per gateway node: every meter job is written and flushed there before it is queued; on start a job the engine never acknowledged is sent again under its original request reference and billed exactly once. A damaged journal refuses to open. Unset, meter jobs are held in memory only |
Money and units are decimal digit strings end to end, and the plugin is mode-agnostic by construction: Control Mode, stablecoin and credit card credentials verify identically. Real money is Release-gated.
Deployment shape
DB-less: mount the package's kong/ tree, then
KONG_DATABASE=off KONG_PLUGINS=bundled,dynamo
KONG_LUA_PACKAGE_PATH=/opt/dynamo/?.lua;;
with a declarative config carrying the plugin block. Tested images, each pinned by digest: kong:3.9, Kong Gateway 3.14 LTS and 3.16, and Kong AI Gateway 2.2 (DB-less). The operator path ships a compose-based example.
Verify
Docker is required.
cd "$DYNAMO_REPO"
pwd
make test-gateways # the core spec inside the PINNED kong:3.9 image
make test-gateways-journal # core + meter journal on Kong 3.9, 3.14 LTS, 3.16 and APISIX 3.11
make audit-plugin-core # core byte-identical across gateways
make conformance-kong # full x402 catalog vs a LIVE Kong container
make test-kong-aigw2 # the same plugin, unchanged, on Kong AI Gateway 2.2
make p17 # 10k-vector decision parity vs {reference, litellm, apisix}
Parity is doctrine, not aspiration: every gateway surface passes the identical conformance vector set - denial classes, ordering, and the 402 challenge schema never fork per gateway.