From 6321037ac1e772eb9316a5461ef80fb1a55f0e77d16a0d3d5cec9aace7a3325b Mon Sep 17 00:00:00 2001 From: Tyler King Date: Thu, 26 Feb 2026 19:38:13 -0500 Subject: [PATCH] Add network-policy extension and network governance lifecycle events MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New shellstream extension §10.6 network-policy@guildhouse.dev carrying GovernedNetworkPolicy hash in SSH certificates. New §8.7 in upper layers spec documenting network governance lifecycle events (attach, detach, flow policy, route announce/withdraw) emitted by governance-notifier using the tiered consent transport model. Co-Authored-By: Claude Opus 4.6 --- docs/shellstream-spec-0001-upper-layers.md | 18 +++++++++- specs/shellstream-extensions.md | 39 ++++++++++++++++++++++ 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/shellstream-spec-0001-upper-layers.md b/docs/shellstream-spec-0001-upper-layers.md index 4749cfb..61dc82d 100644 --- a/docs/shellstream-spec-0001-upper-layers.md +++ b/docs/shellstream-spec-0001-upper-layers.md @@ -988,7 +988,23 @@ Shellstream sessions originating from HFL modules carry the module's attenuated **Consent channel negotiation at session establishment.** When an SSP session (L2) is established, the server MAY advertise available consent channels via the `consent-channels@guildhouse.dev` SSH certificate extension ([Shellstream Extensions](../../guildhouse-spire-plugins/specs/shellstream-extensions.md)). Client modules use this information to determine which consent transport tier is available (see [GH-DESIGN-0005 §5](../../guildhouse-platform/docs/GH-DESIGN-0005-wasm-component-model.md)). The formal WIT interface for consent is defined in `substrate:consent@0.1.0`. -**WIT as the formal contract.** The HFL's host function signatures are defined in WIT (WebAssembly Interface Types). Three packages — `substrate:governance`, `substrate:identity`, `substrate:consent` — capture the governance-layer abstractions. Standard Component Model toolchains can target these interfaces, making HFL modules portable across hosts that implement the same WIT packages. +**WIT as the formal contract.** The HFL's host function signatures are defined in WIT (WebAssembly Interface Types). Four packages — `substrate:governance`, `substrate:identity`, `substrate:consent`, `substrate:network` — capture the governance-layer abstractions. Standard Component Model toolchains can target these interfaces, making HFL modules portable across hosts that implement the same WIT packages. + +### 8.7. Network Governance Lifecycle Events + +The `governance-notifier` SPIRE plugin emits network lifecycle events alongside credential lifecycle events. These events use the same tiered transport model described in [GH-DESIGN-0005 §5](../../guildhouse-platform/docs/GH-DESIGN-0005-wasm-component-model.md) (Tier 0–3 consent channels): + +| Event | Trigger | Notarized | +|-------|---------|-----------| +| Workload attached to network | Kedge `CNI ADD` → `substrate:network/workload-network.attach-workload` | Yes | +| Workload detached from network | Kedge `CNI DEL` → `substrate:network/workload-network.detach-workload` | Yes | +| Flow policy installed/updated | `substrate:network/firewall.install-flow-policy` | Yes | +| Route announced | `substrate:network/routing.announce-route` | Yes | +| Route withdrawn | `substrate:network/routing.withdraw-route` | Yes | + +On vanilla Linux without Pulsar (Tier 0–1), network events go to local store-and-forward queues. On full deployments with message queue fabric (Tier 2), they publish to governed Pulsar topics. The transport tier is determined by the host's `HostCapabilities.consent_channels` in the SAT (SAT-SPEC-0001 §3.9). + +Network lifecycle events follow the same `MutationEnvelope` format as credential events (see [Credential Governance](../specs/credential-governance.md)): each event is wrapped in an envelope, canonicalized via RFC 8785 JCS, and anchored in the Quartermaster merkle tree via `NotaryService.CreateAnchor`. --- diff --git a/specs/shellstream-extensions.md b/specs/shellstream-extensions.md index 9fca5ea..f5fa4f6 100644 --- a/specs/shellstream-extensions.md +++ b/specs/shellstream-extensions.md @@ -533,6 +533,45 @@ consent-channels@guildhouse.dev = local-tty,unix-socket,http-webhook consent-channels@guildhouse.dev = local-tty ``` +### 10.6 `network-policy@guildhouse.dev` + +**Presence:** OPTIONAL. + +**Value:** SHA-256 hash (lowercase hexadecimal, exactly 64 characters) of the +GovernedNetworkPolicy applied to this workload. The hash is computed over the +canonical (RFC 8785 JCS) JSON serialization of the policy object. + +This extension binds network governance policy to workload identity through +the SPIRE credential chain. The `ssh-credential-composer` embeds the policy +hash when SPIRE issues an SVID for a pod. At CNI ADD time, Kedge reads the +policy hash from the workload's SVID and passes it to the host function layer +via `substrate:network/workload-network.attach-workload()` in the +`governance-context` field. The host function layer resolves the hash to a +full GovernedNetworkPolicy and installs identity-based flow rules in the eBPF +enforcement plane. + +The trust chain: + +1. SPIRE attests workload identity +2. `ssh-credential-composer` embeds `network-policy@guildhouse.dev` hash +3. Kedge CNI reads the hash during `CNI ADD` +4. `substrate:network` WIT host functions install governed flow policy +5. eBPF in the VPP processing graph enforces at wire speed +6. `governance-notifier` records the network attach event in Chronicle + +See [GH-DESIGN-0005 §11](../../guildhouse-platform/docs/GH-DESIGN-0005-wasm-component-model.md) +for the GovernedNetworkPolicy schema and the network-as-API model. + +**Example:** +``` +network-policy@guildhouse.dev = a1b2c3d4e5f6...64 hex chars... +``` + +**Co-occurrence:** This extension MAY appear alongside `sat-hash@guildhouse.dev`. +When both are present, the SAT's `HostCapabilities.wit_packages` SHOULD include +`substrate:network@0.1` to indicate that the host supports network governance +host functions. + ## 11. References - **OpenSSH PROTOCOL.certkeys** -- OpenSSH certificate format and