CLI Tray Subsystem Architectural Guide
Comprehensive architectural, operational, and security guide for the CLI Tray subsystem within the ZQK Knowledge Kernel.
1. Architectural Overview & Design Principles
The ZQK Tray Subsystem provides a secure, deterministic veneer layer bridging desktop environments (operating system menu bars, desktop task trays, notification area widgets, and custom developer shortcuts) with ZQK Knowledge Kernel capabilities. Rather than exposing raw shell execution hooks or untracked aliases, the tray subsystem introduces an objectified, schema-validated command manifest coupled with ECDSA P-256 cryptographic signing and fail-closed argument authorization.
flowchart TD
subgraph Client["Desktop & Operator Entry Points"]
OSMenu["OS Menu Bar / Status Bar Widget"]
DevHarness["Developer / Operator CLI"]
end
subgraph TrayCLI["zqk tray Subsystem"]
CmdList["zqk tray list"]
CmdShow["zqk tray show"]
CmdExplain["zqk tray explain"]
CmdRun["zqk tray run"]
CmdSign["zqk tray sign"]
end
subgraph ManifestLayer["Entry Manifest Hierarchy"]
EmbeddedDefaults["In-Memory Embedded Defaults (intake, whats-next, ...)"]
ProjectManifest[".zqk/tray.yaml (Project-Specific Overrides & Additions)"]
end
subgraph SecurityBoundary["Cryptographic Security Boundary"]
PrivilegeFilter["Privilege & Destructive Verb Filter (IsPrivilegedArgv)"]
SmugglingGuard["Runtime Appended Argument Smuggling Guard"]
Keystore[".zqk/keystore/auditor.pub / auditor.priv"]
SignatureVerifier["ECDSA P-256 ASN.1 Signature Verifier"]
end
subgraph ExecutionLayer["Subprocess Execution & Environment Isolation"]
EnvWiring["zqkenv Isolation Wiring (ZQK_EXEC_SOURCE=tray)"]
SubprocessExec["Subprocess Dispatcher (execwrap.CommandContext)"]
end
OSMenu -->|triggers action| CmdRun
DevHarness --> TrayCLI
CmdList --> ManifestLayer
CmdShow --> ManifestLayer
CmdExplain --> ManifestLayer
CmdSign --> Keystore
CmdSign --> ProjectManifest
CmdRun --> ManifestLayer
CmdRun --> PrivilegeFilter
PrivilegeFilter -->|safe entry| ExecutionLayer
PrivilegeFilter -->|privileged entry| SmugglingGuard
SmugglingGuard -->|appended flags clean| SignatureVerifier
SignatureVerifier -->|signature valid| ExecutionLayer
SignatureVerifier -->|invalid / unsigned| AccessDenied["Fail-Closed Access Denied"]
SmugglingGuard -->|smuggled restricted flag| AccessDenied
ExecutionLayer --> EnvWiring
EnvWiring --> SubprocessExec
Core Design Principles
- Veneer Decoupling: Tray actions are structured command-line argument lists (
Argv: []string{"workflow", "whats-next"}) targeting the same binary, ensuring consistent CLI argument parsing and error formatting without bypassing the core CLI router. - Layered Manifest Hierarchy: Embedded in-memory defaults guarantee operational readiness on zero-configuration installations, while
.zqk/tray.yamlenables projects to customize or extend the catalog. - Cryptographic Provenance: Indirect desktop execution of privileged or destructive operations (
system purge,object delete,--override,--force) is prohibited unless cryptographically signed by an auditor private key. - Smuggling Invariant: Runtime arguments appended after a tray entry name are evaluated through the privilege filter; appended restricted flags cannot piggyback on a pre-signed safe entry.
- Fail-Closed Verification: Any signature mismatch, missing auditor key, or YAML tampering immediately halts dispatch with an access denial error.
2. Subsystem Command Taxonomy
The zqk tray command group exposes five distinct operations:
| Command | Syntax | Primary Role |
|---|---|---|
list |
zqk tray list [-f table\|json\|yaml] |
Enumerate available tray entries and descriptions. |
show |
zqk tray show <name> [-f table\|json\|yaml] |
Inspect an individual entry's definition and argv array. |
explain |
zqk tray explain <name> [-f table\|json\|yaml] |
Format the shell-escaped command invocation line. |
run |
zqk tray run <name> [args...] [--dry-run] |
Execute or preview the command referenced by the entry. |
sign |
zqk tray sign <name> [--key-path <path>] |
Cryptographically sign a privileged entry in .zqk/tray.yaml. |
2.1 zqk tray list
Queries the merged manifest catalog (embedded defaults plus .zqk/tray.yaml) and displays available actions:
# Human-readable tabular listing
zqk tray list
# Machine-readable JSON output for menu bar widgets
zqk tray list -f json
Example JSON output:
{
"entries": [
{
"name": "intake",
"description": "Interactive workflow intake for new work or inquiries"
},
{
"name": "whats-next",
"description": "Print next recommended workflow action"
}
],
"meta": {
"count": 2,
"project_root": "/workspace"
}
}
2.2 zqk tray show
Inspects the raw entry specification, including its resolved argv array:
zqk tray show whats-next
Example output:
argv:
- workflow
- whats-next
description: Print next recommended workflow action
name: whats-next
project_root: /workspace
2.3 zqk tray explain
Constructs and displays the exact shell invocation string that run executes, accounting for binary resolution:
zqk tray explain intake
Output:
intake: zqk workflow intake
2.4 zqk tray run
Dispatches execution of the entry's argv through the current executable.
# Preview execution without spawning subprocess
zqk tray run whats-next --dry-run
# Execute with additional runtime arguments
zqk tray run whats-next -- -f json
Dry-run mode outputs diagnostic telemetry:
{
"argv": ["workflow", "whats-next"],
"binary": "zqk",
"command_line": "zqk workflow whats-next",
"dry_run": true,
"entry": "whats-next",
"project_root": "/workspace"
}
2.5 zqk tray sign
Signs an entry inside .zqk/tray.yaml using an ECDSA P-256 auditor private key, updating signature and signed_by:
# Sign using default project keystore key (.zqk/keystore/auditor.priv)
zqk tray sign purge-cache
# Sign using custom key path
zqk tray sign purge-cache --key-path .zqk/keystore/custom_auditor.priv
3. Entry Manifest Hierarchy & Schema
Tray configuration resolves via a two-layer hierarchy:
+-------------------------------------------------------------+
| Layer 1: Embedded Defaults (pkg/tray/embedded.go) |
| - intake: zqk workflow intake |
| - whats-next: zqk workflow whats-next |
+-------------------------------------------------------------+
|
v (overridden and extended by)
+-------------------------------------------------------------+
| Layer 2: Project Manifest (.zqk/tray.yaml) |
| - custom-task: zqk test run ... |
| - purge-cache: zqk cache clear --force (signed) |
+-------------------------------------------------------------+
Manifest Schema (.zqk/tray.yaml)
$schema: "https://zqk.dev/schemas/tray_config.schema.json"
version: 1
entries:
- name: "custom-verification"
description: "Run verification test suite"
argv:
- "test"
- "run"
- "--suite"
- "hygiene"
- name: "purge-cache"
description: "Force clear local build cache"
argv:
- "cache"
- "clear"
- "--force"
signed_by: "ACC-COMMUNITY-001"
signature: "3045022100...0220..."
4. Cryptographic Security Model & Verification Invariants
Desktop tray shortcuts present a unique security challenge: users frequently click menu items expecting routine utility, but actions execute with local user privileges. Malicious repository configurations or compromised settings could define destructive actions disguised as innocuous shortcuts.
4.1 Privilege Detection (IsPrivilegedArgv)
The subsystem classifies argv slices as privileged if they contain:
- Restricted Flags:
--override,--force,--clear-cache,--internal - Destructive Verbs:
object deletesystem shutdownsystem purgeio reap
4.2 Fail-Closed Authorization Pipeline
sequenceDiagram
participant Caller as Operator / Tray UI
participant TrayRun as zqk tray run
participant Security as Security Boundary
participant Keystore as Auditor Keystore
participant Exec as Subprocess Runner
Caller->>TrayRun: run <entry> [extra_args...]
TrayRun->>Security: IsPrivilegedArgv(entry.Argv + extra_args)
alt Argv contains no privileged tokens
Security-->>TrayRun: Safe (No signature required)
TrayRun->>Exec: Dispatch subprocess
else Argv contains privileged tokens
Security->>Security: Check extra_args for restricted tokens
alt extra_args contains smuggled token
Security-->>Caller: 403 Access Denied (Smuggled argument rejected)
else extra_args is clean
TrayRun->>Security: Check entry.Signature
alt entry.Signature is empty
Security-->>Caller: 403 Access Denied (Unsigned privileged entry)
else entry.Signature present
TrayRun->>Keystore: resolveAuditorPublicKey(projectRoot)
Keystore-->>Security: Return auditor public key (hex)
Security->>Security: VerifyEntry(entry, pubHex)
alt Signature valid
Security-->>TrayRun: Authorized
TrayRun->>Exec: Dispatch subprocess
else Signature invalid / tampered
Security-->>Caller: 403 Access Denied (Signature mismatch)
end
end
end
end
4.3 Digital Signatures (ECDSA P-256 ASN.1)
- Digest Calculation: A canonical SHA-256 digest is computed across the entry name and each argv element via
traypkg.ComputeArgvDigest(name, argv). - Signature Creation: The digest is signed using
ecdsa.SignASN1with the auditor's P-256 private key. The resulting ASN.1 DER sequence is hex-encoded intoentry.Signature. - Attribution: The signing identity (
qa.AuditorAccountIDor active context security principal) is recorded inentry.SignedBy.
4.4 Verification Without Private Keys
Production workstations, CI runners, and menu bar harnesses rarely hold private signing keys. The verification logic in resolveAuditorPublicKey:
- Prefers
.zqk/keystore/auditor.pub(supports both PKIX PEM and raw uncompressed hex strings). - Falls back to reading the public component of
.zqk/keystore/auditor.privif present on administrative workstations. - Never generates keys during verification: Verifying signatures is strictly read-only and never writes unauthenticated key material to disk.
4.5 Smuggling Prevention Invariant
Even if an entry is signed, operators may pass appended arguments:
zqk tray run safe-entry -- --override
The tray engine independently checks args[1:]. If appended runtime arguments introduce restricted flags or destructive verbs, execution halts immediately:
access denied: appended arguments to tray entry "safe-entry" contain restricted flag/command (--override)
5. Execution Environment & Process Isolation
When an action is authorized, zqk tray run configures and executes the child process:
- Binary Continuity: Spawns
os.Args[0], ensuring the child process runs with the identical binary version and build metadata. - Project Isolation: Invokes
zqkenv.WireExecForIsolatedProject(cmd, projectRoot)to establish consistent working directories and project settings. - Provenance Tracing: Appends
ZQK_EXEC_SOURCE=trayto the environment block, allowing internal observability layers to identify tray-originated invocations. - Standard Stream Coupling: Transparently connects standard input, output, and error streams for interactive subcommands.
- Exit Code Propagation: Distinguishes process spawn failures from non-zero exit codes returned by the underlying command:
tray run: subprocess exited with code 42
6. Verification & Statement Coverage Invariant
The CLI tray subsystem is subject to a strict >=95.0% statement coverage done-gate invariant across cmd/zqk/tray.
Coverage Breakdown
| Source Component | Statement Coverage | Invariant Standard |
|---|---|---|
cmd/zqk/tray/tray.go (Command & Veneer Layer) |
98.3% | >= 95.0% |
pkg/tray (Core Manifest & Cryptographic Engine) |
96.5% | >= 95.0% |
Running the Subsystem Test Suite
To verify the tray package and its test coverage:
# Run tray subsystem tests with coverage profile (bounded 30s timeout)
go test -v -timeout 30s -cover ./cmd/zqk/tray
Verified Failure Modes & Boundary Protections
The comprehensive test suite verifies:
- Context resolution failure when CLI initialization context is omitted.
- Graceful recovery and root discovery when project roots are unresolvable.
- Schema and YAML syntax error propagation on corrupted
.zqk/tray.yamlmanifests. - Missing entry error reporting with suggested discovery commands (
see: zqk tray list). - Type-mismatched flag parsing defense on
--dry-runand--key-path. - Rejection of tampered signatures where
argvwas altered after signing. - Rejection of signatures signed by unauthorized or mismatched auditor keys.
- Accurate capture of subprocess exit statuses (
ExitCode()). - Generation and persistence of public keys (
auditor.pub) alongside newly generated private keys. - Read-only filesystem fail-closed behavior when writing updated signatures.
7. Illustrative Traceability & Entity Relationship Model
To illustrate proper integration with the Knowledge Kernel while respecting clean, non-prohibited namespace conventions:
| Entity Kind | Clean Illustrative Identifier | Role in Tray Lifecycle |
|---|---|---|
requirement |
REQ-TRAY-001 |
Specification for CLI desktop veneer, shortcut discovery, and cryptographic authorization |
tray_entry |
TRY-DEMO-001 |
Named shortcut entry (demo-task) expanding to ["workflow", "whats-next"] |
account |
ACC-COMMUNITY-001 |
Auditor identity used to sign privileged tray actions (signed_by) |
criteria |
CRIT-TRAY-001 |
Static statement coverage invariant (>= 95.0%) for cmd/zqk/tray |
test_case |
TST-TRAY-001 |
Unified verification group executing full tray CLI test suite |