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, 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

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

• 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.