@shelbyb/daywalker-sdk 0.3.0 → 0.4.1

package/README.md

@@ -1,20 +1,24 @@
 <p align="center">
-  <img src="./assets/logo-512.png" alt="Daywalker" width="160" />
+  <img src="https://raw.githubusercontent.com/Shelbyb/daywalker-sdk/main/assets/logo-512.png" alt="Daywalker" width="160" />
 </p>
 
 # @shelbyb/daywalker-sdk
 
-Zero-dependency, runtime-agnostic client library for [Daywalker Auth](https://auth.daywalker.dev). Supports **RFC 9421 (HTTP Message Signatures)**, **RFC 9530 (Digest Fields)**, **Web Crypto standards**, **Push Architecture key registration**, and **hardened web & Next.js middleware**.
+[![npm](https://img.shields.io/npm/v/@shelbyb/daywalker-sdk)](https://www.npmjs.com/package/@shelbyb/daywalker-sdk)
+[![CI](https://github.com/Shelbyb/daywalker-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Shelbyb/daywalker-sdk/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@shelbyb/daywalker-sdk)](./LICENSE)
 
-Runs seamlessly across **Node.js 18+**, **Bun**, **Deno**, **Cloudflare Workers**, **Next.js Edge**, and standard browser runtimes.
+Runtime-agnostic client library for [Daywalker Auth](https://auth.daywalker.dev). Supports **RFC 9421 (HTTP Message Signatures)**, **RFC 9530 (Digest Fields)**, **Web Crypto standards**, **Push Architecture key registration**, and **hardened web & Next.js middleware**.
 
-- **Zero-Dependency Web Standards Core**: 100% standard `crypto.subtle`, `Uint8Array`, `fetch`, `Request`, and `Response`.
-- **RFC 9421 (HTTP Message Signatures)**: Cryptographically binds `@method`, `@path`, `@authority`, and `content-digest` using Ed25519 signatures (`Signature-Input`, `Signature`).
+Runs on **Node.js 20.19+**, **Bun**, **Deno**, **Cloudflare Workers**, **Next.js Edge**, and browsers. ESM only; `require()` works on Node 20.19+ and 22.12+.
+
+- **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.
 - **Class-Based Client Architecture**: Instantiable `Daywalker` client supporting dependency injection, with a lazy default singleton for plug-and-play simplicity.
-- **Resilience & Rate Limiting**: Automatic exponential backoff with jitter and `Retry-After` header parsing directly inside client fetch requests.
+- **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.
 - **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), health check bypass, and self-healing diagnostic error routing.
+- **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.
 - **Decoupled Push Architecture CLI**: `npx daywalker init --json` registers keys directly via `POST /api/v1/keys/register` with zero runtime reverse-HTTP calls.
 
@@ -34,17 +38,19 @@ 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 (domain is required by the API):
-npx daywalker init --service my-service-slug --domain app.example.com --api-key srv_live_...
+# Register the public key with Daywalker Auth (domain is required by the API).
+# The API key comes from DAYWALKER_API_KEY, or from stdin so it stays out of shell history:
+op read op://vault/daywalker/api-key | npx daywalker init --service my-service-slug --domain app.example.com --api-key-stdin
 
-# Pipe JSON secrets directly into Vercel, Fly.io, DigitalOcean, or AWS SSM:
-npx daywalker init --service my-service-slug --api-key srv_live_... --json
+# Print JSON for Vercel, Fly.io, DigitalOcean, or AWS SSM (nothing written to disk):
+DAYWALKER_API_KEY=srv_live_... npx daywalker init --service my-service-slug --domain app.example.com --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` (`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`
+- Writes `DAYWALKER_SERVICE_SLUG`, `DAYWALKER_KEY_ID`, `DAYWALKER_SIGNING_KEY`, and `DAYWALKER_AUTH_URL` to `.env.local` (atomically, mode `0600`), and only after registration succeeds. `--skip-register` writes without registering.
+- `--force` replaces an existing key and keeps the old one as `DAYWALKER_SIGNING_KEY_PREVIOUS`
 - No route injectors or public `/.well-known/` endpoints needed
 
 The private key is never printed unless you pass `--print-key`.
@@ -79,6 +85,7 @@ const client = new Daywalker({
   apiKey: process.env.DAYWALKER_API_KEY,
   serviceSlug: "sonalyze",
   maxRetries: 3,
+  timeoutMs: 5000, // per attempt (default)
 });
 
 // Option 2: Default lazy singleton (reads process.env automatically)
@@ -89,6 +96,7 @@ if (result.ok) {
   console.log("Validated tenant:", result.data.tenantId);
   console.log("Rate limit remaining:", result.data.rateLimit.remaining);
 } else {
+  // SERVICE_UNAVAILABLE (503) when Daywalker can't be reached: the token is NOT treated as valid.
   console.error(`Validation failed (${result.status} ${result.error}): ${result.message}`);
 }
 ```
@@ -96,6 +104,8 @@ if (result.ok) {
 ### Type-Safe Verification & Error Handling
 
 ```ts
+import { DaywalkerRateLimitError } from "@shelbyb/daywalker-sdk";
+
 // requireValidToken returns data or throws DaywalkerAuthError / DaywalkerRateLimitError
 try {
   const auth = await client.requireValidToken(req.headers.get("x-api-token"));
@@ -115,6 +125,7 @@ try {
 const res = await client.fetch("/api/v1/tokens/validate", {
   method: "POST",
   body: { token: "user_token", serviceSlug: "other-service" },
+  idempotencyKey: crypto.randomUUID(), // optional: lets a POST be retried after a network error
 });
 ```
 
@@ -123,21 +134,22 @@ const res = await client.fetch("/api/v1/tokens/validate", {
 ## Hardened Next.js Middleware (`@shelbyb/daywalker-sdk/next`)
 
 ```ts
-// middleware.ts
-import { createDaywalkerMiddleware } from "@shelbyb/daywalker-sdk/next";
+// proxy.ts (Next.js 16; middleware.ts with `export const middleware = createDaywalkerMiddleware(...)` on 15)
+import { createDaywalkerProxy } from "@shelbyb/daywalker-sdk/next";
 
-export const middleware = createDaywalkerMiddleware({
+export const proxy = createDaywalkerProxy({
   serviceSlug: "sonalyze",
   errorPath: "/service-error", // redirect unauthorized web visitors
   validateServerActions: true, // drops malformed CVE-2025-55182 scanner probes
 });
 
 export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+  // Keep public files out with the matcher: list what is public, not what isn't.
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|robots.txt|images/).*)"],
 };
 ```
 
-Each request must carry `Authorization: Bearer <token>` or `x-api-token`; without one, API routes get `401` and pages redirect to `errorPath`. Only `/_next/static/`, `/_next/image`, the favicon and static file extensions outside `/api/` skip auth. 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>` 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.
 
 ### Route Handler Wrapper
 
@@ -169,6 +181,23 @@ app.get("/api/me", (c) => {
 
 ---
 
+## Express / Connect / Node `http` (`@shelbyb/daywalker-sdk/express`)
+
+```ts
+import express from "express";
+import { daywalkerAuth, daywalkerKeys } 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.
+
+---
+
 ## Zero-Egress Offline Verification
 
 When high-throughput internal microservices need zero latency and zero external egress, Daywalker Auth can issue asymmetric JWT leases. Configure `DAYWALKER_PUBLIC_KEY` (PEM or standard JWK) and token validation runs entirely in memory without network calls:
@@ -193,9 +222,9 @@ Leases must have a numeric `exp` and an `aud` (or `serviceSlug`) equal to your s
 
 | Command | Description |
 |---|---|
-| `npx daywalker init --service <slug> [--api-key <key>] [--json]` | Generate Ed25519 key, register with Daywalker Auth, and write `.env.local` or output JSON |
+| `npx daywalker init --service <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 [--api-key <key>] [--json]` | Generate and register a new key while preserving the previous key in `.env.local` |
+| `npx daywalker rotate [--api-key-stdin] [--skip-register] [--json]` | Generate and register a new key while preserving the previous key in `.env.local` |
 
 ---
 
@@ -215,20 +244,20 @@ Inbound tokens may be supplied as `x-api-token: srv_live_...` or `Authorization:
 ## 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";nonce="<random>"`
+- `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>`
 
 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).
+Verification reads the covered components from `Signature-Input`, requires `content-digest` to be covered whenever there is a body, and rejects replays. The default replay cache is per process: with several instances, pass a shared `replayStore` (e.g. Redis `SET NX PX`). The exact signature base and test cases are verified against [`test-vectors/signing-rfc9421.json`](./test-vectors/signing-rfc9421.json).
 
 ---
 
 ## 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 and has zero dependencies; `react` and the OpenFeature SDKs are optional peer dependencies used only by their subpaths.
+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.
 
 | Import | What it is | Docs |
 |---|---|---|
@@ -249,6 +278,18 @@ const analytics = createAnalytics({ writeKey: "dpa_…", host: "https://devpulse
 
 ---
 
+## Provenance & Releases
+
+Releases are published from GitHub Actions ([`publish.yml`](./.github/workflows/publish.yml)) with [npm trusted publishing](https://docs.npmjs.com/trusted-publishers): npm accepts a short-lived OIDC token from this repository's workflow, so there is no long-lived npm token anywhere. Each version carries a signed [provenance attestation](https://docs.npmjs.com/generating-provenance-statements) linking it to the commit and workflow run that built it. Check it on the npm page, or after installing:
+
+```bash
+npm audit signatures
+```
+
+To cut a release (maintainers): bump `version` in `package.json`, add a `CHANGELOG.md` entry, merge to `main`, then either push a matching tag (`git tag v0.5.0 && git push origin v0.5.0`) or run the **Publish** workflow from `main` with the version. The workflow refuses tags not on `main`, versions that don't match `package.json`, and versions already on npm. Tests and packing run in a job without the OIDC token; only the final job, which uploads the tested tarball, can publish.
+
+---
+
 ## License
 
 MIT

package/dist/analytics/index.d.ts

@@ -37,6 +37,14 @@ export type AnalyticsOptions = {
      * so OAuth codes, reset tokens and the like never leave the page.
      */
     captureFullUrls?: boolean;
+    /**
+     * Rewrite URL paths before they leave the page: applied to $pathname, $initial_pathname and the
+     * path of every URL sent ($current_url, $referrer, $initial_current_url, $initial_referrer).
+     * Use it for secrets embedded in paths, e.g.
+     * `sanitizePath: (p) => p.replace(/^\/reset\/[^/]+/, "/reset/:token")`. Default: unchanged.
+     * If it throws, the path is sent as "/".
+     */
+    sanitizePath?: (path: string) => string;
     fetch?: typeof fetch;
     onError?: (err: Error) => void;
 };
@@ -47,7 +55,7 @@ export type CaptureOptions = {
     $set?: Properties;
     $set_once?: Properties;
 };
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.4.0";
 /** Drop the fragment and every query parameter outside the campaign allowlist. */
 export declare function sanitizeUrl(raw: string): string;
 /** Time-ordered UUID (v7). */
@@ -94,14 +102,20 @@ export declare class Analytics {
     private disabled;
     private context;
     private url;
+    private path;
     private flagProps;
     /** Rolling session: renewed after inactivity or at most every 24 hours. */
     private session;
     private enqueue;
     private schedule;
+    /** Take up to MAX_BATCH_EVENTS queued events whose body stays under maxBytes (always at least one). */
+    private takeBatch;
     /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
     private send;
-    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    /**
+     * On page hide, hand the queue to sendBeacon so it survives navigation, in batches under the
+     * browser's 64 KiB beacon budget; whatever doesn't fit stays queued (and persists in memory).
+     */
     private beacon;
     private attachBrowser;
 }

package/dist/analytics/index.js

@@ -1,5 +1,13 @@
 import { assertSecureUrl } from "../config.js";
-export const VERSION = "0.1.0";
+import { SDK_VERSION } from "../flags/common/version.js";
+export const VERSION = SDK_VERSION;
+/** keepalive fetches and sendBeacon share a 64 KiB in-flight budget in browsers. */
+const KEEPALIVE_MAX_BYTES = 60_000;
+/** Stay well under DevPulse's 2 MB capture body limit. */
+const MAX_BATCH_BYTES = 1_000_000;
+const MAX_BATCH_EVENTS = 100;
+const encoder = new TextEncoder();
+const byteLength = (s) => encoder.encode(s).length;
 const KEPT_QUERY_PARAMS = new Set(["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "gclid", "fbclid", "ref"]);
 /** Drop the fragment and every query parameter outside the campaign allowlist. */
 export function sanitizeUrl(raw) {
@@ -128,7 +136,7 @@ export class Analytics {
                 $initial_referrer: document.referrer ? this.url(document.referrer) : "$direct",
                 $initial_referring_domain: referringDomain(document.referrer) ?? "$direct",
                 $initial_current_url: url,
-                $initial_pathname: location.pathname,
+                $initial_pathname: this.path(location.pathname),
                 ...Object.fromEntries(Object.entries(utm).map(([k, v]) => [`$initial_${k}`, v])),
             };
             this.state.initialSent = true;
@@ -196,6 +204,10 @@ export class Analytics {
         clearTimeout(this.timer);
         this.timer = undefined;
         while (this.queue.length) {
+            if (this.state.optedOut) {
+                this.queue = [];
+                return;
+            }
             if (this.sending)
                 await this.sending;
             else {
@@ -230,7 +242,7 @@ export class Analytics {
             ...base,
             $current_url: this.url(location.href),
             $host: location.host,
-            $pathname: location.pathname,
+            $pathname: this.path(location.pathname),
             $referrer: document.referrer ? this.url(document.referrer) : "$direct",
             $referring_domain: referringDomain(document.referrer) ?? "$direct",
             $screen_width: screen.width,
@@ -242,7 +254,28 @@ export class Analytics {
         };
     }
     url(raw) {
-        return this.opts.captureFullUrls ? raw : sanitizeUrl(raw);
+        const out = this.opts.captureFullUrls ? raw : sanitizeUrl(raw);
+        if (!this.opts.sanitizePath || !out)
+            return out;
+        try {
+            const u = new URL(out);
+            u.pathname = this.path(u.pathname);
+            return u.toString();
+        }
+        catch {
+            return this.path(out);
+        }
+    }
+    path(p) {
+        if (!this.opts.sanitizePath)
+            return p;
+        try {
+            return this.opts.sanitizePath(p);
+        }
+        catch (err) {
+            this.opts.onError?.(err);
+            return "/";
+        }
     }
     flagProps() {
         if (!this.opts.flags)
@@ -284,9 +317,29 @@ export class Analytics {
         }, this.backoff || this.opts.flushInterval);
         this.timer.unref?.();
     }
+    /** Take up to MAX_BATCH_EVENTS queued events whose body stays under maxBytes (always at least one). */
+    takeBatch(maxBytes) {
+        const sentAt = new Date().toISOString();
+        const encode = (batch) => JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: sentAt });
+        let size = byteLength(encode([]));
+        let n = 0;
+        while (n < Math.min(MAX_BATCH_EVENTS, this.queue.length)) {
+            const add = byteLength(JSON.stringify(this.queue[n])) + (n ? 1 : 0);
+            if (n && size + add > maxBytes)
+                break;
+            size += add;
+            n++;
+        }
+        const batch = this.queue.splice(0, n);
+        return { batch, body: encode(batch) };
+    }
     /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
     async send() {
-        const batch = this.queue.splice(0, 100);
+        if (this.state.optedOut) {
+            this.queue = [];
+            return true;
+        }
+        const { batch, body } = this.takeBatch(MAX_BATCH_BYTES);
         if (!batch.length)
             return true;
         const f = this.opts.fetch ?? globalThis.fetch;
@@ -294,8 +347,9 @@ export class Analytics {
             const res = await f(this.endpoint, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
-                body: JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() }),
-                keepalive: isBrowser,
+                body,
+                // Browsers reject keepalive bodies over 64 KiB outright, so only small ones get it.
+                keepalive: isBrowser && byteLength(body) < KEEPALIVE_MAX_BYTES,
             });
             if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 429)) {
                 if (!res.ok)
@@ -306,6 +360,11 @@ export class Analytics {
             throw new Error(`HTTP ${res.status}`);
         }
         catch (err) {
+            // Opted out while this was in flight: the batch must not be retried.
+            if (this.state.optedOut) {
+                this.queue = [];
+                return false;
+            }
             this.queue.unshift(...batch);
             this.backoff = Math.min(60_000, (this.backoff || 1000) * 2);
             this.opts.onError?.(err);
@@ -313,15 +372,21 @@ export class Analytics {
             return false;
         }
     }
-    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    /**
+     * On page hide, hand the queue to sendBeacon so it survives navigation, in batches under the
+     * browser's 64 KiB beacon budget; whatever doesn't fit stays queued (and persists in memory).
+     */
     beacon() {
-        if (!this.queue.length || typeof navigator.sendBeacon !== "function")
+        if (this.state.optedOut || typeof navigator.sendBeacon !== "function")
             return;
-        const batch = this.queue.splice(0, 100);
-        const body = JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() });
-        // text/plain avoids a CORS preflight, which beacons can't do.
-        if (!navigator.sendBeacon(this.endpoint, new Blob([body], { type: "text/plain" })))
-            this.queue.unshift(...batch);
+        while (this.queue.length) {
+            const { batch, body } = this.takeBatch(KEEPALIVE_MAX_BYTES);
+            // text/plain avoids a CORS preflight, which beacons can't do.
+            if (byteLength(body) >= KEEPALIVE_MAX_BYTES || !navigator.sendBeacon(this.endpoint, new Blob([body], { type: "text/plain" }))) {
+                this.queue.unshift(...batch);
+                return;
+            }
+        }
     }
     attachBrowser() {
         const onHide = () => document.visibilityState === "hidden" && this.beacon();