🕊️ Freebird rate limiting

For more information about Freebird, go here.

Freebird is an optional anonymous admission-control integration for new attestation jobs. It is not required for private local networks and it does not hide transport metadata.

Configure the gateway

For a public gateway, configure the verifier and require tokens:

export FREEBIRD_VERIFIER_URL=https://freebird-verifier.example.org
export FREEBIRD_REQUIRED=true
export FREEBIRD_CONSUME_TOKENS=true

Consuming mode sends { "token_b64": "..." } to Freebird's POST /v1/verify and rejects reuse. With FREEBIRD_CONSUME_TOKENS=false, Witness uses POST /v1/check; this checks possession without consuming the token and must be paired with another replay or rate-control boundary.

Pass a token from the CLI

Create a token file with the current verifier shape:

{"token_b64":"<base64url-freebird-token>"}

Then pass it to the supported attestation command:

witness attest --file document.pdf --freebird-token token.json

Polling an existing job and retrying a request for an existing canonical hash do not consume another token. New-job admission is the protected operation.

Caveats

Use HTTPS for the verifier and review issuer, expiry, audience, and scope policy there. FREEBIRD_ALLOW_INSECURE_LOCAL=true is for plaintext loopback smoke tests only and must not be used for a public gateway. Freebird reduces an admission linkability or abuse problem; it does not provide content confidentiality, transport anonymity, or Byzantine fault tolerance. See the full Freebird integration reference.