@shelbyb/daywalker-sdk 0.6.0 → 0.8.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedConfig } from "./config.js";
-import { type DaywalkerConfig, type TokenSet, type GetTokensOptions, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+import { type DaywalkerConfig, type ValidateTokenOptions, type TokenSet, type GetTokensOptions, type License, type LicenseOptions, type ConfigBundle, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
 /** Validation results kept in memory; the least recently used are evicted past this. */
 export declare const MAX_VALIDATION_CACHE_ENTRIES = 1000;
 /** Longest 429 `Retry-After` waited out by default (`retry.maxRetryAfterMs`); longer ones return the 429. */
@@ -17,21 +17,45 @@ export type DaywalkerFetchInit = Omit<RequestInit, "body"> & {
     /** Sent as `Idempotency-Key` (unless already set) and lets non-idempotent requests retry network errors. */
     idempotencyKey?: string;
 };
+/**
+ * Longest a successful validation is cached (5 minutes), whatever `cacheTtlMs` says, so a revoked token
+ * can't stay accepted for long.
+ */
+export declare const MAX_CACHE_TTL_MS = 300000;
+/** Longest incoming token accepted (characters); longer input is refused without calling Daywalker. */
+export declare const MAX_TOKEN_LENGTH = 8192;
+/** How long a fetched JWKS (`jwks: "auto"`) is used before it is refetched. */
+export declare const JWKS_CACHE_TTL_MS = 600000;
+/**
+ * Least time between two JWKS fetches, whatever triggers them (an unknown `kid`, an expired set, a failed
+ * fetch), so a flood of tokens naming made-up `kid`s costs at most one request to Daywalker per interval.
+ */
+export declare const JWKS_REFETCH_COOLDOWN_MS = 30000;
+/** What signs this client's requests, and where it came from. */
+type SignerSource = "signer" | "signingKey" | "ephemeral" | "keyStore";
 export declare class Daywalker {
-    private readonly _config;
-    private readonly _rawConfig;
-    private _signingKeyPromise?;
-    private _previousSigningKeyPromise?;
-    private readonly _cache;
-    private readonly _inflight;
+    #private;
     constructor(config?: DaywalkerConfig);
-    get config(): ResolvedConfig;
+    /** The resolved configuration, frozen, with the API key and private keys shown as "[configured]". */
+    get config(): Readonly<ResolvedConfig>;
     toJSON(): Record<string, unknown>;
-    private getLoadedSigningKey;
-    private _dpopKey;
-    /** The client's DPoP key, generated on first use. Issued tokens are bound to it for this client's life. */
-    private getDpopKey;
-    private getLoadedPreviousSigningKey;
+    /**
+     * Shuts the client down: revokes its ephemeral signing key (which also ends the OAuth sessions it started)
+     * and forgets its tokens. Afterwards every call that needs Daywalker fails with CLIENT_CLOSED. Safe to call
+     * twice. Keys from `signingKey`, `keyStore` or `signer` are long-lived and are left alone.
+     */
+    close(): Promise<{
+        revoked: string[];
+        failed: string[];
+    }>;
+    /**
+     * Resolves the signing key now instead of on the first request: loads it, or provisions and registers it
+     * (see `keyStore`). Call it at startup to fail fast. Returns where the key came from and its id.
+     */
+    provisionSigningKey(): Promise<{
+        source: SignerSource;
+        keyId: string;
+    } | null>;
     /**
      * Signs and executes a request to Daywalker Auth (same origin as `authUrl` only).
      * - Redirects are never followed: a 3xx throws a DaywalkerError (code UNEXPECTED_REDIRECT), so the API key,
@@ -41,58 +65,49 @@ export declare class Daywalker {
      * - 429s are retried with exponential backoff, honoring `Retry-After` up to `retry.maxRetryAfterMs`. Network
      *   errors and timeouts are retried only for GET / HEAD / OPTIONS, with an `idempotencyKey`, or when
      *   `retry.retryNetworkErrors` is true. Options merge as defaults < `config.retry` < `init.retry`.
-     * - An explicit `Authorization` header is sent as given; otherwise `Bearer <apiKey>` is added. The signature
-     *   covers method, path, query, authority and Content-Digest, never Authorization.
+     * - An explicit `Authorization` header is sent as given; otherwise `DPoP <access token>` from the OAuth
+     *   client credentials flow (`accessToken()`) is added, with a DPoP proof bound to it. The API key is never
+     *   sent here: it only authenticates the client credentials grant. An answer of 401 ACCESS_TOKEN_EXPIRED
+     *   refreshes the token and retries once. The signature covers method, path, query, authority and
+     *   Content-Digest, never Authorization.
      */
     fetch(path: string, init?: DaywalkerFetchInit): Promise<Response>;
-    private _cacheGet;
-    private _cacheSet;
     /**
-     * Validates an incoming bearer token with memory caching and discriminated union return.
-     * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
-     * A missing token is always rejected (401); it never falls back to this service's own API key —
-     * use `validateServiceKey()` for that.
-     * Online validation fails closed: only a 2xx JSON answer with `valid: true` and a sane shape is accepted.
-     * Outages (network errors, timeouts, 5xx, malformed answers) return status 503 with error NETWORK_ERROR or
-     * SERVICE_UNAVAILABLE and are never cached. Each call gets its own copy of the (cached) result.
+     * Validates an incoming token with memory caching and a discriminated union result.
+     * - Access tokens (JWTs) are verified offline when Daywalker's public key is configured. A DPoP-bound
+     *   token (`cnf.jkt`) is only accepted with a valid DPoP proof (`options.dpop`; the adapters pass it).
+     * - Other tokens are validated online with `POST /api/v1/tokens/validate`, authenticated with this
+     *   service's own DPoP-bound access token. The answer must name the expected service.
+     * - A missing, oversized or malformed token is rejected (401) without calling Daywalker. A token is never
+     *   replaced by this service's own credentials: use `validateServiceCredentials()` for that.
+     * - Online validation fails closed: only a 2xx JSON answer with `valid: true` and a sane shape is accepted.
+     *   Outages (network errors, timeouts, 5xx, malformed answers) return status 503 with error NETWORK_ERROR or
+     *   SERVICE_UNAVAILABLE and are never cached. Each call gets its own copy of the (cached) result.
      */
-    validateToken(tokenOrOptions?: string | {
+    validateToken(tokenOrOptions?: string | (ValidateTokenOptions & {
         token?: string;
-        serviceSlug?: string;
-        forceRefresh?: boolean;
-        offlineOnly?: boolean;
-    }, options?: {
-        serviceSlug?: string;
-        forceRefresh?: boolean;
-        offlineOnly?: boolean;
-    }): Promise<ValidateResult>;
-    private _validateOnline;
+    }), options?: ValidateTokenOptions): Promise<ValidateResult>;
     /**
-     * Service health check: validates this service's own configured API key (DAYWALKER_API_KEY).
-     * Never use this to authenticate an incoming request.
+     * Service health check: runs this service's OAuth client credentials flow (`accessToken()`) and checks
+     * that the granted services include `serviceSlug` (default: the configured one; with none configured, at
+     * least one service must be granted). Never use this to authenticate an incoming request. `forceRefresh`
+     * starts a new client credentials grant.
      */
-    validateServiceKey(options?: {
+    validateServiceCredentials(options?: {
         serviceSlug?: string;
         forceRefresh?: boolean;
     }): Promise<ValidateResult>;
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */
-    requireValidToken(tokenOrOptions?: string | {
+    requireValidToken(tokenOrOptions?: string | (ValidateTokenOptions & {
         token?: string;
-        serviceSlug?: string;
-        offlineOnly?: boolean;
-    }, options?: {
-        serviceSlug?: string;
-        offlineOnly?: boolean;
-    }): Promise<TokenPayload>;
-    private _tokens;
-    private _tokenFlight;
-    private _tokenRequest;
+    }), options?: ValidateTokenOptions): Promise<TokenPayload>;
     /**
      * Client credentials grant (RFC 6749 §4.4): the signed request (API key + registered Ed25519 key) is
-     * exchanged for a short-lived access token JWT listing every service the credentials cover, and a
-     * rotating refresh token. No service slug is sent. The tokens are remembered for `accessToken()`.
+     * exchanged for a short-lived access token JWT and a rotating refresh token. By default the grant is
+     * narrowed to the configured service slug(s) (least privilege); with none configured it covers every
+     * service the credentials do. The tokens are remembered for `accessToken()`. The result is frozen.
      */
     getTokens(options?: GetTokensOptions): Promise<TokenSet>;
     /**
@@ -107,6 +122,20 @@ export declare class Daywalker {
      * refresh token is never presented twice.
      */
     accessToken(): Promise<string>;
+    /**
+     * The service's license key from Daywalker (issued with the client credentials grant, valid for one hour,
+     * cached in memory until a minute before it expires). A revoked or suspended service gets no license: this
+     * throws the DaywalkerAuthError Daywalker answered with (`SERVICE_REVOKED`, `SERVICE_SUSPENDED`,
+     * `DOMAIN_REVOKED`, ...). `LICENSE_UNAVAILABLE` (403) means Daywalker granted the service without a license.
+     * Never log the key.
+     */
+    getLicense(options?: LicenseOptions): Promise<License>;
+    /**
+     * Fetches the config bundle (`POST /api/v1/services/:slug/bundle`) and opens it with the license key
+     * (AES-256-GCM). The bundle can only be read by a client that got the license from Daywalker. At a window
+     * rollover the key is refreshed once and the bundle opened again. Cached until shortly before it expires.
+     */
+    fetchBundle(options?: LicenseOptions): Promise<ConfigBundle>;
     /**
      * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
      * Uses the configured `fetch`, sends no credentials, never follows redirects and times out after `timeoutMs`.
@@ -122,7 +151,8 @@ export declare class Daywalker {
         keys: PublicJwk[];
     }>;
     /**
-     * Check configuration and verify signature readiness.
+     * Check configuration and verify signature readiness. Never provisions or registers a key: with a
+     * `keyStore` it only reads what is stored and reports what first use would need.
      */
     selfCheck(): Promise<SelfCheckResult>;
 }
@@ -131,3 +161,4 @@ export declare class Daywalker {
  */
 export declare function createDaywalker(config?: DaywalkerConfig): Daywalker;
 export declare const daywalker: Daywalker & (() => Daywalker);
+export {};