@shelbyb/daywalker-sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,20 +1,20 @@
 <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**.
+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**.
 
-Runs seamlessly across **Node.js 18+**, **Bun**, **Deno**, **Cloudflare Workers**, **Next.js Edge**, and standard browser runtimes.
+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+.
 
-- **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`).
+- **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 +34,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 +81,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 +92,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 +100,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 +121,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 +130,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
 
@@ -193,9 +201,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 +223,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 |
 |---|---|---|

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();

package/dist/cli.js

@@ -7,20 +7,27 @@ import { generateSigningKey, loadSigningKey, registerPublicKey, redactSecrets }
 const HELP = `daywalker: connect a service to Daywalker Auth (RFC 9421 / Push Architecture)
 
 Usage:
-  daywalker init   --service <slug> [--api-key <key>] [--domain <host>] [--auth-url <url>] [--json|--export] [--print-key]
-  daywalker rotate [--service <slug>] [--api-key <key>] [--auth-url <url>] [--json|--export] [--print-key]
+  daywalker init   --service <slug> [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--force] [--skip-register] [--json|--export] [--print-key]
+  daywalker rotate [--service <slug>] [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--skip-register] [--json|--export] [--print-key]
   daywalker check
 
 init     Generates an Ed25519 keypair, registers the public key directly with Daywalker Auth
          (POST /api/v1/keys/register), and writes DAYWALKER_* settings to .env.local (or outputs JSON with --json).
-         No public ingress or /.well-known route handlers are required.
+         Nothing is written if registration fails. --force replaces an existing key (kept as
+         DAYWALKER_SIGNING_KEY_PREVIOUS for rollback). No public ingress or /.well-known route handlers are required.
 rotate   Generates a new Ed25519 key, registers it with Daywalker Auth, and keeps the old one
          in .env.local as DAYWALKER_SIGNING_KEY_PREVIOUS during deployment transition.
+         Nothing is written, and the exit code is non-zero, unless registration succeeds.
 check    Validates configuration and confirms Daywalker Auth connection and signature readiness.
 
 Options:
+  --api-key-stdin   Read the Daywalker API key from stdin (e.g. \`op read ... | daywalker init --api-key-stdin\`).
+                    The key is otherwise taken from DAYWALKER_API_KEY in the environment or .env.local.
+                    --api-key <key> also works but exposes the key in shell history and process listings.
+  --skip-register   Do not register the public key (alias: --no-register); register it yourself before deploying.
   --json, --export  Output configuration as JSON for piping into Vercel, DigitalOcean, Fly.io, AWS SSM, etc.
-  --print-key       Print the private key to stdout (disabled by default for security).
+                    The JSON includes the private key (DAYWALKER_SIGNING_KEY); nothing is written to .env.local.
+  --print-key       Print the private key to stdout after writing .env.local (disabled by default for security).
 `;
 function args(argv) {
     const out = {};
@@ -42,6 +49,35 @@ function fail(message) {
     console.error(redactSecrets(`✖ ${message}`));
     process.exit(1);
 }
+/** Read all of stdin (for --api-key-stdin), so the key never appears in argv. */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        fail("--api-key-stdin expects the key on stdin (pipe it in)");
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function resolveApiKey(opts, existing) {
+    if (typeof opts["api-key"] === "string")
+        return opts["api-key"].trim() || null;
+    if (opts["api-key-stdin"]) {
+        const fromStdin = await readStdin();
+        if (!fromStdin)
+            fail("--api-key-stdin: no API key received on stdin");
+        return fromStdin;
+    }
+    return String(existing.get("DAYWALKER_API_KEY") ?? process.env.DAYWALKER_API_KEY ?? "").trim() || null;
+}
+function skipRegister(opts) {
+    return Boolean(opts["skip-register"] || opts["no-register"]);
+}
+/** --json prints the private key by design (for secret stores); say so on stderr so it is never a surprise. */
+function warnJsonIncludesKey(values) {
+    if (values.DAYWALKER_SIGNING_KEY) {
+        console.warn("! --json output includes the private signing key (DAYWALKER_SIGNING_KEY); pipe it straight into your secret store.");
+    }
+}
 function readEnvFile(file) {
     const map = new Map();
     if (!fs.existsSync(file))
@@ -53,8 +89,35 @@ function readEnvFile(file) {
     }
     return map;
 }
-function writeEnvFile(file, values) {
-    const lines = fs.existsSync(file) ? fs.readFileSync(file, "utf8").split("\n") : [];
+/**
+ * Values are written as KEY="value". Anything a dotenv parser could interpret (quotes, `$` expansion
+ * as done by Next.js / dotenv-expand, backslash escapes, newlines or other control characters) is
+ * rejected instead of escaped, since parsers disagree on escaping rules.
+ */
+const UNSAFE_ENV_VALUE = /["'`$\\\u0000-\u001f\u007f]/;
+function assertSafeEnvValues(values) {
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== null && UNSAFE_ENV_VALUE.test(value)) {
+            fail(`${key} contains quotes, "$", backslashes, newlines or control characters; refusing to write it to .env.local`);
+        }
+    }
+}
+function writeEnvFile(file, values, comments = {}) {
+    assertSafeEnvValues(values);
+    let stat = null;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    // Never follow a symlink (it could point anywhere, e.g. a world-readable file); refuse non-files.
+    if (stat && stat.isSymbolicLink())
+        fail(`${path.basename(file)} is a symlink; refusing to write secrets through it`);
+    if (stat && !stat.isFile())
+        fail(`${path.basename(file)} is not a regular file`);
+    const lines = stat ? fs.readFileSync(file, "utf8").split("\n") : [];
     const seen = new Set();
     const out = [];
     for (const line of lines) {
@@ -73,12 +136,38 @@ function writeEnvFile(file, values) {
     if (added.length) {
         if (out.length)
             out.push("");
-        out.push("# Daywalker Auth (managed by `daywalker init`)", ...added.map(([k, v]) => `${k}="${v}"`));
+        out.push("# Daywalker Auth (managed by `daywalker init`)");
+        for (const [k, v] of added) {
+            if (comments[k])
+                out.push(`# ${comments[k]}`);
+            out.push(`${k}="${v}"`);
+        }
+    }
+    // Atomic replace: write a fresh 0600 temp file in the same directory, then rename it over the
+    // target, so the secrets never sit in a file with looser permissions and readers never see a
+    // half-written file.
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    const fd = fs.openSync(tmp, "wx", 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, out.join("\n") + "\n");
+        fs.fsyncSync(fd);
+    }
+    catch (err) {
+        fs.closeSync(fd);
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    fs.closeSync(fd);
+    try {
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
     }
-    fs.writeFileSync(file, out.join("\n") + "\n", { mode: 0o600 });
-    // `mode` only applies when the file is created; tighten an existing file too.
-    fs.chmodSync(file, 0o600);
 }
+const PREVIOUS_KEY_COMMENT = "Previous signing key, kept for rollback while the new key rolls out; remove it once deployed.";
 function ensureGitignored(dir, entry) {
     const file = path.join(dir, ".gitignore");
     const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
@@ -104,15 +193,22 @@ async function init(opts) {
         if (!domain)
             fail(`--domain (${rawDomain}) is not a valid public hostname`);
     }
-    const apiKey = String(opts["api-key"] ?? existing.get("DAYWALKER_API_KEY") ?? process.env.DAYWALKER_API_KEY ?? "").trim() || null;
+    const apiKey = await resolveApiKey(opts, existing);
     const authUrl = String(opts["auth-url"] ?? existing.get("DAYWALKER_AUTH_URL") ?? process.env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
-    const keyExists = Boolean(existing.get("DAYWALKER_SIGNING_KEY")) && !opts.force;
+    const existingKey = existing.get("DAYWALKER_SIGNING_KEY") || null;
+    const keyExists = Boolean(existingKey) && !opts.force;
     const key = keyExists ? null : await generateSigningKey();
-    const activeKey = key ?? (existing.get("DAYWALKER_SIGNING_KEY") ? await loadSigningKey(existing.get("DAYWALKER_SIGNING_KEY")) : null);
+    // --force over an existing key: keep the old one so a deployment can roll back to it.
+    const previousKey = key && existingKey ? existingKey : null;
+    const activeKey = key ?? (existingKey ? await loadSigningKey(existingKey) : null);
     const kid = activeKey?.publicJwk.kid ?? String(opts["key-id"] ?? "");
-    // Register public key directly with Daywalker Auth if API key is provided
+    // Register public key directly with Daywalker Auth if API key is provided. Replacing a key
+    // requires registration: writing an unregistered key would break request signing.
     let registered = false;
-    if (apiKey && activeKey && !opts["skip-register"]) {
+    if (previousKey && !apiKey && !skipRegister(opts)) {
+        fail("Replacing DAYWALKER_SIGNING_KEY requires registering the new key: set DAYWALKER_API_KEY (or use --api-key-stdin), or pass --skip-register to write it anyway");
+    }
+    if (apiKey && activeKey && !skipRegister(opts)) {
         if (!isJson)
             console.log(`• Registering public key (${activeKey.publicJwk.kid}) with Daywalker Auth...`);
         const regResult = await registerPublicKey({
@@ -128,13 +224,11 @@ async function init(opts) {
                 console.log(`✔ Public key registered with Daywalker Auth (Push Architecture)`);
         }
         else {
-            if (!isJson) {
-                console.warn(redactSecrets(`! Key registration warning (${regResult.status}): ${regResult.error}`));
-                console.warn(`  You can register the key later by re-running init with your DAYWALKER_API_KEY.`);
-            }
+            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n` +
+                `  Nothing was written. Fix the problem and re-run, or pass --skip-register to write the key without registering it.`);
         }
     }
-    else if (!apiKey && !opts["skip-register"] && !isJson) {
+    else if (!apiKey && !skipRegister(opts) && !isJson) {
         console.log(`• Note: Set DAYWALKER_API_KEY in .env.local to automatically register public keys.`);
     }
     const signingKeyStr = key?.privateKeyPkcs8Base64 ?? existing.get("DAYWALKER_SIGNING_KEY") ?? "";
@@ -145,12 +239,14 @@ async function init(opts) {
         ...(domain ? { DAYWALKER_DOMAIN: domain } : {}),
         ...(apiKey ? { DAYWALKER_API_KEY: apiKey } : {}),
         ...(signingKeyStr ? { DAYWALKER_SIGNING_KEY: signingKeyStr } : {}),
+        ...(previousKey ? { DAYWALKER_SIGNING_KEY_PREVIOUS: previousKey } : {}),
     };
     if (isJson) {
+        warnJsonIncludesKey(envValues);
         console.log(JSON.stringify(envValues, null, 2));
         return;
     }
-    writeEnvFile(envFile, envValues);
+    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(`  • RFC 9421 / RFC 9530 HTTP Message Signing active`);
@@ -159,6 +255,8 @@ async function init(opts) {
         console.log(`  • Key ID (RFC 7638 thumbprint): ${kid}`);
     if (registered)
         console.log(`  • Zero-ingress push architecture: public key registered directly`);
+    if (previousKey)
+        console.log(`  • Previous key kept as DAYWALKER_SIGNING_KEY_PREVIOUS for rollback; remove it once the new key is deployed.`);
     if (opts["print-key"] && signingKeyStr)
         console.log(`\nDAYWALKER_SIGNING_KEY=${signingKeyStr}`);
 }
@@ -171,11 +269,16 @@ async function rotate(opts) {
     if (!current)
         fail("No DAYWALKER_SIGNING_KEY found; run `daywalker init` first");
     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 apiKey = await resolveApiKey(opts, existing);
     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) {
+    // 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 (!isJson)
             console.log(`• Registering new public key (${key.publicJwk.kid}) with Daywalker Auth...`);
         const regResult = await registerPublicKey({
@@ -185,25 +288,24 @@ async function rotate(opts) {
             domain: rotateDomain,
             publicJwk: key.publicJwk,
         });
-        if (regResult.ok) {
-            if (!isJson)
-                console.log(`✔ New public key registered with Daywalker Auth`);
-        }
-        else {
-            if (!isJson)
-                console.warn(redactSecrets(`! Key registration warning: ${regResult.error}`));
+        if (!regResult.ok) {
+            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n  Nothing was written; the current key is still active.`);
         }
+        if (!isJson)
+            console.log(`✔ New public key registered with Daywalker Auth`);
     }
     const envValues = {
         DAYWALKER_KEY_ID: key.publicJwk.kid,
         DAYWALKER_SIGNING_KEY: key.privateKeyPkcs8Base64 ?? "",
+        // Kept for rollback: services still signing with the old key keep working during rollout.
         DAYWALKER_SIGNING_KEY_PREVIOUS: current,
     };
     if (isJson) {
+        warnJsonIncludesKey(envValues);
         console.log(JSON.stringify(envValues, null, 2));
         return;
     }
-    writeEnvFile(envFile, envValues);
+    writeEnvFile(envFile, envValues, { DAYWALKER_SIGNING_KEY_PREVIOUS: PREVIOUS_KEY_COMMENT });
     console.log(`✔ New key ${key.publicJwk.kid} written; previous key preserved as DAYWALKER_SIGNING_KEY_PREVIOUS.`);
     console.log(`  After deployment rollout is complete, you may remove DAYWALKER_SIGNING_KEY_PREVIOUS.`);
     if (opts["print-key"])