License Validation and Enforcement

Overview

The License Validator is a system component responsible for parsing, validating, and enforcing the terms of the product license. It ensures that the platform operates within the capacity limits and feature entitlements granted by a signed JSON Web Token (JWT).

The validator's primary input is a license JWT, which is either uploaded by a platform operator or read from the database. It verifies the token's authenticity, integrity, and claims against the specific installation's identity. As a fallback for new installations, it uses a time-limited, embedded "bootstrap" license.

The key output is a LicenseState object, which represents the effective entitlements and capacity limits. This state is cached for performance and consulted by various system components to enforce license terms, such as gating the creation of new services or enabling specific features. The validator runs periodically and upon specific events (like application startup or a new license upload) to ensure the license state remains current.

How it Works

The system determines the current license state by following a strict precedence order: a valid, active license JWT is always preferred. If one is not available or fails re-validation, it attempts to fall back to a temporary bootstrap license. If neither is available, the system enters a disabled state with zero capacity.

License Resolution Flow

The LicenseValidator resolves the effective license state by checking for an active license in the database, re-validating it, and falling back to the bootstrap license if necessary. This process is executed on application startup, on a recurring hourly schedule, and whenever the cached state expires (after 30 seconds) and a new check is triggered.

The following diagram illustrates the license resolution logic:

flowchart TD
    subgraph "License Resolution Process"
        direction TD
        A(Start: Resolve License) --> B{Active license present?}
        B -- Yes --> C[Re-verify JWT signature and claims]
        C --> D{Verification successful?}
        D -- Yes --> E{Expired beyond 24hr grace period?}
        E -- No --> F[Apply thresholds from license meta claim]
        F --> G(State: Licensed)
        E -- Yes --> H[Deactivate expired license in DB]
        H --> I{Bootstrap license available?}
        D -- No --> J[Log warning and use fallback]
        J --> I
        B -- No --> I

        subgraph "Bootstrap and Disabled States"
            I -- Yes --> K{Bootstrap conditions met?<br>(Install < 45 days old AND not HARD_STOP)}
            K -- Yes --> L(State: Bootstrap)
            K -- No --> M{System in HARD_STOP state?}
            M -- Yes --> N(State: Disabled)
            M -- No --> O[Attempt last-resort bootstrap load]
            O --> P{Bootstrap now available?}
            P -- Yes --> L
            P -- No --> N
        end
    end

JWT Verification

Every active license JWT is re-validated to ensure its integrity and applicability. The validation process, performed by the verifyV3 method, is strict and enforces multiple conditions. A token that fails any of these checks is considered invalid.

1. Signature Verification: The JWT signature is verified using the RS256 algorithm. The public key is resolved using the kid (Key ID) from the JWT header.

   • For the bootstrap license (kid = bootstrap-placeholder-v1), a bundled public key is used.
   • For all other licenses, the key is fetched from a live JWKS (JSON Web Key Set) endpoint via the SpecariaJwksProvider.

2. Header Validation:

   • alg (Algorithm) must be RS256.
   • typ (Type) must be JWT.

3. Claim Validation:

   • iss (Issuer): Must be https://license.specaria.io.
   • exp (Expiration Time): The token must not be expired, accounting for a 300-second clock skew tolerance. An active license that is expired beyond a 24-hour grace period (EXPIRY_GRACE) is deactivated.
   • license_format_version: Must be 3. No other versions are supported.
   • aud (Audience): Must match spc:<product_slug>:<installation_id> (e.g., spc:s2r:uuid-goes-here) to bind the license to the specific installation. For the bootstrap license, the literal spc:s2r:bootstrap is also accepted.
   • installation_id: The UUID in this claim must match the installation's own ID. This serves as a defense-in-depth check.

Caching

To optimize performance, the resolved LicenseState is held in a 30-second in-memory cache (CACHE_TTL).

• Calls to effective() or currentState() will return the cached state if it is still valid.
• If the cache is expired, a full re-resolution is triggered, and the cache is repopulated with the fresh state.
• The cache is explicitly invalidated via invalidateCache() after a new license is successfully uploaded to ensure the new terms take effect immediately.

Bootstrap License

For new installations, a temporary bootstrap license is used. Its activation is gated by two conditions:

1. The installation must be less than 45 days old, tracked from the bootstrap_activated_at timestamp.
2. The system must not be in a HARD_STOP state as determined by the SpecariaGraceStateMachine.

If these conditions are not met, the bootstrap license is not used, and the system will proceed to a disabled state if no other valid license is found.

License Upload and Activation

A new license JWT can be provided to the system by a platform operator. The uploadAndActivate method handles this process.

Procedure:

1. A platform operator provides the new license as a raw JWT string.
2. The system calls uploadAndActivate(jwtRaw, uploadedBy).
3. The validator first checks that the token is not null or blank (ERR_BAD_REQUEST).
4. It then invokes verifyV3 to perform the full suite of JWT validation checks. The allowBootstrap flag is set to false, meaning an operator cannot upload a bootstrap token.
5. If validation succeeds, the claims from the JWT are parsed and persisted to the database as the new active license row.
6. The in-memory license cache is invalidated by calling invalidateCache().
7. The method returns the new LicenseState, which is resolved by an immediate call to effective().

Expected Result: A successful upload replaces the current license. The system immediately begins operating under the terms of the new license.

Failure Conditions: If the JWT fails validation for any reason (e.g., bad signature, incorrect aud claim, unsupported format), the method throws a LicenseException with a specific error code, and the current license state remains unchanged.

JWT Claims Reference

The validator parses specific claims from the JWT to determine license entitlements. The token must be a v3 format license.

Standard Claims

Custom Claims

These claims define the specific terms and features of the license.

limits Object

The limits object defines the capacity caps for the installation. Any key in this object with an integer value is treated as an enforceable capacity dimension.

meta Object

The meta object contains operator-tunable settings and consent flags.

commerce Object

This object contains commercial details for reference. These fields are not enforced by the validator.

enforcement Object

This object defines how license expiry is handled. If the object is absent, the policy defaults to updates-only.

API Reference

The LicenseValidator exposes several public methods for other components to query the license state and perform enforcement checks.

Troubleshooting

When license validation fails, the validator throws a LicenseException containing one of the following error codes.

See Also

• Bootstrap License Loader: The component responsible for loading and managing the initial 45-day bootstrap license for new installations.
• JWKS Provider: The service (SpecariaJwksProvider) that fetches and caches public keys from a re<customer>e JWKS endpoint for verifying license JWT signatures.
• Grace State Machine: The component (SpecariaGraceStateMachine) that manages the system's operational state (e.g., READ_ONLY, HARD_STOP) during periods of license expiry or offline operation.
• Heartbeat Client: The client (SpecariaHeartbeatClient) that sends telemetry data, which includes the raw license JWT obtained from this validator.

All SOAP-to-REST docs