@shelbyb/daywalker-sdk 0.6.0 → 0.8.0

package/README.md

@@ -15,11 +15,13 @@ Runs on **Node.js 20.19+**, **Bun**, **Deno**, **Cloudflare Workers**, **Next.js
 - **Web Standards Core**: standard `crypto.subtle`, `Uint8Array`, `fetch`, `Request`, and `Response`. The one runtime dependency is [`re2js`](https://www.npmjs.com/package/re2js), so flag regex rules run in linear time.
 - **RFC 9421 (HTTP Message Signatures)**: Cryptographically binds `@method`, `@path`, `@query` (when the URL has one), `@authority`, and `content-digest` (POST/PUT/PATCH and any request with a body) using Ed25519 signatures (`Signature-Input`, `Signature`).
 - **RFC 9530 (Digest Fields)**: Computes standard `Content-Digest: sha-256=:<base64>:` headers for payload integrity.
+- **OAuth 2.0 Client Credentials**: Calls to Daywalker Auth carry a short-lived, DPoP-bound (RFC 9449) access token from `POST /api/v1/oauth/token`, refreshed automatically with rotating refresh tokens. The API key is only the client credential for that grant and is never sent anywhere else.
 - **Class-Based Client Architecture**: Instantiable `Daywalker` client supporting dependency injection, with a lazy default singleton for plug-and-play simplicity.
-- **Resilience & Rate Limiting**: 5s per-attempt timeout, exponential backoff with jitter, `Retry-After` honored up to 60s. Network errors are retried only for idempotent requests (or with an `idempotencyKey`), and redirects are never followed, so the API key can't leak to another host.
+- **Resilience & Rate Limiting**: 5s per-attempt timeout, exponential backoff with jitter, `Retry-After` honored up to 60s. Network errors are retried only for idempotent requests (or with an `idempotencyKey`), and redirects are never followed, so credentials and access tokens can't leak to another host.
 - **Deterministic Type-Safe Results**: Discriminated union returns (`Result<T, E>`) for clean handling without try/catch boilerplate.
 - **Security-Hardened Next.js Middleware**: Built-in Server Action probe mitigation (CVE-2025-55182 defense), normalized paths (no `%2e%2e` / `//` bypasses), open-redirect-safe error routing, and fail-closed validation (503 when Daywalker is unreachable).
-- **Zero-Egress Inbound Verification**: In-memory caching (60–300s TTL) and offline JWT token lease validation using Daywalker's asymmetric public key.
+- **Zero-Egress Inbound Verification**: In-memory caching (60s by default, never more than 300s) and offline verification of Daywalker access tokens, including the DPoP proof of sender-constrained tokens.
+- **Tamper-Resistant by Design**: client state lives in true private fields, config and prototypes are frozen, WebCrypto is captured at load, and every input is bounded and validated. See [Security model](#security-model).
 - **Decoupled Push Architecture CLI**: `npx daywalker init --json` registers keys directly via `POST /api/v1/keys/register` with zero runtime reverse-HTTP calls.
 
 ---
@@ -55,21 +57,97 @@ DAYWALKER_API_KEY=srv_live_... npx daywalker init --service my-service-slug --do
 
 The private key is never printed unless you pass `--print-key`.
 
+### Or: ephemeral keys (nothing stored anywhere)
+
+With `ephemeralKey`, each process generates its signing key in memory as a **non-extractable** key. It registers that key with a lifetime and replaces it in place before it expires. There's no private key in env vars, files or a store, and nothing to rotate by hand:
+
+```ts
+const client = new Daywalker({
+  ephemeralKey: { ttlSeconds: 21_600, instanceId: process.env.HOSTNAME }, // or DAYWALKER_EPHEMERAL_KEY=true
+});
+process.on("SIGTERM", async () => {
+  await client.close(); // revokes the key (and the OAuth sessions it started)
+  process.exit(0);
+});
+```
+
+- **Lifetime** (`ttlSeconds`, env `DAYWALKER_KEY_TTL_SECONDS`): 1 hour to 30 days, default 6 hours. When a quarter of it is left, a new key is registered in the same slot. Requests keep using the old key until the new one is ready, and Daywalker keeps the old key valid for 10 more minutes. The next OAuth session starts with the new key.
+- **Slot** (`instanceId`, env `DAYWALKER_INSTANCE_ID`): one key per (domain, slot). Registering in an occupied slot retires the previous key. Default: a random slot per process.
+- **Limit:** Daywalker allows 20 live keys per domain. Give long-lived instances a stable `instanceId` so a restart replaces its own key, call `close()` on shutdown, and use a shared `keyStore` instead on serverless platforms with many short-lived instances. When the domain is full, the error says so: list keys with `npx daywalker keys` and revoke unused ones with `npx daywalker revoke <keyId>`.
+
+### Or: provision the key automatically
+
+Instead of running `init` and copying `DAYWALKER_SIGNING_KEY` into every environment, give the client a **key store**. On first use it loads the key from the store, or generates one, registers it for the service's domain (`POST /api/v1/keys/register`, with `DAYWALKER_API_KEY`) and saves it:
+
+```ts
+import { Daywalker } from "@shelbyb/daywalker-sdk";
+import { fileKeyStore } from "@shelbyb/daywalker-sdk/keystore/file";
+
+const client = new Daywalker({
+  keyStore: fileKeyStore(), // .daywalker/signing-key.json (0600, in a 0700 directory)
+});
+await client.provisionSigningKey(); // optional: provision at startup and fail fast, instead of on the first request
+```
+
+All you need is `DAYWALKER_API_KEY` and a domain. The domain is detected from `VERCEL_PROJECT_PRODUCTION_URL`, `RAILWAY_PUBLIC_DOMAIN`, `RENDER_EXTERNAL_HOSTNAME`, `APP_URL` and similar; set `DAYWALKER_DOMAIN` elsewhere.
+
+| Store | Import | Use it for |
+|---|---|---|
+| `fileKeyStore({ path? })` | `@shelbyb/daywalker-sdk/keystore/file` | VMs and containers with a persistent volume (Node.js). Atomic create-if-absent; refuses symlinks and files others can read |
+| `memoryKeyStore()` | `@shelbyb/daywalker-sdk/keystore` | Tests and single long-lived processes: every new process registers a new key |
+| `envKeyStore(env?)` | `@shelbyb/daywalker-sdk/keystore` | Read-only: the key `daywalker init` wrote to the environment |
+| your own | — | Serverless and several instances: any shared store with an atomic create-if-absent (Redis `SET key value NX`, Vercel / Cloudflare KV, a secrets manager) |
+
+A store is `{ load(), saveIfAbsent?(record) }`. `saveIfAbsent` must be atomic: when several instances start at once, exactly one save wins and the others load the winner's key. Each of them may already have registered its own key; the losers revoke theirs right away (`DELETE /api/v1/keys/{keyId}`). Stored keys don't expire; every key the SDK registers gets its own slot (`dw-<keyId>`), so registering one never retires a key another deployment is still using.
+
+```ts
+const redisKeyStore = (redis) => ({
+  load: async () => JSON.parse((await redis.get("daywalker:signing-key")) ?? "null"),
+  saveIfAbsent: async (record) => (await redis.set("daywalker:signing-key", JSON.stringify(record), { NX: true })) === "OK",
+});
+```
+
+Safeguards:
+- Only keys this process generated **and registered** are ever saved, so a key planted in the store is never registered with your API key.
+- A stored key is checked against its `keyId` (RFC 7638 thumbprint) and domain on every load, and imported non-extractable.
+- `selfCheck()` / `npx daywalker check --offline` only read the store; they never provision.
+
+Treat the store like any secret: it holds the private key. `DAYWALKER_SIGNING_KEY` and `signer` take precedence over `keyStore`.
+
+### Or: keep the key in a KMS (no private key in the app at all)
+
+Pass a `signer` and the SDK never sees the private key. Every RFC 9421 signature is made by your KMS or HSM. `sign` receives the signature base and must return the raw 64-byte Ed25519 signature:
+
+```ts
+const client = new Daywalker({
+  signer: {
+    keyId: "kms-ed25519-2026-10", // the id you registered the key under
+    publicJwk,                    // optional but recommended: the SDK checks the signer against it once before any request
+    sign: async (data) => yourKms.signEd25519(KMS_KEY_ID, data), // must resolve to the raw 64-byte signature (Uint8Array)
+  },
+});
+```
+
+Your KMS must support Ed25519 (pure EdDSA over the message, not a pre-hashed variant). Register the KMS public key once with `registerPublicKey({ apiKey, domain, publicJwk })`. The signer is captured at construction, so changing the object later has no effect.
+
 ---
 
 ## Environment
 
 | Variable | Required | Purpose |
 |---|---|---|
-| `DAYWALKER_API_KEY` | ✅ | The service's Daywalker API token (`srv_live_…`) or access token |
+| `DAYWALKER_API_KEY` | ✅ | The service's OAuth client credential (`srv_live_…`). It is sent only to `POST /api/v1/oauth/token` (client credentials grant, together with the signing key) and to `POST /api/v1/keys/register` by `daywalker init` / `rotate`. Every other call uses an access token. See [Authentication](#authentication-oauth-20-client-credentials) |
 | `DAYWALKER_SERVICE_SLUG` | ✅ | The service slug to validate against (e.g. `sonalyze`). One API key can cover several services: a comma-separated list (`gigpulse,devpulse`) is accepted and the first is the default. See [One API key, several services](#one-api-key-several-services) |
-| `DAYWALKER_SIGNING_KEY` | for signed requests | Ed25519 private key from `daywalker init` (PKCS#8 Base64 DER or PEM) |
+| `DAYWALKER_SIGNING_KEY` | for signed requests | Ed25519 private key from `daywalker init` (PKCS#8 Base64 DER or PEM). Not needed with a `keyStore` (auto-provisioning) or a `signer` (KMS); see [Setup](#setup-once-per-service) |
 | `DAYWALKER_KEY_ID` | optional | RFC 7638 JWK thumbprint derived during key generation |
 | `DAYWALKER_SIGNING_KEY_PREVIOUS` | during rotation | Previous private key, maintained during deployment transitions |
-| `DAYWALKER_DOMAIN` | optional | Optional caller identifier or host domain name |
+| `DAYWALKER_DOMAIN` | when not detected | The service's public domain: the key is registered for it. Detected from your platform's URL variables when unset |
+| `DAYWALKER_EPHEMERAL_KEY` | optional | `true` for [ephemeral signing keys](#or-ephemeral-keys-nothing-stored-anywhere), with `DAYWALKER_KEY_TTL_SECONDS` and `DAYWALKER_INSTANCE_ID` |
 | `DAYWALKER_PUBLIC_KEY` | optional | Daywalker Auth public key for zero-egress offline JWT lease verification |
+| `DAYWALKER_JWKS` | optional | `auto` verifies access tokens offline against Daywalker's JWKS, fetched from `${DAYWALKER_AUTH_URL}/.well-known/jwks.json` and cached, so signing-key rotation needs no redeploy. Default `off`. See [Zero-Egress Offline Verification](#zero-egress-offline-verification) |
 | `DAYWALKER_AUTH_URL` | optional | Defaults to `https://auth.daywalker.dev`; must be `https://` (except localhost) |
 | `DAYWALKER_LEASE_ISSUER` | optional | Expected `iss` of offline-verified JWTs (default `https://auth.daywalker.dev`) |
+| `DAYWALKER_PUBLIC_ORIGIN` | behind a proxy | The origin clients use to reach this service (e.g. `https://api.example.com`), for checking DPoP proofs. Defaults to the request URL's origin |
 
 ---
 
@@ -90,7 +168,7 @@ const client = new Daywalker({
 
 // Option 2: Default lazy singleton (reads process.env automatically)
 const result = await daywalker.validateToken(incomingToken);
-// Service health check of this service's own DAYWALKER_API_KEY: daywalker.validateServiceKey()
+// Service health check of this service's own OAuth client credentials: daywalker.validateServiceCredentials()
 
 if (result.ok) {
   console.log("Validated tenant:", result.data.tenantId);
@@ -101,6 +179,28 @@ if (result.ok) {
 }
 ```
 
+### Authentication (OAuth 2.0 Client Credentials)
+
+The SDK authenticates to Daywalker Auth with the OAuth 2.0 client credentials grant ([RFC 6749 §4.4](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)) described in the [Daywalker API docs](https://auth.daywalker.dev/docs). You don't call it yourself: the first request that needs it runs the flow.
+
+1. **Client credentials grant.** `POST /api/v1/oauth/token` with `grant_type=client_credentials`, authenticated by the API key (`Authorization: Bearer srv_live_…`) **and** an RFC 9421 signature from the registered Ed25519 signing key, from an allowlisted domain or IP. This is the only request that carries the API key.
+2. **DPoP-bound tokens.** Every token request carries a DPoP proof ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) from a key the client generates in memory. Daywalker answers with `token_type: "DPoP"`: a 5 to 15 minute EdDSA access token bound to that key (`cnf.jkt`), plus a single-use refresh token (30 day session).
+3. **Calls use the access token.** `validateToken()` and `client.fetch()` send `Authorization: DPoP <access_token>` plus a fresh DPoP proof with `ath` (bearer or unbound tokens are refused with `401 DPOP_REQUIRED`).
+4. **Refresh.** Within 30 seconds of expiry, or on `401 ACCESS_TOKEN_EXPIRED` (retried once), the client trades the refresh token for a new pair (`grant_type=refresh_token`, no API key, same DPoP key). When the session has ended (`invalid_grant`), it runs the client credentials grant again.
+
+```ts
+const client = new Daywalker({
+  apiKey: process.env.DAYWALKER_API_KEY,          // client credential, used only at the token endpoint
+  signingKey: process.env.DAYWALKER_SIGNING_KEY,  // signs the grant (RFC 9421)
+});
+
+await client.validateToken(incomingToken);   // Authorization: DPoP <access token>, obtained on demand
+await client.accessToken();                  // the current access token, refreshed as needed
+await client.validateServiceCredentials();   // health check: can this service still get a token for its service?
+```
+
+If the grant itself fails (revoked API key, unregistered signing key, allowlist mismatch), `validateToken()` returns `503 SERVICE_UNAVAILABLE` with the token endpoint's code in the message, never a `401` for the caller's token; a missing `DAYWALKER_API_KEY` is `500 CONFIGURATION_ERROR`.
+
 ### Type-Safe Verification & Error Handling
 
 ```ts
@@ -120,11 +220,11 @@ try {
 ### RFC 9421 Signed Requests with Automatic Backoff
 
 ```ts
-// Outbound request automatically computes Content-Digest (RFC 9530)
-// and attaches RFC 9421 signature headers. Retries 429 rate limits automatically.
+// Outbound request automatically adds `Authorization: DPoP <access token>` with a DPoP proof,
+// computes Content-Digest (RFC 9530) and attaches RFC 9421 signature headers. Retries 429 rate limits automatically.
 const res = await client.fetch("/api/v1/tokens/validate", {
   method: "POST",
-  body: { token: "user_token", serviceSlug: "other-service" },
+  body: { token: "user_token" },
   idempotencyKey: crypto.randomUUID(), // optional: lets a POST be retried after a network error
 });
 ```
@@ -149,7 +249,7 @@ export const config = {
 };
 ```
 
-Each request must carry `Authorization: Bearer <token>` or `x-api-token`; without one, API routes get `401` and pages redirect to `errorPath` (without an error message in the URL). Paths are decoded and normalized before any check, so `/_next/static/../admin` is authenticated. Only `/_next/static/`, `/_next/image`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml` and the health paths skip auth by default. File extensions say nothing about whether a route is public, so they no longer skip auth; opt in with `staticFileExtensions: STATIC_FILE_EXTENSIONS` if you rely on that. When Daywalker is unreachable the middleware answers `503`, and `500` for a configuration error. To gate the app on this service's own API key instead (the self-healing error page), use `createDaywalkerServiceHealthMiddleware` with the same options.
+Each request must carry `Authorization: Bearer <token>`, `Authorization: DPoP <token>` with its `DPoP` proof header, or `x-api-token`. An `Authorization` header with any other scheme, or a credentials header sent twice, is refused rather than skipped. Without credentials, API routes get `401` and pages redirect to `errorPath` (without an error message in the URL). Paths are decoded and normalized before any check, so `/_next/static/../admin` is authenticated. Only `/_next/static/`, `/_next/image`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml` and the health paths skip auth by default. File extensions say nothing about whether a route is public, so they no longer skip auth; opt in with `staticFileExtensions: STATIC_FILE_EXTENSIONS` if you rely on that. When Daywalker is unreachable the middleware answers `503`, and `500` for a configuration error. To gate the app on this service's own OAuth client credentials instead (the self-healing error page), use `createDaywalkerServiceHealthMiddleware` with the same options.
 
 ### Route Handler Wrapper
 
@@ -185,16 +285,15 @@ app.get("/api/me", (c) => {
 
 ```ts
 import express from "express";
-import { daywalkerAuth, daywalkerKeys } from "@shelbyb/daywalker-sdk/express";
+import { daywalkerAuth } from "@shelbyb/daywalker-sdk/express";
 
 const app = express();
-app.use(daywalkerKeys()); // serves GET /.well-known/daywalker-keys.json
 app.use("/api", daywalkerAuth({ serviceSlug: "sonalyze" }));
 
 app.get("/api/me", (req, res) => res.json({ auth: req.auth }));
 ```
 
-`daywalkerAuth` reads `Authorization: Bearer <token>` or `x-api-token`, answers `401` when neither is present, and otherwise returns the same status codes as the other middleware (`429` with `Retry-After`, `503` when Daywalker is unreachable). On success the validated payload is on `req.auth`. Both functions also work with plain `http.createServer` handlers.
+`daywalkerAuth` reads credentials the same way as the Next middleware, answers `401` when there are none (or they are malformed), and otherwise returns the same status codes as the other middleware (`429` with `Retry-After`, `503` when Daywalker is unreachable). On success the validated payload is on `req.auth`. It also works with plain `http.createServer` handlers.
 
 ---
 
@@ -213,7 +312,7 @@ DAYWALKER_API_KEY=srv_live_… npx daywalker init --service devpulse --domain de
 
 `init` and `rotate` take no service: the API key decides which services your credentials cover (`--service` is optional and only sets the audience for offline verification, `DAYWALKER_SERVICE_SLUG`).
 
-**Client credentials flow (the JWT lists every service).** Your backend authenticates with its client credentials (API key + registered signing key) and gets a short-lived access token (5 to 15 minutes) plus a rotating refresh token. No request names a service; the token lists them:
+**Client credentials flow (the JWT lists every service).** Your backend authenticates with its client credentials (API key + registered signing key, see [Authentication](#authentication-oauth-20-client-credentials)) and gets a short-lived access token (5 to 15 minutes) plus a rotating refresh token. No request names a service; the token lists them:
 
 ```ts
 const tokens = await client.getTokens();
@@ -278,17 +377,46 @@ const client = new Daywalker({
 const result = await client.validateToken(incomingJwt);
 ```
 
-Tokens must have a numeric `exp`, a `jti`, and an `aud` (or `serviceSlug`) containing your service slug, so `serviceSlug` must be configured. A lease that lists `services` must list yours too. `result.data.services` is every service the lease covers (see [One API key, several services](#one-api-key-several-services)). Set `leaseIssuer` (or `DAYWALKER_LEASE_ISSUER`) to also check `iss`.
+### Surviving Daywalker key rotation (`jwks: "auto"`)
+
+A static `DAYWALKER_PUBLIC_KEY` stops verifying the moment Daywalker rotates its signing key. Set `DAYWALKER_JWKS=auto` (or `jwks: "auto"`) and the client verifies against Daywalker's published key set instead:
+
+```ts
+const client = new Daywalker({ serviceSlug: "myservice", jwks: "auto" });
+```
+
+- The set is fetched from `${authUrl}/.well-known/jwks.json` and nowhere else: a `jwks_uri` in a token response or in the set itself is never followed. The fetch sends no credentials, follows no redirects, bypasses HTTP caches, is capped at 1 MiB and times out after `timeoutMs`.
+- Only Ed25519 signing keys for EdDSA with a `kid` are kept (`kty: OKP`, `crv: Ed25519`, `alg` absent or `EdDSA`, `use` absent or `sig`, no private part), at most 16. Everything else in the set is ignored.
+- The set is cached in the client for 10 minutes (`JWKS_CACHE_TTL_MS`). A token naming a `kid` the set doesn't have (a rotation) triggers a refetch, but fetches are never closer than 30 seconds apart (`JWKS_REFETCH_COOLDOWN_MS`), whatever triggers them, so tokens with made-up `kid`s can't make the client hammer Daywalker. Concurrent callers share one fetch.
+- A failed refresh (outage, redirect, non-JSON, no usable key) keeps the last good set.
+- Fail closed: while no set has ever been obtained, the static `daywalkerPublicKey` is used if one is configured; otherwise `offlineOnly` validation returns `503 SERVICE_UNAVAILABLE` and normal validation goes online (`POST /api/v1/tokens/validate`).
+
+Without `jwks: "auto"`, offline verification uses `daywalkerPublicKey` exactly as before.
+
+Tokens must be RFC 9068 access tokens (`typ: at+jwt`, `alg: EdDSA`) with a numeric `exp`, a `jti`, and an `aud` containing your service slug, so `serviceSlug` must be configured. A token that lists `services` must list yours too. A DPoP-bound token (`cnf.jkt`) is only accepted with `Authorization: DPoP` and a valid proof: right method and URL, signed by the bound key, fresh, carrying the token's hash, and never used before. A copied token alone is useless. With several instances, pass a shared `dpopReplayStore` (like `replayStore` for signatures). `result.data.services` is every service the lease covers (see [One API key, several services](#one-api-key-several-services)). Set `leaseIssuer` (or `DAYWALKER_LEASE_ISSUER`) to also check `iss`.
 
 ---
 
+## Service License & Config Bundle
+
+Daywalker issues each service a license key with the client credentials grant: derived per service, signing key and one-hour window, never returned for a revoked or suspended service.
+
+```ts
+const { licenseKey, expiresAt } = await client.getLicense();   // cached until a minute before expiry
+const bundle = await client.fetchBundle();                     // { dataKeySalt, features, issuedAt, expiresAt, ... }
+```
+
+`fetchBundle()` downloads a bundle sealed (AES-256-GCM) under the license key and opens it locally, so only a client that got the license from Daywalker can read it. Derive app secrets from `licenseKey` + `bundle.dataKeySalt` (HKDF) so removing the SDK breaks the app. Errors are `DaywalkerAuthError`s: `SERVICE_REVOKED`, `SERVICE_SUSPENDED`, `DOMAIN_REVOKED`, `DOMAIN_MISMATCH`, `LICENSE_UNAVAILABLE`, `BUNDLE_UNREADABLE`. Never log the key.
+
 ## CLI Reference
 
 | Command | Description |
 |---|---|
 | `npx daywalker init --service <slug[,slug…]> [--domain <host>] [--api-key-stdin] [--skip-register] [--force] [--json]` | Generate Ed25519 key, register with Daywalker Auth, and write `.env.local` or output JSON |
-| `npx daywalker check` | Validate configuration, signature readiness, and connection |
-| `npx daywalker rotate [--service <slug[,slug…]>] [--api-key-stdin] [--skip-register] [--json]` | Generate and register a new key while preserving the previous key in `.env.local` |
+| `npx daywalker check [--offline]` | Validate configuration and signature readiness, then run the OAuth client credentials grant to confirm the credentials work and cover the configured service(s) (`--offline` skips that) |
+| `npx daywalker rotate [--service <slug[,slug…]>] [--api-key-stdin] [--skip-register] [--json]` | Generate and register a new key while preserving the previous key in `.env.local`. The previous key stays registered until you revoke it, so running deployments keep working |
+| `npx daywalker keys [--domain <host>] [--json]` | List the domain's signing keys: status, slot, expiry, last use, and which one is current or previous |
+| `npx daywalker revoke <keyId> [--force]` | Revoke a key now; Daywalker also ends the OAuth sessions it started. Refuses the current `DAYWALKER_KEY_ID` unless `--force` |
 
 ---
 
@@ -296,12 +424,14 @@ Tokens must have a numeric `exp`, a `jti`, and an `aud` (or `serviceSlug`) conta
 
 | Endpoint | SDK usage | Notes |
 |---|---|---|
-| `POST /api/v1/tokens/validate` | `client.validateToken()` | Body `{ token, serviceSlug }`; signed with `Signature-Input`, `Signature`, `Content-Digest`. Errors: `400` (`DIGEST_MISMATCH`/missing fields), `401` (`INVALID_SIGNATURE`/invalid token), `403`, `429`. Response includes `valid`, `tokenId`, `tokenName`, `userId`, `stage`, `rateLimit`, `rateLimitHourly` and `X-RateLimit-*` / `X-RateLimit-Hourly-*` headers |
-| `POST /api/v1/keys/register` | `npx daywalker init` / `rotate` | Bearer auth; body `{ keyId, domain, publicKey, serviceSlug? }`; `403 service_not_covered` if the key doesn't cover `serviceSlug` |
-| `POST /api/v1/oauth/token` | `client.getTokens({ scope?, expiresIn? })`, `client.refreshTokens()`, `client.accessToken()` | `client_credentials` (signed request) and `refresh_token` grants return `{ accessToken, refreshToken, expiresAt, services, … }`; refresh tokens rotate and reuse revokes the session |
+| `POST /api/v1/tokens/validate` | `client.validateToken()` | `Authorization: DPoP <access_token>` + `DPoP` proof; body `{ token }`; signed with `Signature-Input`, `Signature`, `Content-Digest`. Errors: `400` (`DIGEST_MISMATCH`/missing fields), `401` (`INVALID_SIGNATURE`, `DPOP_REQUIRED`, `INVALID_DPOP_PROOF`, `DPOP_REPLAY`, `ACCESS_TOKEN_EXPIRED`, invalid token), `403` (`SERVICE_NOT_GRANTED`, allowlist), `429`. Response includes `valid`, `tokenId`, `tokenName`, `userId`, `stage`, `rateLimit`, `rateLimitHourly` and `X-RateLimit-*` / `X-RateLimit-Hourly-*` headers |
+| `POST /api/v1/keys/register` | `registerPublicKey()`, `npx daywalker init` / `rotate`, `keyStore` / `ephemeralKey` provisioning | `Authorization: Bearer <API key>` (bootstraps the signing key the client credentials grant needs); body `{ keyId, domain, publicKey, serviceSlug?, instanceId?, ttlSeconds?, expiresAt? }`. `200` re-registration (idempotent), `201` new; `409 KEY_LIMIT_REACHED` (20 live keys per domain) or `KEY_ID_CONFLICT`; `403 domain_not_allowed`. The SDK always passes an `instanceId`, because without one Daywalker retires every other slot-less key of the domain after 10 minutes |
+| `GET /api/v1/keys?domain=` | `listSigningKeys()`, `npx daywalker keys` | The domain's keys with `status`, `instanceId`, `expiresAt`, `lastUsedAt` |
+| `DELETE /api/v1/keys/{keyId}` | `revokeSigningKey()`, `client.close()`, `npx daywalker revoke` | Revokes now and ends the OAuth sessions started with the key |
+| `POST /api/v1/oauth/token` | `client.getTokens({ scope?, expiresIn? })`, `client.refreshTokens()`, `client.accessToken()` (called for you by `validateToken()` / `fetch()`) | `client_credentials` (API key as Bearer + signed request, mandatory DPoP) and `refresh_token` grants return `{ accessToken, refreshToken, expiresAt, services, … }`; tokens are sender-constrained via DPoP (RFC 9449), refresh tokens rotate, and reuse revokes the session |
 | `GET /.well-known/jwks.json` | `client.fetchJwks()` | Daywalker public JWKS for offline lease verification |
 
-Inbound tokens may be supplied as `x-api-token: srv_live_...` or `Authorization: Bearer <JWT or API key>`.
+Inbound tokens may be supplied as `x-api-token: srv_live_...`, `Authorization: Bearer <token>`, or `Authorization: DPoP <access token>` with a `DPoP` proof. An online answer must name your service: a token validated for a sibling service your credentials also cover is refused with `403 SERVICE_NOT_GRANTED`.
 
 ---
 
@@ -311,7 +441,7 @@ Each outbound request signed by `@shelbyb/daywalker-sdk` includes:
 - `Content-Digest: sha-256=:<base64-encoded-hash>:` (POST/PUT/PATCH, and any request with a body)
 - `Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");created=<unix_seconds>;keyid="<kid>";alg="ed25519";nonce="<random>"`. `"@query"` is added after `"@path"` when the URL has a query string; `"content-digest"` is left out only for bodyless GET/HEAD/DELETE/OPTIONS requests.
 - `Signature: sig1=:<base64-encoded-signature>:`
-- `Authorization: Bearer <DAYWALKER_API_KEY>`
+- `Authorization: DPoP <access_token>` and `DPoP: <proof JWT>` (`htm`, `htu`, `iat`, `jti`, `ath`). Only the client credentials grant on `/api/v1/oauth/token` sends `Authorization: Bearer <DAYWALKER_API_KEY>` instead.
 
 A fresh random `nonce` is generated for every attempt (including retries), so identical requests in the same second still produce unique signatures and never trip replay protection. `validateToken()` also shares one in-flight request between concurrent callers for the same token, and briefly caches failures (`negativeCacheTtlMs`, default 3000ms; 429s and network errors are never cached).
 
@@ -319,6 +449,22 @@ Verification reads the covered components from `Signature-Input`, requires `cont
 
 ---
 
+## Security Model
+
+This SDK checks that callers hold a valid Daywalker credential, and that the service it runs in holds valid OAuth client credentials. It is built to resist tampering by **other code in the same process** (a compromised dependency, an injected script, a confused AI agent editing at runtime):
+
+- **No reachable internals.** Caches, tokens, the DPoP key and the config are ES `#private` fields, so `client._cache` doesn't exist to be poisoned. `Daywalker.prototype`, the class and each instance are frozen, so `validateToken` can't be swapped by assignment, including on the shared `daywalker` client.
+- **Frozen, secret-free config.** `client.config` is frozen and shows the API key and private keys only as `"[configured]"`. The options object is read once, so changing it later (say, `authUrl` or `fetch`) has no effect.
+- **Captured primitives.** WebCrypto (`subtle.verify`, `sign`, `digest`, …) is captured when the SDK loads, so replacing `crypto.subtle.verify` later can't make forged tokens verify. The Next adapter builds its own responses and ignores any `NextResponse` planted on `globalThis`.
+- **Sender-constrained tokens.** The SDK's own access tokens are DPoP-bound to a non-extractable key generated in memory, and only the token endpoint ever sees the API key. Incoming DPoP-bound tokens need a valid proof.
+- **Bounded, validated input.** Tokens (≤ 8 KiB, token characters only), headers, DPoP proofs, JWTs and response bodies (≤ 1 MiB) are size-checked and validated before use. Nothing is followed through a redirect, cached by an HTTP cache (`cache: "no-store"`), or trusted from an answer of the wrong shape (fail closed).
+
+**What no client-side SDK can do:** stop the operator of the server it runs on. Whoever controls a deployment can edit `node_modules`, patch the code, or delete the middleware, and obfuscation only slows that down. So treat this package as the *enforcement point*, and put the *decision* on Daywalker's side, where it can't be removed:
+
+1. Make the service depend on what only a valid grant provides. Read limits and features from the verified access token (`service_limits`, `service_features`) rather than from local config, so code with the SDK ripped out has nothing to run on.
+2. Revoke on Daywalker. Revoking the API key, signing key or allowlist entry ends the client credentials session (and every refresh) at the next token request, within 15 minutes at most.
+3. Keep the signing key and API key in a secret manager, run `npx daywalker check` in CI and at startup, and watch Daywalker's usage analytics for clients that stop calling in.
+
 ## DevPulse SDKs (one package)
 
 The same package ships the [DevPulse](https://github.com/shelbyb/devpulse) client SDKs as subpath exports. Each subpath is tree-shakeable; `react` and the OpenFeature SDKs are optional peer dependencies used only by their subpaths.

package/dist/cli.js

@@ -3,27 +3,35 @@ import fs from "node:fs";
 import path from "node:path";
 import { createDaywalker } from "./client.js";
 import { parseServiceSlugs, publicHostname } from "./config.js";
-import { generateSigningKey, loadSigningKey, registerPublicKey, redactSecrets } from "./crypto/index.js";
+import { generateSigningKey, keySlotFor, listSigningKeys, loadSigningKey, registerPublicKey, redactSecrets, revokeSigningKey } from "./crypto/index.js";
 const HELP = `daywalker: connect a service to Daywalker Auth (RFC 9421 / Push Architecture)
 
 Usage:
   daywalker init   [--service <slug[,slug…]>] [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--force] [--skip-register] [--json|--export] [--print-key]
   daywalker rotate [--service <slug[,slug…]>] [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--skip-register] [--json|--export] [--print-key]
-  daywalker check
+  daywalker check  [--offline]
+  daywalker keys   [--domain <host>] [--auth-url <url>] [--api-key-stdin] [--json]
+  daywalker revoke <keyId> [--domain <host>] [--auth-url <url>] [--api-key-stdin] [--force]
 
 init     Generates an Ed25519 keypair, registers the public key directly with Daywalker Auth
          (POST /api/v1/keys/register), and writes DAYWALKER_* settings to .env.local (or outputs JSON with --json).
          Nothing is written if registration fails. --force replaces an existing key (kept as
          DAYWALKER_SIGNING_KEY_PREVIOUS for rollback). No public ingress or /.well-known route handlers are required.
 rotate   Generates a new Ed25519 key, registers it with Daywalker Auth, and keeps the old one
-         in .env.local as DAYWALKER_SIGNING_KEY_PREVIOUS during deployment transition.
+         in .env.local as DAYWALKER_SIGNING_KEY_PREVIOUS during deployment transition. The old key stays
+         registered until you revoke it (\`daywalker revoke <keyId>\`) once the new key is deployed everywhere.
          Nothing is written, and the exit code is non-zero, unless registration succeeds.
-check    Validates configuration and confirms Daywalker Auth connection and signature readiness.
+check    Validates configuration and signature readiness, then runs the OAuth client credentials grant
+         against Daywalker Auth to confirm the credentials work and cover the configured service(s).
+keys     Lists the signing keys registered for the domain (status, slot, expiry, last use).
+revoke   Revokes a signing key now; Daywalker also ends the OAuth sessions it started. Refuses the key in
+         DAYWALKER_KEY_ID (the one this service signs with) unless --force.
 
 Options:
   --api-key-stdin   Read the Daywalker API key from stdin (e.g. \`op read ... | daywalker init --api-key-stdin\`).
                     The key is otherwise taken from DAYWALKER_API_KEY in the environment or .env.local.
-                    --api-key <key> also works but exposes the key in shell history and process listings.
+                    (--api-key <key> is refused: it would expose the key in shell history and process listings.)
+  --offline         check only: skip the live OAuth client credentials check against Daywalker Auth.
   --skip-register   Do not register the public key (alias: --no-register); register it yourself before deploying.
   --json, --export  Output configuration as JSON for piping into Vercel, DigitalOcean, Fly.io, AWS SSM, etc.
                     The JSON includes the private key (DAYWALKER_SIGNING_KEY); nothing is written to .env.local.
@@ -59,8 +67,6 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8").trim();
 }
 async function resolveApiKey(opts, existing) {
-    if (typeof opts["api-key"] === "string")
-        return opts["api-key"].trim() || null;
     if (opts["api-key-stdin"]) {
         const fromStdin = await readStdin();
         if (!fromStdin)
@@ -69,6 +75,13 @@ async function resolveApiKey(opts, existing) {
     }
     return String(existing.get("DAYWALKER_API_KEY") ?? process.env.DAYWALKER_API_KEY ?? "").trim() || null;
 }
+/** Why a key API call failed, with what to do when the domain is full. */
+function keyApiFailure(what, result) {
+    const hint = result.code === "KEY_LIMIT_REACHED"
+        ? "\n  The domain has 20 live keys: list them with `daywalker keys` and revoke unused ones with `daywalker revoke <keyId>`."
+        : "";
+    return `${what} failed (${result.status || "network"}${result.code ? ` ${result.code}` : ""}): ${result.error}${hint}`;
+}
 function skipRegister(opts) {
     return Boolean(opts["skip-register"] || opts["no-register"]);
 }
@@ -211,11 +224,13 @@ async function init(opts) {
     if (apiKey && activeKey && !skipRegister(opts)) {
         if (!isJson)
             console.log(`• Registering public key (${activeKey.publicJwk.kid}) with Daywalker Auth...`);
+        // Each key gets its own slot, so registering it never retires a key a running deployment still uses.
         const regResult = await registerPublicKey({
             authUrl,
             apiKey,
             domain,
             publicJwk: activeKey.publicJwk,
+            instanceId: keySlotFor(activeKey.publicJwk.kid),
         });
         if (regResult.ok) {
             registered = true;
@@ -223,7 +238,7 @@ async function init(opts) {
                 console.log(`✔ Public key registered with Daywalker Auth (Push Architecture)`);
         }
         else {
-            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n` +
+            fail(`${keyApiFailure("Key registration", regResult)}\n` +
                 `  Nothing was written. Fix the problem and re-run, or pass --skip-register to write the key without registering it.`);
         }
     }
@@ -254,8 +269,12 @@ async function init(opts) {
         console.log(`  • Key ID (RFC 7638 thumbprint): ${kid}`);
     if (registered)
         console.log(`  • Zero-ingress push architecture: public key registered directly`);
-    if (previousKey)
-        console.log(`  • Previous key kept as DAYWALKER_SIGNING_KEY_PREVIOUS for rollback; remove it once the new key is deployed.`);
+    if (previousKey) {
+        const previousKid = (await loadSigningKey(previousKey).catch(() => null))?.publicJwk.kid;
+        console.log(`  • Previous key kept as DAYWALKER_SIGNING_KEY_PREVIOUS for rollback; it stays registered.`);
+        if (previousKid)
+            console.log(`    Once the new key is deployed everywhere: npx daywalker revoke ${previousKid}`);
+    }
     if (opts["print-key"] && signingKeyStr)
         console.log(`\nDAYWALKER_SIGNING_KEY=${signingKeyStr}`);
 }
@@ -285,9 +304,10 @@ async function rotate(opts) {
             apiKey,
             domain: rotateDomain,
             publicJwk: key.publicJwk,
+            instanceId: keySlotFor(key.publicJwk.kid),
         });
         if (!regResult.ok) {
-            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n  Nothing was written; the current key is still active.`);
+            fail(`${keyApiFailure("Key registration", regResult)}\n  Nothing was written; the current key is still active.`);
         }
         if (!isJson)
             console.log(`✔ New public key registered with Daywalker Auth`);
@@ -305,14 +325,27 @@ async function rotate(opts) {
     }
     writeEnvFile(envFile, envValues, { DAYWALKER_SIGNING_KEY_PREVIOUS: PREVIOUS_KEY_COMMENT });
     console.log(`✔ New key ${key.publicJwk.kid} written; previous key preserved as DAYWALKER_SIGNING_KEY_PREVIOUS.`);
-    console.log(`  After deployment rollout is complete, you may remove DAYWALKER_SIGNING_KEY_PREVIOUS.`);
+    const previousKid = (await loadSigningKey(current).catch(() => null))?.publicJwk.kid;
+    console.log(`  The previous key stays registered, so running deployments keep working.`);
+    if (previousKid)
+        console.log(`  Once the new key is deployed everywhere: npx daywalker revoke ${previousKid}, then remove DAYWALKER_SIGNING_KEY_PREVIOUS.`);
     if (opts["print-key"])
         console.log(`\nDAYWALKER_SIGNING_KEY=${key.privateKeyPkcs8Base64}`);
 }
-async function check() {
+async function check(opts) {
     const env = { ...process.env, ...Object.fromEntries(readEnvFile(path.join(process.cwd(), ".env.local"))) };
     const client = createDaywalker({ env });
     const result = await client.selfCheck();
+    if (result.ok && !opts.offline) {
+        const live = await client.validateServiceCredentials();
+        if (!live.ok) {
+            result.ok = false;
+            result.problems.push(`OAuth client credentials check failed (${live.status} ${live.error}): ${live.message}`);
+        }
+        else {
+            console.log(`✔ OAuth client credentials grant succeeded (services: ${(live.data.services ?? []).join(", ")})`);
+        }
+    }
     if (result.ok) {
         console.log(`✔ Daywalker configuration looks good`);
         if (result.serviceSlugs.length > 1)
@@ -334,11 +367,58 @@ async function check() {
         console.error(redactSecrets(`  - ${p}`));
     process.exit(1);
 }
+/** Domain, API key and auth URL for the key commands, from flags, .env.local or the environment. */
+async function keyCommandContext(opts) {
+    const existing = readEnvFile(path.join(process.cwd(), ".env.local"));
+    const apiKey = await resolveApiKey(opts, existing);
+    if (!apiKey)
+        fail("Set DAYWALKER_API_KEY (or pipe it to --api-key-stdin)");
+    const rawDomain = String(opts.domain ?? existing.get("DAYWALKER_DOMAIN") ?? process.env.DAYWALKER_DOMAIN ?? "");
+    const domain = publicHostname(rawDomain);
+    const authUrl = String(opts["auth-url"] ?? existing.get("DAYWALKER_AUTH_URL") ?? process.env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    const currentKid = existing.get("DAYWALKER_KEY_ID") ?? process.env.DAYWALKER_KEY_ID ?? null;
+    const previous = existing.get("DAYWALKER_SIGNING_KEY_PREVIOUS") ?? process.env.DAYWALKER_SIGNING_KEY_PREVIOUS;
+    const previousKid = previous ? ((await loadSigningKey(previous).catch(() => null))?.publicJwk.kid ?? null) : null;
+    return { apiKey, domain, rawDomain, authUrl, currentKid, previousKid };
+}
+async function keys(opts) {
+    const ctx = await keyCommandContext(opts);
+    if (!ctx.domain)
+        fail(`--domain (${ctx.rawDomain || "not set"}) must be a public hostname (or set DAYWALKER_DOMAIN)`);
+    const result = await listSigningKeys({ authUrl: ctx.authUrl, apiKey: ctx.apiKey, domain: ctx.domain });
+    if (!result.ok)
+        fail(keyApiFailure("Listing keys", result));
+    const list = result.keys ?? [];
+    if (opts.json) {
+        console.log(JSON.stringify(list, null, 2));
+        return;
+    }
+    const when = (t) => (t === null ? "-" : new Date(t * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"));
+    console.log(`Signing keys for ${ctx.domain} (${list.filter((k) => k.status !== "REVOKED").length} live of 20 allowed):`);
+    for (const k of list) {
+        const tag = k.keyId === ctx.currentKid ? " (current)" : k.keyId === ctx.previousKid ? " (previous)" : "";
+        console.log(`  ${k.keyId}${tag}  ${k.status}  slot=${k.instanceId ?? "-"}  expires=${when(k.expiresAt)}  lastUsed=${when(k.lastUsedAt)}`);
+    }
+}
+async function revoke(keyId, opts) {
+    if (!keyId)
+        fail("Usage: daywalker revoke <keyId>");
+    const ctx = await keyCommandContext(opts);
+    if (keyId === ctx.currentKid && !opts.force) {
+        fail(`${keyId} is DAYWALKER_KEY_ID, the key this service signs with: revoking it stops this service from authenticating. Pass --force if that is what you want.`);
+    }
+    const result = await revokeSigningKey({ authUrl: ctx.authUrl, apiKey: ctx.apiKey, keyId });
+    if (!result.ok)
+        fail(keyApiFailure(`Revoking ${keyId}`, result));
+    console.log(`✔ Revoked signing key ${keyId}; Daywalker ended the OAuth sessions it started.`);
+    if (keyId === ctx.previousKid)
+        console.log("  You can now remove DAYWALKER_SIGNING_KEY_PREVIOUS from .env.local.");
+}
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const parsedArgs = args(rest);
-    if (typeof parsedArgs["api-key"] === "string") {
-        console.warn("! --api-key exposes the key in shell history and process listings; prefer DAYWALKER_API_KEY in the environment or .env.local.");
+    if (parsedArgs["api-key"] !== undefined) {
+        fail("--api-key is not supported: it exposes the key in shell history and process listings. Use DAYWALKER_API_KEY in the environment or .env.local, or pipe it to --api-key-stdin.");
     }
     if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
         console.log(HELP);
@@ -351,7 +431,13 @@ async function main() {
         await rotate(parsedArgs);
     }
     else if (cmd === "check") {
-        await check();
+        await check(parsedArgs);
+    }
+    else if (cmd === "keys") {
+        await keys(parsedArgs);
+    }
+    else if (cmd === "revoke") {
+        await revoke(rest[0] && !rest[0].startsWith("--") ? rest[0] : undefined, parsedArgs);
     }
     else {
         fail(`Unknown command "${cmd}". Run \`daywalker --help\` for usage.`);