Tyler King
420a4e2ea0
Critical fixes: - F-01: SatScope array form support (single pointer → slice with polymorphic JSON) - F-02: Add governance-intent@guildhouse.dev as 10th Shellstream extension - F-06: Replace os.Exit(1) stubs with go-plugin Serve() boilerplate in all cmd/ - F-13: Validate SatScope.ResourcePattern is non-empty High priority: - F-03: Add normative Accord policy syntax note to credential-governance.md §8.2 - F-04: Replace OID XXXXX placeholder with explicit PEN reference and IANA TODO - F-05: Document CredentialComposer hook mapping in spec and plugin-types.md - F-07/F-08: Commit CI pipeline (.github/workflows/ci.yaml) - F-09: Add hashicorp/go-plugin v1.6.3 to go.mod Medium priority: - F-10: Wire sample-ssh-cert-extensions.json fixture into shellstream tests - F-11: Cross-reference merkle proof depth limit (256 leaves) in governance spec - F-12: Add YAML format clarification headers to deploy configs - F-14: Expand README with project status, docs links, and quick-start Low priority: - F-15: Standardize "SSH SVID" → "SSH-SVID" terminology across docs - F-16: Add GovernanceEpochSeconds to PluginConfig and deploy configs - F-17: Add troubleshooting section to deployment.md, error handling to OIDC docs Global: Rename all extension keys from @guildhouse.io to @guildhouse.dev Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
98 lines
3.9 KiB
Markdown
98 lines
3.9 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`, `pkg/oidc`, `pkg/governance`, `pkg/sshcert` | Scaffolded — interfaces and validation stubs |
|
|
| Plugin binaries (`cmd/`) | go-plugin boilerplate in place, interface methods pending |
|
|
| CI pipeline | Configured (`.github/workflows/ci.yaml`) |
|
|
|
|
"Scaffolded" means the package defines its public types, interfaces, and configuration validation, but core logic returns `"not yet implemented"` errors. This provides a clear skeleton for implementation while allowing the full project to compile and pass structural tests.
|
|
|
|
## 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 (fully implemented)
|
|
- **`oidc`** — OIDC token verification (scaffolded)
|
|
- **`governance`** — GovernanceService/CeremonyService gRPC client (scaffolded)
|
|
- **`sshcert`** — SSH certificate builder (scaffolded)
|
|
- **`config`** — Plugin configuration loading (scaffolded)
|
|
|
|
## 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).
|