# 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).