@shelbyb/daywalker-sdk 0.7.0 → 0.8.0

package/README.md

@@ -397,6 +397,17 @@ Tokens must be RFC 9068 access tokens (`typ: at+jwt`, `alg: EdDSA`) with a numer
 
 ---
 
+## Service License & Config Bundle
+
+Daywalker issues each service a license key with the client credentials grant: derived per service, signing key and one-hour window, never returned for a revoked or suspended service.
+
+```ts
+const { licenseKey, expiresAt } = await client.getLicense();   // cached until a minute before expiry
+const bundle = await client.fetchBundle();                     // { dataKeySalt, features, issuedAt, expiresAt, ... }
+```
+
+`fetchBundle()` downloads a bundle sealed (AES-256-GCM) under the license key and opens it locally, so only a client that got the license from Daywalker can read it. Derive app secrets from `licenseKey` + `bundle.dataKeySalt` (HKDF) so removing the SDK breaks the app. Errors are `DaywalkerAuthError`s: `SERVICE_REVOKED`, `SERVICE_SUSPENDED`, `DOMAIN_REVOKED`, `DOMAIN_MISMATCH`, `LICENSE_UNAVAILABLE`, `BUNDLE_UNREADABLE`. Never log the key.
+
 ## CLI Reference
 
 | Command | Description |

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedConfig } from "./config.js";
-import { type DaywalkerConfig, type ValidateTokenOptions, 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. */
@@ -122,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`.

package/dist/client.js

@@ -1,7 +1,7 @@
 import { parseServiceSlugs, resolveConfig } from "./config.js";
 import { API_KEY_PATTERN, SAFE_IDENTIFIER_PATTERN, SERVICE_SLUG_PATTERN } from "./crypto/signatures.js";
 import { parseStoredSigningKey } from "./keystore/index.js";
-import { loadSigningKey, loadPublicKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, generateDpopKey, createDpopProof, verifyDpopProof, importSigningKey, generateSigningKey, registerPublicKey, revokeSigningKey, keySlotFor, randomInstanceId, calculateJwkThumbprint, base64UrlToBytes, utf8ToString, } from "./crypto/index.js";
+import { loadSigningKey, loadPublicKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, generateDpopKey, createDpopProof, verifyDpopProof, importSigningKey, generateSigningKey, registerPublicKey, revokeSigningKey, keySlotFor, randomInstanceId, calculateJwkThumbprint, base64UrlToBytes, base64ToBytes, hexToBytes, utf8ToString, } from "./crypto/index.js";
 import { webcrypto } from "./crypto/webcrypto.js";
 import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
@@ -1237,6 +1237,7 @@ export class Daywalker {
             ? Array.from(new Set(json.services.filter((x) => typeof x === "string" && SERVICE_SLUG_PATTERN.test(x.toLowerCase())).map((x) => x.toLowerCase())))
             : [];
         const refreshExpiresIn = Math.max(0, Math.floor(Number(json.refresh_expires_in) || 0));
+        this.#rememberLicenses(json, services);
         return deepFreeze({
             accessToken: json.access_token,
             refreshToken: json.refresh_token,
@@ -1323,6 +1324,115 @@ export class Daywalker {
         }
         return (await this.#tokenFlight).accessToken;
     }
+    /** Licenses from the client credentials grant, by service slug. Kept out of TokenSet so they are never serialized. */
+    #licenses = new Map();
+    #rememberLicenses(json, services) {
+        const found = new Map();
+        const add = (slug, key, expires) => {
+            if (typeof key !== "string" || !/^[0-9a-f]{64}$/i.test(key) || typeof expires !== "string" || !Number.isFinite(Date.parse(expires)))
+                return;
+            if (!SERVICE_SLUG_PATTERN.test(slug))
+                return;
+            found.set(slug, { serviceSlug: slug, licenseKey: key.toLowerCase(), expiresAt: expires });
+        };
+        if (json.licenses && typeof json.licenses === "object") {
+            for (const [slug, v] of Object.entries(json.licenses))
+                add(slug.toLowerCase(), v?.licenseKey, v?.expiresAt);
+        }
+        const primary = services[0];
+        if (primary && !found.has(primary))
+            add(primary, json.licenseKey ?? json.license_key, json.licenseExpiresAt ?? json.license_expires_at);
+        // A refresh carries no licenses; keep the ones we hold until they expire.
+        for (const [slug, license] of found)
+            this.#licenses.set(slug, license);
+    }
+    #licenseCached(slug) {
+        const license = this.#licenses.get(slug);
+        // A minute of margin so a key never expires between fetching it and using it.
+        return license && Date.parse(license.expiresAt) - 60_000 > Date.now() ? license : null;
+    }
+    /**
+     * 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.
+     */
+    async getLicense(options = {}) {
+        const slug = String(options.serviceSlug ?? this.#config.serviceSlug ?? "").toLowerCase();
+        if (!slug || !SERVICE_SLUG_PATTERN.test(slug)) {
+            throw new DaywalkerAuthError("getLicense: a valid serviceSlug is required", 500, "CONFIGURATION_ERROR");
+        }
+        if (options.forceRefresh !== true) {
+            await this.accessToken();
+            const cached = this.#licenseCached(slug);
+            if (cached)
+                return { ...cached };
+        }
+        const tokens = await this.getTokens();
+        if (!tokens.services.includes(slug)) {
+            throw new DaywalkerAuthError(`The OAuth client credentials don't cover ${slug}`, 403, "SERVICE_NOT_GRANTED");
+        }
+        const license = this.#licenseCached(slug);
+        if (!license)
+            throw new DaywalkerAuthError(`Daywalker Auth issued no license for ${slug}`, 403, "LICENSE_UNAVAILABLE");
+        return { ...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.
+     */
+    async fetchBundle(options = {}) {
+        const slug = String(options.serviceSlug ?? this.#config.serviceSlug ?? "").toLowerCase();
+        if (!slug || !SERVICE_SLUG_PATTERN.test(slug)) {
+            throw new DaywalkerAuthError("fetchBundle: a valid serviceSlug is required", 500, "CONFIGURATION_ERROR");
+        }
+        const cached = options.forceRefresh === true ? undefined : this.#bundles.get(slug);
+        if (cached && Date.parse(cached.expiresAt) - 60_000 > Date.now())
+            return structuredClone(cached);
+        let license = await this.getLicense(options);
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetch(`/api/v1/services/${slug}/bundle`, { method: "POST", body: {} });
+            const json = await readJsonObject(res, this.#config.timeoutMs);
+            const str = (v) => (typeof v === "string" ? v.slice(0, 500) : undefined);
+            if (res.status !== 200) {
+                throw new DaywalkerAuthError(redactSecrets(str(json.message) ?? str(json.error) ?? `Bundle request failed with HTTP ${res.status}`), res.status, str(json.code) ?? str(json.error));
+            }
+            const sealed = json.bundle;
+            if (!sealed || typeof sealed.iv !== "string" || typeof sealed.tag !== "string" || typeof sealed.ciphertext !== "string") {
+                throw new DaywalkerAuthError("Daywalker Auth returned a malformed bundle", 502, "SERVICE_UNAVAILABLE");
+            }
+            let bundle = null;
+            try {
+                bundle = await this.#openBundle(license.licenseKey, sealed, slug);
+            }
+            catch {
+                bundle = null;
+            }
+            if (bundle) {
+                this.#bundles.set(slug, bundle);
+                return structuredClone(bundle);
+            }
+            if (attempt >= 1)
+                throw new DaywalkerAuthError("The bundle could not be opened with the license key", 502, "BUNDLE_UNREADABLE");
+            license = await this.getLicense({ ...options, forceRefresh: true });
+        }
+    }
+    #bundles = new Map();
+    async #openBundle(licenseKey, sealed, slug) {
+        const key = await webcrypto.importKey("raw", hexToBytes(licenseKey), { name: "AES-GCM" }, false, ["decrypt"]);
+        const tag = base64ToBytes(sealed.tag);
+        const data = base64ToBytes(sealed.ciphertext);
+        const joined = new Uint8Array(data.length + tag.length);
+        joined.set(data);
+        joined.set(tag, data.length);
+        const plain = await webcrypto.decrypt({ name: "AES-GCM", iv: base64ToBytes(sealed.iv), tagLength: 128 }, key, joined);
+        const parsed = JSON.parse(utf8ToString(new Uint8Array(plain)));
+        if (!parsed || typeof parsed !== "object" || parsed.serviceSlug !== slug || typeof parsed.dataKeySalt !== "string")
+            throw new Error("bad bundle");
+        return deepFreeze(parsed);
+    }
     /**
      * 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`.

package/dist/crypto/webcrypto.d.ts

@@ -2,6 +2,7 @@ export declare const webcrypto: Readonly<{
     digest: (algorithm: AlgorithmIdentifier, data: BufferSource) => Promise<ArrayBuffer>;
     sign: (algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams, key: CryptoKey, data: BufferSource) => Promise<ArrayBuffer>;
     verify: (algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams, key: CryptoKey, signature: BufferSource, data: BufferSource) => Promise<boolean>;
+    decrypt: (algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, key: CryptoKey, data: BufferSource) => Promise<ArrayBuffer>;
     importKey: {
         (format: "jwk", keyData: JsonWebKey, algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKey>;
         (format: Exclude<KeyFormat, "jwk">, keyData: BufferSource, algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;

package/dist/crypto/webcrypto.js

@@ -17,6 +17,7 @@ export const webcrypto = Object.freeze({
     digest: capture(subtleRef, "digest"),
     sign: capture(subtleRef, "sign"),
     verify: capture(subtleRef, "verify"),
+    decrypt: capture(subtleRef, "decrypt"),
     importKey: capture(subtleRef, "importKey"),
     exportKey: capture(subtleRef, "exportKey"),
     generateKey: capture(subtleRef, "generateKey"),

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, MAX_CACHE_TTL_MS, MAX_TOKEN_LENGTH, JWKS_CACHE_TTL_MS, JWKS_REFETCH_COOLDOWN_MS, } from "./client.js";
 export type { DaywalkerFetchInit, } from "./client.js";
 export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
-export type { DaywalkerConfig, RateLimitWindow, TokenPayload, IncomingDpop, ValidateTokenOptions, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, TokenSet, GetTokensOptions, AccessTokenUser, KeyStore, StoredSigningKey, MessageSigner, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
+export type { DaywalkerConfig, RateLimitWindow, TokenPayload, IncomingDpop, ValidateTokenOptions, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, TokenSet, License, LicenseOptions, ConfigBundle, GetTokensOptions, AccessTokenUser, KeyStore, StoredSigningKey, MessageSigner, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
 export { resolveConfig, parseServiceSlugs, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
 export type { ResolvedConfig, } from "./config.js";
 export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, importSigningKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, leaseServices, registerPublicKey, listSigningKeys, revokeSigningKey, keySlotFor, MIN_KEY_TTL_SECONDS, MAX_KEY_TTL_SECONDS, verifyDpopProof, MAX_DPOP_PROOF_LENGTH, DPOP_MAX_AGE_SECONDS, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";

package/dist/types.d.ts

@@ -220,6 +220,36 @@ export interface TokenSet {
     services: string[];
     jwksUri?: string;
 }
+/** A service's license key from Daywalker: derived per service, signing key and one-hour window. */
+export interface License {
+    serviceSlug: string;
+    /** 64 hex characters (32 bytes). A secret: never log it or send it anywhere. */
+    licenseKey: string;
+    /** ISO 8601: the end of the window the key is valid for. */
+    expiresAt: string;
+}
+/** The config bundle Daywalker seals under the license key. Fields beyond these are passed through. */
+export interface ConfigBundle {
+    serviceSlug: string;
+    /** Random per issue; derive per-process secrets from it (and the license key), never store it. */
+    dataKeySalt: string;
+    features: {
+        exclusiveTier?: boolean;
+        stage?: string;
+        rateLimitPerMinute?: number | null;
+        rateLimitPerHour?: number | null;
+        [key: string]: unknown;
+    };
+    issuedAt: string;
+    expiresAt: string;
+    [key: string]: unknown;
+}
+export interface LicenseOptions {
+    /** Default: the configured service slug. */
+    serviceSlug?: string;
+    /** Ignore the cached license and start a new client credentials grant. */
+    forceRefresh?: boolean;
+}
 export interface GetTokensOptions {
     /** Narrow the grant to these service slugs (least privilege); default: every service the credentials cover. */
     scope?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Daywalker Auth service validation plus the DevPulse client SDKs (feature flags, OpenFeature, product analytics) in one package with a single runtime dependency (re2js).",
   "type": "module",
   "main": "./dist/index.js",