The NEBULA documents
One normative specification and five guides, rendered directly from the specification repository at e44c684. Nothing on these pages is transcribed by hand, so nothing on them can drift from the source — and where a page and the file it names disagree, the file wins.
- New to NEBULA
- Start with the specification — it is short, and every other document points back into it. Then the integration guide for the HTTP layer around it.
- Shipping it
- The bundled in-memory store is a test fixture. Production store is the six methods as SQL; Operations is what to measure and what to do when a token is stolen.
- Reviewing it
- The threat model states what is out of scope as plainly as what is in it. Compliance mapping is control by control, and is not a certification.
One of these documents is normative and five are not. The specification defines conformance: its 53 requirements are numbered [N-1]…[N-53], each one a permanent anchor you can cite (https://nebulatoken.dev/spec/#N-30). The five guides explain how to use it and carry no requirements of their own; where a guide and the specification disagree, the specification wins.
The normative specification
The one document an implementation is measured against.
The guides
Non-normative. Each answers one question the specification deliberately leaves alone.
Integration guide
The specification defines no transport — so what do the endpoints, the cookie and the error responses actually look like?
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.
- 1. The shape of the thing
- 2. Setting up the engine
- 3. The cookie, attribute by attribute
- 4. The three endpoints
- 5. Device binding, honestly
- 6. The ten error codes at the boundary
- +4 more
docs/INTEGRATION.mdProduction store
The bundled in-memory store is a test fixture — how do I write the real one?
Implementing a production store: the schema, the six methods as SQL, how a lost compare-and-set becomes CONFLICT, retention, transactions and isolation.
- 1. Schema
- 2. The six methods, as SQL
- 3. How a lost compare-and-set becomes CONFLICT
- 4. Retention: what you must not delete, and why
- 5. Transaction boundaries and isolation
- 6. Stores that are not read-after-write consistent
- +3 more
docs/STORE.mdThreat model
Which attacks does NEBULA stop, which does it not, and what risk is left with me?
Assets, trust boundaries, adversary model, threats and mitigations, the quantum adversary, explicit non-goals, and the security events worth alerting on.
- Assets
- Trust boundaries
- Adversary model
- Threats and mitigations
- Quantum adversary
- Explicit non-goals (residual risk for the adopter)
- +2 more
docs/THREAT_MODEL.mdOperations
It is deployed and it is correct — now what do I measure, alarm on, and do at 3am?
Running NEBULA: metrics, what to alarm on, planned and emergency pepper rotation, the garbage-collection job, capacity, backups and incident response.
- 1. Metrics to emit
- 2. What to alarm on
- 3. Pepper rotation
- 4. The garbage-collection job
- 5. Capacity and row growth
- 6. Backups, restores, and replica promotion
- +2 more
docs/OPERATIONS.mdCompliance mapping
Which ASVS and NIST SP 800-63B controls does this satisfy, and which stay mine?
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.
- 1. OWASP ASVS — V3 Session Management
- 2. NIST SP 800-63B — session management (§7)
- 3. PCI DSS
- 4. GDPR and data protection
- 5. What NEBULA does not address at all
- 6. Evidence you can hand an assessor
docs/COMPLIANCE.md
Conformance artefacts
Machine-readable, and the reason conformance is a fact rather than a claim. These are files rather than pages, so they link to the repository at 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
38 normative scenarios against an injected clock — rotation, replay, the grace window, expiry, sender binding, pepper rotation, concurrent-refresh conflicts, revocation.
- 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
Ready-to-apply table definitions for PostgreSQL, MySQL and SQLite. The guidance that goes with them is in the production store guide.
- COMPATIBILITY.md
What version 1 freezes, what may still move, and the support window — read before you depend on anything not in the specification.