license-manager-docs/docs/en/guide/license-token-structure.md

License Structure & Validation (Client Essentials)

The system issues licenses as Base64-encoded JSON strings. During startup the client must decode the string and run through signature verification, hardware fingerprint checks, and expiry/status validation. This guide follows a “flow → structure → payload → example → checklist” order for quick reference.

1. Startup Flow Overview

Begin with the big picture: the following Mermaid diagram outlines each validation checkpoint after the client receives a license string, including all failure exits.

flowchart TD
    %% Nodes
    Start([Client boot]) --> GetToken[Fetch Base64 license string]
    GetToken --> Decode[Base64 decode]

    Decode --> ParseJSON{Parse JSON structure?}
    ParseJSON -- No --> ErrFormat[Stop: invalid format]
    ParseJSON -- Yes --> Extract[Extract core fields: <br/>data, signature, algorithm]

    %% Signature stage
    Extract --> VerifySig[[RSA signature verify]]
    VerifySig -- Fail --> ErrTamper[Stop: license tampered]
    VerifySig -- Pass --> ParseData[Deserialize data payload]

    %% Business logic
    ParseData --> CheckStatus{Check status & validity}
    CheckStatus -- Locked / Expired --> ErrStatus[Stop: locked or expired]
    CheckStatus -- Normal & valid --> CheckType{Detect deployment type}

    %% Branches
    CheckType -- standalone --> CheckHW{Compare hardware fingerprint}
    CheckType -- cloud / hybrid --> CheckNet{Online/heartbeat validation}

    %% Final results
    CheckHW -- Mismatch --> ErrHW[Stop: fingerprint mismatch]
    CheckNet -- Rejected --> ErrNet[Stop: server rejected]

    CheckHW -- Match --> Success([All checks passed])
    CheckNet -- Accepted --> Success

    %% Styles
    classDef error fill:#f9f2f4,stroke:#c00,stroke-width:2px,color:#c00;
    classDef success fill:#e1fdf4,stroke:#009966,stroke-width:2px,color:#009966;
    classDef process fill:#f9f9f9,stroke:#333,stroke-width:1px;

    class ErrFormat,ErrTamper,ErrStatus,ErrHW,ErrNet error;
    class Success success;
    class Decode,VerifySig,ParseData,CheckHW,CheckNet process;

2. Top-Level License Structure

Once the Base64 string is decoded you will get a JSON object containing three core fields. The structure keeps the payload human-readable while protecting integrity through an asymmetrical signature.

Field reference

Field	Type	Description
algorithm	String	Algorithm used to generate the signature, for example RSA-PSS-SHA256.
data	String	Primary payload serialized as a JSON string. Contains all enforcement rules, time limits, and fingerprint bindings.
signature	String	Base64 signature generated from the data field. Clients must verify it with the embedded public key before trusting the payload.

---

3. data Payload Details

The data field carries every parameter that governs runtime behavior. After deserializing the string, reference the values below to decide how the software should run.

Core parameters

Parameter	Values / Type	Description & engineering tips
status	normal, locked, expired	Overall authorization state. normal allows execution, locked indicates an admin-enforced block, expired means the time window has passed.
deployment_type	standalone, cloud, hybrid	Determines the validation path: standalone = local fingerprint only; cloud = mandatory online heartbeat; hybrid = prefer online, allow short offline grace period.
start_date / end_date	ISO 8601 timestamp	Validity window for the license. Compare against system time during startup; treat any end_date in the past as expired.
hardware_fingerprint	String	Combination of hardware identifiers (MAC/CPU/HostID, etc.). Recalculate locally and compare; mismatch implies unauthorized copy.
usage_limits	Object	Usage quotas (API calls, seat counts, etc.).
feature_config	Object	Key-value feature switches controlling which modules (Basic vs Pro) the client may enable.
license_key	String	Unique identifier for the licensed device; use for logging and backend correlation.

---

4. Decoded Example

Here is a decoded license sample to highlight formatting and field expectations:

{
  "algorithm": "RSA-PSS-SHA256",
  "data": "{\"activated_at\":\"2025-11-01T22:30:02...\",\"status\":\"normal\",\"deployment_type\":\"standalone\",\"hardware_fingerprint\":\"MAC:5e:a3...\",\"end_date\":\"3025-03-03T23:59:59+08:00\", ...}",
  "signature": "MQDlxx/crzncJfw2Y00X5spzN1bPWKuU4IDxB48Mwy1WMhOoYUDCcrYjiMgNJHsXzUSD14MURqCBKBMgQAc7EOiUUcwfJ1mhSGvbFYnrSGFxjpbEHUg6dJlgSB4jSxwh4jtHSOb82SvPkHrNE0/p/HKN2Vr3Dj2qU0JB7hM2Jd0vb3Tk7WiFWd9as3vvAChhzoXqHo53vtY7ZyUb56VM/M4UMwJ4w4S7M3DZiPwAAobOn1MfOmOnchXzc+lkhC9c67xprmOi33ms775Dc0tNurv+rCLTQN8wgnt5dfhmdyMbsIk2c188IK/7uca2Pi3qaBKSIkVkSKN78pI2A6gMYIA=="
}

Note: data must remain in its original string form when verifying the signature. Only deserialize after the RSA verification succeeds.

---

5. Client Validation Checklist

Use this checklist to implement a hardened validation pipeline:

1. Decode: Base64-decode the license string.
2. Verify signature: With the built-in public key, run RSA verification against the original data string and the provided signature. Abort immediately if the signature fails.
3. Parse payload: Deserialize data into an object.
4. Evaluate status & timeline:
   • Require status === "normal".
   • Confirm current time is between start_date and end_date.
5. Match environment:
   • Branch based on deployment_type.
   • Standalone: recompute hardware fingerprint and compare with hardware_fingerprint.
   • Cloud/Hybrid: perform online heartbeat or fallback strategy.

Consider implementing the checklist as a modular validation pipeline so additional strategies (SaaS tenant isolation, audit logging, etc.) can be plugged in later.