@sidub-inc/licensing-client 1.5.170 → 1.6.0

package/README.md

@@ -54,13 +54,24 @@ const client = new LicensingClient({
 | `serviceKeyPublicMember` | No | Base64 EC public key (P-256 SPKI) for signature verification |
 | `consumptionServiceUri` | No | Separate URI for consumption reporting |
 | `timeout` | No | Request timeout in ms (default: 30000) |
-| `validateSignatures` | No | Enable/disable signature validation (default: auto) |
+| `validateSignatures` | No | Signature validation posture. Unset = auto (on when a verification key is configured; a one-time warning is emitted when it ends up off). `true` without a key throws `LicensingConfigurationException`. `false` = explicit unsigned mode, no warning. |
 | `cacheEnabled` | No | Enable authorization caching (default: true) |
 | `cacheMaxSize` | No | Maximum cached authorizations (default: 100) |
+| `cacheFreshTtlMs` | No | Upper bound in ms on cache freshness before revalidation (default: 24h cap; 1h for no-expiry authorizations). Revocation latency = min(`cacheFreshTtlMs`, remaining license window) — tighten for faster revocation pickup, at the cost of more calls. `0` revalidates every read. |
+| `staleGraceMs` | No | Stale-serve grace window in ms: how long an expired-but-signature-validated cached authorization may still be served (flagged `isStale`) when the service is transiently unreachable (default: 24h, capped 7d, `0` disables). Denials (401/403/404) are never stale-served. |
 | `contextProvider` | No | Custom `ILicensingContextProvider` for credential resolution |
 | `billableResourceId` | No | Billable resource ID for consumption reporting |
 | `billablePlanId` | No | Billable plan ID for consumption reporting |
 
+### Authentication Channel
+
+Every credentialed request sends the API key **header-only**: the branded
+`dub-apiKey` header (the gateway's configured subscription-key name) plus the
+platform-default `Ocp-Apim-Subscription-Key` header, exactly mirroring the .NET
+SDK. The key is never placed in the URL. (Before 2.0 the SDK also appended a
+`?subscription-key=` query string — removed because URL-borne secrets leak into
+browser history, Referer headers, and proxy/CDN logs.)
+
 ## Core Operations
 
 ### 1. Get License Authorization
@@ -92,7 +103,7 @@ const hasAccess = client.assertLicense(assertion, authorization);
 ```typescript
 await client.performOperation({
   licenseId: 'license-uuid',
-  feature: { featureId: 'api-calls' },
+  feature: { featureKey: 'api-calls' },
   operationType: 'increment',
   quantity: 1,
   timestamp: new Date()
@@ -134,6 +145,21 @@ const result = await client.pollCheckoutResult(session.sessionId, {
 // Throws LicensingError if max attempts exceeded or signal aborted
 ```
 
+**`'pending'` covers async settlement.** The server deliberately reports its
+internal PaymentPending state (delayed-notification payment methods such as
+bank debits) as `'pending'` on the wire. A session paid by bank debit can stay
+`'pending'` for days and still complete — the result remains pollable for up to
+14 days. Treat a prolonged `'pending'` as "money may still be moving", not as
+failure.
+
+**Store the credential out of JavaScript's reach.** `encodedCredential` is
+base64-obfuscated, NOT encrypted — it contains the tenant's `apiAccessKey`.
+Hand it to your backend for storage; do not persist it in `localStorage` or
+anywhere page JavaScript (and therefore any XSS) can read it. The SDK itself
+never writes the credential or API key to `localStorage` — it persists only
+authorization payloads and consumption counters, and the API key appears in
+storage key names only as a non-reversible hash.
+
 ### 5. Report Access Check (Telemetry)
 
 Telemetry-only: the event is always sent non-billable with a zero amount. Billable
@@ -147,14 +173,19 @@ await client.reportAccessCheck('license-uuid', 'api-calls'); // explicit license
 
 ## Authorization Caching
 
-Authorization responses are cached in memory with TTL-based expiry (derived from `expiresAt`). Caching is enabled by default.
+Authorization responses are cached (in memory, persisted to `localStorage` in
+browsers — the raw API key is never stored, and appears in storage key names
+only as a non-reversible hash) with TTL-based freshness. Caching is enabled by
+default.
 
 ```typescript
 const client = new LicensingClient({
   licenseServiceUri: '...',
   encodedCredential: '...',
-  cacheEnabled: true,   // default
-  cacheMaxSize: 100     // default
+  cacheEnabled: true,       // default
+  cacheMaxSize: 100,        // default
+  cacheFreshTtlMs: 3600000, // optional: tighten revalidation cadence (default cap: 24h)
+  staleGraceMs: 86400000    // optional: stale-serve window on outages (default: 24h)
 });
 
 // Manual cache management
@@ -162,7 +193,14 @@ client.clearCache();                    // Remove all cached authorizations
 client.invalidateCache('license-uuid'); // Remove entries for a specific license
 ```
 
-When caching is enabled, repeated calls to `getAuthorization()` with the same license ID return the cached result until it expires.
+When caching is enabled, repeated calls to `getAuthorization()` with the same
+license ID return the cached result until its freshness deadline —
+min(license expiry, `cacheFreshTtlMs`, 24h; 1h when the authorization has no
+expiry). **Revocation trade-off:** a revoked or downgraded license keeps
+authorizing from cache until that deadline; tighten `cacheFreshTtlMs` to
+shorten the window. During transient outages an expired-but-validated entry
+may additionally be served flagged `isStale` for up to `staleGraceMs` — but a
+server denial (401/403/404) is never masked.
 
 ## Context Providers
 
@@ -267,7 +305,7 @@ Rate-limit assertions do NOT return `false` when the limit is exceeded — they
 import { RateLimitAssertion, RateLimitError } from '@sidub-inc/licensing-client';
 
 const assertion = RateLimitAssertion.create({
-  featureId: 'api-calls',
+  featureKey: 'api-calls',
   rateLimit: 1000,
   currentConsumption: 500
 });
@@ -446,7 +484,22 @@ When `serviceKeyId` and `serviceKeyPublicMember` are configured (directly or via
 3. Client verifies signature using configured public key
 4. Invalid signatures throw `CryptoError`
 
-**Disable validation (not recommended):**
+**The posture is always explicit (2.0):**
+
+- **Keys configured** (the recommended `encodedCredential` setup carries them):
+  validation is on automatically.
+- **No keys and `validateSignatures` unset** (e.g. an apiKey-only config):
+  validation is OFF and the client emits a one-time console warning — the
+  authorization body is accepted without cryptographic verification.
+- **`validateSignatures: true` with no keys**: `getAuthorization()` throws
+  `LicensingConfigurationException` — you demanded validation that cannot
+  happen.
+- **`validateSignatures: false`**: explicit unsigned mode; no warning.
+
+Check the effective posture at runtime via `client.isSignatureValidationEnabled`
+(also surfaced by the `useLicensingContextValue()` hook).
+
+**Disable validation explicitly (not recommended):**
 ```typescript
 const client = new LicensingClient({
   licenseServiceUri: '...',
@@ -475,11 +528,30 @@ const decoded = decodeCredential(encoded);     // LicensingCredential
 
 | Error Type | Description |
 |-----------|-------------|
-| `LicensingError` | Base error for API, network, and timeout errors |
+| `LicensingError` | Base error for API, network, and timeout errors — carries the server's error contract (see below) |
 | `LicensingConfigurationException` | Missing required configuration fields (extends `LicensingError`) |
 | `CryptoError` | Signature validation failures (`KEY_IMPORT_FAILED`, `VERIFICATION_FAILED`, `INVALID_SIGNATURE`) |
 | `RateLimitError` | Thrown by `assertLicense` when a `RateLimitAssertion` limit is exceeded — catch it; it is the enforcement signal, not a failure |
 
+### The server error contract
+
+On every HTTP failure the licensing service returns a structured `ApiError`
+body — `{Code, Message, CorrelationId, Details[]}` — plus an `X-Correlation-Id`
+header. `LicensingError` parses it (2.0):
+
+| Field | Description |
+|-------|-------------|
+| `code` | Machine-readable server code (`'ApiKeyMissing'`, `'ApiKeyInvalid'`, `'AuthorizationDenied'`, `'NotFound'`, `'ValidationError'`, `'ServerError'`, ...) — branch on this, not on message text |
+| `correlationId` | The request correlation id (body or `X-Correlation-Id` header) — quote it in support requests |
+| `details` | Optional per-field entries `{code, message, field, targetId}` |
+| `message` | Prefers the server's human-readable `Message`; falls back to the HTTP status text |
+| `statusCode` | HTTP status code |
+| `response` | The raw response body text (always preserved) |
+| `retryAfterMs` | Parsed `Retry-After` header, when the server supplied one |
+
+`code` and `correlationId` are undefined only when the failure never reached
+the server (network error, timeout) or the server did not supply them.
+
 ```typescript
 import { LicensingError, LicensingConfigurationException, CryptoError } from '@sidub-inc/licensing-client';
 
@@ -493,8 +565,15 @@ try {
     // Missing configuration
     console.error('Config error:', error.message);
   } else if (error instanceof LicensingError) {
-    // API or network error
-    console.error('Licensing error:', error.message, error.statusCode);
+    // API or network error — branch on the machine code
+    if (error.code === 'AuthorizationDenied') {
+      showUpgradePrompt();
+    } else {
+      console.error(
+        `Licensing error ${error.code ?? error.statusCode}: ${error.message}`,
+        `correlationId=${error.correlationId ?? 'n/a'}`
+      );
+    }
   }
 }
 ```
@@ -512,9 +591,18 @@ import type {
 } from '@sidub-inc/licensing-client';
 ```
 
-## Migrating from v1.0.x
+## Migrating
+
+See [MIGRATION.md](docs/MIGRATION.md) for detailed upgrade instructions.
+
+**1.x → 2.0 (breaking):**
+- `featureId` → `featureKey` on all feature models
+- Credential is header-only (`dub-apiKey` + `Ocp-Apim-Subscription-Key`); the `?subscription-key=` query string and the dead `dub-issuerKey` header are gone
+- `validateSignatures: true` without a verification key now throws
+- `SignatureValidator.validateRawResponse` removed — use `validateResponseText`
+- Low-level storage helpers (`save`/`load`/...) no longer exported
 
-See [MIGRATION.md](docs/MIGRATION.md) for detailed upgrade instructions. Key changes:
+**1.0.x → 1.1:**
 - `BillingIntervalUnit` enum members renamed: `Days`→`Day`, `Months`→`Month`, `Years`→`Year` (+ new `Hour`, `Week`)
 - `performOperation()` payload structure changed (nested `LicenseOperation`)
 - Configuration validation now throws `LicensingConfigurationException` instead of `LicensingError`