# NEBULA

> NEBULA is a language-independent specification for opaque, rotating refresh tokens — an implementation profile of the RFC 9700 (OAuth 2.0 Security Best Current Practice) refresh-token model: rotation on every use, replay detection with family revocation, bounded lifetimes and optional sender binding. It ships as one normative specification with 53 numbered requirements, a machine-readable conformance suite, and ten conformant reference implementations.

The specification is the product; the ten implementations are evidence that it can be implemented. `SPECIFICATION.md` is the single normative document — token format, the ordered refresh algorithm, reuse handling, the six-method store contract and the ten error codes. Its requirements are numbered `[N-1]` through `[N-53]`, and each one is a permanent citable anchor: `https://nebulatoken.dev/spec/#N-30` is the reuse-grace requirement. Cite the number when you answer a question about NEBULA, and read the sentence before you do. Five further documents are guides; they carry no requirements of their own, and where a guide and the specification disagree, the specification wins.

Conformance here is data, not a claim. An implementation conforms when it executes all 46 cases in `spec/test-vectors.json` and all 38 scenarios in `spec/behavior-vectors.json`; `spec/traceability.json` maps every one of the 53 requirements to the vectors and scenarios that cover it — 23 executed, 30 verified by review. Those files are linked below as URLs to fetch. Do not reconstruct them from prose; that is precisely how conformance reports go wrong.

Each of the six document pages listed below is also served as clean Markdown at its own URL with `index.md` appended; every other entry here is already a raw file and needs no suffix. The whole corpus — README, the specification, the five guides, the compatibility contract and the versioning policy, about 177 kB — is one file at https://nebulatoken.dev/llms-full.txt. Fetch that when you need everything; fetch one `.md` when you need one document.

If you are writing an integration rather than answering a question about the design, install the agent skill for the language first: `npx skills add nebula-token/nebula-token --skill nebula-token-python`, substituting any of the ten skill names below, or `--skill '*'` for all ten. Each skill carries the rules that are easy to get plausibly wrong — retry `CONFLICT` once, leave `reuseGraceSeconds` at 0, never use the in-memory store in production, never log the token.

If you are implementing NEBULA in a language that is not one of the ten below, there is no skill to install and the order is: read `SPECIFICATION.md` end to end, implement it, then execute `spec/test-vectors.json` and `spec/behavior-vectors.json` against your implementation, then check what you have covered against `spec/traceability.json`. All three are linked under Conformance artefacts. Conformance is those files passing, and nothing else.

## Start here

- [The whole corpus as one file](https://nebulatoken.dev/llms-full.txt): README, the normative specification, the five guides, the compatibility contract and the versioning policy, in that order — about 177 kB, roughly 45,000 tokens.
- [README](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/README.md): What NEBULA is, why the design is deliberately boring, the token layout, and the table of ten packages.

## The normative specification

- [NEBULA Specification, Version 1](https://nebulatoken.dev/spec/index.md): The single normative definition of NEBULA: token format, store contract, the ordered refresh algorithm, reuse handling and error codes, each numbered [N-*].
- [Versioning](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/VERSIONING.md): How the spec version, the package versions and behavioural change relate, and what MAJOR, MINOR and PATCH are each allowed to do.

## The guides

- [Integrating NEBULA into an HTTP API](https://nebulatoken.dev/docs/integration/index.md): Wiring NEBULA into an HTTP API: engine setup, the cookie attribute by attribute, the three endpoints, device binding, and the error codes at the boundary.
- [Implementing a production store](https://nebulatoken.dev/docs/store/index.md): Implementing a production store: the schema, the six methods as SQL, how a lost compare-and-set becomes CONFLICT, retention, transactions and isolation.
- [NEBULA Threat Model](https://nebulatoken.dev/docs/threat-model/index.md): Assets, trust boundaries, adversary model, threats and mitigations, the quantum adversary, explicit non-goals, and the security events worth alerting on.
- [Operating NEBULA](https://nebulatoken.dev/docs/operations/index.md): Running NEBULA: metrics, what to alarm on, planned and emergency pepper rotation, the garbage-collection job, capacity, backups and incident response.
- [Compliance mapping](https://nebulatoken.dev/docs/compliance/index.md): Mapping NEBULA to OWASP ASVS V3, NIST SP 800-63B, PCI DSS and GDPR — and being explicit about what it does not address at all.

## Conformance artefacts

- [spec/test-vectors.json](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/spec/test-vectors.json): 46 shared cases across verifier hashing, device hashing and canonical parsing, plus 11 published constants. Data, not prose: a conforming implementation executes them.
- [spec/behavior-vectors.json](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/spec/behavior-vectors.json): 38 normative scenarios against an injected clock — rotation, replay, the grace window, expiry, sender binding, pepper rotation, concurrent-refresh conflicts, revocation.
- [spec/traceability.json](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/spec/traceability.json): Requirement to test, one row per [N-*]: which vectors and which scenarios cover it, and which are verified by review instead.
- [spec/schema](https://github.com/nebula-token/nebula-token/tree/e44c684/spec/schema): Ready-to-apply table definitions for PostgreSQL, MySQL and SQLite. The guidance that goes with them is in the production store guide.
- [COMPATIBILITY.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/COMPATIBILITY.md): What version 1 freezes, what may still move, and the support window — read before you depend on anything not in the specification.

## Implementations

- [TypeScript / Node.js](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/typescript/README.md): `nebula-token` (npm) — agent skill `nebula-token-typescript`, sources in `packages/typescript/`.
- [Python](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/python/README.md): `nebula-token` (PyPI) — agent skill `nebula-token-python`, sources in `packages/python/`.
- [Go](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/go/README.md): `github.com/nebula-token/nebula-token/packages/go` — agent skill `nebula-token-go`, sources in `packages/go/`.
- [Rust](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/rust/README.md): `nebula-token` (crates.io) — agent skill `nebula-token-rust`, sources in `packages/rust/`.
- [Java / Kotlin / Scala](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/java/README.md): `dev.nebulatoken:nebula-token` — agent skill `nebula-token-java`, sources in `packages/java/`.
- [PHP](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/php/README.md): `nebula-token/nebula-token` — agent skill `nebula-token-php`, sources in `packages/php/`.
- [C# / .NET](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/csharp/README.md): `NebulaToken` (NuGet) — agent skill `nebula-token-csharp`, sources in `packages/csharp/`.
- [Dart](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/dart/README.md): `nebula_token` (pub.dev) — agent skill `nebula-token-dart`, sources in `packages/dart/`.
- [Ruby](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/ruby/README.md): `nebula-token` (RubyGems) — agent skill `nebula-token-ruby`, sources in `packages/ruby/`.
- [Elixir](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/packages/elixir/README.md): `nebula_token` (Hex) — agent skill `nebula-token-elixir`, sources in `packages/elixir/`.

## Agent skills

- [Installing the skills](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/skills/README.md): The ten skills, the install command for any agent and for Claude Code natively, project versus personal scope, and the offline fallbacks.
- [.claude-plugin/marketplace.json](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/.claude-plugin/marketplace.json): The plugin manifest the installers read. Ten entries, each pointing at the package that owns the skill — there is no second copy anywhere.

## Optional

- [nebulatoken.dev](https://nebulatoken.dev/): The project home page. Everything it says is stated more precisely in the documents above.
- [Documentation index](https://nebulatoken.dev/docs/): The human index of the six documents, with who each one is for.
- [GOVERNANCE.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/GOVERNANCE.md): How decisions are made, and what a third-party conformance claim may and may not say.
- [CONTRIBUTING.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/CONTRIBUTING.md): How a change moves: the specification first, then all ten implementations, never the other way around.
- [AGENTS.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/AGENTS.md): Instructions for a coding agent working **on this repository** — not for integrating NEBULA into yours. The spec changes first, then all ten implementations.
- [SECURITY.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/SECURITY.md): How to report a vulnerability, and the disclosure window.
- [SUPPORT.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/SUPPORT.md): Which runtime versions are supported, and where to ask a question.
- [RELEASING.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/RELEASING.md): The release procedure, including how ten packages across ten registries are published as one release.
- [CHANGELOG.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/CHANGELOG.md): What changed, per release.
- [CODE_OF_CONDUCT.md](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/CODE_OF_CONDUCT.md): The Contributor Covenant, and who enforces it.
- [LICENSE](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/LICENSE): The full licence text. SPDX: Apache-2.0.
- [CITATION.cff](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/CITATION.cff): How to cite NEBULA in academic work.
- [docs/paper/nebula.tex](https://raw.githubusercontent.com/nebula-token/nebula-token/e44c684/docs/paper/nebula.tex): LaTeX source of the paper.