# martinbaillie/vault-plugin-secrets-github architecture

> Architecture diagram of the GitHub repository martinbaillie/vault-plugin-secrets-github, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martinbaillie/vault-plugin-secrets-github
- Repository: https://github.com/martinbaillie/vault-plugin-secrets-github

## Overview

##### Project type and purpose
- This is a Vault “secrets engine” plugin written in Go, named vault-plugin-secrets-github.
- It extends HashiCorp Vault by mounting under a path (e.g. `/github`) and handling CRUD on config, permission-sets, tokens, revocation, metrics and info.
- It protects a GitHub App private key in Vault’s storage and performs the GitHub App installation authentication/token-minting flow on behalf of Vault clients.

a. Client (User / CI / Vault CLI / API consumer)
b. Vault Core Server
c. Vault Storage Backend (e.g. Consul, Raft, etc.)
d. Plugin Process (vault-plugin-secrets-github)
- Subcomponents:
- Config Manager (handles `/config`)
- PermissionSet Manager (handles `/permissionset`)
- Token Engine (handles `/token`)
- Revocation Handler (handles lease revocation)
- Metrics Exporter (`/metrics`)
- Internal Modules (reflecting code in github/*.go): path parsing, API client, JWT builder, GitHub HTTP client
e. External GitHub API
f. Observability System (e.g. Prometheus & Dashboard)

##### Relationships and data flows
1. Authentication flow
- Client → Vault Core: POST `/v1/auth/...` → Vault Core Auth Backends → Vault Core → Client OK
2. Token request flow
a. Client → Vault Core: POST `/v1/github/token` (or GET/PUT)
b. Vault Core → Plugin Process via Vault RPC protocol (gRPC over stdio)
c. Plugin → Vault Storage Backend via RPC: read config (`app_id`, `prv_key`, optional `base_url`, etc.)
d. Plugin → Plugin subcomponent: mint JWT using stored private key
e. Plugin → GitHub API: POST `/app/installations/{id}/access_tokens` with JWT
f. GitHub API → Plugin: returns installation token + metadata
g. Plugin → Vault Core: return token response, record lease, metrics, logs
h. Vault Core → Client: JSON payload with `token`, `expire_time`, `repositories` or filtered names
3. Revocation & lease lookup
- Client or Vault Core (sys/leases) → Plugin: revoke token via GitHub DELETE `/installation/token`
4. Metrics & Info
- Observability (Prometheus) → Vault Core (or directly the plugin if exposed) → scrape `/metrics`
- Client/Operators GET `/v1/github/metrics` or `/v1/github/info`

##### Architectural patterns and principles
- Plugin-based extension: Vault Core delegates certain secret paths to an external process over a defined RPC protocol.
- Secrets engine pattern: mount‐time isolation by path, lease management, policy enforcement.
- Configuration as data: plugin uses durable storage, no in-process files except private key stored in Vault.
- High cohesion: each module in `github/*.go` has one responsibility (config, client, paths, JWT, revocation).

##### Technologies and frameworks
- Go 1.22+ (modules `go.mod`, `go.sum`, package `github/…`)
- Vault plugin RPC protocol (gRPC over stdio)
- GitHub REST API v3 (JWT & installation token endpoints)
- Prometheus/OpenMetrics (`/metrics`)
- Nix + direnv for development environment
- goreleaser for cross-compilation
- Unit & integration tests (stubbed GitHub API, local Vault instance)

- Use clear labels: e.g. “Vault Core”, “vault-plugin-secrets-github”, “GitHub API”, “Consul/Raft Storage”, “Prometheus”.
- Client → Vault Core (/auth, /github/token)
- Vault Core → Plugin (gRPC RPC)
- Plugin → Storage (read config)
- Plugin → GitHub (HTTPS POST)
- GitHub → Plugin (token response)
- Plugin → Vault Core (return)
- Prometheus → Plugin (/metrics)
- Blue rectangles for Vault Core & Storage
- Green for Plugin and submodules
- Orange for external GitHub API
- Purple cloud for observability
- Cloud for external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client\n(User/CI/Vault CLI/API)"]:::client

    %% Vault Core
    VaultCore["Vault Core\n(AuthN/Z, Policy, Lease"]:::vault

    %% Plugin Process
    subgraph "vault-plugin-secrets-github" 
        direction TB
        Main["Plugin Entry Point\n(main.go)"]:::plugin
        BackendSetup["Vault RPC Setup\n(backend.go)"]:::plugin
        subgraph "Routing & Path Parsing"
            PathParser["Path Parser\n(path.go)"]:::plugin
        end
        subgraph "Config Management"
            ConfigManager["Config Manager\n(config.go)"]:::plugin
            ConfigPath["Config Paths\n(path_config.go)"]:::plugin
        end
        subgraph "PermissionSet Management"
            PermSetPath["PermissionSet Paths\n(path_permission_set.go)"]:::plugin
            TokenPermSetPath["TokenPermSet Paths\n(path_token_permission_set.go)"]:::plugin
        end
        subgraph "Token Engine"
            TokenPath["Token Path\n(path_token.go)"]:::plugin
            InstallationsPath["Installations Path\n(path_installations.go)"]:::plugin
        end
        Revoker["Revocation Handler\n(revocation.go)"]:::plugin
        Metrics["Metrics Exporter\n(path_metrics.go)"]:::plugin
        Info["Info Endpoint\n(path_info.go)"]:::plugin
        GitHubClient["GitHub Client & JWT\n(client.go)"]:::plugin
    end

    %% Storage Backend
    Storage[(Storage Backend\nConsul/Raft/etc.)]:::storage

    %% External Services
    GitHubAPI["GitHub REST API\n(v3 endpoints)"]:::external
    Observability["Observability\n(Prometheus)"]:::observability

    %% Flows
    Client -->|"/v1/auth/*"| VaultCore
    Client -->|"/v1/github/token"| VaultCore
    VaultCore -->|"gRPC over stdio"| BackendSetup
    BackendSetup --> PathParser
    PathParser --> ConfigManager
    PathParser --> ConfigPath
    PathParser --> PermSetPath
    PathParser --> TokenPermSetPath
    PathParser --> TokenPath
    PathParser --> InstallationsPath
    PathParser --> Revoker
    PathParser --> Metrics
    PathParser --> Info
    ConfigManager -->|read/write| Storage
    ConfigPath -->|read/write| Storage
    PermSetPath -->|read/write| Storage
    TokenPermSetPath -->|manage leases| Storage
    TokenPath --> GitHubClient
    InstallationsPath --> GitHubClient
    GitHubClient -->|POST JWT to| GitHubAPI
    GitHubAPI -->|token response| GitHubClient
    GitHubClient -->|return token/lease| VaultCore
    Revoker -->|DELETE token| GitHubAPI
    Metrics -->|"/metrics"| VaultCore
    Observability -->|scrape /metrics| Metrics
    Client -->|"/v1/github/metrics"| VaultCore
    Client -->|"/v1/github/info"| VaultCore

    %% Click Events
    click Main "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/main.go"
    click BackendSetup "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/backend.go"
    click PathParser "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path.go"
    click ConfigManager "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/config.go"
    click ConfigPath "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_config.go"
    click PermSetPath "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_permission_set.go"
    click TokenPermSetPath "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_token_permission_set.go"
    click TokenPath "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_token.go"
    click InstallationsPath "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_installations.go"
    click Revoker "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/revocation.go"
    click Metrics "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_metrics.go"
    click Info "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/path_info.go"
    click GitHubClient "https://github.com/martinbaillie/vault-plugin-secrets-github/blob/master/github/client.go"

    %% Styles
    classDef client fill:#e3f2fd,stroke:#2196f3,color:#0d47a1,stroke-width:2px
    classDef vault fill:#bbdefb,stroke:#1e88e5,color:#0d47a1,stroke-width:2px
    classDef plugin fill:#c8e6c9,stroke:#43a047,color:#1b5e20,stroke-width:2px
    classDef storage fill:#eeeeee,stroke:#9e9e9e,color:#424242,stroke-width:2px
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100,stroke-width:2px
    classDef observability fill:#f3e5f5,stroke:#8e24aa,color:#4a148c,stroke-width:2px
```
