@shelbyb/daywalker-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shelby Brayton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @shelbyb/daywalker-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect any service to [Daywalker Auth](https://auth.daywalker.dev): validate API tokens and make **domain-signed** API calls that pass token allowlists from any host, CDN, container, or serverless platform.
+
+## Setup (once per service)
+
+```bash
+npm install @shelbyb/daywalker-sdk
+npx daywalker init --domain myservice.daywalker.dev --service my-service-slug
+# On DigitalOcean App Platform, also set the env vars on the live app:
+npx daywalker init --domain myservice.daywalker.dev --service my-service-slug --do-app my-app
+```
+
+`init`:
+- generates an Ed25519 signing key
+- adds the `/.well-known/daywalker-keys.json` route (Next.js; for Express it prints the one line to add)
+- writes `DAYWALKER_SERVICE_SLUG`, `DAYWALKER_DOMAIN`, and `DAYWALKER_SIGNING_KEY` to `.env.local` (git-ignored)
+- with `--do-app`, sets them on your DigitalOcean app through `doctl`, with the key as an encrypted secret
+
+The private key is never printed unless you pass `--print-key`.
+
+Then set `DAYWALKER_API_KEY` to the service's token, deploy, run `npx daywalker check`, and in the Daywalker dashboard click **Connect** on the token to add your domain to its allowed callers.
+
+## Environment
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `DAYWALKER_API_KEY` | ✅ | The service's Daywalker API token (`srv_live_…`) |
+| `DAYWALKER_SERVICE_SLUG` | ✅ | The service slug to validate against. Each service sets its own |
+| `DAYWALKER_SIGNING_KEY` | for allowlisted tokens | Ed25519 private key from `daywalker init` (secret) |
+| `DAYWALKER_DOMAIN` | recommended | Public hostname that serves the key. Falls back to `APP_URL`, `NEXTAUTH_URL`, `NEXT_PUBLIC_APP_URL`, `BETTER_AUTH_URL`, `PUBLIC_URL`, `SITE_URL`, `URL`, `VERCEL_PROJECT_PRODUCTION_URL`, `RENDER_EXTERNAL_HOSTNAME`, `RAILWAY_PUBLIC_DOMAIN`, `VERCEL_URL` |
+| `DAYWALKER_SIGNING_KEY_PREVIOUS` | during rotation | Old key, still published so in-flight requests verify |
+| `DAYWALKER_AUTH_URL` | optional | Defaults to `https://auth.daywalker.dev` |
+
+Internal addresses (`0.0.0.0`, `localhost`, IPs) are never used as the domain, so a container's bind address can't end up in a signature.
+
+## Usage
+
+```ts
+import { daywalker } from "@shelbyb/daywalker-sdk";
+
+// Validate DAYWALKER_API_KEY for DAYWALKER_SERVICE_SLUG (successful results cached for 60s)
+const result = await daywalker().validateToken();
+if (!result.valid) console.error(result.status, result.data.message);
+
+// Or validate a token your own users send you
+await daywalker().requireValidToken({ token: req.headers["x-api-token"] }); // throws DaywalkerError
+
+// Signed call to any Daywalker Auth API path
+const res = await daywalker().fetch("/api/v1/tokens/validate", { body: { token, serviceSlug: "other" } });
+```
+
+`result.data` includes `rateLimit` (per minute) and `rateLimitHourly` (per hour), each `{ limit, remaining, reset }`. On a `429`, `result.retryAfter` is the number of seconds to wait.
+
+### Serving the public key
+
+Next.js (App Router), which `init` creates for you:
+
+```ts
+// app/.well-known/daywalker-keys.json/route.ts
+export { GET, dynamic } from "@shelbyb/daywalker-sdk/next";
+```
+
+Express / Connect / Node http:
+
+```ts
+import { daywalkerKeys } from "@shelbyb/daywalker-sdk/express";
+app.use(daywalkerKeys());
+```
+
+Anything else: serve `JSON.stringify(daywalker().keys())` at `GET /.well-known/daywalker-keys.json`. It must be on the domain itself over HTTPS, without redirects.
+
+### Custom clients
+
+```ts
+import { createDaywalker } from "@shelbyb/daywalker-sdk";
+const client = createDaywalker({ serviceSlug: "gigpulse", domain: "gigpulse.daywalker.dev", cacheTtlMs: 0 });
+```
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `npx daywalker init --domain <host> --service <slug> [--do-app <app>]` | Generate a key, add the key route, write env (re-running keeps the existing key; `--force` replaces it) |
+| `npx daywalker check` | Validate config and confirm the domain publishes the current key |
+| `npx daywalker rotate [--do-app <app>]` | New key; the old one stays published as `DAYWALKER_SIGNING_KEY_PREVIOUS`. Remove that after the deploy is live |
+
+## How signing works
+
+Each request carries `X-Daywalker-Domain`, `-Key-Id`, `-Timestamp`, `-Nonce`, and `-Signature`, an Ed25519 signature over the method, path, domain, timestamp, nonce, and the body's SHA-256. Daywalker fetches the public key from your domain over HTTPS, so a valid signature proves the request comes from whoever controls the domain. Timestamps must be within 5 minutes and nonces are single-use. See the Daywalker README for the full protocol.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createDaywalker } from "./client.js";
+import { publicHostname } from "./config.js";
+import { generateSigningKey } from "./signing.js";
+const HELP = `daywalker: connect a service to Daywalker Auth
+
+Usage:
+  daywalker init   --domain <host> --service <slug> [--do-app <name|id>] [--framework next|express] [--print-key]
+  daywalker rotate [--do-app <name|id>] [--print-key]
+  daywalker check
+
+init     Generates a signing key, adds the /.well-known/daywalker-keys.json route for your
+         framework, and writes DAYWALKER_* settings to .env.local. With --do-app it also sets
+         them on your DigitalOcean App Platform app (as an encrypted secret, via doctl).
+rotate   Generates a new key and keeps the old one published as DAYWALKER_SIGNING_KEY_PREVIOUS,
+         so requests signed with either key verify during the switch. Remove the previous key
+         a few minutes after deploying.
+check    Validates config and confirms your domain serves the current public key.
+
+The private key is never printed unless you pass --print-key.`;
+function args(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--"))
+            continue;
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+            out[a.slice(2)] = next;
+            i++;
+        }
+        else
+            out[a.slice(2)] = true;
+    }
+    return out;
+}
+function fail(message) {
+    console.error(`✖ ${message}`);
+    process.exit(1);
+}
+// --- .env.local ---------------------------------------------------------------
+function readEnvFile(file) {
+    const map = new Map();
+    if (!fs.existsSync(file))
+        return map;
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)$/);
+        if (m)
+            map.set(m[1], m[2].replace(/^"(.*)"$/, "$1"));
+    }
+    return map;
+}
+function writeEnvFile(file, values) {
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, "utf8").split("\n") : [];
+    const seen = new Set();
+    const out = [];
+    for (const line of lines) {
+        const key = line.match(/^\s*([A-Z0-9_]+)\s*=/)?.[1];
+        if (key && key in values) {
+            seen.add(key);
+            if (values[key] !== null)
+                out.push(`${key}="${values[key]}"`);
+            continue;
+        }
+        out.push(line);
+    }
+    while (out.length && out[out.length - 1] === "")
+        out.pop();
+    const added = Object.entries(values).filter(([k, v]) => !seen.has(k) && v !== null);
+    if (added.length) {
+        if (out.length)
+            out.push("");
+        out.push("# Daywalker Auth (managed by `daywalker init`)", ...added.map(([k, v]) => `${k}="${v}"`));
+    }
+    fs.writeFileSync(file, out.join("\n") + "\n", { mode: 0o600 });
+}
+function ensureGitignored(dir, entry) {
+    const file = path.join(dir, ".gitignore");
+    const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const covered = content.split("\n").some((l) => [entry, ".env*", ".env.*", ".env*.local", "*.local"].includes(l.trim()));
+    if (!covered)
+        fs.appendFileSync(file, `${content.endsWith("\n") || !content ? "" : "\n"}${entry}\n`);
+}
+// --- framework route ------------------------------------------------------------
+function detectFramework(dir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps.next)
+            return "next";
+        if (deps.express || deps.fastify || deps.koa || deps.hono)
+            return "express";
+    }
+    catch {
+        // no package.json
+    }
+    return null;
+}
+function addNextRoute(dir) {
+    const appDir = ["src/app", "app"].map((d) => path.join(dir, d)).find((d) => fs.existsSync(d)) ?? path.join(dir, "app");
+    const routeDir = path.join(appDir, ".well-known", "daywalker-keys.json");
+    const routeFile = path.join(routeDir, "route.ts");
+    const rel = path.relative(dir, routeFile);
+    if (fs.existsSync(routeFile))
+        return `${rel} already exists (left unchanged)`;
+    // A static file here would shadow the route and pin an old key
+    const staticFile = path.join(dir, "public", ".well-known", "daywalker-keys.json");
+    if (fs.existsSync(staticFile))
+        console.warn(`! Remove ${path.relative(dir, staticFile)}; the route serves keys from env now.`);
+    fs.mkdirSync(routeDir, { recursive: true });
+    fs.writeFileSync(routeFile, `// Serves this service's public signing key so Daywalker Auth can verify its requests.\nexport { GET, dynamic } from "@shelbyb/daywalker-sdk/next";\n`);
+    return `created ${rel}`;
+}
+// --- DigitalOcean ---------------------------------------------------------------
+function setDigitalOceanEnv(app, values) {
+    const doctl = (a, input) => execFileSync("doctl", a, { encoding: "utf8", input, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
+    let appId = app;
+    if (!/^[0-9a-f-]{36}$/.test(app)) {
+        const apps = JSON.parse(doctl(["apps", "list", "--output", "json"]));
+        appId = apps.find((a) => a.spec.name === app)?.id ?? fail(`No DigitalOcean app named "${app}"`);
+    }
+    const spec = JSON.parse(doctl(["apps", "spec", "get", appId, "--format", "json"]));
+    const components = [...(spec.services ?? []), ...(spec.workers ?? []), ...(spec.jobs ?? [])];
+    if (!components.length)
+        fail("The app spec has no services, workers, or jobs to configure");
+    for (const component of components) {
+        component.envs = (component.envs ?? []).filter((e) => !(e.key in values));
+        for (const [key, { value, secret }] of Object.entries(values)) {
+            if (value !== null)
+                component.envs.push({ key, value, scope: "RUN_TIME", ...(secret ? { type: "SECRET" } : {}) });
+        }
+    }
+    // Spec goes in via stdin so secrets never appear in process arguments
+    doctl(["apps", "update", appId, "--spec", "-", "--output", "json"], JSON.stringify(spec));
+    return appId;
+}
+// --- commands ---------------------------------------------------------------
+async function init(opts) {
+    const dir = process.cwd();
+    const envFile = path.join(dir, ".env.local");
+    const existing = readEnvFile(envFile);
+    const domain = publicHostname(String(opts.domain ?? existing.get("DAYWALKER_DOMAIN") ?? ""));
+    if (!domain)
+        fail("--domain must be the public hostname that serves this app, e.g. --domain sonalyze.daywalker.dev");
+    const slug = String(opts.service ?? existing.get("DAYWALKER_SERVICE_SLUG") ?? "").trim().toLowerCase();
+    if (!/^[a-z0-9_-]+$/.test(slug))
+        fail("--service must be this service's Daywalker slug, e.g. --service sonalyze");
+    const keyExists = Boolean(existing.get("DAYWALKER_SIGNING_KEY")) && !opts.force;
+    const key = keyExists ? null : generateSigningKey();
+    const framework = opts.framework || detectFramework(dir);
+    let routeNote;
+    if (framework === "next")
+        routeNote = addNextRoute(dir);
+    else if (framework === "express")
+        routeNote = `add app.use(daywalkerKeys()) from "@shelbyb/daywalker-sdk/express" before your routes`;
+    else
+        routeNote = `serve GET /.well-known/daywalker-keys.json with daywalker().keys() (see the SDK README)`;
+    writeEnvFile(envFile, {
+        DAYWALKER_SERVICE_SLUG: slug,
+        DAYWALKER_DOMAIN: domain,
+        ...(key ? { DAYWALKER_SIGNING_KEY: key.privateKey } : {}),
+    });
+    ensureGitignored(dir, ".env.local");
+    console.log(`✔ Daywalker configured for ${domain} (service "${slug}")`);
+    console.log(`  • ${routeNote}`);
+    console.log(`  • .env.local: DAYWALKER_SERVICE_SLUG, DAYWALKER_DOMAIN${key ? ", DAYWALKER_SIGNING_KEY" : " (kept existing signing key)"}`);
+    if (key)
+        console.log(`  • key id ${key.publicJwk.kid}`);
+    if (opts["do-app"]) {
+        const signingKey = key?.privateKey ?? existing.get("DAYWALKER_SIGNING_KEY");
+        const appId = setDigitalOceanEnv(String(opts["do-app"]), {
+            DAYWALKER_SERVICE_SLUG: { value: slug, secret: false },
+            DAYWALKER_DOMAIN: { value: domain, secret: false },
+            DAYWALKER_SIGNING_KEY: { value: signingKey, secret: true },
+        });
+        console.log(`  • DigitalOcean app ${appId}: env vars set (signing key encrypted); a redeploy has started`);
+        console.log(`    Pull the updated spec into .do/app.yaml before your next spec deploy, or the key will be removed.`);
+    }
+    else {
+        console.log(`  • Production: set DAYWALKER_SERVICE_SLUG, DAYWALKER_DOMAIN, and DAYWALKER_SIGNING_KEY (as a secret)`);
+        console.log(`    on your host, or re-run with --do-app <name> for DigitalOcean App Platform.`);
+    }
+    if (opts["print-key"] && key)
+        console.log(`\nDAYWALKER_SIGNING_KEY=${key.privateKey}`);
+    console.log(`\nNext: deploy, then run \`npx daywalker check\`, and add ${domain} (or *.${domain.split(".").slice(1).join(".")}) to your token's allowed callers.`);
+}
+async function rotate(opts) {
+    const envFile = path.join(process.cwd(), ".env.local");
+    const existing = readEnvFile(envFile);
+    const current = existing.get("DAYWALKER_SIGNING_KEY");
+    if (!current)
+        fail("No DAYWALKER_SIGNING_KEY in .env.local; run `daywalker init` first");
+    const key = generateSigningKey();
+    writeEnvFile(envFile, { DAYWALKER_SIGNING_KEY: key.privateKey, DAYWALKER_SIGNING_KEY_PREVIOUS: current });
+    console.log(`✔ New key ${key.publicJwk.kid} written; the old key stays published as DAYWALKER_SIGNING_KEY_PREVIOUS.`);
+    if (opts["do-app"]) {
+        const appId = setDigitalOceanEnv(String(opts["do-app"]), {
+            DAYWALKER_SIGNING_KEY: { value: key.privateKey, secret: true },
+            DAYWALKER_SIGNING_KEY_PREVIOUS: { value: current, secret: true },
+        });
+        console.log(`  • DigitalOcean app ${appId} updated; a redeploy has started.`);
+    }
+    console.log(`  After the deploy is live, remove DAYWALKER_SIGNING_KEY_PREVIOUS to retire the old key.`);
+    if (opts["print-key"])
+        console.log(`\nDAYWALKER_SIGNING_KEY=${key.privateKey}`);
+}
+async function check() {
+    // Merge .env.local over the process env, like Next.js does in development
+    const env = { ...process.env, ...Object.fromEntries(readEnvFile(path.join(process.cwd(), ".env.local"))) };
+    const result = await createDaywalker({ env }).selfCheck();
+    console.log(`domain:  ${result.domain ?? "(none)"}`);
+    console.log(`keys:    ${result.keysUrl ?? "(none)"}`);
+    console.log(`signing: ${result.signing ? "yes" : "no"}`);
+    if (result.ok)
+        console.log("✔ Ready: requests will be signed and your key is published.");
+    else {
+        for (const p of result.problems)
+            console.log(`✖ ${p}`);
+        process.exit(1);
+    }
+}
+const [command, ...rest] = process.argv.slice(2);
+const opts = args(rest);
+const commands = { init, rotate, check };
+if (!command || !commands[command] || opts.help) {
+    console.log(HELP);
+    process.exit(command && !opts.help ? 1 : 0);
+}
+commands[command](opts).catch((err) => fail(err.message));

package/dist/client.d.ts

@@ -0,0 +1,78 @@
+import { type DaywalkerOptions, type ResolvedConfig } from "./config.js";
+import { type PublicJwk } from "./signing.js";
+export interface RateLimitWindow {
+    limit: number;
+    remaining: number;
+    /** Unix seconds when `remaining` next increases */
+    reset: number;
+}
+/** Body of POST /api/v1/tokens/validate */
+export interface TokenValidation {
+    valid: boolean;
+    serviceSlug?: string;
+    tokenId?: string;
+    tokenName?: string;
+    userId?: string;
+    stage?: string;
+    rateLimit?: RateLimitWindow;
+    rateLimitHourly?: RateLimitWindow;
+    retryAfter?: number;
+    error?: string;
+    message?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    /** HTTP status from Daywalker, or 503 when it couldn't be reached */
+    status: number;
+    data: TokenValidation;
+    /** Seconds to wait before retrying (429 responses) */
+    retryAfter?: number;
+    /** Whether the request carried a domain signature */
+    signed: boolean;
+}
+export interface SelfCheckResult {
+    ok: boolean;
+    domain: string | null;
+    keysUrl: string | null;
+    signing: boolean;
+    problems: string[];
+}
+export declare class DaywalkerError extends Error {
+    readonly status: number;
+    readonly result?: ValidationResult | undefined;
+    constructor(message: string, status: number, result?: ValidationResult | undefined);
+}
+export interface Daywalker {
+    readonly config: ResolvedConfig;
+    /**
+     * Validate an API token (defaults to DAYWALKER_API_KEY) for a service (defaults to
+     * DAYWALKER_SERVICE_SLUG). Successful results are cached briefly.
+     */
+    validateToken(options?: {
+        token?: string;
+        serviceSlug?: string;
+        forceRefresh?: boolean;
+    }): Promise<ValidationResult>;
+    /** Like validateToken, but throws DaywalkerError when the token isn't valid. */
+    requireValidToken(options?: {
+        token?: string;
+        serviceSlug?: string;
+    }): Promise<ValidationResult>;
+    /**
+     * fetch() for any Daywalker Auth API path (e.g. "/api/v1/tokens/validate"), domain-signed
+     * when a signing key and domain are configured. Pass the body as a string, or as an object
+     * to send JSON.
+     */
+    fetch(path: string, init?: Omit<RequestInit, "body"> & {
+        body?: string | object;
+    }): Promise<Response>;
+    /** The JWKS document to serve at /.well-known/daywalker-keys.json */
+    keys(): {
+        keys: PublicJwk[];
+    };
+    /** Check configuration and that the domain serves this service's public key. */
+    selfCheck(): Promise<SelfCheckResult>;
+}
+export declare function createDaywalker(options?: DaywalkerOptions): Daywalker;
+/** A process-wide client configured from environment variables. */
+export declare function daywalker(): Daywalker;

package/dist/client.js

@@ -0,0 +1,143 @@
+import { resolveConfig } from "./config.js";
+import { signRequest, KEYS_PATH } from "./signing.js";
+export class DaywalkerError extends Error {
+    status;
+    result;
+    constructor(message, status, result) {
+        super(message);
+        this.status = status;
+        this.result = result;
+        this.name = "DaywalkerError";
+    }
+}
+export function createDaywalker(options = {}) {
+    const config = resolveConfig(options);
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const cacheTtlMs = options.cacheTtlMs ?? 60_000;
+    const cache = new Map();
+    const signing = Boolean(config.signingKey && config.domain);
+    async function signedFetch(path, init = {}) {
+        const url = new URL(path, config.authUrl);
+        const method = (init.method ?? (init.body !== undefined ? "POST" : "GET")).toUpperCase();
+        const body = init.body === undefined ? "" : typeof init.body === "string" ? init.body : JSON.stringify(init.body);
+        const headers = new Headers(init.headers);
+        if (init.body !== undefined && typeof init.body !== "string" && !headers.has("content-type")) {
+            headers.set("content-type", "application/json");
+        }
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+        if (config.domain) {
+            // A hint for DNS-based allowlist checks; the signature below is the actual proof
+            headers.set("x-caller-origin", `https://${config.domain}`);
+        }
+        if (signing) {
+            for (const [k, v] of Object.entries(signRequest({ method, path: url.pathname, domain: config.domain, body, key: config.signingKey }))) {
+                headers.set(k, v);
+            }
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await doFetch(url, {
+                ...init,
+                method,
+                headers,
+                body: method === "GET" || method === "HEAD" ? undefined : body,
+                signal: init.signal ?? controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async function validateToken(opts = {}) {
+        const token = opts.token ?? config.apiKey;
+        const serviceSlug = (opts.serviceSlug ?? config.serviceSlug ?? "").toLowerCase();
+        if (!token || !serviceSlug) {
+            const message = !token ? "DAYWALKER_API_KEY is not set" : "DAYWALKER_SERVICE_SLUG is not set";
+            return { valid: false, status: 500, signed: false, data: { valid: false, error: "Configuration Error", message } };
+        }
+        const cacheKey = `${serviceSlug}:${token}`;
+        const cached = cache.get(cacheKey);
+        if (!opts.forceRefresh && cached && cached.expiresAt > Date.now())
+            return cached.result;
+        let result;
+        try {
+            const res = await signedFetch("/api/v1/tokens/validate", { method: "POST", body: { token, serviceSlug } });
+            const data = (await res.json().catch(() => ({ valid: false })));
+            const retryAfter = Number(res.headers.get("retry-after")) || data.retryAfter || undefined;
+            result = { valid: res.ok && data.valid === true, status: res.status, data, retryAfter, signed: signing };
+        }
+        catch (err) {
+            const timedOut = err.name === "AbortError";
+            result = {
+                valid: false,
+                status: 503,
+                signed: signing,
+                data: {
+                    valid: false,
+                    error: timedOut ? "Request Timeout" : "Service Unavailable",
+                    message: timedOut ? "Daywalker Auth did not respond in time" : `Could not reach Daywalker Auth: ${err.message}`,
+                },
+            };
+        }
+        if (result.valid && cacheTtlMs > 0)
+            cache.set(cacheKey, { result, expiresAt: Date.now() + cacheTtlMs });
+        else
+            cache.delete(cacheKey);
+        if (!result.valid && result.status !== 503) {
+            console.warn(`[daywalker] Token validation failed (${result.status}): ${result.data.message ?? result.data.error}`);
+        }
+        return result;
+    }
+    function keys() {
+        const list = [config.signingKey, config.previousSigningKey]
+            .filter((k) => Boolean(k))
+            .map((k) => k.publicJwk);
+        return { keys: list.filter((k, i) => list.findIndex((o) => o.kid === k.kid) === i) };
+    }
+    async function selfCheck() {
+        const problems = [...config.problems];
+        if (!config.signingKey)
+            problems.push("DAYWALKER_SIGNING_KEY is not set: requests are unsigned, so domain allowlists can't match");
+        const keysUrl = config.domain ? `https://${config.domain}${KEYS_PATH}` : null;
+        if (keysUrl && config.signingKey) {
+            try {
+                const res = await doFetch(keysUrl, { headers: { accept: "application/json" }, redirect: "manual" });
+                if (res.status !== 200) {
+                    problems.push(`${keysUrl} returned HTTP ${res.status} (it must serve the key directly, without redirects)`);
+                }
+                else {
+                    const doc = (await res.json().catch(() => null));
+                    if (!doc?.keys?.some((k) => k.kid === config.signingKey.publicJwk.kid)) {
+                        problems.push(`${keysUrl} doesn't publish this service's current key (kid ${config.signingKey.publicJwk.kid})`);
+                    }
+                }
+            }
+            catch (err) {
+                problems.push(`Could not fetch ${keysUrl}: ${err.message}`);
+            }
+        }
+        return { ok: problems.length === 0, domain: config.domain, keysUrl, signing, problems };
+    }
+    return {
+        config,
+        validateToken,
+        async requireValidToken(opts = {}) {
+            const result = await validateToken(opts);
+            if (!result.valid)
+                throw new DaywalkerError(result.data.message ?? "Token validation failed", result.status, result);
+            return result;
+        },
+        fetch: signedFetch,
+        keys,
+        selfCheck,
+    };
+}
+let shared = null;
+/** A process-wide client configured from environment variables. */
+export function daywalker() {
+    shared ??= createDaywalker();
+    return shared;
+}

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+import { type SigningKey } from "./signing.js";
+/**
+ * Everything a service needs, read from its environment:
+ *
+ *   DAYWALKER_API_KEY          the service's Daywalker API token (srv_live_…)          required
+ *   DAYWALKER_SERVICE_SLUG     the service it validates against (e.g. "sonalyze")       required
+ *   DAYWALKER_SIGNING_KEY      Ed25519 private key from `daywalker init`                required for allowlisted tokens
+ *   DAYWALKER_SIGNING_KEY_PREVIOUS  old key, still published during a rotation          optional
+ *   DAYWALKER_DOMAIN           public hostname that serves /.well-known/daywalker-keys.json
+ *                              (defaults to the hostname of APP_URL, NEXTAUTH_URL, …)
+ *   DAYWALKER_AUTH_URL         defaults to https://auth.daywalker.dev
+ */
+export interface DaywalkerOptions {
+    apiKey?: string;
+    serviceSlug?: string;
+    /** Private key (PEM or base64 DER) or an already loaded key. */
+    signingKey?: string | SigningKey | null;
+    previousSigningKey?: string | SigningKey | null;
+    domain?: string;
+    authUrl?: string;
+    /** Override for tests or custom runtimes. */
+    fetch?: typeof fetch;
+    /** Request timeout in ms (default 5000). */
+    timeoutMs?: number;
+    /** How long a successful validation is cached, in ms (default 60000, 0 disables). */
+    cacheTtlMs?: number;
+    env?: Record<string, string | undefined>;
+}
+export interface ResolvedConfig {
+    apiKey: string | null;
+    serviceSlug: string | null;
+    signingKey: SigningKey | null;
+    previousSigningKey: SigningKey | null;
+    domain: string | null;
+    /** Where the domain came from, for diagnostics. */
+    domainSource: string | null;
+    authUrl: string;
+    problems: string[];
+}
+/**
+ * A public hostname from a URL or bare host, or null for anything that can't be fetched over
+ * the internet (localhost, 0.0.0.0, IP addresses, single labels). Containers often report their
+ * bind address (http://0.0.0.0:3000) as the request origin, which must never be used.
+ */
+export declare function publicHostname(value: string | undefined | null): string | null;
+export declare function resolveConfig(options?: DaywalkerOptions): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,87 @@
+import net from "node:net";
+import { loadSigningKey } from "./signing.js";
+// Platform variables that commonly hold the app's public URL or hostname, in priority order
+const URL_ENV_VARS = [
+    "APP_URL",
+    "NEXTAUTH_URL",
+    "NEXT_PUBLIC_APP_URL",
+    "BETTER_AUTH_URL",
+    "PUBLIC_URL",
+    "SITE_URL",
+    "URL", // Netlify
+    "VERCEL_PROJECT_PRODUCTION_URL",
+    "RENDER_EXTERNAL_HOSTNAME",
+    "RAILWAY_PUBLIC_DOMAIN",
+    "VERCEL_URL",
+];
+const DOMAIN_PATTERN = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/;
+/**
+ * A public hostname from a URL or bare host, or null for anything that can't be fetched over
+ * the internet (localhost, 0.0.0.0, IP addresses, single labels). Containers often report their
+ * bind address (http://0.0.0.0:3000) as the request origin, which must never be used.
+ */
+export function publicHostname(value) {
+    if (!value || !value.trim())
+        return null;
+    let host = value.trim().toLowerCase();
+    try {
+        host = new URL(/^[a-z][a-z0-9+.-]*:\/\//.test(host) ? host : `https://${host}`).hostname;
+    }
+    catch {
+        return null;
+    }
+    host = host.replace(/\.$/, "");
+    if (net.isIP(host.replace(/^\[|\]$/g, "")) || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+        return null;
+    }
+    return DOMAIN_PATTERN.test(host) ? host : null;
+}
+function keyFrom(value, name, problems) {
+    if (!value)
+        return null;
+    if (typeof value !== "string")
+        return value;
+    try {
+        return loadSigningKey(value);
+    }
+    catch (err) {
+        problems.push(`${name} could not be loaded: ${err.message}`);
+        return null;
+    }
+}
+export function resolveConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const problems = [];
+    const apiKey = (options.apiKey ?? env.DAYWALKER_API_KEY ?? "").trim() || null;
+    const serviceSlug = (options.serviceSlug ?? env.DAYWALKER_SERVICE_SLUG ?? "").trim().toLowerCase() || null;
+    if (!apiKey)
+        problems.push("DAYWALKER_API_KEY is not set");
+    if (!serviceSlug)
+        problems.push("DAYWALKER_SERVICE_SLUG is not set");
+    const signingKey = keyFrom(options.signingKey ?? env.DAYWALKER_SIGNING_KEY, "DAYWALKER_SIGNING_KEY", problems);
+    const previousSigningKey = keyFrom(options.previousSigningKey ?? env.DAYWALKER_SIGNING_KEY_PREVIOUS, "DAYWALKER_SIGNING_KEY_PREVIOUS", problems);
+    let domain = null;
+    let domainSource = null;
+    const explicit = options.domain ?? env.DAYWALKER_DOMAIN ?? env.DAYWALKER_SIGNING_DOMAIN;
+    if (explicit) {
+        domain = publicHostname(explicit);
+        domainSource = options.domain ? "options.domain" : env.DAYWALKER_DOMAIN ? "DAYWALKER_DOMAIN" : "DAYWALKER_SIGNING_DOMAIN";
+        if (!domain)
+            problems.push(`${domainSource} (${explicit}) is not a public domain name`);
+    }
+    else {
+        for (const name of URL_ENV_VARS) {
+            const host = publicHostname(env[name]);
+            if (host) {
+                domain = host;
+                domainSource = name;
+                break;
+            }
+        }
+    }
+    if (signingKey && !domain) {
+        problems.push("No public domain found: set DAYWALKER_DOMAIN (requests will be sent unsigned)");
+    }
+    const authUrl = (options.authUrl ?? env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    return { apiKey, serviceSlug, signingKey, previousSigningKey, domain, domainSource, authUrl, problems };
+}

package/dist/express.d.ts

@@ -0,0 +1,18 @@
+import { type Daywalker } from "./client.js";
+interface Req {
+    method?: string;
+    path?: string;
+    url?: string;
+}
+interface Res {
+    setHeader(name: string, value: string): unknown;
+    statusCode?: number;
+    end(body?: string): unknown;
+}
+/**
+ * Express / Connect / Node http middleware that serves /.well-known/daywalker-keys.json.
+ *
+ *   app.use(daywalkerKeys());
+ */
+export declare function daywalkerKeys(client?: Daywalker): (req: Req, res: Res, next?: () => void) => void;
+export {};

package/dist/express.js

@@ -0,0 +1,20 @@
+import { daywalker } from "./client.js";
+import { KEYS_PATH } from "./signing.js";
+/**
+ * Express / Connect / Node http middleware that serves /.well-known/daywalker-keys.json.
+ *
+ *   app.use(daywalkerKeys());
+ */
+export function daywalkerKeys(client = daywalker()) {
+    return (req, res, next) => {
+        const path = req.path ?? (req.url ?? "").split("?")[0];
+        if ((req.method ?? "GET") === "GET" && path === KEYS_PATH) {
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.setHeader("Cache-Control", "public, max-age=300");
+            res.end(JSON.stringify(client.keys()));
+            return;
+        }
+        next?.();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createDaywalker, daywalker, DaywalkerError } from "./client.js";
+export type { Daywalker, ValidationResult, TokenValidation, RateLimitWindow, SelfCheckResult } from "./client.js";
+export { resolveConfig, publicHostname } from "./config.js";
+export type { DaywalkerOptions, ResolvedConfig } from "./config.js";
+export { generateSigningKey, loadSigningKey, signRequest, canonicalPayload, KEYS_PATH, SIGNATURE_VERSION } from "./signing.js";
+export type { SigningKey, PublicJwk } from "./signing.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createDaywalker, daywalker, DaywalkerError } from "./client.js";
+export { resolveConfig, publicHostname } from "./config.js";
+export { generateSigningKey, loadSigningKey, signRequest, canonicalPayload, KEYS_PATH, SIGNATURE_VERSION } from "./signing.js";

package/dist/next.d.ts

@@ -0,0 +1,10 @@
+import { type Daywalker } from "./client.js";
+/**
+ * Next.js App Router route handler for /.well-known/daywalker-keys.json.
+ *
+ *   // app/.well-known/daywalker-keys.json/route.ts
+ *   export { GET, dynamic } from "@shelbyb/daywalker-sdk/next";
+ */
+export declare const dynamic = "force-dynamic";
+export declare function keysRouteHandler(client?: Daywalker): () => Response;
+export declare const GET: () => Response;

package/dist/next.js

@@ -0,0 +1,14 @@
+import { daywalker } from "./client.js";
+/**
+ * Next.js App Router route handler for /.well-known/daywalker-keys.json.
+ *
+ *   // app/.well-known/daywalker-keys.json/route.ts
+ *   export { GET, dynamic } from "@shelbyb/daywalker-sdk/next";
+ */
+export const dynamic = "force-dynamic";
+export function keysRouteHandler(client = daywalker()) {
+    return function GET() {
+        return Response.json(client.keys(), { headers: { "Cache-Control": "public, max-age=300" } });
+    };
+}
+export const GET = () => keysRouteHandler()();

package/dist/signing.d.ts

@@ -0,0 +1,53 @@
+import { type KeyObject } from "node:crypto";
+/**
+ * Domain-signed requests to Daywalker Auth.
+ *
+ * Each request is signed with an Ed25519 key whose public half the calling service serves at
+ * https://<domain>/.well-known/daywalker-keys.json. Daywalker fetches that key over HTTPS, so
+ * a valid signature proves the request comes from whoever controls the domain, wherever the
+ * service is hosted. This must match Daywalker's verifier exactly (src/lib/request-signature.ts
+ * in daywalker-service-auth).
+ */
+export declare const SIGNATURE_VERSION = "daywalker-v1";
+export declare const KEYS_PATH = "/.well-known/daywalker-keys.json";
+export interface PublicJwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    kid: string;
+    use: "sig";
+    alg: "EdDSA";
+}
+export interface SigningKey {
+    privateKey: KeyObject;
+    publicJwk: PublicJwk;
+}
+/** Generate a new key; `privateKey` is base64 PKCS#8 DER, the format DAYWALKER_SIGNING_KEY expects. */
+export declare function generateSigningKey(): {
+    privateKey: string;
+    publicJwk: PublicJwk;
+};
+/**
+ * Load a private key from env: PKCS#8 PEM (literal "\n" escapes are fine) or base64 PKCS#8 DER.
+ * The key id is the RFC 7638 JWK thumbprint, so it's stable without extra configuration.
+ */
+export declare function loadSigningKey(raw: string): SigningKey;
+export declare function canonicalPayload(p: {
+    method: string;
+    path: string;
+    domain: string;
+    timestamp: string;
+    nonce: string;
+    body: string;
+}): string;
+/** The X-Daywalker-* headers for one request. Send exactly `body` as the request body. */
+export declare function signRequest(params: {
+    method: string;
+    /** URL path only, e.g. /api/v1/tokens/validate */
+    path: string;
+    domain: string;
+    body: string;
+    key: SigningKey;
+    timestamp?: number;
+    nonce?: string;
+}): Record<string, string>;

package/dist/signing.js

@@ -0,0 +1,51 @@
+import crypto from "node:crypto";
+/**
+ * Domain-signed requests to Daywalker Auth.
+ *
+ * Each request is signed with an Ed25519 key whose public half the calling service serves at
+ * https://<domain>/.well-known/daywalker-keys.json. Daywalker fetches that key over HTTPS, so
+ * a valid signature proves the request comes from whoever controls the domain, wherever the
+ * service is hosted. This must match Daywalker's verifier exactly (src/lib/request-signature.ts
+ * in daywalker-service-auth).
+ */
+export const SIGNATURE_VERSION = "daywalker-v1";
+export const KEYS_PATH = "/.well-known/daywalker-keys.json";
+/** Generate a new key; `privateKey` is base64 PKCS#8 DER, the format DAYWALKER_SIGNING_KEY expects. */
+export function generateSigningKey() {
+    const { privateKey } = crypto.generateKeyPairSync("ed25519");
+    const der = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64");
+    return { privateKey: der, publicJwk: loadSigningKey(der).publicJwk };
+}
+/**
+ * Load a private key from env: PKCS#8 PEM (literal "\n" escapes are fine) or base64 PKCS#8 DER.
+ * The key id is the RFC 7638 JWK thumbprint, so it's stable without extra configuration.
+ */
+export function loadSigningKey(raw) {
+    const value = raw.trim();
+    const privateKey = value.includes("-----BEGIN")
+        ? crypto.createPrivateKey(value.replace(/\\n/g, "\n"))
+        : crypto.createPrivateKey({ key: Buffer.from(value, "base64"), format: "der", type: "pkcs8" });
+    if (privateKey.asymmetricKeyType !== "ed25519") {
+        throw new Error(`DAYWALKER_SIGNING_KEY must be an Ed25519 key (got ${privateKey.asymmetricKeyType})`);
+    }
+    const { x } = crypto.createPublicKey(privateKey).export({ format: "jwk" });
+    const kid = crypto.createHash("sha256").update(JSON.stringify({ crv: "Ed25519", kty: "OKP", x })).digest("base64url");
+    return { privateKey, publicJwk: { kty: "OKP", crv: "Ed25519", x, kid, use: "sig", alg: "EdDSA" } };
+}
+export function canonicalPayload(p) {
+    const bodySha256 = crypto.createHash("sha256").update(p.body, "utf8").digest("hex");
+    return [SIGNATURE_VERSION, p.method.toUpperCase(), p.path, p.domain.toLowerCase(), p.timestamp, p.nonce, bodySha256].join("\n");
+}
+/** The X-Daywalker-* headers for one request. Send exactly `body` as the request body. */
+export function signRequest(params) {
+    const timestamp = String(params.timestamp ?? Math.floor(Date.now() / 1000));
+    const nonce = params.nonce ?? crypto.randomBytes(24).toString("base64url");
+    const payload = canonicalPayload({ ...params, timestamp, nonce });
+    return {
+        "X-Daywalker-Domain": params.domain.toLowerCase(),
+        "X-Daywalker-Key-Id": params.key.publicJwk.kid,
+        "X-Daywalker-Timestamp": timestamp,
+        "X-Daywalker-Nonce": nonce,
+        "X-Daywalker-Signature": crypto.sign(null, Buffer.from(payload), params.key.privateKey).toString("base64url"),
+    };
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Validate Daywalker API tokens and make domain-signed calls to Daywalker Auth from any service.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js"
+    }
+  },
+  "bin": {
+    "daywalker": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shelbyb/daywalker-service-auth.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "daywalker",
+    "api-token",
+    "authentication",
+    "ed25519",
+    "request-signing"
+  ],
+  "homepage": "https://auth.daywalker.dev/docs"
+}