114 lines
6.5 KiB
Markdown
114 lines
6.5 KiB
Markdown
# Architecture Overview
|
|
|
|
This document describes how the Guildhouse SPIRE plugins integrate SPIFFE workload identity with Guildhouse's governance platform.
|
|
|
|
## System Diagram
|
|
|
|
```
|
|
+----------------------------------------------------------+
|
|
| Kubernetes Cluster |
|
|
| |
|
|
| +--------------------+ +-------------------------+ |
|
|
| | SPIRE Agent | | SPIRE Server | |
|
|
| | | | | |
|
|
| | +----------------+ | | +---------------------+ | |
|
|
| | | oidc-attestor | | | | ssh-credential- | | |
|
|
| | | (WorkloadAttr) | | | | composer (CredComp) | | |
|
|
| | +----------------+ | | +---------------------+ | |
|
|
| | | | | |
|
|
| +--------|-----------+ | +---------------------+ | |
|
|
| | | | governance-notifier | | |
|
|
| | | | (Notifier) | | |
|
|
| | | +---------------------+ | |
|
|
| | | | |
|
|
| +--------v-----------+ | +---------------------+ | |
|
|
| | Workloads | | | substrate-keymanager| | |
|
|
| | (present OIDC | | | (KeyManager) | | |
|
|
| | tokens for | | +---------------------+ | |
|
|
| | attestation) | +------|--------|----------+ |
|
|
| +--------------------+ | | |
|
|
| gRPC | gRPC | |
|
|
| (mTLS) | | (mTLS) |
|
|
| +-----------------------------+ | +------------------+
|
|
| | Quartermaster |<--+ | Bascule |
|
|
| | | | |
|
|
| | - GovernanceService | | - CeremonyServ |
|
|
| | (MutationIntents) | | (multi-party |
|
|
| | - NotaryService | | approval) |
|
|
| | (Merkle anchoring) | | |
|
|
| +-----------------------------+ +------------------+
|
|
+----------------------------------------------------------+
|
|
```
|
|
|
|
## Components
|
|
|
|
### SPIRE Agent Plugins
|
|
|
|
**oidc-attestor** (WorkloadAttestor) runs inside the SPIRE Agent. When a workload calls the Workload API to request an SVID, the agent invokes oidc-attestor to identify the workload. The plugin discovers an OIDC token from the workload's environment (file path or environment variable), verifies it against a JWKS endpoint, and returns selectors derived from token claims.
|
|
|
|
### SPIRE Server Plugins
|
|
|
|
Three plugins run inside the SPIRE Server:
|
|
|
|
- **ssh-credential-composer** (CredentialComposer) intercepts credential minting. When the server issues an SSH SVID, this plugin encodes Shellstream extensions into the SSH certificate's critical options, embedding governance metadata (intent ID, ceremony outcome, SAT hash) into the cert itself.
|
|
|
|
- **governance-notifier** (Notifier) receives SPIRE lifecycle events (bundle updates, registration entry changes, SVID rotations). On relevant events, it calls GovernanceService to create or update MutationIntents, and may trigger CeremonyService flows for operations requiring multi-stakeholder approval.
|
|
|
|
- **substrate-keymanager** (KeyManager) manages the signing keys used by the SPIRE Server. It stores key material with governance-aware lifecycle management, ensuring key rotations are captured as auditable intents.
|
|
|
|
## Guildhouse gRPC Services
|
|
|
|
All plugin-to-service communication uses mTLS via SPIFFE SVIDs. The plugins themselves hold SPIFFE identities and authenticate to Guildhouse services through mutual TLS.
|
|
|
|
| Service | Package | Plugin Consumers |
|
|
|---------|---------|-----------------|
|
|
| GovernanceService | `quartermaster.v1` | governance-notifier, ssh-credential-composer |
|
|
| NotaryService | `quartermaster.v1` | governance-notifier, ssh-credential-composer |
|
|
| CeremonyService | `bascule.v1` | governance-notifier |
|
|
|
|
## Data Flow: SSH Certificate Issuance
|
|
|
|
1. A workload calls the SPIRE Workload API requesting an SSH SVID.
|
|
2. The SPIRE Agent invokes **oidc-attestor**, which discovers and verifies the workload's OIDC token and returns selectors.
|
|
3. The agent matches selectors against registration entries and forwards the request to the SPIRE Server.
|
|
4. The server invokes **ssh-credential-composer** during credential minting.
|
|
5. The composer calls **GovernanceService.CreateIntent** to record the SSH cert issuance as a MutationIntent.
|
|
6. If the intent requires approval, **CeremonyService.CreateCeremony** is called and the flow blocks until approval.
|
|
7. The composer constructs a MutationEnvelope (RFC 8785 JCS canonicalization, domain-separated SHA-256 hash), which becomes a merkle leaf.
|
|
8. **NotaryService.CreateAnchor** anchors the envelope hash into the merkle tree.
|
|
9. The composer encodes Shellstream extensions into the SSH certificate's critical options (intent ID, SAT hash, ceremony result).
|
|
10. The signed SSH certificate is returned to the workload through the agent.
|
|
|
|
## Package Map
|
|
|
|
```
|
|
guildhouse-spire-plugins/
|
|
cmd/
|
|
oidc-attestor/ # WorkloadAttestor plugin binary
|
|
ssh-credential-composer/ # CredentialComposer plugin binary
|
|
governance-notifier/ # Notifier plugin binary
|
|
substrate-keymanager/ # KeyManager plugin binary
|
|
pkg/
|
|
shellstream/ # Encode/decode SSH cert Shellstream extensions
|
|
oidc/ # OIDC token discovery and verification
|
|
governance/ # GovernanceService + CeremonyService client
|
|
sshcert/ # SSH certificate construction helpers
|
|
config/ # Shared plugin configuration loading
|
|
proto/
|
|
quartermaster/v1/ # governance.proto, notary.proto, credentials.proto
|
|
bascule/v1/ # ceremony.proto
|
|
specs/ # Formal specifications (read-only reference)
|
|
deploy/ # Kubernetes manifests and Helm values
|
|
test/ # Integration tests and fixtures
|
|
```
|
|
|
|
## Proto Dependencies
|
|
|
|
| Proto File | Service | Package |
|
|
|-----------|---------|---------|
|
|
| `governance.proto` | GovernanceService | `quartermaster.v1` |
|
|
| `notary.proto` | NotaryService | `quartermaster.v1` |
|
|
| `credentials.proto` | Credential types | `quartermaster.v1` |
|
|
| `ceremony.proto` | CeremonyService | `bascule.v1` |
|
|
|
|
Generated Go code from these protos lives alongside the `.proto` files or in a generated output directory. The `pkg/governance` package wraps the raw gRPC stubs with higher-level client logic (retries, circuit breaking, intent lifecycle management).
|