The refresh token,
finally specified.

When to use NEBULA — and when not to

Use NEBULA when you build first-party authentication in your own backend and want refresh-token handling that matches what managed identity providers do internally: no per-user pricing, no vendor lock-in, session data in your own database (relevant for GDPR / data residency), identical behavior across every language in your stack.

Do not use NEBULA when: you already run a managed IdP (Auth0, Okta, Cognito — use its built-in rotation); you need full OAuth 2.0 / OIDC with third-party clients, scopes, and consent screens (you need an authorization server such as Keycloak or Ory, not a token library); you operate under FAPI 2.0 / open-banking requirements (you additionally need cryptographic sender-constraining — DPoP or mTLS — at the protocol layer; NEBULA's device binding is application-level); or your stack is a single language and its authorization-server framework already does this (OpenIddict, Spring Authorization Server, Fosite, Authlib — each is better integrated with its ecosystem than NEBULA will ever be, and the ten-language conformance guarantee is worth nothing to you).

FAQ

Why does it need a database? Because instant revocation and reuse detection require server-side state — a stateless token cannot be revoked before it expires, which is exactly why RFC 9700 moved the industry away from stateless refresh tokens. NEBULA doesn't pick your database: it defines a six-method contract you implement over whatever you already run. Cost: one indexed lookup per refresh.

Why not a JWT as refresh token? A JWT proves who signed it, but cannot be un-signed: revocation requires a server-side denylist — at which point you have a database anyway, plus a signature scheme you no longer need. Claims belong in the short-lived access token; the refresh token is a credential, not an envelope.

Why not self-host Ory, Keycloak or Supabase Auth? If you need what those are — an identity provider that owns login, consent and the OAuth 2.0 protocol surface — run one, and take its rotation with it. The question only gets interesting when the refresh-token mechanism is all you need. Those engines are multi-language in the sense that any language can call their HTTP API: there is one implementation, behind a network hop, that you deploy, patch, monitor and keep available, and it wants to own your user table. NEBULA is multi-language in a different sense — ten in-process implementations that agree byte-for-byte, pinned by shared vectors. A refresh is an HMAC and one compare-and-set write against the database you already run: no service in the path, nothing extra that can be down, and session data that stays in your own schema. What NEBULA competes with is not an identity provider; it is the rotation logic you would otherwise write by hand — where the usual defect is the concurrent refresh: two parallel requests presenting the same token both observe it as active, both mint a successor, and the family forks into two independently valid lineages — which defeats reuse detection entirely. That is not an exotic race; it is a mobile client retrying, or two browser tabs refreshing together. Here it is a compare-and-set with a specified losing branch ([N-34] step 5, returning a retryable CONFLICT per [N-35]) rather than something left to the reader.

What is genuinely new here? Not the cryptography — deliberately. What did not exist before is a precise, testable, language-independent specification of the RFC 9700 rotation model: exact check order, exact reuse/grace semantics, shared conformance vectors, and ten implementations held to them by one executable suite rather than by ten hand-written ones.

Maturity, stated plainly

A library on an authentication path should tell you what it has and has not been through. NEBULA's position, as of 1.0.0:

• No independent security audit. None has been performed. SECURITY.md keeps the full list of what is missing — no formal verification of the rotation state machine, no fuzzing beyond the published vectors.
• No production track record. These implementations are new. Nobody can yet tell you how they behave at scale, because nobody has run them at scale.
• What is real is the conformance. Behaviour is not asserted in prose and hoped for in code: it is pinned by 46 test vectors and 38 executable behavioural scenarios that every implementation runs on every CI run, in all ten languages, with a runner that must assert the published case counts and fail on an empty section ([N-48]). Two implementations that pass agree at every point those artefacts observe: the accept/reject decision for the token strings the parsing vectors cover, the byte-level output of both keyed hashes, and — per scenario — the outcome code, the generation, the family and expiry relations, and the resulting multiset of record statuses in the store. That is a bounded claim rather than a universal one, and it is deliberately the one this project makes: the vectors do not observe timing, log output or store call ordering, and no differential harness yet drives all ten from one random transcript. It is also checkable — checkable by you, not just by our CI: node scripts/docker-test.mjs runs all ten suites in official images pinned by digest at the declared version floors, with nothing installed but Docker (docker/README.md).
• The surface is small on purpose. Each implementation is one small, dependency-free module meant to be read in a sitting. The most useful thing you can do before adopting it is read it.

What is frozen and what may still move is spelled out in COMPATIBILITY.md; how a third-party port may claim conformance ([N-53]) is in GOVERNANCE.md.