feat: gsh governed shell — design exploration
DESIGN.md: complete architecture exploration for gsh,
the GCAP governed shell binary.
Two modes:
Machine: headless JSON I/O, GSAP AC consumption,
CR posting, exit code governance mapping.
Auto-detected: no TTY → machine mode.
What SK plugin and Logic Apps need now.
Human: interactive, [governed] prompt,
inline elevation, session-level AC.
What Sam needs for daily ops.
Architecture: gsh binary + libgsh library.
common/: AC validation, CR posting, Chronicle env.
machine/: headless executor.
human/: reedline shell, prompt, interceptor.
6 open design questions documented.
MVP: machine mode first (~200 lines Rust).
Before building: resolve Q2 (session vs per-command AC)
and Q6 (full shell vs bash wrapper).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tyler J King
parent
6833d34e68
commit
3a2ed1ed42
1 changed files with 232 additions and 0 deletions
232
DESIGN.md
Normal file
232
DESIGN.md
Normal file
|
|
@ -0,0 +1,232 @@
|
||||||
|
# gsh — GCAP Governed Shell
|
||||||
|
|
||||||
|
## Design Exploration
|
||||||
|
|
||||||
|
**Status:** Exploration (pre-build)
|
||||||
|
**Spec:** GCAP-SPEC-SHELLBOUND-BROKER-0001 (Layer 3)
|
||||||
|
**Language:** Rust
|
||||||
|
**License:** Apache 2.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What gsh is
|
||||||
|
|
||||||
|
gsh is the binary that makes GCAP tangible. Everything else in the stack — Chronicle, GSAP brokers, connectors, functions, specs — is infrastructure for the moment an operator types into gsh or an AI agent invokes it.
|
||||||
|
|
||||||
|
Two modes. Same governance logic. Different UX.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mode 1: Machine (headless, GSAP-governed)
|
||||||
|
|
||||||
|
**Invoked by:** `gsh --exec "command"` or piped JSON on stdin
|
||||||
|
**Who uses it:** AI agents (SK plugin), CI/CD, Logic Apps, bxnet-ops
|
||||||
|
**Auto-detected:** No TTY → machine mode automatically
|
||||||
|
|
||||||
|
### Protocol
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Read GSAP_AC from env var or --ac flag.
|
||||||
|
The AC was issued by the broker BEFORE gsh was invoked.
|
||||||
|
gsh does not request ACs. The caller does.
|
||||||
|
This separation is intentional:
|
||||||
|
SK plugin requests AC → gsh consumes it → gsh posts CR.
|
||||||
|
|
||||||
|
2. Validate AC:
|
||||||
|
R-22: single-use (filesystem registry)
|
||||||
|
R-23: corpus_entry_cid matches installed version
|
||||||
|
R-24: parameters_cid matches input
|
||||||
|
|
||||||
|
3. exec(sh, -c, command)
|
||||||
|
Capture stdout, stderr, exit code.
|
||||||
|
Read Chronicle env vars from eBPF companion:
|
||||||
|
CHRONICLE_SESSION_ID
|
||||||
|
CHRONICLE_BEHAVIOR_STATE
|
||||||
|
CHRONICLE_MERKLE_ROOT
|
||||||
|
|
||||||
|
4. Post CR to broker.
|
||||||
|
outcome: completed (exit 0) | failed (exit != 0)
|
||||||
|
Include Chronicle evidence from env.
|
||||||
|
|
||||||
|
5. Print JSON to stdout:
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"exit_code": 0,
|
||||||
|
"output": "...",
|
||||||
|
"lineage_cid": "sha256:...",
|
||||||
|
"session_url": "https://broker/governance/session/{ctx}/"
|
||||||
|
}
|
||||||
|
|
||||||
|
6. Exit with mapped code:
|
||||||
|
0 = success (CR: completed)
|
||||||
|
1 = execution failure (CR: failed)
|
||||||
|
2 = authorization failure (no valid AC)
|
||||||
|
3 = governance violation (CR: violated)
|
||||||
|
4 = broker unavailable (self-auth fallback)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why machine mode first
|
||||||
|
|
||||||
|
The SK plugin needs it now. Logic Apps needs it now. CI/CD needs it now. Sam needs human mode — but Sam already has bxnet-ops for daily playbook runs. Machine mode is the unblocked path to the AI agent demo.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mode 2: Human (interactive, TTY-attached)
|
||||||
|
|
||||||
|
**Invoked by:** `gsh` (no arguments, TTY detected)
|
||||||
|
**Who uses it:** Sam, operators, developers
|
||||||
|
**Feel:** bash with governance awareness
|
||||||
|
|
||||||
|
### The prompt
|
||||||
|
|
||||||
|
```
|
||||||
|
[governed] sam@ffc.guildhouse.dev:~$
|
||||||
|
```
|
||||||
|
|
||||||
|
Governance states:
|
||||||
|
- `[governed]` — Active accord. Chronicle live. Green.
|
||||||
|
- `[elevated]` — PIM/elevation active. Yellow.
|
||||||
|
- `[ungoverned]` — No broker configured. Yellow warning.
|
||||||
|
- `[violated]` — eBPF detected violation. Red.
|
||||||
|
|
||||||
|
### Session lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Shell starts. Reads GSAP_BROKER_URL.
|
||||||
|
2. If broker: authenticate, establish session accord, Chronicle SESSION_STARTED.
|
||||||
|
3. If no broker: yellow banner, ungoverned mode, still works.
|
||||||
|
4. Operator types commands.
|
||||||
|
5. Some commands need elevation → inline prompt.
|
||||||
|
6. On exit: Chronicle SESSION_ENDED.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Command categorization (not every command is governed)
|
||||||
|
|
||||||
|
**Free commands** — ls, cat, echo, grep, cd, pwd.
|
||||||
|
No governance overhead. No Chronicle. Standard POSIX.
|
||||||
|
|
||||||
|
**Observed commands** — file writes, network connections matching declared endpoints.
|
||||||
|
Chronicle records but does not gate. Passive lineage.
|
||||||
|
|
||||||
|
**Governed commands** — playbook patterns, infrastructure mutations, privileged ops.
|
||||||
|
AC required before exec. CR posted after. Full GSAP cycle.
|
||||||
|
|
||||||
|
The determination is made by the session's accord template. The accord IS the shell policy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
gsh (binary crate)
|
||||||
|
├── main.rs — mode detection, CLI
|
||||||
|
├── machine/
|
||||||
|
│ ├── mod.rs — machine mode entry
|
||||||
|
│ ├── ac.rs — AC validation (R-22/23/24)
|
||||||
|
│ ├── exec.rs — command execution + capture
|
||||||
|
│ └── cr.rs — CR posting
|
||||||
|
├── human/
|
||||||
|
│ ├── mod.rs — human mode entry
|
||||||
|
│ ├── shell.rs — reedline loop
|
||||||
|
│ ├── prompt.rs — [governed] prompt
|
||||||
|
│ └── intercept.rs — command categorization
|
||||||
|
└── common/
|
||||||
|
├── mod.rs
|
||||||
|
├── chronicle.rs — eBPF env reader
|
||||||
|
├── accord.rs — policy enforcement
|
||||||
|
└── gsap.rs — AC/CR types + HTTP client
|
||||||
|
|
||||||
|
libgsh (library crate) — extracted later
|
||||||
|
The governance logic. No UX. No I/O.
|
||||||
|
Designed for extraction to a reusable library.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Relationship to bxnet-ops
|
||||||
|
|
||||||
|
bxnet-ops has `gsap_client.rs` with AC validation and CR posting. gsh extracts this into a standalone binary. The `gsap_client` module becomes `common/gsap.rs` in gsh. bxnet-ops can eventually depend on libgsh instead of maintaining its own GSAP client.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Open Design Questions
|
||||||
|
|
||||||
|
### Q1: Command categorization strategy
|
||||||
|
How does the shell determine which commands are governed?
|
||||||
|
- Option A: Regex patterns in the accord (e.g. `ansible-playbook.*` → governed).
|
||||||
|
- Option B: Binary whitelist in corpus map (only corpus binaries are governed).
|
||||||
|
- Option C: Heuristic based on capability_mask + endpoint declarations.
|
||||||
|
**Leaning:** B for strict mode, C for permissive mode. Accord chooses.
|
||||||
|
|
||||||
|
### Q2: Session-level vs per-command AC
|
||||||
|
Does the operator get one AC for the whole session, or one per governed command?
|
||||||
|
- Session AC: faster UX, one auth for N commands. Risk: over-authorization.
|
||||||
|
- Per-command AC: precise, each command separately authorized. Risk: slow for interactive.
|
||||||
|
**Leaning:** Session AC for human mode (bound by session TTL). Per-command for machine mode (caller provides AC per invocation). Different modes, different answers.
|
||||||
|
|
||||||
|
### Q3: Pipeline governance
|
||||||
|
When the operator runs `cmd1 | cmd2 | cmd3`, which is governed?
|
||||||
|
- Option A: The pipeline as a whole (one AC for the pipeline).
|
||||||
|
- Option B: Each command individually (three ACs).
|
||||||
|
- Option C: Only the first command (the rest inherit the session).
|
||||||
|
**Leaning:** C. The pipeline is one operation. The first command is the intent.
|
||||||
|
|
||||||
|
### Q4: Accord policy storage
|
||||||
|
Where does gsh read the accord policy?
|
||||||
|
- Option A: From the AC itself (the broker embeds it).
|
||||||
|
- Option B: From a local policy file (fetched at session start).
|
||||||
|
- Option C: From a K8s ConfigMap / environment variable.
|
||||||
|
**Leaning:** A. The AC already carries accord_template. gsh resolves the template to a policy at session start. The broker is authoritative for what the accord means.
|
||||||
|
|
||||||
|
### Q5: Long-running command AC expiry
|
||||||
|
If a command takes 2 hours but the AC expires in 30 minutes?
|
||||||
|
- Option A: AC expiry kills the command.
|
||||||
|
- Option B: AC expiry flags but doesn't kill (CR records the overage).
|
||||||
|
- Option C: gsh requests AC extension from broker mid-execution.
|
||||||
|
**Leaning:** B. Don't kill running infra operations. Record the overage. The CR is honest.
|
||||||
|
|
||||||
|
### Q6: Full shell vs bash wrapper
|
||||||
|
Is gsh a full shell implementation or a wrapper around bash?
|
||||||
|
- Full shell: custom parser, built-in command set. Maximum control. Massive scope.
|
||||||
|
- Bash wrapper: exec(bash) with eBPF + GSAP wrapping. Minimal scope. Less control.
|
||||||
|
**Leaning:** Bash wrapper for MVP. Full shell is a multi-year project. The governance logic is the value, not the shell parser. bash is the shell. gsh is the governance layer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MVP Scope (machine mode first)
|
||||||
|
|
||||||
|
~200 lines of Rust. One week.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gsh --exec "ansible-playbook site.yml"
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Read `GSAP_AC` from environment (JSON or base64).
|
||||||
|
2. Validate AC (corpus CID, params CID, single-use).
|
||||||
|
3. `exec(sh, -c, command)`.
|
||||||
|
4. Capture stdout/stderr/exit code.
|
||||||
|
5. Post CR to broker.
|
||||||
|
6. Print JSON to stdout.
|
||||||
|
7. Exit with mapped code.
|
||||||
|
|
||||||
|
Human mode builds on top. Same governance logic. Different UX layer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The billing drain connection
|
||||||
|
|
||||||
|
```
|
||||||
|
gsh --exec → CR posted → lineage_cid in JSON
|
||||||
|
↓
|
||||||
|
SK plugin reads lineage_cid
|
||||||
|
↓
|
||||||
|
Chronicle: GSAP_CR_RECEIVED
|
||||||
|
↓
|
||||||
|
FunctionRuntime.dispatch("GSAP_CR_RECEIVED")
|
||||||
|
↓
|
||||||
|
BillingProcessor.handle()
|
||||||
|
↓
|
||||||
|
Invoice line item with Chronicle CID
|
||||||
|
↓
|
||||||
|
Auditor: the invoice IS the governance proof
|
||||||
|
```
|
||||||
|
|
||||||
|
This is the complete chain from operator keystroke to auditable invoice.
|
||||||
Loading…
Reference in a new issue