docs(admin): internal license operations reference
Creator-only ADMIN.md covering keypair generation, blob minting, dev vs. production key model, tier matrix, and recovery if the private key is lost. Includes a TL;DR for minting a dev license against the in-tree keypair. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
199
docs/ADMIN.md
Normal file
199
docs/ADMIN.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# ADMIN — Internal license operations
|
||||
|
||||
Creator/operator-only reference. End users should read `USER-GUIDE.md` instead.
|
||||
|
||||
This doc covers everything the creator does that buyers never see: generating
|
||||
the signing keypair, minting license blobs, the dev vs. production key story,
|
||||
and how to recover from key loss.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR — I just need a license for my dev machine
|
||||
|
||||
You're running from source, so the repo's embedded dev keypair signs and
|
||||
verifies. No env vars needed.
|
||||
|
||||
```bash
|
||||
python scripts/generate_license.py \
|
||||
--name "Michael Dombaugh" \
|
||||
--email michael.dombaugh@gmail.com \
|
||||
--tier core
|
||||
```
|
||||
|
||||
Copy the `DTLIC2:…` blob from stdout, then activate:
|
||||
|
||||
```bash
|
||||
python -m src.license_cli activate "DTLIC2:..." \
|
||||
--name "Michael Dombaugh" \
|
||||
--email michael.dombaugh@gmail.com
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
python -m src.license_cli status
|
||||
```
|
||||
|
||||
License lands at `~/.datatools/license.json`, valid 1 year.
|
||||
|
||||
> The `--name` / `--email` you pass to `activate` **must** match the values
|
||||
> the blob was minted with — they're part of the signed payload.
|
||||
|
||||
---
|
||||
|
||||
## Key model (Ed25519, asymmetric)
|
||||
|
||||
| Key | Lives where | Used for |
|
||||
|-----|------------|---------|
|
||||
| **Private** (32 bytes hex) | Creator's password manager / KMS only | Signing license blobs |
|
||||
| **Public** (32 bytes hex) | Baked into the shipped binary | Verifying blobs at activation |
|
||||
|
||||
The split is the whole point: an attacker with a copy of the binary still
|
||||
can't mint blobs — they'd need the private key, which never ships.
|
||||
|
||||
There's also an in-tree **dev keypair** (`src/license/_dev_keypair.py`)
|
||||
derived deterministically from a seed. It's used when no env vars are set,
|
||||
so devs/tests can sign and verify locally without juggling secrets. Frozen
|
||||
builds that still use it are rejected at startup by
|
||||
`assert_production_safe` — see `src/license/crypto.py:84`.
|
||||
|
||||
Blob format prefix: `DTLIC2:` (v1 was HMAC; v2 is Ed25519).
|
||||
|
||||
---
|
||||
|
||||
## One-time setup — generating the production keypair
|
||||
|
||||
Run once, before the first paid release.
|
||||
|
||||
```bash
|
||||
python scripts/generate_keypair.py --output keypair.env
|
||||
```
|
||||
|
||||
You'll get:
|
||||
|
||||
```
|
||||
DATATOOLS_LICENSE_PRIVKEY=<64 hex chars> # KEEP SECRET
|
||||
DATATOOLS_LICENSE_PUBKEY=<64 hex chars> # BAKE INTO BUILD
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
1. **Stash the private key** in a password manager / KMS / hardware token.
|
||||
Losing it means no more renewals — see "Recovery" below.
|
||||
2. **Delete `keypair.env`** from disk once stored.
|
||||
3. **Set the public key** as `DATATOOLS_LICENSE_PUBKEY` in the PyInstaller
|
||||
build environment. The shipped binary embeds it via the env at freeze time.
|
||||
|
||||
---
|
||||
|
||||
## Minting a buyer license (production)
|
||||
|
||||
With the production private key loaded:
|
||||
|
||||
```bash
|
||||
export DATATOOLS_LICENSE_PRIVKEY=<your-private-hex>
|
||||
|
||||
python scripts/generate_license.py \
|
||||
--name "Buyer Name" \
|
||||
--email buyer@example.com \
|
||||
--tier core \
|
||||
--years 1 \
|
||||
--output buyer.dtlic
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
| Flag | Default | Notes |
|
||||
|------|---------|-------|
|
||||
| `--name` | required | Buyer's full name. Goes into signed payload. |
|
||||
| `--email` | required | Buyer's email. Goes into signed payload. |
|
||||
| `--tier` | `core` | One of: `lite`, `core`, `pro` |
|
||||
| `--years` | `1` | Lifetime in years |
|
||||
| `--key` | random | Override the auto-generated license key |
|
||||
| `--output` / `-o` | stdout | Write blob to file instead of printing |
|
||||
|
||||
Deliver the blob to the buyer either inline in the purchase email or as
|
||||
the attached `.dtlic` file.
|
||||
|
||||
---
|
||||
|
||||
## Tiers
|
||||
|
||||
| Tier | Features |
|
||||
|------|---------|
|
||||
| **lite** | Deduplicator, Text Cleaner, Format Standardizer |
|
||||
| **core** | All 9 tools |
|
||||
| **pro** | All 9 tools + future Pro-only features |
|
||||
|
||||
Source of truth: `src/license/features.py::all_features_for_tier`.
|
||||
|
||||
---
|
||||
|
||||
## Useful one-liners
|
||||
|
||||
Mint a free internal/team license (dev key, no env needed):
|
||||
|
||||
```bash
|
||||
python scripts/generate_license.py --name "QA Bot" --email qa@datatools.app --tier core --years 5
|
||||
```
|
||||
|
||||
Mint with a stable, human-readable key:
|
||||
|
||||
```bash
|
||||
python scripts/generate_license.py --name "Acme Corp" --email ops@acme.com \
|
||||
--tier pro --key "DT1-PRO-ACME-2026"
|
||||
```
|
||||
|
||||
Renew an existing buyer (just re-mint with the same email; they paste the
|
||||
new blob):
|
||||
|
||||
```bash
|
||||
python -m src.license_cli renew "DTLIC2:..."
|
||||
```
|
||||
|
||||
Check what's active locally:
|
||||
|
||||
```bash
|
||||
python -m src.license_cli status
|
||||
```
|
||||
|
||||
Wipe a local license (move to a new machine, debug a buyer issue):
|
||||
|
||||
```bash
|
||||
python -m src.license_cli deactivate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recovery — what if the private key is lost?
|
||||
|
||||
Existing licenses keep working until they expire (the public key in the
|
||||
shipped binary still verifies them). What breaks:
|
||||
|
||||
- **Renewals** — you can't mint a new blob for an existing buyer.
|
||||
- **New sales** — you can't mint anything.
|
||||
|
||||
Path forward:
|
||||
|
||||
1. Generate a new keypair (`scripts/generate_keypair.py`).
|
||||
2. Ship a new build with the new public key.
|
||||
3. Re-issue every active buyer a new blob signed by the new private key.
|
||||
4. Communicate the upgrade path to buyers.
|
||||
|
||||
Treat the private key like a code-signing cert — back it up to two
|
||||
independent secure locations.
|
||||
|
||||
---
|
||||
|
||||
## Files & code pointers
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `scripts/generate_keypair.py` | One-time keypair generation |
|
||||
| `scripts/generate_license.py` | Mint a signed blob |
|
||||
| `src/license/crypto.py` | Sign / verify / dev-key detection |
|
||||
| `src/license/_dev_keypair.py` | In-tree dev keypair (never ships in prod) |
|
||||
| `src/license/manager.py` | `assert_production_safe` startup check |
|
||||
| `src/license/features.py` | Tier → features mapping |
|
||||
| `src/license_cli.py` | End-user `activate` / `status` / `renew` / `deactivate` |
|
||||
| `~/.datatools/license.json` | Where activated licenses are stored on each machine |
|
||||
Reference in New Issue
Block a user