Offline Cryptographic License Verification, Ed25519 Signatures & Feature Entitlements Architecture Guide
Overview
The pkg/license package implements cryptographically secure, offline license verification for enterprise feature gating across ZQK clusters, relays, and autonomous swarms. It ensures that features (such as relay routing, multi-cluster mesh federation, and high-concurrency worker pools) are authenticated without network egress, telephone-home dependencies, or centralized verification latency.
Architectural Placement & Security Model
┌─────────────────────────────────────────────────────────────┐
│ ZQK License JWT │
│ - Algorithm: EdDSA (Ed25519) │
│ - Claims: Features ([]string), RegisteredClaims (Expiry) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ pkg/license.Validator │
│ - Hardcoded / Embedded Ed25519 Public Key │
│ - Offline Signature Verification │
│ - Algorithm Downgrade Attack Prevention (Strict EdDSA) │
│ - Expiration Invalidation (ErrExpiredToken) │
└──────────────────────────────┬──────────────────────────────┘
│
┌──────────────────┴──────────────────┐
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ HasFeature() │ │ RequireFeature() │
│ - Non-blocking check │ │ - Fail-closed enforcement │
│ - Feature availability │ │ - ErrMissingFeature return │
└─────────────────────────────┘ └─────────────────────────────┘
Core Architectural Invariants
-
Strict Algorithm Enforcement (Anti-Downgrade): The verification pipeline explicitly checks
token.Method.(*jwt.SigningMethodEd25519)and configuresjwt.WithValidMethods([]string{"EdDSA"}). Symmetric key confusion attacks (e.g., signing with HMAC using the public key as the secret) are completely blocked. -
Offline Hermetic Operation: Verification requires zero network connectivity. The Ed25519 public key is supplied during validator construction, ensuring that disconnected air-gapped environments function seamlessly.
-
Deterministic Error Taxonomy: -
ErrInvalidToken: Returned when signature verification fails, tokens are malformed, or cryptographic assertions are violated. -ErrExpiredToken: Returned when theexpclaim indicates expiration. -ErrMissingFeature: Returned byRequireFeaturewhen the license is structurally valid but lacks the requested capability tag. -
Fail-Closed Entitlement Checks: Any parsing failure, key mismatch, or expired timestamp immediately aborts feature access, maintaining a strict fail-closed posture across all enterprise surfaces.
Verification & Testing Standards
- Coverage Floor: Statement coverage must be strictly maintained at >= 85.0% (target 100.0%).
- Boundary Validation: Test suites must explicitly exercise algorithm confusion/downgrade attacks, expired tokens, key mismatches, and missing claims.
- Negative Testing: All exported error sentinels must be verified for message consistency and
errors.Iswrapping compatibility.