OAuth token revocation (RFC 7009) #438

Merged
jcoffey-dev merged 1 commits from feat/oauth-revocation into main 2026-11-18 15:55:25 +00:00
Owner

Closes #427 (K-S4, part of inbuxa for Kubernetes). Webmail sign-out (inbuxa-webmail#104) calls this so a copied session cookie stops working.

What it does

  • POST /auth/revoke takes an access or refresh token. From then on it is refused on every node until it would have expired.
  • Both discovery documents list revocation_endpoint and revocation_endpoint_auth_methods_supported (none, client_secret_post, client_secret_basic).
  • A token issued to a client is revoked only by that client, with its secret if it has one. Naming no client stands for the token's own, as with a refresh. Another client gets 401 invalid_client.
  • A token that doesn't validate (expired, already revoked, garbage) gets 200, as the RFC asks. No token is 400 invalid_request; a live or RSVP token is 400 unsupported_token_type.

How

  • Each account keeps one list of revoked tokens in the in-memory store (KV_OAUTH_REVOKED, 202): token id (xxh3-128 of the token) and its expiry. The list's TTL is its longest-lived entry, and expired entries are dropped on every read.
  • The list is loaded with the account's cached access token, in build_access_token, so every way that cache is filled carries it. Validation already loads that entry for the credential-version check, so an access token costs no extra read.
  • Revoking rewrites the list under a per-account lock, then drops the account's access-token cache entry on every node through the existing cache-invalidation broadcast.
  • A refresh token is also checked against the store when it is redeemed. That covers a node that was rebuilding its cache entry while the revocation went in: it can't mint new access tokens from a revoked refresh token.
  • Cap: 2048 unexpired revocations per account (503 temporarily_unavailable past it). Filling it takes that many valid tokens of the account.

Not covered

  • Revoking a refresh token doesn't revoke the access tokens it already minted (nothing links them). A client revokes both; access tokens are short-lived.
  • An open WebSocket or EventSource keeps running until its own token-expiry check; that check is unchanged.

Tests

  • Unit: list parse/serialize, expiry, damaged lines, sorted ids.
  • system::system_tests (RocksDB) passes, including new OIDC steps: discovery lists the endpoint; four refused revocations (no secret, wrong secret, another client) leave the token working; a revoked access token can't sign in; revoking twice or a garbage token returns 200; no token returns 400; the refresh token still works after its access token is revoked; a revoked refresh token is refused (basic auth).
  • Local CI: fmt, cargo test --workspace --locked --no-run, cargo build -p inbuxa --locked, fork checks (notice added to the 2 upstream files touched).

docs/spec/contract.md: the "no revocation endpoint" note now says what 27.1 adds.

Closes #427 (K-S4, part of inbuxa for Kubernetes). Webmail sign-out (inbuxa-webmail#104) calls this so a copied session cookie stops working. **What it does** - `POST /auth/revoke` takes an access or refresh token. From then on it is refused on every node until it would have expired. - Both discovery documents list `revocation_endpoint` and `revocation_endpoint_auth_methods_supported` (none, client_secret_post, client_secret_basic). - A token issued to a client is revoked only by that client, with its secret if it has one. Naming no client stands for the token's own, as with a refresh. Another client gets `401 invalid_client`. - A token that doesn't validate (expired, already revoked, garbage) gets `200`, as the RFC asks. No token is `400 invalid_request`; a live or RSVP token is `400 unsupported_token_type`. **How** - Each account keeps one list of revoked tokens in the in-memory store (`KV_OAUTH_REVOKED`, 202): token id (xxh3-128 of the token) and its expiry. The list's TTL is its longest-lived entry, and expired entries are dropped on every read. - The list is loaded with the account's cached access token, in `build_access_token`, so every way that cache is filled carries it. Validation already loads that entry for the credential-version check, so an access token costs no extra read. - Revoking rewrites the list under a per-account lock, then drops the account's access-token cache entry on every node through the existing cache-invalidation broadcast. - A refresh token is also checked against the store when it is redeemed. That covers a node that was rebuilding its cache entry while the revocation went in: it can't mint new access tokens from a revoked refresh token. - Cap: 2048 unexpired revocations per account (`503 temporarily_unavailable` past it). Filling it takes that many valid tokens of the account. **Not covered** - Revoking a refresh token doesn't revoke the access tokens it already minted (nothing links them). A client revokes both; access tokens are short-lived. - An open WebSocket or EventSource keeps running until its own token-expiry check; that check is unchanged. **Tests** - Unit: list parse/serialize, expiry, damaged lines, sorted ids. - `system::system_tests` (RocksDB) passes, including new OIDC steps: discovery lists the endpoint; four refused revocations (no secret, wrong secret, another client) leave the token working; a revoked access token can't sign in; revoking twice or a garbage token returns 200; no token returns 400; the refresh token still works after its access token is revoked; a revoked refresh token is refused (basic auth). - Local CI: fmt, `cargo test --workspace --locked --no-run`, `cargo build -p inbuxa --locked`, fork checks (notice added to the 2 upstream files touched). `docs/spec/contract.md`: the "no revocation endpoint" note now says what 27.1 adds.
jcoffey-dev added this to the 27.1 milestone 2026-11-18 08:17:21 +00:00
jcoffey-dev added 1 commit 2026-11-18 08:17:21 +00:00
OAuth: revoke access and refresh tokens (RFC 7009)
ci / fork-checks (pull_request) Skipped
ci / build (pull_request) Skipped
github/ci (branch) GitHub Actions
ci / github (pull_request) Successful in 12m46s
71737d31e3
/auth/revoke takes an access or refresh token and refuses it from then
on, on every node, until it would have expired. Each account keeps a
list of revoked tokens in the in-memory store; the list is cached with
the account's access token, and a revocation drops that cache entry
cluster-wide. A refresh token is also checked against the store when
redeemed. A token issued to a client is revoked only by that client,
with its secret if it has one; one that doesn't validate is answered
200 as the RFC asks. Both discovery documents list revocation_endpoint.

Closes #427
jcoffey-dev merged commit e3c491224b into main 2026-11-18 15:55:25 +00:00
jcoffey-dev deleted branch feat/oauth-revocation 2026-11-18 15:55:25 +00:00
Sign in to join this conversation.