guildhouse-spire-plugins/README.md

Guildhouse SPIRE Plugins

SPIRE plugins and specifications for governed SSH access via SPIFFE identity.

This repository extends the SPIFFE 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

# 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/:

• SPIFFE SSH-SVID — Defines SSH certificates whose identity derives from SPIFFE IDs
• Shellstream Extensions — Vendor-suffixed SSH certificate extensions for governance metadata
• Credential Governance — Credential lifecycle events as governed mutations with merkle anchoring

Plugins

Four SPIRE plugins in 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/:

• 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/:

• Architecture — System design, data flow, package map
• Plugin Types — SPIRE plugin interfaces, method signatures, invocation timing
• SSH Certificate Flow — End-to-end certificate issuance sequence
• OIDC Attestation — Workload OIDC token verification flow
• Governance Integration — Intent lifecycle, MutationEnvelope construction
• Deployment — Kubernetes deployment with Kustomize
• Testing — Test strategy, fixtures, CI pipeline

Building

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 monorepo. To regenerate Go bindings:

make proto-gen

Requires buf to be installed.

License

Apache License 2.0 — see LICENSE.