@shelbyb/daywalker-sdk 0.0.0-stage → 0.1.1

package/dist/client.js

@@ -0,0 +1,376 @@
+import { resolveConfig } from "./config.js";
+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 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: 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;
+        }
+    }
+    /**
+     * 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;
+        }
+        // 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 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) {
+            return {
+                ok: false,
+                error: "NETWORK_ERROR",
+                status: 503,
+                message: redactSecrets(`Could not reach Daywalker Auth: ${err.message}`),
+            };
+        }
+    }
+    /**
+     * 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.data;
+    }
+    /**
+     * The public JWK(s) configured for this service.
+     */
+    async keys() {
+        const key = await this.getLoadedSigningKey();
+        return { keys: key ? [key.publicJwk] : [] };
+    }
+    /**
+     * 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");
+        }
+        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,
+        };
+    }
+}
+/**
+ * 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();
+    },
+});

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+import type { DaywalkerConfig, PublicJwk, SigningKey } from "./types.js";
+export interface ResolvedConfig {
+    apiKey: string | null;
+    signingKey: string | SigningKey | null;
+    previousSigningKey: string | SigningKey | null;
+    keyId: string | null;
+    serviceSlug: string | null;
+    domain: string | null;
+    domainSource: string | null;
+    daywalkerPublicKey: string | PublicJwk | null;
+    authUrl: string;
+    cacheTtlMs: number;
+    maxRetries: number;
+    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).
+ */
+export declare function publicHostname(value: string | undefined | null): string | null;
+export declare function resolveConfig(options?: DaywalkerConfig): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,100 @@
+const URL_ENV_VARS = [
+    "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",
+];
+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]$/;
+function isIpAddress(host) {
+    if (host.length > 253)
+        return false;
+    // IPv4
+    if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(host))
+        return true;
+    // IPv6
+    if (host.includes(":"))
+        return true;
+    return false;
+}
+/**
+ * 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).
+ */
+export function publicHostname(value) {
+    if (!value || !value.trim())
+        return null;
+    let host = value.trim().toLowerCase();
+    if (host.length > 253)
+        return null;
+    try {
+        host = new URL(/^[a-z][a-z0-9+.-]*:\/\//.test(host) ? host : `https://${host}`).hostname;
+    }
+    catch {
+        return null;
+    }
+    host = host.replace(/\.$/, "");
+    if (host.length > 253 || isIpAddress(host.replace(/^\[|\]$/g, "")) || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+        return null;
+    }
+    return DOMAIN_PATTERN.test(host) ? host : null;
+}
+export function resolveConfig(options = {}) {
+    const env = options.env ?? (typeof process !== "undefined" && process.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 = options.signingKey ?? env.DAYWALKER_SIGNING_KEY ?? null;
+    const previousSigningKey = options.previousSigningKey ?? env.DAYWALKER_SIGNING_KEY_PREVIOUS ?? null;
+    const keyId = (options.keyId ?? env.DAYWALKER_KEY_ID ?? "").trim() || null;
+    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 val = env[name];
+            if (val) {
+                const host = publicHostname(val);
+                if (host) {
+                    domain = host;
+                    domainSource = name;
+                    break;
+                }
+            }
+        }
+    }
+    const daywalkerPublicKey = options.daywalkerPublicKey ?? (env.DAYWALKER_PUBLIC_KEY ? env.DAYWALKER_PUBLIC_KEY.trim() : null);
+    const authUrl = (options.authUrl ?? env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    const cacheTtlMs = options.cacheTtlMs ?? 60_000;
+    const maxRetries = options.maxRetries ?? (options.retry?.maxRetries ?? 3);
+    return {
+        apiKey,
+        signingKey,
+        previousSigningKey,
+        keyId,
+        serviceSlug,
+        domain,
+        domainSource,
+        daywalkerPublicKey,
+        authUrl,
+        cacheTtlMs,
+        maxRetries,
+        problems,
+    };
+}

package/dist/crypto/digest.d.ts

@@ -0,0 +1,17 @@
+/** Default upper bound for body payload digest calculation (10MB). */
+export declare const DEFAULT_MAX_BODY_SIZE_BYTES: number;
+/**
+ * RFC 9530 Digest Fields computation.
+ * Hashes payload with SHA-256 via WebCrypto `crypto.subtle.digest`.
+ * Formats as `sha-256=:<base64-digest>:` (RFC 9651 structured field byte sequence).
+ * Enforces body size limit to mitigate memory exhaustion DoS.
+ */
+export declare function computeContentDigest(body: Uint8Array | string | null | undefined, maxSizeBytes?: number): Promise<string | null>;
+/**
+ * Compute SHA-256 hash returned as base64 string.
+ */
+export declare function sha256Base64(data: Uint8Array | string): Promise<string>;
+/**
+ * Compute SHA-256 hash returned as base64url string (useful for JWK thumbprints).
+ */
+export declare function sha256Base64Url(data: Uint8Array | string): Promise<string>;

package/dist/crypto/digest.js

@@ -0,0 +1,36 @@
+import { bytesToBase64, stringToUtf8 } from "./encoding.js";
+/** Default upper bound for body payload digest calculation (10MB). */
+export const DEFAULT_MAX_BODY_SIZE_BYTES = 10 * 1024 * 1024;
+/**
+ * RFC 9530 Digest Fields computation.
+ * Hashes payload with SHA-256 via WebCrypto `crypto.subtle.digest`.
+ * Formats as `sha-256=:<base64-digest>:` (RFC 9651 structured field byte sequence).
+ * Enforces body size limit to mitigate memory exhaustion DoS.
+ */
+export async function computeContentDigest(body, maxSizeBytes = DEFAULT_MAX_BODY_SIZE_BYTES) {
+    if (body === null || body === undefined) {
+        return null;
+    }
+    const data = typeof body === "string" ? stringToUtf8(body) : body;
+    if (data.byteLength > maxSizeBytes) {
+        throw new Error(`Request body size (${data.byteLength} bytes) exceeds maximum allowed limit (${maxSizeBytes} bytes)`);
+    }
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", data);
+    const hashBase64 = bytesToBase64(new Uint8Array(hashBuffer));
+    return `sha-256=:${hashBase64}:`;
+}
+/**
+ * Compute SHA-256 hash returned as base64 string.
+ */
+export async function sha256Base64(data) {
+    const bytes = typeof data === "string" ? stringToUtf8(data) : data;
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return bytesToBase64(new Uint8Array(hashBuffer));
+}
+/**
+ * Compute SHA-256 hash returned as base64url string (useful for JWK thumbprints).
+ */
+export async function sha256Base64Url(data) {
+    const base64 = await sha256Base64(data);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/dist/crypto/encoding.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Zero-dependency Web standard encoding utilities.
+ * Runs in Node.js 18+, Bun, Deno, Cloudflare Workers, and browser/Edge runtimes.
+ */
+export declare function stringToUtf8(str: string): Uint8Array;
+export declare function utf8ToString(bytes: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlToBytes(b64url: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Constant-time byte comparison to mitigate microarchitectural timing attacks.
+ */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Constant-time string comparison helper.
+ */
+export declare function timingSafeEqualString(a: string, b: string): boolean;
+/**
+ * Masks a secret string for safe display/logging (e.g. `srv_...cdef` or `[none]`).
+ */
+export declare function maskSecret(val: string | null | undefined): string;
+/**
+ * Redacts secrets, tokens, keys, and authorization headers from strings.
+ * Used across SDK error handlers and logs to prevent sensitive credential exposure.
+ */
+export declare function redactSecrets(input: string | null | undefined): string;