dbsc-toolkit 2.9.1 → 2.9.3

package/README.md

@@ -7,18 +7,48 @@
 
 > **Stop stolen session cookies from being replayed on another device.**
 >
-> `dbsc-toolkit` implements W3C [Device Bound Session Credentials](https://www.w3.org/TR/dbsc/) on the server, and ships a Web Crypto polyfill so the same protection works on browsers that don't speak native DBSC yet. Native DBSC on Chromium 146+ Windows; the polyfill on every other browser. **One server, every browser, no user prompts.**
+> `dbsc-toolkit` implements W3C [Device Bound Session Credentials](https://www.w3.org/TR/dbsc/) on the server, and ships a Web Crypto polyfill so the same protection works on browsers that don't speak native DBSC yet. Native DBSC on Chromium 146+ (TPM / Secure Enclave); the polyfill on every other browser. **One server, every browser, no user prompts.**
 >
 > Works with **Express · Fastify · Hono · Next.js · Redis · PostgreSQL**.
 
+```ts
+// In your login route — one line to bind the session:
+app.post("/login", async (req, res) => {
+  await dbsc.bind(res, sessionId, { userId });
+  res.json({ ok: true });
+});
+
+// On any sensitive route — one guard:
+app.post("/payment", express.raw({ type: "*/*" }), requireProof(), paymentHandler);
+```
+
+That's it. The rest — key generation, protocol routes, cookie management, polyfill — is handled by the library.
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Live demo](#live-demo)
+- [Why dbsc-toolkit](#why-dbsc-toolkit)
+- [Comparison](#comparison)
+- [Why not JWT?](#why-not-just-use-jwt)
+- [How it works](#how-it-works-the-30-second-version)
+- [Who is this for?](#who-is-this-for)
+- [Adding to an existing app](#adding-to-an-existing-app)
+- [Protect your routes](#protect-your-routes)
+- [Production checklist](#production-checklist)
+- [API](#subpath-imports)
+- [Security model](#security-model)
+- [Going deeper](#going-deeper)
+
 ## Why dbsc-toolkit
 
 Native DBSC ships on Chrome 146+ for Windows users with a TPM. That's about a third of internet users. Every other DBSC implementation gives the rest of your users nothing — they remain on plain bearer cookies.
 
-This library is the **only** DBSC implementation that covers the other two-thirds via a Web Crypto polyfill. Same wire-level protection against cookie theft, same `requireProof()` guard server-side, key stored non-extractably in IndexedDB instead of a TPM. No biometric prompt, no user interaction, no checkbox.
+This library is among the first DBSC implementations to provide a Web Crypto fallback for browsers that don't support native DBSC. Same wire-level protection against cookie theft, same `requireProof()` guard server-side, key stored non-extractably in IndexedDB instead of a TPM. No biometric prompt, no user interaction, no checkbox.
 
-- ✅ **Native W3C DBSC** on Chromium 146+ (TPM / Secure Enclave / Android Keystore)
-- ✅ **Web Crypto polyfill** on Firefox, Safari, older Chromium — same protection, IndexedDB key
+- ✅ **Native W3C DBSC** on Chromium 146+ (TPM on Windows, Secure Enclave on macOS)
+- ✅ **Web Crypto polyfill** on Firefox, Safari, mobile, older Chromium — same protection, IndexedDB key
 - ✅ **Express, Fastify, Hono, Next.js** adapters — all four ship in one package
 - ✅ **Memory, Redis, Postgres** storage — pick one, swap with one line
 - ✅ **`requireProof()`** per-request signature guard — works on every browser, body-hash defended against MITM
@@ -110,42 +140,19 @@ The native-DBSC column refers to a server that uses the spec without a polyfill
 
 JWTs are still bearer tokens. Whoever has the bytes can replay them. Steal a JWT from a log line, an XSS, a leaked proxy header, a misconfigured intermediary — paste it into another machine and the server treats it as the legitimate user, exactly like a stolen cookie.
 
-DBSC pins the session to a cryptographic key that lives on the user's device (TPM, Secure Enclave, Android Keystore, or — under the polyfill — a non-extractable IndexedDB key). The token alone is no longer sufficient: the browser has to prove possession of the key on every refresh, and on every guarded request via `requireProof()`. The attacker's device has no key, so the replay fails and the session demotes within one cycle.
+DBSC pins the session to a cryptographic key that lives on the user's device (TPM on Windows, Secure Enclave on macOS, or — under the polyfill — a non-extractable IndexedDB key on every other browser). The token alone is no longer sufficient: the browser has to prove possession of the key on every refresh, and on every guarded request via `requireProof()`. The attacker's device has no key, so the replay fails and the session demotes within one cycle.
 
 DBSC complements your existing auth (passwords, MFA, JWT/session cookies) — it does not replace them. It closes the *replay-after-issue* gap that bearer tokens cannot.
 
 ## How it works (the 30-second version)
 
 ```
-  Browser                                              Server
-  ───────                                              ──────
-   │  POST /login (username, password)                    │
-   │ ───────────────────────────────────────────────────▶ │
-   │                                                      │ verify password
-   │  200 + Secure-Session-Registration header            │
-   │ ◀─────────────────────────────────────────────────── │
-   │                                                      │
-   │ generate keypair                                     │
-   │ (TPM / Secure Enclave / IndexedDB)                   │
-   │                                                      │
-   │  POST /dbsc/registration                             │
-   │  Secure-Session-Response: <JWS containing pub key>   │
-   │ ───────────────────────────────────────────────────▶ │
-   │                                                      │ verify self-signature
-   │                                                      │ store sessionId → pubkey
-   │  200 + __Host-dbsc-session cookie (Max-Age 10 min)   │
-   │ ◀─────────────────────────────────────────────────── │
-   │                                                      │
-   │  every ~10 min, browser hits /dbsc/refresh           │
-   │  signing a fresh server challenge with the key       │
-   │ ───────────────────────────────────────────────────▶ │
-   │                                                      │ verify signature
-   │                                                      │ reissue cookie
-   │  200 + fresh __Host-dbsc-session                     │
-   │ ◀─────────────────────────────────────────────────── │
+Login → Key Registration → Cookie Issued → Challenge → Signature Verification → Session Refresh
 ```
 
-A copy of `__Host-dbsc-session` pasted into another browser has no matching key — the next refresh fails, the session demotes to `tier: "none"`, and `requireProof()` 403s every guarded request immediately (not on the next refresh cycle). Full walk-through with the exact wire format: [HOW-IT-WORKS.md](./HOW-IT-WORKS.md).
+On login the server responds with a `Secure-Session-Registration` header. The browser generates an ECDSA keypair in the TPM (Chrome) or IndexedDB (Firefox/Safari/polyfill), POSTs the public key, and gets back a short-lived session cookie. Every ~10 minutes the browser re-signs a fresh server challenge to renew the cookie. A copy of the cookie pasted into another device has no key — the next refresh fails and `requireProof()` 403s every guarded request immediately.
+
+Full wire-format walk-through: [HOW-IT-WORKS.md](./HOW-IT-WORKS.md).
 
 ## Who is this for?
 
@@ -220,6 +227,16 @@ For apps with a stricter threat model (active MITM, log-spillage exposure), v2.8
 
 The full threat boundary, the per-framework wiring (Fastify / Hono / Next.js), and the migration timeline for an existing app are in [docs/integrating-existing-auth.md](./docs/integrating-existing-auth.md) and [docs/per-request-signing.md](./docs/per-request-signing.md).
 
+## Production checklist
+
+- [ ] HTTPS enabled — DBSC requires `Secure` cookies; plain HTTP locks every user to `tier: "none"`
+- [ ] Redis or PostgreSQL storage — `MemoryStorage` is lost on restart; bound browsers loop registration
+- [ ] `requireProof()` on every authenticated route — read-only public routes need no guard
+- [ ] `wrapFetch({ signBody: true })` on the client side for those routes (already the default in v2.8+)
+- [ ] Replay cache enabled — `replayCache: new RedisReplayCache(redis)` in `createDbsc({...})`
+- [ ] `trust proxy` already set — `install()` sets it, but verify if you have your own app config overriding it
+- [ ] Polyfill script loaded — the `<script type="module">` tag; without it Firefox/Safari stay on `tier: "none"`
+
 ## Subpath imports
 
 | Import | What it is |
@@ -240,7 +257,7 @@ Tree-shaking eliminates anything you don't import. Using Koa, Hapi, raw `http`,
 
 | Tier | Mechanism | Protects against |
 |------|-----------|------------------|
-| `dbsc` | Native W3C DBSC, key in TPM / Secure Enclave / Android Keystore | Cookie theft (XSS, network, logs, paste-to-other-browser) **and** infostealer malware reading the browser profile |
+| `dbsc` | Native W3C DBSC, key in TPM (Windows) or Secure Enclave (macOS) | Cookie theft (XSS, network, logs, paste-to-other-browser) **and** infostealer malware reading the browser profile |
 | `bound` | Web Crypto polyfill, non-extractable ECDSA P-256 key in IndexedDB | Cookie theft. Does not defeat infostealer malware on the user's machine. |
 | `none` | No active / fresh binding | Nothing the cookie itself doesn't already do |
 
@@ -251,6 +268,23 @@ Tree-shaking eliminates anything you don't import. Using Koa, Hapi, raw `http`,
 
 There is no third option, and **never gate a route on `tier === "dbsc"`** — that locks out every Firefox and Safari user (they can only reach `tier: "bound"`), and `requireProof()` already gives those browsers the same per-request guarantee via a signed proof. `requireProof()` is the one guard; it works on every browser. Read `res.locals.dbsc.tier` only if you want to *display* binding state in the UI — not to build a gate. Full guidance in [docs/security/best-practices.md](./docs/security/best-practices.md).
 
+## Security model
+
+`dbsc-toolkit` protects against:
+
+- Stolen session cookies replayed from another device
+- Stolen bearer tokens (same category — bearer == portable)
+- Cookie exfiltration via XSS, network capture, log leakage, or proxy leakage
+
+The Web Crypto polyfill (`tier: "bound"`) does **not** protect against:
+
+- Malware already running on the user's machine with access to the browser profile
+- Browser or OS compromise
+
+Native DBSC (`tier: "dbsc"`) provides stronger protection against local malware because the private key lives inside the TPM or Secure Enclave — software cannot extract it even with admin access. The polyfill key is non-extractable to JavaScript, but the encrypted blob lives on disk and a sufficiently privileged attacker can reach it.
+
+Neither tier is a substitute for HTTPS, input validation, strong passwords, or MFA.
+
 ## Going deeper
 
 - **Concepts and protocol:** [HOW-IT-WORKS.md](./HOW-IT-WORKS.md)
@@ -267,7 +301,7 @@ There is no third option, and **never gate a route on `tier === "dbsc"`** — th
 
 ## Status
 
-Verified end-to-end on Chrome 147 / Windows / TPM 2.0. Native DBSC supported on Chromium 145+ across Windows, macOS Apple Silicon, and Android. The bound polyfill works on every browser with Web Crypto + IndexedDB (Firefox, Safari, older Chromium). No third-party security audit yet. Production-readiness table and adoption guidance: [HOW-IT-WORKS.md#production-readiness](./HOW-IT-WORKS.md#production-readiness).
+Verified end-to-end on Chrome 147 / Windows / TPM 2.0. Native DBSC requires Chromium 145+ on Windows or macOS Apple Silicon. The bound polyfill works on every browser with Web Crypto + IndexedDB (Firefox, Safari, mobile browsers, older Chromium). No third-party security audit yet. Production-readiness table and adoption guidance: [HOW-IT-WORKS.md#production-readiness](./HOW-IT-WORKS.md#production-readiness).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbsc-toolkit",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "Server-side Device Bound Session Credentials (DBSC) for Node.js plus a Web Crypto polyfill for Firefox, Safari, and older Chromium. Cookie-theft protection on every modern browser.",
   "license": "Apache-2.0",
   "type": "module",