Role Entitlements, Capability Matrix & Object Elevation Operational Architecture Guide
1. Executive Architectural Summary
The Role Entitlements and Capability Matrix Subsystem (pkg/entitlements, pkg/license, and cmd/zqk/object/elevated.go) provides the authoritative tier governance, feature gating, and privilege elevation boundary for the ZQK Knowledge Kernel. In a multi-agent autonomous environment where human operators, background daemons, and autonomous AI swarms interact with kernel graphs, Content-Addressed Storage (CAS), and Model Context Protocol (MCP) services, a clear separation between identity, role-based authorization, and cryptographic platform entitlements is critical.
The subsystem enforces five core architectural invariants:
- Dual-Tier Entitlement Enforcement: Distinguishes between the free Community Tier (unbounded core knowledge operations with conservative safety caps on autonomous refactoring loops) and the licensed Enterprise Tier (unbounded concurrency, autonomous mesh federation, and privileged object elevation).
- Offline Cryptographic Verification: Evaluates platform licenses completely offline using Ed25519 asymmetric signatures and JSON Web Tokens (JWT), preventing external network telemetry requirements and ensuring air-gapped sovereign execution.
- Fail-Closed Fallback Invariant: If a license key or file is missing, expired, syntactically malformed, or signed by an untrusted public key, the runtime immediately and safely defaults to the strict
CommunityCheckerimplementation without crashing. - Privileged Object Elevation Boundary: Enforces that internal kernel schema kinds (marked with
visibility: internal) are shielded from standard discovery and mutation unless explicitly requested via--internaland authorized by theelevated_objectentitlement bundle. - Strict Planner vs. Doer Lane Segregation: Complements role-based access control (RBAC) by ensuring execution worker seats are strictly separated from strategic orchestrator seats, preventing runaway self-delegation.
2. Component Topology & Subsystem Architecture
The entitlements subsystem acts as an operational gate between incoming user/agent CLI and MCP commands and high-privilege kernel operations:
flowchart TD
subgraph Callers["Subsystem Invocations"]
CLI["CLI Commands\n(zqk object, zqk system evolve)"]
Mesh["Mesh Networking\n(zqk mesh federation)"]
Swarm["Autonomous Swarm Runner\n(zqk do, zqk agent orchestrate)"]
end
subgraph EntitlementsSubsystem["Entitlements Engine (pkg/entitlements)"]
Facade["Entitlement Facade\n(CheckEvolveEntitlement, CheckMeshEntitlement, CheckEntitlementBundle)"]
GlobalChecker["Active EntitlementChecker\n(globalChecker interface)"]
CommunityImpl["CommunityChecker\n- Evolve Limit <= 3\n- Mesh Denied\n- Elevated Bundle Denied"]
EnterpriseImpl["EnterpriseChecker\n- Unbounded Evolve\n- Mesh Permitted\n- All Bundles Unlocked"]
Loader["License Loader\n(LoadLicense)"]
end
subgraph LicenseSubsystem["License Cryptography (pkg/license)"]
Validator["Ed25519 License Validator\n(NewValidator, Verify, RequireFeature)"]
Claims["Claims Model\n(Features, RegisteredClaims)"]
end
subgraph StorageAndEnv["License Resolution Sources"]
EnvKey["Environment Variable\n(ZQK_LICENSE_KEY)"]
StateDir["State Directory Token\n(~/.zqk-state/license.jwt)"]
DataDir["Fallback Data Directory Token\n(~/.zqk/license.jwt)"]
EmbeddedKey["Embedded Ed25519 Public Key\n(DefaultPublicKeyHex)"]
end
Callers -->|"Check Limit / Feature"| Facade
Facade -->|"Delegate"| GlobalChecker
GlobalChecker -.->|"Free Tier Default"| CommunityImpl
GlobalChecker -.->|"License Active"| EnterpriseImpl
Loader -->|"Read Key"| EnvKey
Loader -->|"Read File"| StateDir
Loader -->|"Read File (Fallback)"| DataDir
Loader -->|"Verify Signature"| Validator
EmbeddedKey -->|"Public Key"| Validator
Validator -->|"Extract Claims"| Claims
Claims -->|"Populate Features"| EnterpriseImpl
Loader -->|"Register"| GlobalChecker
Component Responsibilities
| Component | Primary API / Types | Architectural Responsibility |
|---|---|---|
| Entitlement Facade | CheckEvolveEntitlement, CheckMeshEntitlement, CheckEntitlementBundle |
Package-level entrypoints delegating checks to the active global checker singleton. |
| EntitlementChecker | EntitlementChecker interface |
Interface defining capability verification contracts (CheckEvolveLimit, CheckMeshEntitlement, CheckBundle). |
| CommunityChecker | CommunityChecker struct |
Free-tier implementation enforcing conservative guardrails (e.g., evolution limit \(\le 3\)) and denying enterprise bundles. |
| EnterpriseChecker | EnterpriseChecker struct |
Commercial-tier implementation providing unbounded autonomous limits and granting access to registered features. |
| License Loader | LoadLicense, RegisterChecker, CurrentCheckerForTest |
Initializes runtime tiers, inspects environment variables and filesystem JWT tokens, and installs the active checker. |
| License Validator | license.Validator, license.Claims |
Cryptographic engine verifying Ed25519-signed JWT tokens without external dependencies or phone-home requests. |
| Elevated Object Guard | RequireElevatedInternal, ShouldSkipInternalKind |
Enforces license-or-admin gating when CLI commands specify --internal access to restricted object kinds. |
3. Entitlement Resolution & License Verification Pipeline
The entitlement resolution lifecycle runs during runtime bootstrap and on-demand whenever privileged operations are requested:
sequenceDiagram
autonumber
actor Caller as CLI / Agent / Swarm
participant Facade as Entitlements Facade
participant Checker as Active Checker
participant Loader as License Loader (LoadLicense)
participant Validator as Ed25519 Validator (pkg/license)
Note over Loader: Initialized during package init()
Loader->>Loader: Check Environment (ZQK_LICENSE_KEY)
alt ZQK_LICENSE_KEY is present
Loader->>Checker: Install EnterpriseChecker (Unbounded)
else No Environment Key
Loader->>Loader: Read ~/.zqk-state/license.jwt
opt File not found in state directory
Loader->>Loader: Read ~/.zqk/license.jwt (Fallback)
end
alt License File Found
Loader->>Validator: Verify(tokenBytes, DefaultPublicKeyHex)
alt Signature Valid & Not Expired
Validator-->>Loader: claims.Features
Loader->>Checker: Install EnterpriseChecker(Features)
else Invalid Signature / Expired / Corrupted
Loader->>Checker: Keep CommunityChecker (Fail Closed)
end
else No License File Found
Loader->>Checker: Keep CommunityChecker (Default)
end
end
Caller->>Facade: CheckEntitlementBundle(ctx, "elevated_object")
Facade->>Checker: CheckBundle(ctx, "elevated_object")
alt Enterprise Tier
Checker-->>Caller: Allow (nil error)
else Community Tier
Checker-->>Caller: Deny (Errfmt: requires Enterprise license)
end
Resolution Logic Steps
- Environment Override: If
ZQK_LICENSE_KEYis present and non-empty in the runtime environment, the loader immediately upgrades the global checker toEnterpriseChecker. - Filesystem Discovery: When no environment key is supplied, the loader queries the primary state path (
$HOME/.zqk-state/license.jwt). If missing, it inspects the backward-compatible fallback location ($HOME/.zqk/license.jwt). - Cryptographic Validation: If a license file is discovered, the embedded Ed25519 public key (
DefaultPublicKeyHex) verifies the token's cryptographic signature and validates expiration timestamps. - Claim Extraction: Upon successful signature verification, granted feature strings (e.g.,
mesh,elevated_object,unbounded_evolve) are extracted intoEnterpriseChecker.Features. - Fail-Closed Fallback: If any verification step fails (file unreadable, invalid Ed25519 hex, signature mismatch, or expired token), the system silently preserves the default
CommunityChecker.
4. Role-Based Access Controls (RBAC) & Capability Matrix
The ZQK platform combines role-based authorization (who is allowed to perform an action) with tier entitlements (what capabilities the runtime environment unlocks).
4.1 Platform Tier Capability Matrix
| Operational Capability | Community Tier (Free Core) | Enterprise Tier (Licensed) | Architectural Enforcement |
|---|---|---|---|
| Core Knowledge Graph CRUD | Unbounded | Unbounded | CAS Storage Plane (pkg/kernel) |
| Object Promotion & DoD Verification | Unbounded | Unbounded | VDS Engine (pkg/vds) |
| Autonomous Refactoring Batch Limit | Maximum 3 candidates per cycle | Unbounded | CheckEvolveLimit(ctx, limit) |
| Autonomous Mesh Networking | Denied | Permitted | CheckMeshEntitlement(ctx) |
Elevated Object Access (--internal) |
Denied (Requires Enterprise) | Permitted | CheckBundle(ctx, "elevated_object") |
| Custom Enterprise Bundles | Denied | Permitted based on Claims | CheckBundle(ctx, bundleName) |
| License Check Phone-Home | Zero (100% Offline) | Zero (100% Offline) | Cryptographic Ed25519 Signature |
4.2 Account Role & Privilege Matrix
Within an authenticated workspace, roles define behavioral boundaries across operations:
| Persona / Role | Core Graph CRUD | Autonomous Refactoring | Mesh Federation | Elevated Object Mutation (--internal) |
Strategic Peer Orchestration |
|---|---|---|---|---|---|
| System Administrator | Allowed | Allowed (Tier-bounded) | Allowed (Tier-bounded) | Allowed (Requires License or admin carrier) | Allowed |
| Lead Orchestrator (Planner) | Allowed | Allowed (Tier-bounded) | Allowed (Tier-bounded) | Denied (Read-only review) | Allowed |
| Craftsman / Worker (Doer) | Allowed | Allowed (Tier-bounded) | Denied | Denied | Denied (POL-AGENT-PLANNER-DOER-001) |
| Auditor / Observer | Read-Only | Denied | Read-Only | Read-Only (Masked) | Denied |
5. Object Elevation Lifecycle
Internal schema objects represent foundational kernel mechanics (e.g., system configuration tables, internal state ledgers, and engine manifests) that must not be exposed to casual listing or unauthorized modification.
sequenceDiagram
autonumber
actor User as Engineer / Agent
participant CLI as CLI Object Command (zqk object list/get)
participant Guard as RequireElevatedInternal
participant Ent as pkg/entitlements
participant Spec as Kind Spec Registry
User->>CLI: zqk object list --internal
CLI->>Guard: RequireElevatedInternal(cmd)
alt Admin Binary Carrier (zqk-admin)
Guard-->>CLI: Pass (Admin Bypass)
else Standard Binary
Guard->>Ent: CheckEntitlementBundle(ctx, "elevated_object")
alt Community Checker (No License)
Ent-->>Guard: Error: elevated object access requires Enterprise
Guard-->>User: Command Terminated with Exit Code 1
else Enterprise Checker (Licensed)
Ent-->>Guard: Success
Guard-->>CLI: Proceed
end
end
CLI->>Spec: Filter Kinds (ShouldSkipInternalKind)
Spec-->>CLI: Include visibility: internal kinds
CLI-->>User: Render Complete Elevated Object Table
Elevation Lifecycle Rules
- Flag Detection: When an operator or agent passes
--internal(defined asFlagElevatedInternal), the CLI triggersElevatedInternalRequested(cmd). - Carrier Exemption: For transitional administrative maintenance, executing under the binary name
zqk-adminpasses without license checks. - Entitlement Verification: In standard builds,
RequireElevatedInternalqueriesCheckEntitlementBundle(ctx, BundleElevatedObject). - Visibility Filtering: When
--internalis active and entitled,ShouldSkipInternalKind(kind, elevated=true)returnsfalse, ensuring internal objects are included in listings and inspect outputs. When omitted or denied, internal kinds are hidden to prevent accidental mutation.
6. Security Invariants & Policy Guarantees
The entitlements subsystem strictly adheres to five core security invariants:
-
Fail-Closed Default Invariant: The package initialization sets
globalChecker = &CommunityChecker{}prior to invokingLoadLicense(). Any failure to parse tokens, decode keys, or verify signatures leaves the runtime inCommunityCheckermode. -
Algorithm Downgrade Defense: The cryptographic license validator enforces
jwt.WithValidMethods([]string{"EdDSA"})and explicitly verifies that the parsed algorithm is*jwt.SigningMethodEd25519. Any attempt to present tokens signed with symmetric HMAC (HS256) or RSA algorithms is rejected immediately. -
Zero Secret Leakage: License keys and tokens are never printed to terminal logs, error messages, or telemetry streams. Error messages explicitly instruct the operator on upgrade remediation without disclosing cryptographic tokens.
-
No Hot-Path Disk Thrashing:
LoadLicense()executes once during runtime initialization. Repeated checks toCheckEvolveEntitlement,CheckMeshEntitlement, orCheckEntitlementBundleevaluate in-memory state in under \(10\mu\text{s}\). -
Open-Core Payload Integrity: All public entitlement interfaces, error messages, and documentation avoid hardcoding studio internal nanosecond IDs or proprietary tracking comments.
7. Best Practices & Operational Patterns
7.1 Automated Workstation Provisioning
For continuous integration (CI) runners or developer workstations entitled to Enterprise features:
# Option A: Inject via environment variable (ideal for containerized CI/CD)
export ZQK_LICENSE_KEY="<cryptographic_jwt_token>"
# Option B: Install license file to user state directory (ideal for developer machines)
mkdir -p "$HOME/.zqk-state"
chmod 700 "$HOME/.zqk-state"
cp license.jwt "$HOME/.zqk-state/license.jwt"
chmod 600 "$HOME/.zqk-state/license.jwt"
7.2 Programmatic Entitlement Checking in Custom Commands
When implementing new CLI commands or kernel extensions that require enterprise capabilities:
package mycommand
import (
"github.com/spf13/cobra"
"github.com/zqk-os/zqk/pkg/entitlements"
"github.com/zqk-os/zqk/pkg/errfmt"
)
func runCustomFederation(cmd *cobra.Command, args []string) error {
ctx := cmd.Context()
// Enforce platform tier requirement
if err := entitlements.CheckMeshEntitlement(ctx); err != nil {
return errfmt.Newf("mesh federation is an Enterprise capability").Wrap(err)
}
// Proceed with privileged operation
return executeFederation()
}
8. Troubleshooting & Diagnostics
| Symptom | Probable Cause | Remediation |
|---|---|---|
community tier is limited to 3 evolution candidates per cycle (requested N) |
A cycle requested more than 3 autonomous refactoring candidates without an active Enterprise license. | Keep evolution candidate batches \(\le 3\) for Community use, or provide a valid Enterprise license via ZQK_LICENSE_KEY or ~/.zqk-state/license.jwt. |
autonomous mesh networking is an Enterprise feature. Please upgrade your license. |
An agent or CLI command attempted to invoke peer mesh federation under the Community tier. | Activate an Enterprise license containing the mesh feature. |
elevated object access (--internal) requires an active subscription or an Enterprise license. |
An operator ran zqk object ... --internal without an active license. |
Ensure a valid license is present in $HOME/.zqk-state/license.jwt or execute using the administrative carrier. |
bundle '<bundle_name>' requires an active subscription or an Enterprise license. |
A requested feature pack or bundle is not entitled in the active runtime. | Verify that the presented JWT claims list the requested bundle in its features array. |
License file present in ~/.zqk-state/license.jwt but system remains in Community tier. |
The license file contains an invalid signature, is expired, or permissions prevent reading. | Run zqk system info or verify the token expiration date. Ensure file permissions allow read access (0600). |
9. Verification & Continuous Quality Compliance
The pkg/entitlements package maintains continuous compliance across all standard verification metrics:
| Verification Dimension | Standard Target | Current Status | Evidence & Verification Command |
|---|---|---|---|
| Statement Test Coverage | \(\ge 85.0\%\) (Target 100.0%) | 100.0% | go test -v -coverprofile=coverage.out ./pkg/entitlements |
| Go Vet Invariants | Zero warnings | PASS | go vet ./pkg/entitlements |
| Code Formatting | Clean gofmt | PASS | gofmt -l ./pkg/entitlements |
| Data Race Freedom | Zero data races | PASS | go test -race ./pkg/entitlements |
| Open-Core Payload Integrity | Zero literal nanosecond IDs | PASS | sh scripts/open-core/check-public-release-payload.sh . |