@shelbyb/daywalker-sdk 0.1.0 → 0.1.2

package/dist/client.d.ts

@@ -1,78 +1,60 @@
-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;
+import { type ResolvedConfig } from "./config.js";
+import { type DaywalkerConfig, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+export type DaywalkerFetchInit = Omit<RequestInit, "body"> & {
+    body?: BodyInit | object | null;
+    retry?: RetryOptions;
+};
+export declare class Daywalker {
+    private readonly _config;
+    private readonly _rawConfig;
+    private _signingKeyPromise?;
+    private readonly _cache;
+    constructor(config?: DaywalkerConfig);
+    get config(): ResolvedConfig;
+    toJSON(): Record<string, unknown>;
+    private getLoadedSigningKey;
+    /**
+     * Signs and executes requests with automatic retry and exponential backoff on 429 responses.
+     */
+    fetch(path: string, init?: DaywalkerFetchInit): Promise<Response>;
     /**
-     * Validate an API token (defaults to DAYWALKER_API_KEY) for a service (defaults to
-     * DAYWALKER_SERVICE_SLUG). Successful results are cached briefly.
+     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
      */
-    validateToken(options?: {
+    validateToken(tokenOrOptions?: string | {
         token?: string;
         serviceSlug?: string;
         forceRefresh?: boolean;
-    }): Promise<ValidationResult>;
-    /** Like validateToken, but throws DaywalkerError when the token isn't valid. */
-    requireValidToken(options?: {
+        offlineOnly?: boolean;
+    }, options?: {
+        serviceSlug?: string;
+        forceRefresh?: boolean;
+        offlineOnly?: boolean;
+    }): Promise<ValidateResult>;
+    /**
+     * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
+     */
+    requireValidToken(tokenOrOptions?: string | {
         token?: string;
         serviceSlug?: string;
-    }): Promise<ValidationResult>;
+        offlineOnly?: boolean;
+    }, options?: {
+        serviceSlug?: string;
+        offlineOnly?: boolean;
+    }): Promise<TokenPayload>;
     /**
-     * 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.
+     * The public JWK(s) configured for this service.
      */
-    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(): Promise<{
         keys: PublicJwk[];
-    };
-    /** Check configuration and that the domain serves this service's public key. */
+    }>;
+    /**
+     * Check configuration and verify signature readiness.
+     */
     selfCheck(): Promise<SelfCheckResult>;
 }
-export declare function createDaywalker(options?: DaywalkerOptions): Daywalker;
-/** A process-wide client configured from environment variables. */
-export declare function daywalker(): Daywalker;
+/**
+ * Factory function for creating instantiable Daywalker client instances.
+ */
+export declare function createDaywalker(config?: DaywalkerConfig): Daywalker;
+export declare const daywalker: Daywalker & (() => Daywalker);

package/dist/client.js

@@ -1,143 +1,376 @@
 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";
+import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, } from "./crypto/index.js";
+import { DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
+function parseRetryAfter(headerValue) {
+    if (!headerValue)
+        return undefined;
+    const seconds = parseInt(headerValue.trim(), 10);
+    if (!Number.isNaN(seconds) && seconds >= 0) {
+        return seconds;
     }
+    const date = Date.parse(headerValue);
+    if (!Number.isNaN(date)) {
+        const diff = Math.ceil((date - Date.now()) / 1000);
+        return diff > 0 ? diff : 0;
+    }
+    return undefined;
 }
-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, {
+export class Daywalker {
+    _config;
+    _rawConfig;
+    _signingKeyPromise;
+    _cache = new Map();
+    constructor(config = {}) {
+        this._rawConfig = config;
+        this._config = resolveConfig(config);
+    }
+    get config() {
+        return this._config;
+    }
+    toJSON() {
+        return {
+            serviceSlug: this._config.serviceSlug,
+            domain: this._config.domain,
+            authUrl: this._config.authUrl,
+            keyId: this._config.keyId,
+            apiKey: maskSecret(this._config.apiKey),
+            signingKey: this._config.signingKey ? "[configured]" : null,
+            daywalkerPublicKey: this._config.daywalkerPublicKey ? "[configured]" : null,
+        };
+    }
+    // Node.js custom inspect masking
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toJSON();
+    }
+    async getLoadedSigningKey() {
+        if (!this._config.signingKey)
+            return null;
+        if (typeof this._config.signingKey !== "string" && "privateKey" in this._config.signingKey) {
+            return this._config.signingKey;
+        }
+        if (!this._signingKeyPromise) {
+            this._signingKeyPromise = loadSigningKey(this._config.signingKey);
+        }
+        return this._signingKeyPromise;
+    }
+    /**
+     * Signs and executes requests with automatic retry and exponential backoff on 429 responses.
+     */
+    async fetch(path, init) {
+        const authUrl = this._config.authUrl;
+        const url = new URL(path, authUrl);
+        const method = (init?.method ?? (init?.body !== undefined ? "POST" : "GET")).toUpperCase();
+        const doFetch = this._rawConfig.fetch ?? globalThis.fetch;
+        const retryOpts = {
+            maxRetries: init?.retry?.maxRetries ?? this._config.maxRetries ?? 3,
+            initialDelayMs: init?.retry?.initialDelayMs ?? 500,
+            maxDelayMs: init?.retry?.maxDelayMs ?? 30_000,
+            backoffFactor: init?.retry?.backoffFactor ?? 2,
+            jitter: init?.retry?.jitter ?? true,
+            ...init?.retry,
+        };
+        const rawBody = init?.body;
+        let bodyString = null;
+        if (rawBody !== undefined && rawBody !== null) {
+            if (typeof rawBody === "string") {
+                bodyString = rawBody;
+            }
+            else if (rawBody instanceof Uint8Array) {
+                bodyString = rawBody;
+            }
+            else if (typeof rawBody === "object") {
+                bodyString = JSON.stringify(rawBody);
+            }
+        }
+        const signingKey = await this.getLoadedSigningKey();
+        let attempt = 0;
+        while (true) {
+            const headers = new Headers(init?.headers);
+            if (rawBody !== undefined && !headers.has("content-type") && typeof rawBody === "object" && !(rawBody instanceof Uint8Array)) {
+                headers.set("content-type", "application/json");
+            }
+            if (!headers.has("accept")) {
+                headers.set("accept", "application/json");
+            }
+            if (this._config.apiKey && !headers.has("authorization")) {
+                headers.set("authorization", `Bearer ${this._config.apiKey}`);
+            }
+            if (signingKey) {
+                const signedHeaders = await signRequest({
+                    method,
+                    path: url.pathname,
+                    authority: url.host,
+                    body: bodyString,
+                    key: signingKey,
+                    keyid: this._config.keyId ?? undefined,
+                    apiKey: this._config.apiKey ?? undefined,
+                });
+                for (const [k, v] of Object.entries(signedHeaders)) {
+                    if (v !== undefined) {
+                        headers.set(k, v);
+                    }
+                }
+            }
+            const reqInit = {
                 ...init,
                 method,
                 headers,
-                body: method === "GET" || method === "HEAD" ? undefined : body,
-                signal: init.signal ?? controller.signal,
-            });
-        }
-        finally {
-            clearTimeout(timer);
+                body: bodyString ?? undefined,
+            };
+            let res;
+            try {
+                res = await doFetch(url.toString(), reqInit);
+            }
+            catch (err) {
+                if (attempt < (retryOpts.maxRetries ?? 3)) {
+                    attempt++;
+                    const delay = (retryOpts.initialDelayMs ?? 500) * Math.pow(retryOpts.backoffFactor ?? 2, attempt - 1);
+                    await new Promise((r) => setTimeout(r, delay));
+                    continue;
+                }
+                throw err;
+            }
+            if (res.status === 429 && attempt < (retryOpts.maxRetries ?? 3)) {
+                attempt++;
+                const retryAfterSec = parseRetryAfter(res.headers.get("retry-after"));
+                let delayMs = (retryOpts.initialDelayMs ?? 500) * Math.pow(retryOpts.backoffFactor ?? 2, attempt - 1);
+                if (retryOpts.jitter) {
+                    delayMs = delayMs * (0.8 + Math.random() * 0.4);
+                }
+                if (retryAfterSec !== undefined) {
+                    delayMs = Math.max(delayMs, retryAfterSec * 1000);
+                }
+                delayMs = Math.min(delayMs, retryOpts.maxDelayMs ?? 30_000);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
         }
     }
-    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())
+    /**
+     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
+     */
+    async validateToken(tokenOrOptions, options) {
+        let token;
+        let serviceSlug;
+        let forceRefresh = false;
+        let offlineOnly = false;
+        if (typeof tokenOrOptions === "string") {
+            token = tokenOrOptions;
+            serviceSlug = (options?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
+            forceRefresh = options?.forceRefresh ?? false;
+            offlineOnly = options?.offlineOnly ?? false;
+        }
+        else {
+            token = tokenOrOptions?.token ?? this._config.apiKey ?? undefined;
+            serviceSlug = (tokenOrOptions?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
+            forceRefresh = tokenOrOptions?.forceRefresh ?? false;
+            offlineOnly = tokenOrOptions?.offlineOnly ?? false;
+        }
+        if (!token) {
+            return {
+                ok: false,
+                error: "CONFIGURATION_ERROR",
+                status: 400,
+                message: "Missing token to validate",
+            };
+        }
+        const cacheKey = `${serviceSlug || "default"}:${token}`;
+        const cached = this._cache.get(cacheKey);
+        if (!forceRefresh && cached && cached.expiresAt > Date.now()) {
             return cached.result;
-        let result;
+        }
+        // Check for offline JWT lease verification
+        if (this._config.daywalkerPublicKey && token.split(".").length === 3) {
+            const jwtResult = await verifyJwtLease({
+                token,
+                publicKey: this._config.daywalkerPublicKey,
+                expectedServiceSlug: serviceSlug || undefined,
+            });
+            if (jwtResult.valid && jwtResult.payload) {
+                const payload = jwtResult.payload;
+                const result = {
+                    ok: true,
+                    data: {
+                        serviceSlug: serviceSlug || (payload.serviceSlug || payload.aud || ""),
+                        tenantId: (payload.tenantId || payload.sub || ""),
+                        rateLimit: payload.rateLimit ?? {
+                            limit: 1000,
+                            remaining: 999,
+                            reset: Math.floor(Date.now() / 1000) + 60,
+                        },
+                        rateLimitHourly: payload.rateLimitHourly,
+                        tokenId: (payload.tokenId || payload.sub),
+                        tokenName: payload.tokenName,
+                        userId: payload.userId,
+                        stage: payload.stage,
+                        offlineVerified: true,
+                        ...payload,
+                    },
+                };
+                if (this._config.cacheTtlMs > 0) {
+                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                }
+                return result;
+            }
+            else if (offlineOnly) {
+                return {
+                    ok: false,
+                    error: "INVALID_TOKEN",
+                    status: 401,
+                    message: jwtResult.error ?? "Offline token verification failed",
+                };
+            }
+        }
+        else if (offlineOnly) {
+            return {
+                ok: false,
+                error: "CONFIGURATION_ERROR",
+                status: 500,
+                message: "Offline verification requires DAYWALKER_PUBLIC_KEY and a valid JWT token lease",
+            };
+        }
+        // Online verification
         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 };
+            const validateBody = { token };
+            if (serviceSlug) {
+                validateBody.serviceSlug = serviceSlug;
+            }
+            const res = await this.fetch("/api/v1/tokens/validate", {
+                method: "POST",
+                body: validateBody,
+            });
+            const json = (await res.json().catch(() => ({})));
+            if (res.status === 200 && json.valid !== false) {
+                const payloadData = (typeof json.data === "object" && json.data ? json.data : json);
+                const data = {
+                    serviceSlug: json.serviceSlug || serviceSlug,
+                    tenantId: (payloadData.tenantId || payloadData.userId || json.tenantId || json.userId || ""),
+                    rateLimit: (payloadData.rateLimit || json.rateLimit || { limit: 0, remaining: 0, reset: 0 }),
+                    rateLimitHourly: (payloadData.rateLimitHourly || json.rateLimitHourly),
+                    tokenId: (payloadData.tokenId || json.tokenId),
+                    tokenName: (payloadData.tokenName || json.tokenName),
+                    userId: (payloadData.userId || json.userId),
+                    stage: (payloadData.stage || json.stage),
+                    ...payloadData,
+                };
+                const result = {
+                    ok: true,
+                    data,
+                };
+                if (this._config.cacheTtlMs > 0) {
+                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                }
+                return result;
+            }
+            if (res.status === 429) {
+                const retryAfter = parseRetryAfter(res.headers.get("retry-after")) ?? json.retryAfter;
+                return {
+                    ok: false,
+                    error: "RATE_LIMITED",
+                    status: 429,
+                    message: redactSecrets(json.message || "Rate limit exceeded"),
+                    retryAfter,
+                };
+            }
+            let error = "INVALID_TOKEN";
+            const errMsg = (json.message || json.error || "");
+            if (json.error === "EXPIRED" || /expired/i.test(errMsg)) {
+                error = "EXPIRED";
+            }
+            else if (json.error === "REVOKED" || /revoked/i.test(errMsg)) {
+                error = "REVOKED";
+            }
+            return {
+                ok: false,
+                error,
+                status: res.status,
+                message: redactSecrets(errMsg || `Validation failed with HTTP ${res.status}`),
+            };
         }
         catch (err) {
-            const timedOut = err.name === "AbortError";
-            result = {
-                valid: false,
+            return {
+                ok: false,
+                error: "NETWORK_ERROR",
                 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}`,
-                },
+                message: redactSecrets(`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}`);
+    }
+    /**
+     * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
+     */
+    async requireValidToken(tokenOrOptions, options) {
+        const result = await this.validateToken(tokenOrOptions, options);
+        if (!result.ok) {
+            if (result.status === 429) {
+                throw new DaywalkerRateLimitError(result.message, result.retryAfter);
+            }
+            throw new DaywalkerAuthError(result.message, result.status, result.error);
         }
-        return result;
+        return result.data;
     }
-    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) };
+    /**
+     * The public JWK(s) configured for this service.
+     */
+    async keys() {
+        const key = await this.getLoadedSigningKey();
+        return { keys: key ? [key.publicJwk] : [] };
     }
-    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}`);
-            }
+    /**
+     * Check configuration and verify signature readiness.
+     */
+    async selfCheck() {
+        const problems = [...this._config.problems];
+        const signingKey = await this.getLoadedSigningKey().catch((err) => {
+            problems.push(`Signing key load error: ${err.message}`);
+            return null;
+        });
+        if (!signingKey) {
+            problems.push("DAYWALKER_SIGNING_KEY is not set: requests will be sent without RFC 9421 signature");
         }
-        return { ok: problems.length === 0, domain: config.domain, keysUrl, signing, problems };
+        const keyId = signingKey?.publicJwk.kid ?? null;
+        const offlineVerificationReady = Boolean(this._config.daywalkerPublicKey);
+        return {
+            ok: problems.length === 0,
+            serviceSlug: this._config.serviceSlug,
+            domain: this._config.domain,
+            signing: Boolean(signingKey),
+            keyId,
+            offlineVerificationReady,
+            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;
+/**
+ * Factory function for creating instantiable Daywalker client instances.
+ */
+export function createDaywalker(config) {
+    return new Daywalker(config);
 }
+// Retain lazy default client instance for plug-and-play simplicity,
+// callable as `daywalker()` or usable directly as `daywalker.fetch(...)`.
+let defaultInstance = null;
+function getDefaultInstance() {
+    if (!defaultInstance) {
+        defaultInstance = new Daywalker();
+    }
+    return defaultInstance;
+}
+export const daywalker = new Proxy((() => getDefaultInstance()), {
+    get(_target, prop) {
+        const instance = getDefaultInstance();
+        const val = instance[prop];
+        if (typeof val === "function") {
+            return val.bind(instance);
+        }
+        return val;
+    },
+    apply(_target, _thisArg, args) {
+        if (args.length > 0) {
+            return new Daywalker(args[0]);
+        }
+        return getDefaultInstance();
+    },
+});