Tyler King
a58d548518
- Network-policy SPIRE plugin extension - Governance event notification with merkle anchoring - Shellstream specs for consent channels + HFL embedded ABI - All 17 audit findings from AUDIT.md remediated - SSH credential composer + substrate key manager updates - Test coverage for config + sshcert packages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# Guildhouse SPIRE Plugins
|
|
|
|
SPIRE plugins and specifications for governed SSH access via SPIFFE identity.
|
|
|
|
This repository extends the [SPIFFE](https://spiffe.io/) ecosystem with SSH certificate
|
|
issuance, governance-aware credential lifecycle management, and Guildhouse platform integration.
|
|
|
|
## Project Status
|
|
|
|
**Stage: Active Development**
|
|
|
|
| Component | Status |
|
|
|-----------|--------|
|
|
| Specifications (`specs/`) | Draft — ready for SIG-Spec review |
|
|
| `pkg/shellstream` | Fully implemented with comprehensive tests |
|
|
| `pkg/config` | Implemented — HCL parsing + validation |
|
|
| `pkg/oidc` | Implemented — OIDC discovery, JWKS verification, JWT validation |
|
|
| `pkg/governance` | Implemented — gRPC client with mTLS, intent lifecycle, merkle anchoring |
|
|
| `pkg/sshcert` | Implemented — SSH certificate builder with Shellstream extensions |
|
|
| Plugin binaries (`cmd/`) | Implemented — go-plugin registration, Configure + core methods |
|
|
| Proto codegen (`gen/`) | Generated — quartermaster/v1 + bascule/v1 gRPC stubs |
|
|
| CI pipeline | Configured (`.github/workflows/ci.yaml`) |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone and build
|
|
git clone https://github.com/guildhouse-cooperative/guildhouse-spire-plugins.git
|
|
cd guildhouse-spire-plugins
|
|
make build # Build all plugin binaries → bin/
|
|
|
|
# Run tests
|
|
make test # Run all unit tests
|
|
make lint # Run go vet
|
|
```
|
|
|
|
## Specifications
|
|
|
|
The primary deliverables are three formal specifications in [`specs/`](specs/):
|
|
|
|
- **[SPIFFE SSH-SVID](specs/spiffe-ssh-svid.md)** — Defines SSH certificates whose identity derives from SPIFFE IDs
|
|
- **[Shellstream Extensions](specs/shellstream-extensions.md)** — Vendor-suffixed SSH certificate extensions for governance metadata
|
|
- **[Credential Governance](specs/credential-governance.md)** — Credential lifecycle events as governed mutations with merkle anchoring
|
|
|
|
## Plugins
|
|
|
|
Four SPIRE plugins in [`cmd/`](cmd/):
|
|
|
|
| Plugin | SPIRE Type | Runs In | Purpose |
|
|
|--------|-----------|---------|---------|
|
|
| `oidc-attestor` | WorkloadAttestor | Agent | OIDC token verification, claim-to-selector mapping |
|
|
| `ssh-credential-composer` | CredentialComposer | Server | SSH certificate generation with Shellstream extensions |
|
|
| `governance-notifier` | Notifier | Server | Credential event notification, merkle anchoring |
|
|
| `substrate-keymanager` | KeyManager | Server | Governance-aware signing key management |
|
|
|
|
## Packages
|
|
|
|
Shared Go libraries in [`pkg/`](pkg/):
|
|
|
|
- **`shellstream`** — Encode/decode Shellstream SSH certificate extensions (comprehensive tests)
|
|
- **`oidc`** — OIDC discovery + JWKS key fetching + JWT signature verification (RS256, ES256)
|
|
- **`governance`** — GovernanceService + NotaryService gRPC client with mTLS, intent lifecycle, merkle anchoring
|
|
- **`sshcert`** — SSH certificate builder with Ed25519 keypair generation and Shellstream extension embedding
|
|
- **`config`** — HCL configuration loading and validation
|
|
|
|
## Documentation
|
|
|
|
Detailed documentation in [`docs/`](docs/):
|
|
|
|
- **[Architecture](docs/architecture.md)** — System design, data flow, package map
|
|
- **[Plugin Types](docs/plugin-types.md)** — SPIRE plugin interfaces, method signatures, invocation timing
|
|
- **[SSH Certificate Flow](docs/ssh-certificate-flow.md)** — End-to-end certificate issuance sequence
|
|
- **[OIDC Attestation](docs/oidc-attestation.md)** — Workload OIDC token verification flow
|
|
- **[Governance Integration](docs/governance-integration.md)** — Intent lifecycle, MutationEnvelope construction
|
|
- **[Deployment](docs/deployment.md)** — Kubernetes deployment with Kustomize
|
|
- **[Testing](docs/testing.md)** — Test strategy, fixtures, CI pipeline
|
|
|
|
## Building
|
|
|
|
```bash
|
|
make build # Build all plugin binaries
|
|
make test # Run tests
|
|
make lint # Run go vet
|
|
make clean # Remove build artifacts
|
|
```
|
|
|
|
## Proto Code Generation
|
|
|
|
Proto files in `proto/` are copies from the [Guildhouse](https://github.com/guildhouse-cooperative/guildhouse)
|
|
monorepo. To regenerate Go bindings:
|
|
|
|
```bash
|
|
make proto-gen
|
|
```
|
|
|
|
Requires [buf](https://buf.build/docs/installation) to be installed.
|
|
|
|
## License
|
|
|
|
Apache License 2.0 — see [LICENSE](LICENSE).
|