feat: license handshake and x-descope-license header

[orius123]

Summary

Adds license handshake support so Cloudflare can apply the correct rate-limit bucket per customer tier.

• Adds management.license.get() (GET /v1/mgmt/license) returning { rateLimitTier: string }
• On init, when a managementKey is configured, the SDK fires a one-shot license fetch in the background and caches rateLimitTier
• All subsequent management requests inject x-descope-license: <tier> via the existing beforeRequest hook

Tier values

tier1 (free) / tier2 (pro) / tier3 (growth) / tier4 (enterprise)

Notes

• Handshake failure is non-fatal: errors are logged via logger?.debug and the SDK continues without the header
• The backend interceptor skips license-header validation for GetLicense itself, so the initial fetch is safe before the tier is cached

Test plan

• lib/management/license.test.ts covers the new endpoint
• Integration tests will exercise the end-to-end handshake + header injection

Ref: descope/etc#14245

[Copilot]

Pull request overview

Adds a license-tier handshake to the management SDK so Cloudflare can apply per-customer rate-limit buckets. When a managementKey is configured, the SDK asynchronously fetches the customer's tier on initialization and injects it into every subsequent management request as the x-descope-license header.

Changes:

• New management.license.get() endpoint (GET /v1/mgmt/license) and License type with rateLimitTier.
• On SDK init, fires a one-shot license fetch and caches rateLimitTier; failure logs at debug and is non-fatal.
• Management beforeRequest hook injects x-descope-license: <tier> once cached.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/management/types.ts	Adds License type.
lib/management/paths.ts	Adds /v1/mgmt/license path entry.
lib/management/license.ts	New wrapper exposing get() for the license endpoint.
lib/management/license.test.ts	Unit test for the new get() endpoint.
lib/management/index.ts	Wires withLicense into the management surface.
lib/index.ts	Adds tier cache, fire-and-forget handshake, and header injection in beforeRequest.

Comments suppressed due to low confidence (1)

lib/index.ts:174

• The .catch handler swallows handshake errors with only a logger?.debug?. call. If logger is not provided, or its debug level is filtered out (which is common in production logging configurations), the failure becomes completely invisible — operators have no signal that the handshake is failing and the tier header is missing. Consider using logger?.warn (or at least logger?.info) for handshake failures since a missing tier header will cause Cloudflare to rate-limit the customer at the default/lowest bucket, which has real customer-visible consequences.

      .catch((e) => {
        logger?.debug?.('License handshake failed', e);
      });

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.