> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/obsidian-license/how-it-works.md).

# How It Works

Obsidian License keeps the real, compiled plugin **off the customer's disk**. Customers only ever receive a thin **loader** plugin. At runtime the loader phones home, the **license server** validates the license + machine fingerprint, logs the access, and returns the **encrypted real plugin**, which the loader decrypts and loads entirely in memory via a custom class loader.

```
        ┌───────────────────────┐       HTTPS (activate)       ┌──────────────────────┐
        │  Customer Paper server │  ─────────────────────────▶ │   License Server     │
        │  loader-plugin (thin)  │   licenseKey + fingerprint   │  Node/Express + PG   │
        │                        │  ◀───────────────────────── │  + admin web UI      │
        │  in-memory classloader │   enc(payload) + key + sig   │  encrypts jars at    │
        │  runs the real plugin  │                              │  rest, logs access   │
        └───────────────────────┘                              └──────────────────────┘
```

## The lifecycle, step by step

1. **Upload** your compiled plugin to Obsidian License. It's encrypted (AES-256-GCM) and stored; the plaintext is discarded.
2. **Distribute the loader** — a tiny, generic Paper plugin — to customers instead of your real one.
3. **Issue license keys**: manually, in bulk, or automatically when a marketplace purchase happens.
4. **Every server start**, the loader calls home with the license key and a machine fingerprint. The server validates it, logs the attempt, and — if valid — returns the encrypted plugin plus a decryption key, **signed with Ed25519** so the response can't be forged. The loader decrypts and runs the plugin entirely in memory; nothing touches disk.
5. **Stay in control** from the dashboard: revoke a license, let it expire, rebind it to new hardware, or rate-limit / ban abusive IPs — the protected plugin stops loading on the affected server(s) on their next boot. When activation is denied, the loader prints a plain-English reason and a link to the self-service portal instead of a cryptic error.

## Fail-closed by design

The loader fails closed: the protected plugin will **not** run if the config is missing/invalid, or if the license server is unreachable. This is intentional — there is no offline grace mode by default (strict online).

## The signed activation envelope

The activation response is a signed envelope of the form `nonce.version.payload.key.ent`, covering the encrypted payload, its AES key, and per-license tier/entitlements. Because it's signed, a rogue server can't substitute a malicious payload and the tier/entitlements can't be tampered with on the wire.

{% hint style="warning" %}
The envelope now covers per-license tier/entitlements (`ent`). When the platform is updated, **download and redistribute the latest loader** — older loaders compute the pre-`ent` signature and will fail closed.
{% endhint %}