@shelbyb/daywalker-sdk 0.2.0 → 0.4.0

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,10 +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 });
 }
+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") : "";
@@ -102,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({
@@ -126,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") ?? "";
@@ -143,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`);
@@ -157,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}`);
 }
@@ -169,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({
@@ -183,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"])
@@ -233,6 +337,9 @@ async function check() {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const parsedArgs = args(rest);
+    if (typeof parsedArgs["api-key"] === "string") {
+        console.warn("! --api-key exposes the key in shell history and process listings; prefer DAYWALKER_API_KEY in the environment or .env.local.");
+    }
     if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
         console.log(HELP);
         return;

package/dist/client.d.ts

@@ -1,26 +1,57 @@
 import { type ResolvedConfig } from "./config.js";
 import { type DaywalkerConfig, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+/** Validation results kept in memory; the least recently used are evicted past this. */
+export declare const MAX_VALIDATION_CACHE_ENTRIES = 1000;
+/** Longest 429 `Retry-After` waited out by default (`retry.maxRetryAfterMs`); longer ones return the 429. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
 export type DaywalkerFetchInit = Omit<RequestInit, "body"> & {
+    /**
+     * Plain objects and arrays are sent as JSON. Strings, Uint8Array / ArrayBuffer(View) and URLSearchParams
+     * are sent (and digested) byte for byte, and Blobs are read into memory first when signing. FormData and
+     * ReadableStream bodies can't be digested, so they throw when a signing key is configured.
+     */
     body?: BodyInit | object | null;
     retry?: RetryOptions;
+    /** Per-attempt timeout overriding `config.timeoutMs`; 0 disables. */
+    timeoutMs?: number;
+    /** Sent as `Idempotency-Key` (unless already set) and lets non-idempotent requests retry network errors. */
+    idempotencyKey?: string;
 };
 export declare class Daywalker {
     private readonly _config;
     private readonly _rawConfig;
     private _signingKeyPromise?;
+    private _previousSigningKeyPromise?;
     private readonly _cache;
     private readonly _inflight;
     constructor(config?: DaywalkerConfig);
     get config(): ResolvedConfig;
     toJSON(): Record<string, unknown>;
     private getLoadedSigningKey;
+    private getLoadedPreviousSigningKey;
     /**
-     * Signs and executes requests with automatic retry and exponential backoff on 429 responses.
+     * Signs and executes a request to Daywalker Auth (same origin as `authUrl` only).
+     * - Redirects are never followed: a 3xx throws a DaywalkerError (code UNEXPECTED_REDIRECT), so the API key,
+     *   signature and body never reach another URL and no redirect target's answer is trusted.
+     * - Each attempt times out after `timeoutMs` (default 5000ms) of waiting for response headers; the caller's
+     *   `signal` aborts immediately, including during backoff, and is never retried.
+     * - 429s are retried with exponential backoff, honoring `Retry-After` up to `retry.maxRetryAfterMs`. Network
+     *   errors and timeouts are retried only for GET / HEAD / OPTIONS, with an `idempotencyKey`, or when
+     *   `retry.retryNetworkErrors` is true. Options merge as defaults < `config.retry` < `init.retry`.
+     * - An explicit `Authorization` header is sent as given; otherwise `Bearer <apiKey>` is added. The signature
+     *   covers method, path, query, authority and Content-Digest, never Authorization.
      */
     fetch(path: string, init?: DaywalkerFetchInit): Promise<Response>;
+    private _cacheGet;
+    private _cacheSet;
     /**
-     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Validates an incoming bearer token with memory caching and discriminated union return.
      * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
+     * A missing token is always rejected (401); it never falls back to this service's own API key —
+     * use `validateServiceKey()` for that.
+     * Online validation fails closed: only a 2xx JSON answer with `valid: true` and a sane shape is accepted.
+     * Outages (network errors, timeouts, 5xx, malformed answers) return status 503 with error NETWORK_ERROR or
+     * SERVICE_UNAVAILABLE and are never cached. Each call gets its own copy of the (cached) result.
      */
     validateToken(tokenOrOptions?: string | {
         token?: string;
@@ -33,6 +64,14 @@ export declare class Daywalker {
         offlineOnly?: boolean;
     }): Promise<ValidateResult>;
     private _validateOnline;
+    /**
+     * Service health check: validates this service's own configured API key (DAYWALKER_API_KEY).
+     * Never use this to authenticate an incoming request.
+     */
+    validateServiceKey(options?: {
+        serviceSlug?: string;
+        forceRefresh?: boolean;
+    }): Promise<ValidateResult>;
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */
@@ -55,12 +94,14 @@ export declare class Daywalker {
     }>;
     /**
      * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
+     * Uses the configured `fetch`, sends no credentials, never follows redirects and times out after `timeoutMs`.
      */
     fetchJwks(): Promise<{
         keys: PublicJwk[];
     }>;
     /**
-     * The public JWK(s) configured for this service.
+     * The public JWK(s) configured for this service: the current signing key, then the previous one
+     * (`previousSigningKey`) during a rotation, so requests from instances still on the old key keep verifying.
      */
     keys(): Promise<{
         keys: PublicJwk[];