@shelbyb/daywalker-sdk 0.5.0 → 0.6.0

package/README.md

@@ -61,7 +61,7 @@ The private key is never printed unless you pass `--print-key`.
 
 | Variable | Required | Purpose |
 |---|---|---|
-| `DAYWALKER_API_KEY` | ✅ | The service's Daywalker API token (`srv_live_…`) or JWT lease |
+| `DAYWALKER_API_KEY` | ✅ | The service's Daywalker API token (`srv_live_…`) or access token |
 | `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_KEY_ID` | optional | RFC 7638 JWK thumbprint derived during key generation |
@@ -69,7 +69,7 @@ The private key is never printed unless you pass `--print-key`.
 | `DAYWALKER_DOMAIN` | optional | Optional caller identifier or host domain name |
 | `DAYWALKER_PUBLIC_KEY` | optional | Daywalker Auth public key for zero-egress offline JWT lease 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 JWT leases |
+| `DAYWALKER_LEASE_ISSUER` | optional | Expected `iss` of offline-verified JWTs (default `https://auth.daywalker.dev`) |
 
 ---
 
@@ -211,26 +211,51 @@ DAYWALKER_API_KEY=srv_live_… npx daywalker init --service gigpulse --domain gi
 DAYWALKER_API_KEY=srv_live_… npx daywalker init --service devpulse --domain devpulse.daywalker.dev
 ```
 
-`init` and `rotate` fail right away with `service_not_covered` if the API key doesn't cover the slug you name. An app that serves several services lists them all, `--service gigpulse,devpulse` (`DAYWALKER_SERVICE_SLUG="gigpulse,devpulse"`); the first is the default for `validateToken()`, and `client.config.serviceSlugs` holds the list.
+`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`).
 
-**The JWT lists every service.** Once your backend has authenticated with its signed request, ask for a lease. It lists all the service slugs the token covers (and may use right now):
+**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:
 
 ```ts
-const lease = await client.issueLease();
-lease.services; // ["gigpulse", "devpulse"]; also the JWT's `services` and `aud` claims
+const tokens = await client.getTokens();
+tokens.services; // ["gigpulse", "devpulse"]; also the JWT's `services` and `aud` claims
 
-// Least privilege: only what this process needs. A service the key doesn't cover is refused (403 SERVICE_NOT_GRANTED).
-const narrow = await client.issueLease({ services: ["devpulse"], ttlSeconds: 3600 });
+// Least privilege: only what this process needs (403 SERVICE_NOT_GRANTED for a service the key doesn't cover)
+await client.getTokens({ scope: ["devpulse"], expiresIn: 600 });
+
+// Always-fresh access token: refreshes (and re-authenticates if the session ended) automatically
+const accessToken = await client.accessToken();
+```
+
+**Refresh token rotation.** `client.refreshTokens()` swaps the refresh token for a *new* access token and a *new* refresh token; the old one stops working. Daywalker keeps each session's refresh tokens as a family: presenting an old one again is treated as theft and revokes the whole family, so your client has to start over with its credentials. `accessToken()` serializes refreshes so concurrent requests never present the same token twice. Don't refresh from several processes with one session.
+
+**The access token** is an EdDSA JWT (RFC 9068, `typ: at+jwt`) with `iss`, `aud`, `jti`, `iat`, `nbf`, `exp`, `services`, and a `user` object: the user's public UUID v7 `id`, `name` and `email`. Read it with `accessTokenUser(payload)` **after** verifying:
+
+```ts
+import { verifyJwtLease, accessTokenUser } from "@shelbyb/daywalker-sdk";
+const res = await verifyJwtLease({ token, publicKey: jwks, expectedServiceSlug: "devpulse", expectedIssuer: "https://auth.daywalker.dev" });
+if (res.valid) accessTokenUser(res.payload!); // { id: "018f…", name: "Ada", email: "ada@example.com" }
+```
+
+Verification is strict: only `EdDSA` (never `none` or HMAC, so no algorithm confusion), canonical base64url, `typ` `at+jwt`, issuer, your audience, required `jti` and `exp`, and at most 30 seconds of clock skew. Never decode a token without verifying it.
+
+**Web apps: HttpOnly cookies.** Keep tokens on your server. If the browser must hold them, send them from your backend in cookies scripts can't read:
+
+```ts
+import { daywalkerCookies, clearTokenCookie } from "@shelbyb/daywalker-sdk";
+const tokens = await client.getTokens();
+const res = new Response("ok");
+for (const c of daywalkerCookies(tokens, { refreshPath: "/api/auth/refresh" })) res.headers.append("Set-Cookie", c);
+// HttpOnly; Secure; SameSite=Strict. The refresh token cookie is only sent to /api/auth/refresh.
 ```
 
-Services that are inactive, in `DRAFT`, `TESTING` (unless an admin owns the token), or no longer entitled to the token's owner are left out. Check `lease.services` rather than assuming.
+Services that are inactive, in `DRAFT`, `TESTING` (unless an admin owns the token), or no longer entitled to the token's owner are left out. Check `tokens.services` rather than assuming.
 
-Whoever receives the lease verifies it for **their own** service. It only passes when that slug is in the lease's `services` and `aud`:
+Whoever receives the access token verifies it for **their own** service. It only passes when that slug is in the token's `services` and `aud`:
 
 ```ts
 const verifier = new Daywalker({ serviceSlug: "devpulse", daywalkerPublicKey: process.env.DAYWALKER_PUBLIC_KEY });
 const result = await verifier.validateToken(incomingJwt);
-if (result.ok) result.data.services; // ["gigpulse", "devpulse"]: everything this lease covers
+if (result.ok) result.data.services; // ["gigpulse", "devpulse"]: everything this token covers
 ```
 
 Online validation of an `srv_live_…` token reports the same list in `result.data.services` (a server that predates multi-service tokens yields just the validated slug).
@@ -253,7 +278,7 @@ const client = new Daywalker({
 const result = await client.validateToken(incomingJwt);
 ```
 
-Leases must have a numeric `exp` 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`.
+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`.
 
 ---
 
@@ -273,7 +298,7 @@ Leases must have a numeric `exp` and an `aud` (or `serviceSlug`) containing your
 |---|---|---|
 | `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/leases/issue` | `client.issueLease(ttlSeconds? \| { ttlSeconds?, services? })` | Signed request returns `{ lease, tokenType, expiresAt, jwksUri, services }` (EdDSA JWT listing every service the key covers; `services` narrows it) |
+| `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 |
 | `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>`.

package/dist/cli.js

@@ -7,7 +7,7 @@ import { generateSigningKey, loadSigningKey, registerPublicKey, redactSecrets }
 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 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
 
@@ -181,8 +181,9 @@ async function init(opts) {
     const envFile = path.join(dir, ".env.local");
     const existing = readEnvFile(envFile);
     const slugs = parseServiceSlugs(String(opts.service ?? existing.get("DAYWALKER_SERVICE_SLUG") ?? process.env.DAYWALKER_SERVICE_SLUG ?? ""));
-    if (slugs.length === 0 || !slugs.every((s) => /^[a-z0-9_-]+$/.test(s))) {
-        fail("--service must be this service's Daywalker slug (e.g. --service sonalyze), or a comma-separated list when one API key covers several (--service gigpulse,devpulse)");
+    // Optional: requests never name a service. Only needed to verify access tokens offline (audience check).
+    if (!slugs.every((s) => /^[a-z0-9_-]+$/.test(s))) {
+        fail("--service must be Daywalker service slug(s) (e.g. --service sonalyze, or gigpulse,devpulse)");
     }
     const slug = slugs.join(",");
     const rawDomain = opts.domain ? String(opts.domain) : existing.get("DAYWALKER_DOMAIN") ?? process.env.DAYWALKER_DOMAIN ?? "";
@@ -213,7 +214,6 @@ async function init(opts) {
         const regResult = await registerPublicKey({
             authUrl,
             apiKey,
-            serviceSlug: slug,
             domain,
             publicJwk: activeKey.publicJwk,
         });
@@ -232,7 +232,7 @@ async function init(opts) {
     }
     const signingKeyStr = key?.privateKeyPkcs8Base64 ?? existing.get("DAYWALKER_SIGNING_KEY") ?? "";
     const envValues = {
-        DAYWALKER_SERVICE_SLUG: slug,
+        ...(slug ? { DAYWALKER_SERVICE_SLUG: slug } : {}),
         DAYWALKER_KEY_ID: kid,
         DAYWALKER_AUTH_URL: authUrl,
         ...(domain ? { DAYWALKER_DOMAIN: domain } : {}),
@@ -247,9 +247,9 @@ async function init(opts) {
     }
     writeEnvFile(envFile, envValues, { DAYWALKER_SIGNING_KEY_PREVIOUS: PREVIOUS_KEY_COMMENT });
     ensureGitignored(dir, ".env.local");
-    console.log(`✔ Daywalker configured for service "${slug}"${domain ? ` (${domain})` : ""}`);
+    console.log(`✔ Daywalker configured${slug ? ` (audience "${slug}")` : ""}${domain ? ` (${domain})` : ""}`);
     console.log(`  • RFC 9421 / RFC 9530 HTTP Message Signing active`);
-    console.log(`  • .env.local: DAYWALKER_SERVICE_SLUG, DAYWALKER_KEY_ID, DAYWALKER_AUTH_URL${domain ? ", DAYWALKER_DOMAIN" : ""}${apiKey ? ", DAYWALKER_API_KEY" : ""}${signingKeyStr ? ", DAYWALKER_SIGNING_KEY" : ""}`);
+    console.log(`  • .env.local: ${slug ? "DAYWALKER_SERVICE_SLUG, " : ""}DAYWALKER_KEY_ID, DAYWALKER_AUTH_URL${domain ? ", DAYWALKER_DOMAIN" : ""}${apiKey ? ", DAYWALKER_API_KEY" : ""}${signingKeyStr ? ", DAYWALKER_SIGNING_KEY" : ""}`);
     if (kid)
         console.log(`  • Key ID (RFC 7638 thumbprint): ${kid}`);
     if (registered)
@@ -275,15 +275,14 @@ async function rotate(opts) {
     // The new key only becomes active once Daywalker Auth knows it, so registration must succeed
     // before anything is written (unless the caller explicitly registers it some other way).
     if (!skipRegister(opts)) {
-        if (!apiKey || !slug) {
-            fail("rotate needs DAYWALKER_API_KEY and DAYWALKER_SERVICE_SLUG to register the new key (or pass --skip-register to write it unregistered)");
+        if (!apiKey) {
+            fail("rotate needs DAYWALKER_API_KEY to register the new key (or pass --skip-register to write it unregistered)");
         }
         if (!isJson)
             console.log(`• Registering new public key (${key.publicJwk.kid}) with Daywalker Auth...`);
         const regResult = await registerPublicKey({
             authUrl,
             apiKey,
-            serviceSlug: slug,
             domain: rotateDomain,
             publicJwk: key.publicJwk,
         });

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedConfig } from "./config.js";
-import { type DaywalkerConfig, type IssueLeaseOptions, type LeaseResponse, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+import { type DaywalkerConfig, type TokenSet, type GetTokensOptions, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
 /** Validation results kept in memory; the least recently used are evicted past this. */
 export declare const MAX_VALIDATION_CACHE_ENTRIES = 1000;
 /** Longest 429 `Retry-After` waited out by default (`retry.maxRetryAfterMs`); longer ones return the 429. */
@@ -28,6 +28,9 @@ export declare class Daywalker {
     get config(): ResolvedConfig;
     toJSON(): Record<string, unknown>;
     private getLoadedSigningKey;
+    private _dpopKey;
+    /** The client's DPoP key, generated on first use. Issued tokens are bound to it for this client's life. */
+    private getDpopKey;
     private getLoadedPreviousSigningKey;
     /**
      * Signs and executes a request to Daywalker Auth (same origin as `authUrl` only).
@@ -83,12 +86,27 @@ export declare class Daywalker {
         serviceSlug?: string;
         offlineOnly?: boolean;
     }): Promise<TokenPayload>;
+    private _tokens;
+    private _tokenFlight;
+    private _tokenRequest;
     /**
-     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
-     * The lease lists every service slug the API key covers (`services`, also the JWT's `services` and `aud`
-     * claims), so one set of credentials serves all of them. Pass `{ services: [...] }` to narrow it.
+     * Client credentials grant (RFC 6749 §4.4): the signed request (API key + registered Ed25519 key) is
+     * exchanged for a short-lived access token JWT listing every service the credentials cover, and a
+     * rotating refresh token. No service slug is sent. The tokens are remembered for `accessToken()`.
      */
-    issueLease(options?: number | IssueLeaseOptions): Promise<LeaseResponse>;
+    getTokens(options?: GetTokensOptions): Promise<TokenSet>;
+    /**
+     * Refresh token rotation: trades the refresh token for a NEW access token and a NEW refresh token; the
+     * old refresh token stops working. Presenting an old one again revokes the whole session, so refreshes
+     * are serialized per client and the new refresh token must replace the stored one.
+     */
+    refreshTokens(refreshToken?: string): Promise<TokenSet>;
+    /**
+     * A valid access token, refreshing (or re-authenticating with the client credentials once the session
+     * ended) when it is within 30 seconds of expiry. Concurrent callers share one request, so the single-use
+     * refresh token is never presented twice.
+     */
+    accessToken(): Promise<string>;
     /**
      * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
      * Uses the configured `fetch`, sends no credentials, never follows redirects and times out after `timeoutMs`.

package/dist/client.js

@@ -1,5 +1,5 @@
 import { parseServiceSlugs, resolveConfig } from "./config.js";
-import { loadSigningKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, } from "./crypto/index.js";
+import { loadSigningKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, generateDpopKey, createDpopProof, } from "./crypto/index.js";
 import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
     if (!headerValue)
@@ -173,6 +173,7 @@ function malformedValidation(json, payloadData) {
 function cloneResult(result) {
     return typeof structuredClone === "function" ? structuredClone(result) : JSON.parse(JSON.stringify(result));
 }
+const DEFAULT_ISSUER = "https://auth.daywalker.dev";
 export class Daywalker {
     _config;
     _rawConfig;
@@ -213,6 +214,11 @@ export class Daywalker {
         }
         return this._signingKeyPromise;
     }
+    _dpopKey = null;
+    /** The client's DPoP key, generated on first use. Issued tokens are bound to it for this client's life. */
+    getDpopKey() {
+        return (this._dpopKey ??= generateDpopKey());
+    }
     async getLoadedPreviousSigningKey() {
         const raw = this._config.previousSigningKey;
         if (!raw)
@@ -283,6 +289,14 @@ export class Daywalker {
             if (idempotencyKey && !headers.has("idempotency-key")) {
                 headers.set("idempotency-key", idempotencyKey);
             }
+            // DPoP (RFC 9449) is mandatory on the token endpoint and when presenting a DPoP access token.
+            const auth = headers.get("authorization") ?? "";
+            const isDpopAuth = /^dpop\s+/i.test(auth);
+            const isTokenEndpoint = url.pathname === "/api/v1/oauth/token";
+            if (!headers.has("dpop") && (isTokenEndpoint || isDpopAuth)) {
+                const accessToken = isDpopAuth ? auth.replace(/^dpop\s+/i, "") : undefined;
+                headers.set("dpop", await createDpopProof(await this.getDpopKey(), { method, url: url.toString(), accessToken }));
+            }
             if (signingKey) {
                 // apiKey is left out so the signer can't replace an explicit Authorization header.
                 const signedHeaders = await signRequest({
@@ -412,7 +426,7 @@ export class Daywalker {
                 token,
                 publicKey: this._config.daywalkerPublicKey,
                 expectedServiceSlug: serviceSlug || undefined,
-                expectedIssuer: this._config.leaseIssuer ?? undefined,
+                expectedIssuer: this._config.leaseIssuer ?? DEFAULT_ISSUER,
             });
             if (jwtResult.valid && jwtResult.payload) {
                 const payload = jwtResult.payload;
@@ -487,10 +501,8 @@ export class Daywalker {
             message: redactSecrets(message),
         });
         try {
+            // No service slug is sent: the caller is identified by its credentials, not by naming a service
             const validateBody = { token };
-            if (serviceSlug) {
-                validateBody.serviceSlug = serviceSlug;
-            }
             const res = await this.fetch("/api/v1/tokens/validate", {
                 method: "POST",
                 body: validateBody,
@@ -608,31 +620,88 @@ export class Daywalker {
         }
         return result.data;
     }
+    _tokens = null;
+    _tokenFlight = null;
+    async _tokenRequest(body) {
+        const res = await this.fetch("/api/v1/oauth/token", { method: "POST", body });
+        const json = (await res.json().catch(() => ({})));
+        if (res.status !== 200) {
+            throw new DaywalkerAuthError(redactSecrets(String(json.message || json.error || `Token request failed with HTTP ${res.status}`)), res.status, json.code ?? json.error);
+        }
+        if (typeof json.access_token !== "string" || typeof json.refresh_token !== "string") {
+            throw new DaywalkerAuthError("Daywalker Auth returned a malformed token response", res.status, "SERVICE_UNAVAILABLE");
+        }
+        const services = Array.isArray(json.services) ? json.services.filter((x) => typeof x === "string") : [];
+        return {
+            accessToken: json.access_token,
+            refreshToken: json.refresh_token,
+            tokenType: String(json.token_type ?? "DPoP"),
+            expiresAt: Number(json.expires_at) || Math.floor(Date.now() / 1000) + Number(json.expires_in ?? 0),
+            expiresIn: Number(json.expires_in ?? 0),
+            refreshExpiresIn: Number(json.refresh_expires_in ?? 0),
+            scope: String(json.scope ?? services.join(" ")),
+            services,
+            jwksUri: typeof json.jwks_uri === "string" ? json.jwks_uri : undefined,
+        };
+    }
     /**
-     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
-     * The lease lists every service slug the API key covers (`services`, also the JWT's `services` and `aud`
-     * claims), so one set of credentials serves all of them. Pass `{ services: [...] }` to narrow it.
+     * Client credentials grant (RFC 6749 §4.4): the signed request (API key + registered Ed25519 key) is
+     * exchanged for a short-lived access token JWT listing every service the credentials cover, and a
+     * rotating refresh token. No service slug is sent. The tokens are remembered for `accessToken()`.
      */
-    async issueLease(options) {
-        const opts = typeof options === "number" ? { ttlSeconds: options } : (options ?? {});
-        const services = opts.services ? parseServiceSlugs(opts.services) : undefined;
-        if (opts.services && (!services || services.length === 0)) {
-            throw new DaywalkerAuthError("issueLease: services must list at least one service slug", 400, "INVALID_REQUEST");
-        }
-        const res = await this.fetch("/api/v1/leases/issue", {
-            method: "POST",
-            body: { ...(opts.ttlSeconds ? { ttlSeconds: opts.ttlSeconds } : {}), ...(services ? { services } : {}) },
+    async getTokens(options = {}) {
+        const scope = options.scope ? parseServiceSlugs(options.scope) : undefined;
+        if (options.scope && (!scope || scope.length === 0)) {
+            throw new DaywalkerAuthError("getTokens: scope must list at least one service slug", 400, "INVALID_REQUEST");
+        }
+        const tokens = await this._tokenRequest({
+            grant_type: "client_credentials",
+            ...(scope ? { scope: scope.join(" ") } : {}),
+            ...(options.expiresIn ? { expires_in: options.expiresIn } : {}),
         });
-        const json = (await res.json().catch(() => ({})));
-        if (res.status !== 201 && res.status !== 200) {
-            throw new DaywalkerAuthError(redactSecrets(String(json.message || json.error || `Lease issue failed with HTTP ${res.status}`)), res.status, json.error);
-        }
-        if (typeof json.lease !== "string") {
-            throw new DaywalkerAuthError("Daywalker Auth returned a malformed lease response (no lease)", res.status, "SERVICE_UNAVAILABLE");
+        this._tokens = tokens;
+        return tokens;
+    }
+    /**
+     * Refresh token rotation: trades the refresh token for a NEW access token and a NEW refresh token; the
+     * old refresh token stops working. Presenting an old one again revokes the whole session, so refreshes
+     * are serialized per client and the new refresh token must replace the stored one.
+     */
+    async refreshTokens(refreshToken) {
+        const token = refreshToken ?? this._tokens?.refreshToken;
+        if (!token)
+            throw new DaywalkerAuthError("refreshTokens: no refresh token (call getTokens() first)", 400, "INVALID_REQUEST");
+        const tokens = await this._tokenRequest({ grant_type: "refresh_token", refresh_token: token });
+        this._tokens = tokens;
+        return tokens;
+    }
+    /**
+     * A valid access token, refreshing (or re-authenticating with the client credentials once the session
+     * ended) when it is within 30 seconds of expiry. Concurrent callers share one request, so the single-use
+     * refresh token is never presented twice.
+     */
+    async accessToken() {
+        const current = this._tokens;
+        if (current && current.expiresAt - 30 > Math.floor(Date.now() / 1000))
+            return current.accessToken;
+        if (!this._tokenFlight) {
+            this._tokenFlight = (async () => {
+                if (current) {
+                    try {
+                        return await this.refreshTokens();
+                    }
+                    catch (err) {
+                        if (!(err instanceof DaywalkerAuthError) || err.status !== 400)
+                            throw err;
+                        // invalid_grant: the session ended or was revoked; start a new one
+                    }
+                }
+                return this.getTokens();
+            })().finally(() => {
+                this._tokenFlight = null;
+            });
         }
-        // Servers from before multi-service tokens don't list services; their lease covers the one configured slug.
-        const listed = Array.isArray(json.services) ? json.services.filter((s) => typeof s === "string") : [];
-        return { ...json, lease: json.lease, services: listed.length > 0 ? listed : this._config.serviceSlug ? [this._config.serviceSlug] : [] };
+        return (await this._tokenFlight).accessToken;
     }
     /**
      * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.

package/dist/config.js

@@ -82,8 +82,6 @@ export function resolveConfig(options = {}) {
     const serviceSlug = serviceSlugs[0] ?? null;
     if (!apiKey)
         problems.push("DAYWALKER_API_KEY is not set");
-    if (!serviceSlug)
-        problems.push("DAYWALKER_SERVICE_SLUG is not set");
     const signingKey = options.signingKey ?? env.DAYWALKER_SIGNING_KEY ?? null;
     const previousSigningKey = options.previousSigningKey ?? env.DAYWALKER_SIGNING_KEY_PREVIOUS ?? null;
     const keyId = (options.keyId ?? env.DAYWALKER_KEY_ID ?? "").trim() || null;

package/dist/cookies.d.ts

@@ -0,0 +1,37 @@
+import type { AccessTokenUser } from "./types.js";
+export interface TokenCookieOptions {
+    /** Default `Strict`. Use `Lax` only if users must arrive logged in from links on other sites. */
+    sameSite?: "Strict" | "Lax";
+    /** Default `/`. Scope a refresh token cookie to your refresh route, e.g. `/api/auth/refresh`. */
+    path?: string;
+    /** Lifetime in seconds. */
+    maxAge: number;
+    domain?: string;
+    /** Default true. Only disable for plain-http localhost development. */
+    secure?: boolean;
+}
+/**
+ * `Set-Cookie` header value for a JWT: always `HttpOnly` (scripts, so XSS, can't read it), `Secure`
+ * and `SameSite=Strict` (or `Lax`) so cross-site requests (CSRF) don't carry it. Throws on values that
+ * could inject attributes.
+ */
+export declare function buildTokenCookie(name: string, value: string, options: TokenCookieOptions): string;
+/** `Set-Cookie` value that deletes a cookie set with `buildTokenCookie` (use the same path/domain). */
+export declare function clearTokenCookie(name: string, options?: Pick<TokenCookieOptions, "path" | "domain" | "sameSite" | "secure">): string;
+/**
+ * The two cookies for a web app's session: the access token (`dw_at`, sent everywhere) and the refresh
+ * token (`dw_rt`, only sent to `refreshPath`). Both HttpOnly + Secure + SameSite.
+ */
+export declare function daywalkerCookies(tokens: {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    refreshExpiresIn: number;
+}, options?: {
+    refreshPath?: string;
+    sameSite?: "Strict" | "Lax";
+    secure?: boolean;
+    domain?: string;
+}): string[];
+/** The `user` object (public UUID, name, email) of an access token payload that was already verified. */
+export declare function accessTokenUser(payload: Record<string, unknown>): AccessTokenUser | null;

package/dist/cookies.js

@@ -0,0 +1,58 @@
+const COOKIE_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+const COOKIE_PATH = /^\/[\x21-\x3a\x3c-\x7e]*$/;
+const COOKIE_DOMAIN = /^[A-Za-z0-9.-]+$/;
+/**
+ * `Set-Cookie` header value for a JWT: always `HttpOnly` (scripts, so XSS, can't read it), `Secure`
+ * and `SameSite=Strict` (or `Lax`) so cross-site requests (CSRF) don't carry it. Throws on values that
+ * could inject attributes.
+ */
+export function buildTokenCookie(name, value, options) {
+    if (!COOKIE_NAME.test(name))
+        throw new TypeError("Invalid cookie name");
+    if (!/^[A-Za-z0-9._~+/=-]+$/.test(value))
+        throw new TypeError("Invalid cookie value: expected a JWT");
+    const path = options.path ?? "/";
+    if (!COOKIE_PATH.test(path))
+        throw new TypeError("Invalid cookie path");
+    if (options.domain !== undefined && !COOKIE_DOMAIN.test(options.domain))
+        throw new TypeError("Invalid cookie domain");
+    if (!Number.isFinite(options.maxAge) || options.maxAge < 0)
+        throw new TypeError("maxAge must be a non-negative number of seconds");
+    const sameSite = options.sameSite ?? "Strict";
+    if (sameSite !== "Strict" && sameSite !== "Lax")
+        throw new TypeError("sameSite must be Strict or Lax");
+    return [
+        `${name}=${value}`,
+        `Path=${path}`,
+        `Max-Age=${Math.floor(options.maxAge)}`,
+        ...(options.domain ? [`Domain=${options.domain}`] : []),
+        "HttpOnly",
+        ...(options.secure === false ? [] : ["Secure"]),
+        `SameSite=${sameSite}`,
+    ].join("; ");
+}
+/** `Set-Cookie` value that deletes a cookie set with `buildTokenCookie` (use the same path/domain). */
+export function clearTokenCookie(name, options = {}) {
+    return buildTokenCookie(name, "deleted", { ...options, maxAge: 0 }).replace("=deleted;", "=;");
+}
+/**
+ * The two cookies for a web app's session: the access token (`dw_at`, sent everywhere) and the refresh
+ * token (`dw_rt`, only sent to `refreshPath`). Both HttpOnly + Secure + SameSite.
+ */
+export function daywalkerCookies(tokens, options = {}) {
+    const common = { sameSite: options.sameSite, secure: options.secure, domain: options.domain };
+    return [
+        buildTokenCookie("dw_at", tokens.accessToken, { ...common, path: "/", maxAge: tokens.expiresIn }),
+        buildTokenCookie("dw_rt", tokens.refreshToken, { ...common, path: options.refreshPath ?? "/api/auth/refresh", maxAge: tokens.refreshExpiresIn }),
+    ];
+}
+/** The `user` object (public UUID, name, email) of an access token payload that was already verified. */
+export function accessTokenUser(payload) {
+    const u = payload.user;
+    if (!u || typeof u !== "object")
+        return null;
+    const { id, name, email } = u;
+    if (typeof id !== "string" || typeof email !== "string")
+        return null;
+    return { id, name: typeof name === "string" ? name : null, email };
+}

package/dist/crypto/dpop.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DPoP (RFC 9449) proof-of-possession. Daywalker binds every access and refresh token to a client key and
+ * requires a fresh proof on each token request, refresh and validate call.
+ */
+export interface DpopKey {
+    privateKey: CryptoKey;
+    publicJwk: {
+        kty: "OKP";
+        crv: "Ed25519";
+        x: string;
+    };
+}
+/** A new in-memory Ed25519 DPoP key. Tokens are bound to it, so keep it for the life of the session. */
+export declare function generateDpopKey(): Promise<DpopKey>;
+/**
+ * Builds a DPoP proof JWT for one request. `htu` is the URL without query or fragment. Pass the access token
+ * to add `ath` (its SHA-256, base64url) when presenting it with `Authorization: DPoP`.
+ */
+export declare function createDpopProof(key: DpopKey, params: {
+    method: string;
+    url: string;
+    accessToken?: string;
+}): Promise<string>;

package/dist/crypto/dpop.js

@@ -0,0 +1,28 @@
+import { bytesToBase64Url, stringToUtf8 } from "./encoding.js";
+import { sha256Base64Url } from "./digest.js";
+/** A new in-memory Ed25519 DPoP key. Tokens are bound to it, so keep it for the life of the session. */
+export async function generateDpopKey() {
+    const pair = (await globalThis.crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]));
+    const jwk = (await globalThis.crypto.subtle.exportKey("jwk", pair.publicKey));
+    return { privateKey: pair.privateKey, publicJwk: { kty: "OKP", crv: "Ed25519", x: jwk.x } };
+}
+const b64u = (value) => bytesToBase64Url(stringToUtf8(JSON.stringify(value)));
+/**
+ * Builds a DPoP proof JWT for one request. `htu` is the URL without query or fragment. Pass the access token
+ * to add `ath` (its SHA-256, base64url) when presenting it with `Authorization: DPoP`.
+ */
+export async function createDpopProof(key, params) {
+    const u = new URL(params.url);
+    const header = { typ: "dpop+jwt", alg: "EdDSA", jwk: key.publicJwk };
+    const claims = {
+        jti: globalThis.crypto.randomUUID(),
+        htm: params.method.toUpperCase(),
+        htu: `${u.origin}${u.pathname}`,
+        iat: Math.floor(Date.now() / 1000),
+    };
+    if (params.accessToken)
+        claims.ath = await sha256Base64Url(params.accessToken);
+    const signingInput = `${b64u(header)}.${b64u(claims)}`;
+    const sig = new Uint8Array(await globalThis.crypto.subtle.sign({ name: "Ed25519" }, key.privateKey, stringToUtf8(signingInput)));
+    return `${signingInput}.${bytesToBase64Url(sig)}`;
+}

package/dist/crypto/index.d.ts

@@ -3,3 +3,5 @@ export { DEFAULT_MAX_BODY_SIZE_BYTES, computeContentDigest, sha256Base64, sha256
 export { calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, } from "./keys.js";
 export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, leaseServices, registerPublicKey, } from "./signatures.js";
 export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, ReplayStore, } from "./signatures.js";
+export { generateDpopKey, createDpopProof } from "./dpop.js";
+export type { DpopKey } from "./dpop.js";

package/dist/crypto/index.js

@@ -2,3 +2,4 @@ export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64
 export { DEFAULT_MAX_BODY_SIZE_BYTES, computeContentDigest, sha256Base64, sha256Base64Url, } from "./digest.js";
 export { calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, } from "./keys.js";
 export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, leaseServices, registerPublicKey, } from "./signatures.js";
+export { generateDpopKey, createDpopProof } from "./dpop.js";

package/dist/crypto/signatures.d.ts

@@ -93,8 +93,8 @@ export declare function verifyRequestSignature(params: VerifySignatureParams): P
  * single `serviceSlug` / `service` claim of leases issued before multi-service tokens.
  */
 export declare function leaseServices(payload: Record<string, unknown>): string[];
-/** Clock skew tolerated on JWT lease `exp` / `nbf`. */
-export declare const JWT_CLOCK_SKEW_SECONDS = 60;
+/** Clock skew tolerated on JWT `exp` / `nbf`: 30 seconds, and never more (see `clockSkewSeconds`). */
+export declare const JWT_CLOCK_SKEW_SECONDS = 30;
 /**
  * Zero-egress offline verification for asymmetric JWT token leases.
  * Requires a numeric `exp` and an audience (`aud` or `serviceSlug`) equal to `expectedServiceSlug`;

package/dist/crypto/signatures.js

@@ -415,8 +415,8 @@ export function leaseServices(payload) {
     const fallback = listed.length > 0 ? listed : strings(payload.aud).length > 0 ? strings(payload.aud) : strings(payload.serviceSlug ?? payload.service);
     return Array.from(new Set(fallback.map((s) => s.toLowerCase())));
 }
-/** Clock skew tolerated on JWT lease `exp` / `nbf`. */
-export const JWT_CLOCK_SKEW_SECONDS = 60;
+/** Clock skew tolerated on JWT `exp` / `nbf`: 30 seconds, and never more (see `clockSkewSeconds`). */
+export const JWT_CLOCK_SKEW_SECONDS = 30;
 /**
  * Zero-egress offline verification for asymmetric JWT token leases.
  * Requires a numeric `exp` and an audience (`aud` or `serviceSlug`) equal to `expectedServiceSlug`;
@@ -450,7 +450,8 @@ export async function verifyJwtLease(params) {
         if (header.alg !== "EdDSA" && header.alg !== "ed25519") {
             return { valid: false, error: `Unsupported JWT alg: ${header.alg}` };
         }
-        if (header.typ !== undefined && String(header.typ).toUpperCase() !== "JWT") {
+        // "JWT" (older leases) or "at+jwt" (RFC 9068 access tokens); a refresh token ("rt+jwt") is never accepted here
+        if (header.typ !== undefined && !["JWT", "AT+JWT"].includes(String(header.typ).toUpperCase())) {
             return { valid: false, error: `Unsupported JWT typ: ${header.typ}` };
         }
         // RFC 7515 §4.1.11: extensions we don't understand must be rejected; we implement none.
@@ -467,7 +468,10 @@ export async function verifyJwtLease(params) {
             return { valid: false, error: "JWT signature verification failed" };
         }
         const now = params.currentTime ?? Math.floor(Date.now() / 1000);
-        const skew = Math.max(0, Math.min(params.clockSkewSeconds ?? JWT_CLOCK_SKEW_SECONDS, 300));
+        const skew = Math.max(0, Math.min(params.clockSkewSeconds ?? JWT_CLOCK_SKEW_SECONDS, JWT_CLOCK_SKEW_SECONDS));
+        if (typeof payload.jti !== "string" || payload.jti === "") {
+            return { valid: false, error: "JWT has no jti claim" };
+        }
         if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
             return { valid: false, error: "JWT token lease has no numeric exp claim" };
         }

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, } from "./client.js";
 export type { DaywalkerFetchInit, } from "./client.js";
 export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
-export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, LeaseResponse, IssueLeaseOptions, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
+export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, TokenSet, GetTokensOptions, AccessTokenUser, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
 export { resolveConfig, parseServiceSlugs, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
 export type { ResolvedConfig, } from "./config.js";
 export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, leaseServices, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
 export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, ReplayStore, } from "./crypto/index.js";
+export { buildTokenCookie, clearTokenCookie, daywalkerCookies, accessTokenUser } from "./cookies.js";
+export type { TokenCookieOptions } from "./cookies.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATI
 export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
 export { resolveConfig, parseServiceSlugs, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
 export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, leaseServices, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
+export { buildTokenCookie, clearTokenCookie, daywalkerCookies, accessTokenUser } from "./cookies.js";

package/dist/types.d.ts

@@ -109,25 +109,35 @@ export interface DaywalkerConfig {
     fetch?: typeof fetch;
     env?: Record<string, string | undefined>;
 }
-/** Response of `client.issueLease()` (POST /api/v1/leases/issue). */
-export interface LeaseResponse {
-    /** The signed EdDSA JWT. Verify it with Daywalker's public JWKS. */
-    lease: string;
-    tokenType?: string;
+/** Tokens from the client credentials flow (POST /api/v1/oauth/token). */
+export interface TokenSet {
+    /** Short-lived (5-15 min) EdDSA JWT. Verify it with Daywalker's public JWKS. */
+    accessToken: string;
+    /** Single use: every refresh returns a new one. Keep it server-side. */
+    refreshToken: string;
+    tokenType: string;
     /** Unix seconds. */
-    expiresAt?: number | string;
-    jwksUri?: string;
-    /** Every service slug the lease covers (also its `services` and `aud` claims). */
+    expiresAt: number;
+    expiresIn: number;
+    /** Seconds until the session ends and the client credentials must be used again. */
+    refreshExpiresIn: number;
+    scope: string;
+    /** Every service slug the access token covers (also its `services` and `aud` claims). */
     services: string[];
+    jwksUri?: string;
 }
-export interface IssueLeaseOptions {
-    /** Lease lifetime in seconds (Daywalker clamps it to 1h-24h). */
-    ttlSeconds?: number;
-    /**
-     * Narrow the lease to these service slugs (least privilege). Each must be one the API key covers;
-     * otherwise Daywalker answers 403 `SERVICE_NOT_GRANTED`. Default: every service the key covers.
-     */
-    services?: string[];
+export interface GetTokensOptions {
+    /** Narrow the grant to these service slugs (least privilege); default: every service the credentials cover. */
+    scope?: string[];
+    /** Access token lifetime in seconds (Daywalker clamps it to 300-900). */
+    expiresIn?: number;
+}
+/** The `user` claim of an access token. */
+export interface AccessTokenUser {
+    /** The user's public UUID v7. */
+    id: string;
+    name: string | null;
+    email: string;
 }
 export interface SelfCheckResult {
     ok: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Daywalker Auth service validation plus the DevPulse client SDKs (feature flags, OpenFeature, product analytics) in one package with a single runtime dependency (re2js).",
   "type": "module",
   "main": "./dist/index.js",