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

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

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