@shelbyb/daywalker-sdk 0.1.2 → 0.1.4

package/README.md

@@ -34,8 +34,8 @@ npm install @shelbyb/daywalker-sdk
 # Generate Ed25519 keypair and write .env.local
 npx daywalker init --service my-service-slug
 
-# Or register the public key immediately with Daywalker Auth:
-npx daywalker init --service my-service-slug --api-key srv_live_...
+# Or register the public key immediately with Daywalker Auth (domain is required by the API):
+npx daywalker init --service my-service-slug --domain app.example.com --api-key srv_live_...
 
 # Pipe JSON secrets directly into Vercel, Fly.io, DigitalOcean, or AWS SSM:
 npx daywalker init --service my-service-slug --api-key srv_live_... --json
@@ -43,7 +43,7 @@ npx daywalker init --service my-service-slug --api-key srv_live_... --json
 
 `daywalker init`:
 - Generates an Ed25519 keypair locally using WebCrypto (`crypto.subtle`)
-- Registers the public JWK directly with `POST https://auth.daywalker.dev/api/v1/keys/register`
+- Registers the public JWK directly with `POST https://auth.daywalker.dev/api/v1/keys/register` (`Authorization: Bearer <API key>`, body `{ keyId, domain, publicKey }`; responds `201`)
 - Writes `DAYWALKER_SERVICE_SLUG`, `DAYWALKER_KEY_ID`, `DAYWALKER_SIGNING_KEY`, and `DAYWALKER_AUTH_URL` to `.env.local`
 - No route injectors or public `/.well-known/` endpoints needed
 
@@ -193,14 +193,29 @@ const result = await client.validateToken(incomingJwt);
 
 ---
 
+## API Reference (per the [OpenAPI spec](https://auth.daywalker.dev/docs))
+
+| 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 }` |
+| `POST /api/v1/leases/issue` | `client.issueLease(ttlSeconds?)` | Signed request returns `{ lease, tokenType, expiresAt, jwksUri }` (EdDSA JWT) |
+| `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>`.
+
+---
+
 ## Request Signing Specification (RFC 9421 & RFC 9530)
 
 Each outbound request signed by `@shelbyb/daywalker-sdk` includes:
 - `Content-Digest: sha-256=:<base64-encoded-hash>:`
-- `Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");created=<unix_seconds>;keyid="<kid>";alg="ed25519"`
+- `Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");created=<unix_seconds>;keyid="<kid>";alg="ed25519";nonce="<random>"`
 - `Signature: sig1=:<base64-encoded-signature>:`
 - `Authorization: Bearer <DAYWALKER_API_KEY>`
 
+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).
+
 The exact signature base and test cases are verified against [`test-vectors/signing-rfc9421.json`](./test-vectors/signing-rfc9421.json).
 
 ---

package/dist/cli.js

@@ -171,6 +171,7 @@ async function rotate(opts) {
     const slug = String(opts.service ?? existing.get("DAYWALKER_SERVICE_SLUG") ?? process.env.DAYWALKER_SERVICE_SLUG ?? "").trim().toLowerCase();
     const apiKey = String(opts["api-key"] ?? existing.get("DAYWALKER_API_KEY") ?? process.env.DAYWALKER_API_KEY ?? "").trim() || null;
     const authUrl = String(opts["auth-url"] ?? existing.get("DAYWALKER_AUTH_URL") ?? process.env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    const rotateDomain = publicHostname(String(opts.domain ?? existing.get("DAYWALKER_DOMAIN") ?? process.env.DAYWALKER_DOMAIN ?? ""));
     const key = await generateSigningKey();
     if (apiKey && slug) {
         if (!isJson)
@@ -179,6 +180,7 @@ async function rotate(opts) {
             authUrl,
             apiKey,
             serviceSlug: slug,
+            domain: rotateDomain,
             publicJwk: key.publicJwk,
         });
         if (regResult.ok) {

package/dist/client.d.ts

@@ -9,6 +9,7 @@ export declare class Daywalker {
     private readonly _rawConfig;
     private _signingKeyPromise?;
     private readonly _cache;
+    private readonly _inflight;
     constructor(config?: DaywalkerConfig);
     get config(): ResolvedConfig;
     toJSON(): Record<string, unknown>;
@@ -31,6 +32,7 @@ export declare class Daywalker {
         forceRefresh?: boolean;
         offlineOnly?: boolean;
     }): Promise<ValidateResult>;
+    private _validateOnline;
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */
@@ -42,6 +44,21 @@ export declare class Daywalker {
         serviceSlug?: string;
         offlineOnly?: boolean;
     }): Promise<TokenPayload>;
+    /**
+     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
+     */
+    issueLease(ttlSeconds?: number): Promise<{
+        lease: string;
+        tokenType?: string;
+        expiresAt?: string;
+        jwksUri?: string;
+    }>;
+    /**
+     * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
+     */
+    fetchJwks(): Promise<{
+        keys: PublicJwk[];
+    }>;
     /**
      * The public JWK(s) configured for this service.
      */

package/dist/client.js

@@ -1,6 +1,6 @@
 import { resolveConfig } from "./config.js";
 import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, } from "./crypto/index.js";
-import { DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
+import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
     if (!headerValue)
         return undefined;
@@ -15,11 +15,20 @@ function parseRetryAfter(headerValue) {
     }
     return undefined;
 }
+function generateNonce() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 export class Daywalker {
     _config;
     _rawConfig;
     _signingKeyPromise;
     _cache = new Map();
+    _inflight = new Map();
     constructor(config = {}) {
         this._rawConfig = config;
         this._config = resolveConfig(config);
@@ -104,6 +113,7 @@ export class Daywalker {
                     key: signingKey,
                     keyid: this._config.keyId ?? undefined,
                     apiKey: this._config.apiKey ?? undefined,
+                    nonce: generateNonce(),
                 });
                 for (const [k, v] of Object.entries(signedHeaders)) {
                     if (v !== undefined) {
@@ -231,7 +241,25 @@ export class Daywalker {
                 message: "Offline verification requires DAYWALKER_PUBLIC_KEY and a valid JWT token lease",
             };
         }
-        // Online verification
+        // Online verification, deduplicated across concurrent callers
+        const inflightKey = `${cacheKey}`;
+        const pending = this._inflight.get(inflightKey);
+        if (pending)
+            return pending;
+        const run = this._validateOnline(token, serviceSlug, cacheKey).finally(() => {
+            this._inflight.delete(inflightKey);
+        });
+        this._inflight.set(inflightKey, run);
+        return run;
+    }
+    async _validateOnline(token, serviceSlug, cacheKey) {
+        const negTtl = this._config.negativeCacheTtlMs;
+        const fail = (result) => {
+            if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR") {
+                this._cache.set(cacheKey, { result, expiresAt: Date.now() + negTtl });
+            }
+            return result;
+        };
         try {
             const validateBody = { token };
             if (serviceSlug) {
@@ -282,12 +310,12 @@ export class Daywalker {
             else if (json.error === "REVOKED" || /revoked/i.test(errMsg)) {
                 error = "REVOKED";
             }
-            return {
+            return fail({
                 ok: false,
                 error,
                 status: res.status,
                 message: redactSecrets(errMsg || `Validation failed with HTTP ${res.status}`),
-            };
+            });
         }
         catch (err) {
             return {
@@ -311,6 +339,29 @@ export class Daywalker {
         }
         return result.data;
     }
+    /**
+     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
+     */
+    async issueLease(ttlSeconds) {
+        const res = await this.fetch("/api/v1/leases/issue", {
+            method: "POST",
+            body: ttlSeconds ? { ttlSeconds } : {},
+        });
+        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);
+        }
+        return json;
+    }
+    /**
+     * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
+     */
+    async fetchJwks() {
+        const res = await globalThis.fetch(`${this._config.authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`, { headers: { Accept: "application/json" } });
+        if (!res.ok)
+            throw new DaywalkerError(`Could not fetch JWKS (HTTP ${res.status})`, res.status);
+        return (await res.json());
+    }
     /**
      * The public JWK(s) configured for this service.
      */

package/dist/config.d.ts

@@ -10,6 +10,7 @@ export interface ResolvedConfig {
     daywalkerPublicKey: string | PublicJwk | null;
     authUrl: string;
     cacheTtlMs: number;
+    negativeCacheTtlMs: number;
     maxRetries: number;
     problems: string[];
 }

package/dist/config.js

@@ -82,6 +82,7 @@ export function resolveConfig(options = {}) {
     const daywalkerPublicKey = options.daywalkerPublicKey ?? (env.DAYWALKER_PUBLIC_KEY ? env.DAYWALKER_PUBLIC_KEY.trim() : null);
     const authUrl = (options.authUrl ?? env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
     const cacheTtlMs = options.cacheTtlMs ?? 60_000;
+    const negativeCacheTtlMs = options.negativeCacheTtlMs ?? 3_000;
     const maxRetries = options.maxRetries ?? (options.retry?.maxRetries ?? 3);
     return {
         apiKey,
@@ -94,6 +95,7 @@ export function resolveConfig(options = {}) {
         daywalkerPublicKey,
         authUrl,
         cacheTtlMs,
+        negativeCacheTtlMs,
         maxRetries,
         problems,
     };

package/dist/crypto/signatures.js

@@ -296,6 +296,9 @@ export async function registerPublicKey(params) {
     const authUrl = (params.authUrl ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
     const registerUrl = `${authUrl}/api/v1/keys/register`;
     const doFetch = params.fetchFn ?? globalThis.fetch;
+    if (!params.domain) {
+        return { ok: false, status: 400, error: "domain is required to register a key (set --domain or DAYWALKER_DOMAIN)" };
+    }
     try {
         const res = await doFetch(registerUrl, {
             method: "POST",
@@ -306,8 +309,7 @@ export async function registerPublicKey(params) {
             },
             body: JSON.stringify({
                 keyId: params.publicJwk.kid,
-                domain: params.domain ?? undefined,
-                serviceSlug: params.serviceSlug ?? undefined,
+                domain: params.domain,
                 publicKey: params.publicJwk,
             }),
         });

package/dist/types.d.ts

@@ -57,6 +57,8 @@ export interface DaywalkerConfig {
     daywalkerPublicKey?: string | PublicJwk;
     authUrl?: string;
     cacheTtlMs?: number;
+    /** Short cache for failed validations (not 429/network errors). Default 3000ms; 0 disables. */
+    negativeCacheTtlMs?: number;
     maxRetries?: number;
     retry?: RetryOptions;
     fetch?: typeof fetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Validate Daywalker API tokens and make domain-signed calls to Daywalker Auth from any service.",
   "type": "module",
   "main": "./dist/index.js",