# 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