@shelbyb/daywalker-sdk 0.6.0 → 0.8.0

package/dist/next.js

@@ -1,5 +1,5 @@
 import { daywalker, Daywalker } from "./client.js";
-import { toAuthFailureResponse } from "./middleware.js";
+import { readCredentials, toAuthFailureResponse } from "./middleware.js";
 /**
  * Real Server Action IDs are hex hashes. Scanners probing for CVE-2025-55182 (React2Shell)
  * send junk like `Next-Action: x`, which Next.js rejects with an internal error.
@@ -129,17 +129,23 @@ const REDIRECT_ERROR_CODES = new Set([
     "NETWORK_ERROR",
     "SERVICE_UNAVAILABLE",
     "CONFIGURATION_ERROR",
+    "SERVICE_NOT_GRANTED",
+    "DPOP_REQUIRED",
+    "INVALID_DPOP_PROOF",
 ]);
-function extractToken(req) {
-    const authHeader = req.headers.get("authorization");
-    if (authHeader && authHeader.toLowerCase().startsWith("bearer ")) {
-        return authHeader.slice(7).trim();
-    }
-    const apiTokenHeader = req.headers.get("x-api-token");
-    if (apiTokenHeader) {
-        return apiTokenHeader.trim();
-    }
-    return null;
+function credentialsOf(req) {
+    return readCredentials((name) => req.headers.get(name), { method: req.method, url: req.url });
+}
+/**
+ * Next's "continue" and redirect responses, built here rather than through a `NextResponse` found on
+ * `globalThis`: anything in the process could plant one there and turn a failed check into a pass.
+ * `x-middleware-next: 1` is exactly what `NextResponse.next()` sends.
+ */
+function continueResponse() {
+    return new Response(null, { headers: { "x-middleware-next": "1" } });
+}
+function redirectResponse(url) {
+    return Response.redirect(url.toString(), 307);
 }
 /**
  * Hardened Next.js Middleware for root `middleware.ts`.
@@ -147,7 +153,8 @@ function extractToken(req) {
  * Implements:
  * 1. Server Action probe defense (CVE-2025-55182 scanner mitigation)
  * 2. Static asset and health check bypass
- * 3. Per-request token auth: requests without `Authorization: Bearer` / `x-api-token` get 401
+ * 3. Per-request token auth: requests without `Authorization: Bearer` / `Authorization: DPoP` (with its
+ *    proof) / `x-api-token` get 401
  * 4. Distinct handling for API routes (JSON + CORS) vs UI pages (redirect to `errorPath` with `from`)
  *
  * Only `/_next/static/`, `/_next/image`, `/favicon.ico` and `bypassPaths` skip auth by default.
@@ -166,21 +173,22 @@ function extractToken(req) {
 export function createDaywalkerMiddleware(options = {}) {
     const client = options.client ?? daywalker;
     return buildMiddleware(options, async (request) => {
-        const token = extractToken(request);
-        if (!token) {
-            return { ok: false, error: "INVALID_TOKEN", status: 401, message: "Missing Authorization header or x-api-token" };
+        const credentials = credentialsOf(request);
+        if (!credentials.ok) {
+            return { ok: false, error: "INVALID_TOKEN", status: 401, message: credentials.message };
         }
-        return client.validateToken(token, { serviceSlug: options.serviceSlug });
+        return client.validateToken(credentials.token, { serviceSlug: options.serviceSlug, dpop: credentials.dpop });
     });
 }
 /**
- * Service health gate: checks this service's own DAYWALKER_API_KEY (not the caller's token) and
- * routes every request to `errorPath` while it is invalid, redirecting back once it heals.
+ * Service health gate: checks that this service's OAuth client credentials still get an access token
+ * covering its service (not the caller's token) and routes every request to `errorPath` while they don't,
+ * redirecting back once it heals.
  * It does NOT authenticate callers; use `createDaywalkerMiddleware` or `withDaywalkerAuth` for that.
  */
 export function createDaywalkerServiceHealthMiddleware(options = {}) {
     const client = options.client ?? daywalker;
-    return buildMiddleware(options, () => client.validateServiceKey({ serviceSlug: options.serviceSlug }));
+    return buildMiddleware(options, () => client.validateServiceCredentials({ serviceSlug: options.serviceSlug }));
 }
 function buildMiddleware(options, authenticate) {
     const bypassPaths = options.bypassPaths ?? DEFAULT_BYPASS_PATHS;
@@ -215,9 +223,7 @@ function buildMiddleware(options, authenticate) {
         // 1. Bypass static files and health check probes
         if (pathname !== null &&
             (bypassPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`)) || isStaticNormalized(pathname, matchesExtension))) {
-            return globalThis.NextResponse?.next
-                ? globalThis.NextResponse.next()
-                : new Response(null, { headers: { "x-middleware-next": "1" } });
+            return continueResponse();
         }
         // 2. Authenticate (caller's token, or the service key for the health gate)
         const authResult = await authenticate(request);
@@ -226,14 +232,10 @@ function buildMiddleware(options, authenticate) {
             if (authResult.ok) {
                 // Authorized again: heal/redirect back to home
                 const redirectUrl = new URL(homePath, request.url);
-                return globalThis.NextResponse?.redirect
-                    ? globalThis.NextResponse.redirect(redirectUrl)
-                    : Response.redirect(redirectUrl.toString(), 307);
+                return redirectResponse(redirectUrl);
             }
             // Allow rendering the error page
-            return globalThis.NextResponse?.next
-                ? globalThis.NextResponse.next()
-                : new Response(null, { headers: { "x-middleware-next": "1" } });
+            return continueResponse();
         }
         // 4. Handle invalid token for all other routes
         if (!authResult.ok) {
@@ -250,16 +252,14 @@ function buildMiddleware(options, authenticate) {
                         "Content-Type": "application/json",
                         "Access-Control-Allow-Origin": "*",
                         "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-                        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Api-Token",
+                        "Access-Control-Allow-Headers": "Content-Type, Authorization, DPoP, X-Api-Token",
                         ...(failure.retryAfter ? { "Retry-After": String(failure.retryAfter) } : {}),
                     },
                 });
             }
             // If user only wanted API protection, allow web routes through
             if (options.protectApiOnly) {
-                return globalThis.NextResponse?.next
-                    ? globalThis.NextResponse.next()
-                    : new Response(null, { headers: { "x-middleware-next": "1" } });
+                return continueResponse();
             }
             // Web UI routes: redirect to diagnostic service error screen. Only a fixed error code and
             // status are passed: the free-text message may carry server details and would let anyone
@@ -274,13 +274,9 @@ function buildMiddleware(options, authenticate) {
                     redirectUrl.searchParams.set("from", sanitized);
                 }
             }
-            return globalThis.NextResponse?.redirect
-                ? globalThis.NextResponse.redirect(redirectUrl)
-                : Response.redirect(redirectUrl.toString(), 307);
+            return redirectResponse(redirectUrl);
         }
-        return globalThis.NextResponse?.next
-            ? globalThis.NextResponse.next()
-            : new Response(null, { headers: { "x-middleware-next": "1" } });
+        return continueResponse();
     };
 }
 /**
@@ -303,11 +299,11 @@ export function withDaywalkerAuth(handler, clientOrOptions) {
         : clientOrOptions?.client ?? daywalker;
     const serviceSlug = !(clientOrOptions instanceof Daywalker) ? clientOrOptions?.serviceSlug : undefined;
     return async function daywalkerAuthHandler(req, context) {
-        const token = extractToken(req);
-        if (!token) {
-            return Response.json({ error: "INVALID_TOKEN", message: "Missing Authorization header or x-api-token" }, { status: 401 });
+        const credentials = credentialsOf(req);
+        if (!credentials.ok) {
+            return Response.json({ error: "INVALID_TOKEN", message: credentials.message }, { status: 401 });
         }
-        const result = await client.validateToken(token, { serviceSlug });
+        const result = await client.validateToken(credentials.token, { serviceSlug, dpop: credentials.dpop });
         if (!result.ok) {
             const { status, ...body } = toAuthFailureResponse(result);
             return Response.json(body, {

package/dist/types.d.ts

@@ -20,7 +20,25 @@ export interface TokenPayload {
     offlineVerified?: boolean;
     [key: string]: unknown;
 }
-export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "SERVICE_UNAVAILABLE" | "CONFIGURATION_ERROR" | string;
+/** The DPoP proof that came with an incoming `Authorization: DPoP <token>` request. */
+export interface IncomingDpop {
+    /** The `DPoP` header. */
+    proof: string | null | undefined;
+    method: string;
+    /** The full request URL (its origin is replaced by `publicOrigin` when configured). */
+    url: string;
+}
+export interface ValidateTokenOptions {
+    serviceSlug?: string;
+    forceRefresh?: boolean;
+    offlineOnly?: boolean;
+    /**
+     * The request's DPoP proof. Required to accept a DPoP-bound (`cnf.jkt`) access token; the adapters pass
+     * it for you. A bound token without a valid proof is refused with DPOP_REQUIRED / INVALID_DPOP_PROOF.
+     */
+    dpop?: IncomingDpop;
+}
+export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "SERVICE_UNAVAILABLE" | "CONFIGURATION_ERROR" | "SERVICE_NOT_GRANTED" | "DPOP_REQUIRED" | "INVALID_DPOP_PROOF" | string;
 /**
  * Failures that say nothing about the token: Daywalker Auth was unreachable, timed out, answered 5xx
  * or answered with something that isn't a validation result. Both carry status 503 and are never cached;
@@ -72,7 +90,49 @@ export interface RetryOptions {
      */
     retryNetworkErrors?: boolean;
 }
+/** A provisioned signing key as a `KeyStore` keeps it. Only keys already registered with Daywalker are stored. */
+export interface StoredSigningKey {
+    /** Record format version (1). */
+    version: 1;
+    /** RFC 7638 thumbprint of the public key; checked against the key on every load. */
+    keyId: string;
+    /** The domain the key is registered for. */
+    domain: string;
+    /** The Ed25519 private key, PKCS#8 DER in base64. */
+    privateKeyPkcs8Base64: string;
+    /** Unix seconds when it was registered. */
+    createdAt: number;
+}
+/**
+ * Where an auto-provisioned signing key lives between processes. On first use the client loads it; when
+ * there is none it generates a key, registers it with Daywalker (`POST /api/v1/keys/register`) and saves it
+ * with `saveIfAbsent`, which must be atomic (create-if-absent): when several instances start at once exactly
+ * one save wins and the others load the winner's key. A store without `saveIfAbsent` is read-only.
+ * Built in: `memoryKeyStore()` / `envKeyStore()` (`@shelbyb/daywalker-sdk/keystore`) and `fileKeyStore()`
+ * (`@shelbyb/daywalker-sdk/keystore/file`); Redis (`SET key value NX`), KV or a secrets manager fit too.
+ */
+export interface KeyStore {
+    load(): Promise<StoredSigningKey | null> | StoredSigningKey | null;
+    /** Saves `key` unless one is already stored. True when this call saved it, false when another key was there. */
+    saveIfAbsent?(key: StoredSigningKey): Promise<boolean> | boolean;
+}
+/**
+ * Signs with a key held elsewhere, typically a KMS or HSM, so the private key never exists in this process,
+ * its environment or its files. `sign` receives the RFC 9421 signature base and must return the raw 64-byte
+ * Ed25519 signature. Register the public key once (`registerPublicKey`); pass `publicJwk` so the first
+ * signature is checked against it before anything is sent.
+ */
+export interface MessageSigner {
+    /** The registered key's id (its RFC 7638 thumbprint, or the id you registered it under). */
+    keyId: string;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    publicJwk?: PublicJwk;
+}
 export interface DaywalkerConfig {
+    /**
+     * The OAuth client credential (env DAYWALKER_API_KEY). Sent only on the client credentials grant to
+     * `POST /api/v1/oauth/token`; every other request carries a DPoP-bound access token.
+     */
     apiKey?: string;
     signingKey?: string | SigningKey;
     /**
@@ -91,6 +151,12 @@ export interface DaywalkerConfig {
     domain?: string;
     /** A JWK, a JWKS (`{ keys: [...] }`, selected by the lease's `kid`), PEM, or Base64 SPKI / raw key. */
     daywalkerPublicKey?: string | PublicJwk | PublicJwks;
+    /**
+     * `"auto"` (env DAYWALKER_JWKS=auto) verifies access tokens offline against Daywalker's published key set,
+     * fetched from `${authUrl}/.well-known/jwks.json` only and cached, so signing-key rotation needs no
+     * redeploy. When no key set can be obtained, `daywalkerPublicKey` (if set) is used instead. Default off.
+     */
+    jwks?: "auto" | "off";
     /**
      * Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Daywalker documents no fixed
      * issuer, so `iss` is unchecked when unset; set it whenever leases from other issuers could share your key.
@@ -104,6 +170,34 @@ export interface DaywalkerConfig {
     maxRetries?: number;
     /** Defaults for `fetch()` retries; per-request `init.retry` overrides individual fields. */
     retry?: RetryOptions;
+    /**
+     * Origin clients use to reach this service (e.g. `https://api.example.com`), for checking the `htu` of
+     * DPoP proofs that come with bound access tokens. Defaults to the request URL's origin; set it behind a
+     * proxy or load balancer that rewrites the host.
+     */
+    publicOrigin?: string;
+    /** Shared store for DPoP proof `jti`s (default: per-process memory). Needed with several instances. */
+    dpopReplayStore?: ReplayStore;
+    /**
+     * Auto-provisioning: where the signing key is kept when `signingKey` / DAYWALKER_SIGNING_KEY isn't set.
+     * On first use the client loads it from here, or generates one, registers it for `domain` with the API key
+     * and saves it. Ignored when `signingKey` or `signer` is set.
+     */
+    keyStore?: KeyStore;
+    /**
+     * Ephemeral signing keys (env DAYWALKER_EPHEMERAL_KEY=true): the key is generated in memory, non-extractable,
+     * registered for `domain` with a lifetime (`ttlSeconds`, default 6 hours; env DAYWALKER_KEY_TTL_SECONDS) in
+     * this process's own slot (`instanceId`, default random; env DAYWALKER_INSTANCE_ID), and replaced in the
+     * same slot before it expires. Nothing is stored anywhere. `close()` revokes it at shutdown. Daywalker allows
+     * 20 live keys per domain, so give long-lived instances a stable `instanceId` (a restart then replaces its
+     * previous key) and prefer a shared `keyStore` for serverless. Can't be combined with `keyStore`.
+     */
+    ephemeralKey?: boolean | {
+        ttlSeconds?: number;
+        instanceId?: string;
+    };
+    /** Signs requests with an external key (KMS / HSM) instead of a local one. Takes precedence over everything. */
+    signer?: MessageSigner;
     /** Per-attempt timeout for requests to Daywalker Auth. Default 5000ms; 0 disables. */
     timeoutMs?: number;
     fetch?: typeof fetch;
@@ -126,6 +220,36 @@ export interface TokenSet {
     services: string[];
     jwksUri?: string;
 }
+/** A service's license key from Daywalker: derived per service, signing key and one-hour window. */
+export interface License {
+    serviceSlug: string;
+    /** 64 hex characters (32 bytes). A secret: never log it or send it anywhere. */
+    licenseKey: string;
+    /** ISO 8601: the end of the window the key is valid for. */
+    expiresAt: string;
+}
+/** The config bundle Daywalker seals under the license key. Fields beyond these are passed through. */
+export interface ConfigBundle {
+    serviceSlug: string;
+    /** Random per issue; derive per-process secrets from it (and the license key), never store it. */
+    dataKeySalt: string;
+    features: {
+        exclusiveTier?: boolean;
+        stage?: string;
+        rateLimitPerMinute?: number | null;
+        rateLimitPerHour?: number | null;
+        [key: string]: unknown;
+    };
+    issuedAt: string;
+    expiresAt: string;
+    [key: string]: unknown;
+}
+export interface LicenseOptions {
+    /** Default: the configured service slug. */
+    serviceSlug?: string;
+    /** Ignore the cached license and start a new client credentials grant. */
+    forceRefresh?: boolean;
+}
 export interface GetTokensOptions {
     /** Narrow the grant to these service slugs (least privilege); default: every service the credentials cover. */
     scope?: string[];
@@ -162,12 +286,13 @@ export interface SignRequestParams {
     path: string;
     authority: string;
     body?: string | Uint8Array | null;
-    key: SigningKey | string;
+    /** The local key to sign with. Not needed (and ignored) when `signer` is given. */
+    key?: SigningKey | string;
+    /** Signs with an external key instead (KMS / HSM); `keyid` defaults to `signer.keyId`. */
+    signer?: MessageSigner;
     created?: number;
     keyid?: string;
     alg?: string;
-    /** Sets `Authorization: Bearer <apiKey>` on the returned headers (not covered by the signature). */
-    apiKey?: string;
     /** Must be 1-128 of `[A-Za-z0-9_.-]` so it can't inject Signature-Input parameters. */
     nonce?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -26,6 +26,16 @@
       "import": "./dist/express.js",
       "default": "./dist/express.js"
     },
+    "./keystore": {
+      "types": "./dist/keystore/index.d.ts",
+      "import": "./dist/keystore/index.js",
+      "default": "./dist/keystore/index.js"
+    },
+    "./keystore/file": {
+      "types": "./dist/keystore/file.d.ts",
+      "import": "./dist/keystore/file.js",
+      "default": "./dist/keystore/file.js"
+    },
     "./flags": {
       "types": "./dist/flags/client.d.ts",
       "import": "./dist/flags/client.js",

package/dist/signing.d.ts

@@ -1,3 +0,0 @@
-export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./crypto/index.js";
-export declare const KEYS_PATH = "/.well-known/daywalker-keys.json";
-export type { PublicJwk, SigningKey, SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, } from "./types.js";

package/dist/signing.js

@@ -1,2 +0,0 @@
-export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./crypto/index.js";
-export const KEYS_PATH = "/.well-known/daywalker-keys.json";