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>
66 lines
3 KiB
Markdown
66 lines
3 KiB
Markdown
# CLAUDE.md — Guildhouse SPIRE Plugins
|
|
|
|
## Project Identity
|
|
|
|
Go plugins for [SPIRE](https://spiffe.io/docs/latest/spire-about/) that integrate SPIFFE identity with Guildhouse governance. Four plugins: OIDC workload attestation, SSH credential composition with Shellstream extensions, governance event notification with merkle anchoring, and substrate-aware key management.
|
|
|
|
## Development Environment
|
|
|
|
**No Go toolchain on host.** All build/test/lint commands run inside containers.
|
|
|
|
```bash
|
|
# Build
|
|
podman run --rm -v .:/workspace:Z -w /workspace golang:1.24 go build ./...
|
|
|
|
# Test
|
|
podman run --rm -v .:/workspace:Z -w /workspace golang:1.24 go test ./...
|
|
|
|
# Vet
|
|
podman run --rm -v .:/workspace:Z -w /workspace golang:1.24 go vet ./...
|
|
|
|
# Proto regeneration (requires protoc + Go plugins)
|
|
podman run --rm -v .:/workspace:Z -w /workspace golang:1.24 sh -c '
|
|
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.31.0
|
|
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.3.0
|
|
apt-get update -qq && apt-get install -y -qq protobuf-compiler > /dev/null
|
|
protoc --proto_path=proto --go_out=gen --go_opt=paths=source_relative \
|
|
--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
|
|
quartermaster/v1/*.proto bascule/v1/*.proto
|
|
'
|
|
```
|
|
|
|
## Structure
|
|
|
|
```
|
|
cmd/
|
|
oidc-attestor/ WorkloadAttestor — OIDC token verification
|
|
ssh-credential-composer/ CredentialComposer — SSH cert + Shellstream extensions
|
|
governance-notifier/ Notifier — credential events → merkle anchoring
|
|
substrate-keymanager/ KeyManager — governance-aware signing keys
|
|
pkg/
|
|
shellstream/ Shellstream SSH cert extension encode/decode (855 lines of tests)
|
|
config/ HCL configuration loading + validation
|
|
oidc/ OIDC discovery → JWKS → JWT verification
|
|
governance/ gRPC client for GovernanceService + NotaryService (mTLS)
|
|
sshcert/ SSH certificate builder (Ed25519, Shellstream extensions)
|
|
gen/ Generated proto Go code (committed)
|
|
quartermaster/v1/ governance, notary, credentials services
|
|
bascule/v1/ ceremony service
|
|
proto/ Proto source files (copies from guildhouse monorepo)
|
|
specs/ Formal specifications (SPIFFE SSH-SVID, Shellstream Extensions, Credential Governance)
|
|
deploy/ Kubernetes Kustomize manifests for SPIRE integration
|
|
docs/ Architecture, plugin types, flows, deployment, testing
|
|
```
|
|
|
|
## Key Constraints
|
|
|
|
- **grpc v1.58.3** pinned for compatibility with hashicorp/go-plugin v1.6.3
|
|
- Proto generation uses protoc-gen-go-grpc **v1.3.0** (not latest) for grpc v1.58 compat
|
|
- Proto files in `proto/` are copies from guildhouse monorepo — do not edit here
|
|
- Plugin binaries use hashicorp/go-plugin GRPCPlugin interface for SPIRE registration
|
|
|
|
## Related Repos
|
|
|
|
- `guildhouse/` — Platform monorepo (Quartermaster, Bascule services)
|
|
- `guildhouse-proto/` — Canonical proto definitions
|
|
- `substrate/` — OS platform, Shellstream canonical Rust impl
|