skills/plugins/document-navigator/docs/security-stack/security/license/README.md

@suaveplan/license - Compact, offline-verifiable, secp256k1-signed software-license-key format: 72-bit bitpacked payload (version + signing-key id + product id + tier + flags + time encoding + time value + feature mask + nonce) plus full or truncated (20-byte) signature, Crockford-Base32 encoded with signature-derived obfuscation. suaveplan-enterprise additions: SuaveplanError-typed errors, OTel counters/histograms/spans, Zod boundary validation, injectable Clock/Rng, AbortSignal propagation, pluggable RevocationStore. Universal.

Compact, offline-verifiable, secp256k1-signed software-license-key format. Bit-for-bit wire-format compatible with upstream @suaveplan/license. runs unchanged in Bun, Node, and the browser.

Documentation tree

• base32 — Crockford-style Base32 codec used to serialise the packed payload and signature into a printable license-key string. Th…
  • base32 — Crockford-style Base32 codec used to serialise the packed payload and signature into a printable license-key string. Th…
• bitpack — Bit-precise pack/unpack primitives used to serialise the 72-bit license payload into 9 bytes. Plain DataView / typed-…
  • bitpack — Bit-precise pack/unpack primitives used to serialise the 72-bit license payload into 9 bytes. Plain DataView / typed-…
• obfuscation — Per-key character obfuscation pass run after Base32 encoding. The first 15 non-dash characters of the encoded key (whic…
  • obfuscation — Per-key character obfuscation pass run after Base32 encoding. The first 15 non-dash characters of the encoded key (whic…
• payload — packPayload and unpackPayload are the 72-bit payload codec on top of the bitpack primitives. They emit exactly 9 by…
  • payload — packPayload and unpackPayload are the 72-bit payload codec on top of the bitpack primitives. They emit exactly 9 by…
• constants — Wire-format constants for the license package. Every value here is part of the binary contract: the per-field b…
  • constants — Wire-format constants for the license package. Every value here is part of the binary contract: the per-field b…
• flags — Bitmask helpers for the 5-bit flags field (LicenseFlags) and the 19-bit featureMask field. The flags field stores…
  • flags — Bitmask helpers for the 5-bit flags field (LicenseFlags) and the 19-bit featureMask field. The flags field stores…
• generate — Top-level license-key generation, payload construction, and parse-only inspection. This is the place that brings togeth…
  • generate — Top-level license-key generation, payload construction, and parse-only inspection. This is the place that brings togeth…
• manager — High-level LicenseManager class that bundles a public-key registry, an optional signing key, default signingKeyId /…
  • manager — High-level LicenseManager class that bundles a public-key registry, an optional signing key, default signingKeyId /…
• otel — OpenTelemetry instrumentation for the license package. Registers a single @opentelemetry/api meter (`@suaveplan/licen…
  • instruments — OpenTelemetry instrumentation for the license package. Registers a single @opentelemetry/api meter (`@suaveplan/licen…
• revocation-store — Pluggable revocation blocklist for the license package. The RevocationStore interface defines three methods (add, `…
  • revocation-store — Pluggable revocation blocklist for the license package. The RevocationStore interface defines three methods (add, `…
• schemas — Zod schemas for every public input boundary in the license package. generateLicense, validateLicense, `createPayloa…
  • schemas — Zod schemas for every public input boundary in the license package. generateLicense, validateLicense, `createPayloa…
• time — Time-encoding helpers for the four TimeEncodingType variants. The 72-bit payload encodes time in 18 bits with an addi…
  • time — Time-encoding helpers for the four TimeEncodingType variants. The 72-bit payload encodes time in 18 bits with an addi…
• types — Public type surface for the license package, ported verbatim from the upstream index.types.ts at the wire-format leve…
  • license — Public type surface for the license package, ported verbatim from the upstream index.types.ts at the wire-format leve…
• validate — License-key validation: parse, verify signature, check version, check expiration, surface every failure as a typed enum…
  • validate — License-key validation: parse, verify signature, check version, check expiration, surface every failure as a typed enum…
• error-codes — This module owns the stable error-code registry for @suaveplan/license. It exposes LICENSE_CODES (a frozen `defineC…

Highlights

• 72-bit bitpacked payload (version + signing-key id + product id
  • tier + flags + time encoding + time value + feature mask + nonce) encoded as 9 bytes.
• Truncated 20-byte signature by default keeps keys ~50-60 characters; opt into 64-byte full signatures with useFullSignature: true.
• Crockford-style Base32 alphabet (no I/L/O/U — paste- friendly).
• Signature-derived obfuscation pass rotates the first 15 payload characters by per-license offsets drawn from the signature.
• Four time-encoding strategies: NONE, ABSOLUTE_DAYS, RELATIVE_DAYS, ABSOLUTE_TIMESTAMP.
• 19-bit feature mask + 5-bit flag bitfield (TRIAL, UPGRADE, MACHINE_LOCKED, SUBSCRIPTION, EDUCATIONAL).
• Enterprise extras: typed LicenseError registry, OTel counters/histograms, Zod boundary validation, injectable Clock / Rng, AbortSignal propagation, pluggable RevocationStore.

Quick-start

import { secp256k1 } from "@suaveplan/crypto-curve";
import { LicenseManager, PackageTier } from "@suaveplan/license";

// 1. Generate a signing key (typically done once, off-line)
const secret = secp256k1.randomPrivateKey();
const publicKey = { p: secp256k1.getPublicKey(secret) };

// 2. Bind the manager to that key
const m = new LicenseManager({
    signingKey: { s: secret, p: publicKey.p },
    publicKeys: { 0: publicKey },
});

// 3. Mint a license key
const { key } = await m.generate({
    productId: 5,
    tier: PackageTier.PRO,
    expirationDays: 365,
});

// 4. Hand the key to the user, validate it on incoming requests
const v = await m.validate(key);
if (v.success) {
    console.log(`Tier ${v.details.packageTier}, expires ${v.details.expirationDate}`);
}

Modules

Every feature module is a tree-shakeable subpath export:

Module	Subpath	Docs
Error codes	./error-codes/error-codes	src/error-codes.md
Constants	./constants/constants	src/constants/constants.md
Types + enums	./types/license	src/types/license.md
Base32 codec	./codec/base32/base32	src/codec/base32/base32.md
Bitpack	./codec/bitpack/bitpack	src/codec/bitpack/bitpack.md
Payload codec	./codec/payload/payload	src/codec/payload/payload.md
Obfuscation	./codec/obfuscation/obfuscation	src/codec/obfuscation/obfuscation.md
Time helpers	./time/time	src/time/time.md
Flag helpers	./flags/flags	src/flags/flags.md
Zod schemas	./schemas/schemas	src/schemas/schemas.md
OTel instruments	./otel/instruments	src/otel/instruments.md
Generate	./generate/generate	src/generate/generate.md
Validate	./validate/validate	src/validate/validate.md
Manager	./manager/manager	src/manager/manager.md
Revocation	./revocation/revocation-store/revocation-store	src/revocation/revocation-store/revocation-store.md

The package root (.) re-exports every public symbol from each module for ergonomic single-import usage.

Benchmarks

Captured with mitata on Intel(R) Xeon(R) CPU E5-2696 v4 @ 2.20GHz, Bun 1.3.14 (Linux x64). Run yourself with bun src/__benchmarks__/license.bench.ts.

Benchmark	Mean	p75	p99
base32Encode (73 bytes)	38.09 µs	42.82 µs	134.18 µs
base32Decode (73 bytes)	65.06 µs	70.70 µs	189.76 µs
packPayload	733.58 ns	744.46 ns	1.37 µs
unpackPayload	1.16 µs	1.18 µs	1.75 µs
generateLicense (truncated)	67.64 µs	73.84 µs	242.36 µs
validateLicense (truncated)	40.52 µs	42.73 µs	116.04 µs

A full generate + validate round-trip completes in ~108 µs on this hardware, comfortably below the 1 ms p99 budget targeted by the upstream enterprise audit.

Revocation

Revocation is an opt-in pluggable layer. Wire any store implementing the RevocationStore interface (sync or async); the package ships a synchronous in-memory store with optional LRU eviction.

import {
    createMemoryRevocationStore,
    fingerprintLicense,
    LicenseManager,
} from "@suaveplan/license";

const store = createMemoryRevocationStore({ maxEntries: 100_000 });
const m = new LicenseManager({ signingKey, publicKeys, revocationStore: store });

// Block a compromised key
await m.revoke(fingerprintLicense(compromisedKey));

// Subsequent validates of that key return { error: 'REVOKED' }

Wire format

The on-the-wire layout is unchanged from upstream @suaveplan/license. Each 9-byte payload packs nine fields MSB-first:

| v(3) | kid(5) | pid(6) | tier(4) | flg(5) | te(2) | timeValue(18) | featureMask(19) | nonce(10) |
                                                                                    total = 72 bits

A complete key encodes payload || signature (29 bytes with truncated signature, 73 bytes with full signature) as Base32, dashes inserted every 5 chars for legibility, then runs the signature-derived obfuscation pass over the first 15 payload chars. The seed-from-key-region trick (chars 16-30 carry the obfuscation seed) breaks the circular dependency between "decode needs the seed" and "the seed comes from a decoded signature".

License

MIT.