Revoker

Small Go service for revoking JWT tokens with KrakenD. To learn more about KrakenD's JWT revocation with bloom filters, check out their documentation.

Installation

Download Binary

Download the latest release from the Releases page.

# Example: Download for Linux amd64
curl -LO https://github.com/iustus-lab/go-revoker/releases/latest/download/revoker-linux-amd64
chmod +x revoker-linux-amd64
./revoker-linux-amd64

Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/iustus-lab/go-revoker:latest

# Or use a specific version
docker pull ghcr.io/iustus-lab/go-revoker:1.0.0

Building from Source

Local Build

# Development build
go build -o revoker .

# Production build with version
go build -ldflags "-X main.version=v1.0.0" -o revoker .

Docker Build

# Build with version
docker build --build-arg VERSION=v1.0.0 -t revoker:v1.0.0 .

# Build without version (defaults to "dev")
docker build -t revoker:latest .

Configuration

Revoker supports two discovery modes for finding bloom filter servers: static and dns.

Environment Variables

General

Variable	Required	Default	Description
PORT	No	8080	Port the server listens on
BLOOM_DISCOVERY	No	static	Discovery mode: static or dns

Static Discovery Mode

Variable	Required	Default	Description
BLOOM_SERVERS	Yes	-	Comma-separated list of bloom server addresses (e.g., server1:8020,server2:8020)

DNS Discovery Mode

Variable	Required	Default	Description
BLOOM_DNS_NAME	Yes	-	DNS name to lookup for bloom server IPs (e.g., krakend-gateway.internal)
BLOOM_DNS_PORT	No	8020	Port to connect to on discovered servers

Static Discovery Mode (Default)

For local development or when you have a fixed list of bloom servers:

# Single server
BLOOM_SERVERS=localhost:8020

# Multiple servers
BLOOM_SERVERS=server1:8020,server2:8020,server3:8020

DNS Discovery Mode

For dynamic environments where bloom servers are discovered via DNS (e.g., Fly.io, Kubernetes):

BLOOM_DISCOVERY=dns
BLOOM_DNS_NAME=krakend-gateway.internal
BLOOM_DNS_PORT=8020

In this mode, the service will:

• Perform DNS lookups on BLOOM_DNS_NAME to discover bloom server IPs
• Connect to all discovered addresses (both IPv4 and IPv6) on BLOOM_DNS_PORT
• Periodically refresh the server list every 5 minutes

Example: Fly.io

BLOOM_DISCOVERY=dns
BLOOM_DNS_NAME=krakend-gateway.internal

Example: Kubernetes

BLOOM_DISCOVERY=dns
BLOOM_DNS_NAME=krakend-bloom.default.svc.cluster.local

Extending Discovery

The discovery system is designed to be extensible. New discovery providers can be added by implementing the BloomServerDiscovery interface:

type BloomServerDiscovery interface {
    Discover() ([]string, error)
    SupportsRefresh() bool
}

Routes

The service maintains four (4) routes:

/ (GET)

The base route returns a 200 response to any GET request. This is a simple liveness check that also reports the application version.

Response:

{
  "status": 200,
  "message": "OK",
  "version": "v1.0.0"
}

/_health (GET)

The health route performs a deep health check by verifying connectivity to at least one bloom server. Also reports the application version when healthy.

Response (healthy):

{
  "status": 200,
  "message": "healthy",
  "version": "v1.0.0"
}

Response (unhealthy - no servers configured):

{
  "status": 503,
  "message": "no bloom servers available"
}

Response (unhealthy - servers unreachable):

{
  "status": 503,
  "message": "bloom servers unreachable"
}

/add (POST)

The add route is the primary service route, it allows you to add revocations to the bloom filter.

Payload:

{
  "key": "key",
  "subject": "subject"
}

key: Any JWT claim you've configured in your bloom filter config's token_key property (refer to the documentation for more details).

subject: The data associated to the key.

Response:

{
  "status": 201,
  "message": "Added"
}

/check (POST)

The check route allows you to check if a revocation exists in the bloom filter.

Payload:

{
  "key": "key",
  "subject": "subject"
}

key: Any JWT claim you've configured in your bloom filter config's token_key property (refer to the documentation for more details).

subject: The data associated to the key.

Response:

{
    "status": 200,
    "subject": "key-subject",
    "exists": true
}

Releasing

Releases are created by maintainers only, from the master branch.

Workflow:

1. Create a feature branch and make changes
2. Open a pull request to master
3. CI runs tests automatically on the PR
4. After review and merge, a maintainer tags the release:

git checkout master
git pull origin master
git tag v1.0.0
git push origin v1.0.0

This triggers the release workflow which:

• Verifies the tag is on master
• Runs tests
• Builds binaries for Linux and macOS (amd64 and arm64)
• Creates a GitHub Release with the binaries
• Builds and pushes Docker images to GitHub Container Registry