@defensestation/dpop
v0.1.0
Published
DPoP (RFC 9449) proofs for browsers and Node, for servers using go-dpop
Maintainers
Readme
js-dpop
DPoP (RFC 9449) proofs for browsers and Node, the client side of go-dpop. A client signs every request with a device key that never leaves it, so a stolen access token is useless without the device.
No runtime dependencies: it uses WebCrypto (crypto.subtle), available in
every browser and in Node 20+.
Keys
import { loadOrCreateKeyPair, thumbprint } from "@defensestation/dpop";
const keyPair = await loadOrCreateKeyPair(); // browser: kept in IndexedDB
const jkt = await thumbprint(keyPair.publicKey); // what tokens bind to (cnf.jkt)loadOrCreateKeyPair creates a non-extractable ES256 key on first use
and stores the CryptoKey itself in IndexedDB: script can sign with it but
can never read the private key, and every tab shares it. Pass { name } to
keep several keys apart, and call deleteKeyPair(name) on sign-out.
Trust this device
When sign-in asks whether to trust this device, pass the answer:
import { getKeyPair } from "@defensestation/dpop";
const keyPair = await getKeyPair({ remember: trustThisDevice });
// on sign-out: await deleteKeyPair();Either way the key is kept in IndexedDB, so the user stays signed in across reloads and tabs. The choice decides which key:
| remember | Key |
| --- | --- |
| true | the device's existing key, so the server recognizes the device by its thumbprint |
| false | a new key for this sign-in, replacing any kept one, so it is not linked to a known device |
How long the session lasts is the server's to enforce, as other sites do, for example:
| | Trusted | Not trusted | | --- | --- | --- | | MFA at the next sign-in | skipped for a device whose thumbprint it recorded | asked | | Access token | short, such as 5-15 minutes | the same | | Refresh token | months, such as 90 days idle, renewed with use | short, such as 12 hours, or an hour idle |
Long sessions are safe because the refresh token is bound to the key: a stolen one is useless without the device. The server should still revoke refresh tokens on sign-out everywhere or a password change, list trusted devices by thumbprint so users can remove one, and ask for the password again before sensitive changes.
Send the choice with the token request; the server records proof.Thumbprint
for a trusted device, and binds the refresh token to the key with
dpop.CheckBinding either way.
Outside a browser, or for a key that lives only in memory:
import { generateKeyPair } from "@defensestation/dpop";
const keyPair = await generateKeyPair(); // or generateKeyPair("ML-DSA-65")| Algorithm | Where | Proof size |
| --- | --- | --- |
| ES256 (default) | every browser, Node | ~500 bytes |
| ML-DSA-65 | Node 24.7+ only (no browser yet) | ~8 KB |
The server accepts ES256 alone unless it enables ML-DSA-65 with
dpop.WithAlgorithms; see go-dpop's README for the trade-offs.
fetch
import { createDpopFetch } from "@defensestation/dpop";
const dpopFetch = createDpopFetch({ keyPair, accessToken: () => tokens.current });
const response = await dpopFetch("https://api.example.com/invoices", { method: "POST", body });Every request gets a fresh proof for its method and URL (query and fragment
left out), bound to the token, and Authorization: DPoP <token>.
accessToken runs before each request and may be async; return undefined
for none, or omit it, as for a token request.
Connect (Connect-ES)
For a go-dpop server using dpopconnect.NewInterceptor:
import { createConnectTransport } from "@connectrpc/connect-web";
import { createDpopInterceptor } from "@defensestation/dpop";
const transport = createConnectTransport({
baseUrl: "https://api.example.com", // the server's dpop.Middleware BaseURL
interceptors: [createDpopInterceptor({ keyPair, accessToken: () => tokens.current })],
});A proof names baseUrl plus the procedure, as the server checks it, so
baseUrl must be the server's public URL (its BaseURL), not a proxy's
upstream. It signs unary and streaming calls, and works with the gRPC-Web
transport too.
Nonces and clocks
Both createDpopFetch and createDpopInterceptor keep, per server origin:
- its latest nonce: when the server uses nonces (
dpop.WithNonces), each response'sDPoP-Noncegoes into the proofs that follow; - its clock: a 401's
Dateheader shows how far this device's clock is off, and later proofs'iatis corrected by that much.
A request the DPoP check rejected is retried once, corrected: a
use_dpop_nonce 401 that brought a newer nonce, or an invalid_dpop_proof
401 whose Date shows the clock off by more than 10 seconds. A 401 with
another challenge, such as your token check's, is never resent; one with no
visible challenge (CORS not exposing it) is treated as the DPoP check's. A
Connect stream, or a fetch with a ReadableStream body, is not retried, but
what it teaches is kept.
The proof names the method exactly as the request sends it: fetch
uppercases only the standard methods, so write PATCH, not patch, as the
server's router most likely expects anyway.
Lower level
import { createProof, signHeaders } from "@defensestation/dpop";
const proof = await createProof(keyPair, { method: "POST", url, accessToken });
await signHeaders(headers, "POST", url, { keyPair, accessToken }, { nonce, clockOffset }); // sets DPoP and AuthorizationServer side
Browsers need the server's CORS policy to allow the DPoP and
Authorization request headers, and to expose the DPoP-Nonce,
WWW-Authenticate and Date response headers
(Access-Control-Expose-Headers); without them the client cannot learn
nonces or correct its clock. A rejected proof fails with a challenge such as
WWW-Authenticate: DPoP error="invalid_dpop_proof", algs="ES256". Its usual
cause, once the clock is corrected, is a baseUrl that names another host
or path than the server's BaseURL; scheme and host case and a default port
do not matter.
Development
npm install
npm run check # typecheck and tests (Node 23.6+ runs the TypeScript directly)
npm run build # dist/Publishing
.github/workflows/publish.yml publishes @defensestation/dpop to npmjs.org on pushes to
dev and main. It can also be run manually with either branch selected.
Other branches and pull requests do not publish.
- dev: publishes
<base-version>-dev.<run-number>.<attempt>under npm'sdevtag (for example,0.1.0-dev.42.1). Retries receive a new immutable version. - main: publishes the stable
package.jsonversion underlatest. Bumppackage.jsonandpackage-lock.jsonbefore each new stable release; npm refuses to replace an already published version.
The version is changed only in the runner's checkout. The workflow creates no commits, Git tags, or releases in GitHub. It installs locked dependencies, runs checks, and verifies the package. Provenance is enabled only when both the npm package and GitHub repository are public. Private repositories publish with provenance disabled.
Set the repository Actions variable NPM_ACCESS to public or restricted
(private). The workflow refuses to publish until visibility is explicitly set.
For the first publish, add an npm granular write token for this package as the
repository Actions secret NPM_TOKEN. Alternatively, once the npm package
exists, configure its trusted publisher for GitHub repository defensestation/js-dpop and
workflow filename publish.yml; then no publishing token is needed. The workflow
uses a GitHub-hosted runner with id-token: write for that OIDC flow. Repository
metadata must continue to match the GitHub repository for provenance.
No package is published by adding this workflow locally; publishing starts when
you push it to dev/main or run the action there.
