@shelbyb/daywalker-sdk 0.5.0 → 0.7.0

package/dist/cli.js

@@ -3,27 +3,35 @@ import fs from "node:fs";
 import path from "node:path";
 import { createDaywalker } from "./client.js";
 import { parseServiceSlugs, publicHostname } from "./config.js";
-import { generateSigningKey, loadSigningKey, registerPublicKey, redactSecrets } from "./crypto/index.js";
+import { generateSigningKey, keySlotFor, listSigningKeys, loadSigningKey, registerPublicKey, redactSecrets, revokeSigningKey } from "./crypto/index.js";
 const HELP = `daywalker: connect a service to Daywalker Auth (RFC 9421 / Push Architecture)
 
 Usage:
-  daywalker init   --service <slug[,slug…]> [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--force] [--skip-register] [--json|--export] [--print-key]
+  daywalker init   [--service <slug[,slug…]>] [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--force] [--skip-register] [--json|--export] [--print-key]
   daywalker rotate [--service <slug[,slug…]>] [--api-key-stdin] [--domain <host>] [--auth-url <url>] [--skip-register] [--json|--export] [--print-key]
-  daywalker check
+  daywalker check  [--offline]
+  daywalker keys   [--domain <host>] [--auth-url <url>] [--api-key-stdin] [--json]
+  daywalker revoke <keyId> [--domain <host>] [--auth-url <url>] [--api-key-stdin] [--force]
 
 init     Generates an Ed25519 keypair, registers the public key directly with Daywalker Auth
          (POST /api/v1/keys/register), and writes DAYWALKER_* settings to .env.local (or outputs JSON with --json).
          Nothing is written if registration fails. --force replaces an existing key (kept as
          DAYWALKER_SIGNING_KEY_PREVIOUS for rollback). No public ingress or /.well-known route handlers are required.
 rotate   Generates a new Ed25519 key, registers it with Daywalker Auth, and keeps the old one
-         in .env.local as DAYWALKER_SIGNING_KEY_PREVIOUS during deployment transition.
+         in .env.local as DAYWALKER_SIGNING_KEY_PREVIOUS during deployment transition. The old key stays
+         registered until you revoke it (\`daywalker revoke <keyId>\`) once the new key is deployed everywhere.
          Nothing is written, and the exit code is non-zero, unless registration succeeds.
-check    Validates configuration and confirms Daywalker Auth connection and signature readiness.
+check    Validates configuration and signature readiness, then runs the OAuth client credentials grant
+         against Daywalker Auth to confirm the credentials work and cover the configured service(s).
+keys     Lists the signing keys registered for the domain (status, slot, expiry, last use).
+revoke   Revokes a signing key now; Daywalker also ends the OAuth sessions it started. Refuses the key in
+         DAYWALKER_KEY_ID (the one this service signs with) unless --force.
 
 Options:
   --api-key-stdin   Read the Daywalker API key from stdin (e.g. \`op read ... | daywalker init --api-key-stdin\`).
                     The key is otherwise taken from DAYWALKER_API_KEY in the environment or .env.local.
-                    --api-key <key> also works but exposes the key in shell history and process listings.
+                    (--api-key <key> is refused: it would expose the key in shell history and process listings.)
+  --offline         check only: skip the live OAuth client credentials check against Daywalker Auth.
   --skip-register   Do not register the public key (alias: --no-register); register it yourself before deploying.
   --json, --export  Output configuration as JSON for piping into Vercel, DigitalOcean, Fly.io, AWS SSM, etc.
                     The JSON includes the private key (DAYWALKER_SIGNING_KEY); nothing is written to .env.local.
@@ -59,8 +67,6 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8").trim();
 }
 async function resolveApiKey(opts, existing) {
-    if (typeof opts["api-key"] === "string")
-        return opts["api-key"].trim() || null;
     if (opts["api-key-stdin"]) {
         const fromStdin = await readStdin();
         if (!fromStdin)
@@ -69,6 +75,13 @@ async function resolveApiKey(opts, existing) {
     }
     return String(existing.get("DAYWALKER_API_KEY") ?? process.env.DAYWALKER_API_KEY ?? "").trim() || null;
 }
+/** Why a key API call failed, with what to do when the domain is full. */
+function keyApiFailure(what, result) {
+    const hint = result.code === "KEY_LIMIT_REACHED"
+        ? "\n  The domain has 20 live keys: list them with `daywalker keys` and revoke unused ones with `daywalker revoke <keyId>`."
+        : "";
+    return `${what} failed (${result.status || "network"}${result.code ? ` ${result.code}` : ""}): ${result.error}${hint}`;
+}
 function skipRegister(opts) {
     return Boolean(opts["skip-register"] || opts["no-register"]);
 }
@@ -181,8 +194,9 @@ async function init(opts) {
     const envFile = path.join(dir, ".env.local");
     const existing = readEnvFile(envFile);
     const slugs = parseServiceSlugs(String(opts.service ?? existing.get("DAYWALKER_SERVICE_SLUG") ?? process.env.DAYWALKER_SERVICE_SLUG ?? ""));
-    if (slugs.length === 0 || !slugs.every((s) => /^[a-z0-9_-]+$/.test(s))) {
-        fail("--service must be this service's Daywalker slug (e.g. --service sonalyze), or a comma-separated list when one API key covers several (--service gigpulse,devpulse)");
+    // Optional: requests never name a service. Only needed to verify access tokens offline (audience check).
+    if (!slugs.every((s) => /^[a-z0-9_-]+$/.test(s))) {
+        fail("--service must be Daywalker service slug(s) (e.g. --service sonalyze, or gigpulse,devpulse)");
     }
     const slug = slugs.join(",");
     const rawDomain = opts.domain ? String(opts.domain) : existing.get("DAYWALKER_DOMAIN") ?? process.env.DAYWALKER_DOMAIN ?? "";
@@ -210,12 +224,13 @@ async function init(opts) {
     if (apiKey && activeKey && !skipRegister(opts)) {
         if (!isJson)
             console.log(`• Registering public key (${activeKey.publicJwk.kid}) with Daywalker Auth...`);
+        // Each key gets its own slot, so registering it never retires a key a running deployment still uses.
         const regResult = await registerPublicKey({
             authUrl,
             apiKey,
-            serviceSlug: slug,
             domain,
             publicJwk: activeKey.publicJwk,
+            instanceId: keySlotFor(activeKey.publicJwk.kid),
         });
         if (regResult.ok) {
             registered = true;
@@ -223,7 +238,7 @@ async function init(opts) {
                 console.log(`✔ Public key registered with Daywalker Auth (Push Architecture)`);
         }
         else {
-            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n` +
+            fail(`${keyApiFailure("Key registration", regResult)}\n` +
                 `  Nothing was written. Fix the problem and re-run, or pass --skip-register to write the key without registering it.`);
         }
     }
@@ -232,7 +247,7 @@ async function init(opts) {
     }
     const signingKeyStr = key?.privateKeyPkcs8Base64 ?? existing.get("DAYWALKER_SIGNING_KEY") ?? "";
     const envValues = {
-        DAYWALKER_SERVICE_SLUG: slug,
+        ...(slug ? { DAYWALKER_SERVICE_SLUG: slug } : {}),
         DAYWALKER_KEY_ID: kid,
         DAYWALKER_AUTH_URL: authUrl,
         ...(domain ? { DAYWALKER_DOMAIN: domain } : {}),
@@ -247,15 +262,19 @@ async function init(opts) {
     }
     writeEnvFile(envFile, envValues, { DAYWALKER_SIGNING_KEY_PREVIOUS: PREVIOUS_KEY_COMMENT });
     ensureGitignored(dir, ".env.local");
-    console.log(`✔ Daywalker configured for service "${slug}"${domain ? ` (${domain})` : ""}`);
+    console.log(`✔ Daywalker configured${slug ? ` (audience "${slug}")` : ""}${domain ? ` (${domain})` : ""}`);
     console.log(`  • RFC 9421 / RFC 9530 HTTP Message Signing active`);
-    console.log(`  • .env.local: DAYWALKER_SERVICE_SLUG, DAYWALKER_KEY_ID, DAYWALKER_AUTH_URL${domain ? ", DAYWALKER_DOMAIN" : ""}${apiKey ? ", DAYWALKER_API_KEY" : ""}${signingKeyStr ? ", DAYWALKER_SIGNING_KEY" : ""}`);
+    console.log(`  • .env.local: ${slug ? "DAYWALKER_SERVICE_SLUG, " : ""}DAYWALKER_KEY_ID, DAYWALKER_AUTH_URL${domain ? ", DAYWALKER_DOMAIN" : ""}${apiKey ? ", DAYWALKER_API_KEY" : ""}${signingKeyStr ? ", DAYWALKER_SIGNING_KEY" : ""}`);
     if (kid)
         console.log(`  • Key ID (RFC 7638 thumbprint): ${kid}`);
     if (registered)
         console.log(`  • Zero-ingress push architecture: public key registered directly`);
-    if (previousKey)
-        console.log(`  • Previous key kept as DAYWALKER_SIGNING_KEY_PREVIOUS for rollback; remove it once the new key is deployed.`);
+    if (previousKey) {
+        const previousKid = (await loadSigningKey(previousKey).catch(() => null))?.publicJwk.kid;
+        console.log(`  • Previous key kept as DAYWALKER_SIGNING_KEY_PREVIOUS for rollback; it stays registered.`);
+        if (previousKid)
+            console.log(`    Once the new key is deployed everywhere: npx daywalker revoke ${previousKid}`);
+    }
     if (opts["print-key"] && signingKeyStr)
         console.log(`\nDAYWALKER_SIGNING_KEY=${signingKeyStr}`);
 }
@@ -275,20 +294,20 @@ async function rotate(opts) {
     // The new key only becomes active once Daywalker Auth knows it, so registration must succeed
     // before anything is written (unless the caller explicitly registers it some other way).
     if (!skipRegister(opts)) {
-        if (!apiKey || !slug) {
-            fail("rotate needs DAYWALKER_API_KEY and DAYWALKER_SERVICE_SLUG to register the new key (or pass --skip-register to write it unregistered)");
+        if (!apiKey) {
+            fail("rotate needs DAYWALKER_API_KEY to register the new key (or pass --skip-register to write it unregistered)");
         }
         if (!isJson)
             console.log(`• Registering new public key (${key.publicJwk.kid}) with Daywalker Auth...`);
         const regResult = await registerPublicKey({
             authUrl,
             apiKey,
-            serviceSlug: slug,
             domain: rotateDomain,
             publicJwk: key.publicJwk,
+            instanceId: keySlotFor(key.publicJwk.kid),
         });
         if (!regResult.ok) {
-            fail(`Key registration failed (${regResult.status}): ${regResult.error}\n  Nothing was written; the current key is still active.`);
+            fail(`${keyApiFailure("Key registration", regResult)}\n  Nothing was written; the current key is still active.`);
         }
         if (!isJson)
             console.log(`✔ New public key registered with Daywalker Auth`);
@@ -306,14 +325,27 @@ async function rotate(opts) {
     }
     writeEnvFile(envFile, envValues, { DAYWALKER_SIGNING_KEY_PREVIOUS: PREVIOUS_KEY_COMMENT });
     console.log(`✔ New key ${key.publicJwk.kid} written; previous key preserved as DAYWALKER_SIGNING_KEY_PREVIOUS.`);
-    console.log(`  After deployment rollout is complete, you may remove DAYWALKER_SIGNING_KEY_PREVIOUS.`);
+    const previousKid = (await loadSigningKey(current).catch(() => null))?.publicJwk.kid;
+    console.log(`  The previous key stays registered, so running deployments keep working.`);
+    if (previousKid)
+        console.log(`  Once the new key is deployed everywhere: npx daywalker revoke ${previousKid}, then remove DAYWALKER_SIGNING_KEY_PREVIOUS.`);
     if (opts["print-key"])
         console.log(`\nDAYWALKER_SIGNING_KEY=${key.privateKeyPkcs8Base64}`);
 }
-async function check() {
+async function check(opts) {
     const env = { ...process.env, ...Object.fromEntries(readEnvFile(path.join(process.cwd(), ".env.local"))) };
     const client = createDaywalker({ env });
     const result = await client.selfCheck();
+    if (result.ok && !opts.offline) {
+        const live = await client.validateServiceCredentials();
+        if (!live.ok) {
+            result.ok = false;
+            result.problems.push(`OAuth client credentials check failed (${live.status} ${live.error}): ${live.message}`);
+        }
+        else {
+            console.log(`✔ OAuth client credentials grant succeeded (services: ${(live.data.services ?? []).join(", ")})`);
+        }
+    }
     if (result.ok) {
         console.log(`✔ Daywalker configuration looks good`);
         if (result.serviceSlugs.length > 1)
@@ -335,11 +367,58 @@ async function check() {
         console.error(redactSecrets(`  - ${p}`));
     process.exit(1);
 }
+/** Domain, API key and auth URL for the key commands, from flags, .env.local or the environment. */
+async function keyCommandContext(opts) {
+    const existing = readEnvFile(path.join(process.cwd(), ".env.local"));
+    const apiKey = await resolveApiKey(opts, existing);
+    if (!apiKey)
+        fail("Set DAYWALKER_API_KEY (or pipe it to --api-key-stdin)");
+    const rawDomain = String(opts.domain ?? existing.get("DAYWALKER_DOMAIN") ?? process.env.DAYWALKER_DOMAIN ?? "");
+    const domain = publicHostname(rawDomain);
+    const authUrl = String(opts["auth-url"] ?? existing.get("DAYWALKER_AUTH_URL") ?? process.env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    const currentKid = existing.get("DAYWALKER_KEY_ID") ?? process.env.DAYWALKER_KEY_ID ?? null;
+    const previous = existing.get("DAYWALKER_SIGNING_KEY_PREVIOUS") ?? process.env.DAYWALKER_SIGNING_KEY_PREVIOUS;
+    const previousKid = previous ? ((await loadSigningKey(previous).catch(() => null))?.publicJwk.kid ?? null) : null;
+    return { apiKey, domain, rawDomain, authUrl, currentKid, previousKid };
+}
+async function keys(opts) {
+    const ctx = await keyCommandContext(opts);
+    if (!ctx.domain)
+        fail(`--domain (${ctx.rawDomain || "not set"}) must be a public hostname (or set DAYWALKER_DOMAIN)`);
+    const result = await listSigningKeys({ authUrl: ctx.authUrl, apiKey: ctx.apiKey, domain: ctx.domain });
+    if (!result.ok)
+        fail(keyApiFailure("Listing keys", result));
+    const list = result.keys ?? [];
+    if (opts.json) {
+        console.log(JSON.stringify(list, null, 2));
+        return;
+    }
+    const when = (t) => (t === null ? "-" : new Date(t * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"));
+    console.log(`Signing keys for ${ctx.domain} (${list.filter((k) => k.status !== "REVOKED").length} live of 20 allowed):`);
+    for (const k of list) {
+        const tag = k.keyId === ctx.currentKid ? " (current)" : k.keyId === ctx.previousKid ? " (previous)" : "";
+        console.log(`  ${k.keyId}${tag}  ${k.status}  slot=${k.instanceId ?? "-"}  expires=${when(k.expiresAt)}  lastUsed=${when(k.lastUsedAt)}`);
+    }
+}
+async function revoke(keyId, opts) {
+    if (!keyId)
+        fail("Usage: daywalker revoke <keyId>");
+    const ctx = await keyCommandContext(opts);
+    if (keyId === ctx.currentKid && !opts.force) {
+        fail(`${keyId} is DAYWALKER_KEY_ID, the key this service signs with: revoking it stops this service from authenticating. Pass --force if that is what you want.`);
+    }
+    const result = await revokeSigningKey({ authUrl: ctx.authUrl, apiKey: ctx.apiKey, keyId });
+    if (!result.ok)
+        fail(keyApiFailure(`Revoking ${keyId}`, result));
+    console.log(`✔ Revoked signing key ${keyId}; Daywalker ended the OAuth sessions it started.`);
+    if (keyId === ctx.previousKid)
+        console.log("  You can now remove DAYWALKER_SIGNING_KEY_PREVIOUS from .env.local.");
+}
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const parsedArgs = args(rest);
-    if (typeof parsedArgs["api-key"] === "string") {
-        console.warn("! --api-key exposes the key in shell history and process listings; prefer DAYWALKER_API_KEY in the environment or .env.local.");
+    if (parsedArgs["api-key"] !== undefined) {
+        fail("--api-key is not supported: it exposes the key in shell history and process listings. Use DAYWALKER_API_KEY in the environment or .env.local, or pipe it to --api-key-stdin.");
     }
     if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
         console.log(HELP);
@@ -352,7 +431,13 @@ async function main() {
         await rotate(parsedArgs);
     }
     else if (cmd === "check") {
-        await check();
+        await check(parsedArgs);
+    }
+    else if (cmd === "keys") {
+        await keys(parsedArgs);
+    }
+    else if (cmd === "revoke") {
+        await revoke(rest[0] && !rest[0].startsWith("--") ? rest[0] : undefined, parsedArgs);
     }
     else {
         fail(`Unknown command "${cmd}". Run \`daywalker --help\` for usage.`);

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedConfig } from "./config.js";
-import { type DaywalkerConfig, type IssueLeaseOptions, type LeaseResponse, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+import { type DaywalkerConfig, type ValidateTokenOptions, type TokenSet, type GetTokensOptions, 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,18 +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 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,
@@ -38,57 +65,63 @@ 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>;
+    }), 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 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>;
+    /**
+     * Refresh token rotation: trades the refresh token for a NEW access token and a NEW refresh token; the
+     * old refresh token stops working. Presenting an old one again revokes the whole session, so refreshes
+     * are serialized per client and the new refresh token must replace the stored one.
+     */
+    refreshTokens(refreshToken?: string): Promise<TokenSet>;
     /**
-     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
-     * The lease lists every service slug the API key covers (`services`, also the JWT's `services` and `aud`
-     * claims), so one set of credentials serves all of them. Pass `{ services: [...] }` to narrow it.
+     * A valid access token, refreshing (or re-authenticating with the client credentials once the session
+     * ended) when it is within 30 seconds of expiry. Concurrent callers share one request, so the single-use
+     * refresh token is never presented twice.
      */
-    issueLease(options?: number | IssueLeaseOptions): Promise<LeaseResponse>;
+    accessToken(): Promise<string>;
     /**
      * 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`.
@@ -104,7 +137,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>;
 }
@@ -113,3 +147,4 @@ export declare class Daywalker {
  */
 export declare function createDaywalker(config?: DaywalkerConfig): Daywalker;
 export declare const daywalker: Daywalker & (() => Daywalker);
+export {};