# highflame-ai/zeroid architecture

> Architecture diagram of the GitHub repository highflame-ai/zeroid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/highflame-ai/zeroid
- Repository: https://github.com/highflame-ai/zeroid

## Overview

ZeroID provides agent identity infrastructure: an operator or agent obtains an identity, receives scoped credentials, delegates authority to other agents, and enables relying systems to verify or revoke those credentials. The graph separates identity and delegation, OAuth issuance, trust and revocation, and persistence. HTTP route registration and selected service-to-store wiring are supported by the sampled source; other feature paths are represented at subsystem level from the README and tree, without assuming unsampled call relationships.

Main entry points: [`internal/service/oauth.go`](https://github.com/highflame-ai/zeroid/blob/main/internal/service/oauth.go) (OAuth service), [`internal/handler/routes.go`](https://github.com/highflame-ai/zeroid/blob/main/internal/handler/routes.go) (HTTP API routes), [`internal/store/postgres/oauth_client.go`](https://github.com/highflame-ai/zeroid/blob/main/internal/store/postgres/oauth_client.go) (PostgreSQL repositories), [`internal/service/attestation.go`](https://github.com/highflame-ai/zeroid/blob/main/internal/service/attestation.go) (Attestation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["ZeroID CLI<br/>[index.ts]"]
  node_http["HTTP API routes<br/>[routes.go]"]
end

subgraph group_identity["Identity and delegation"]
  node_agent["Agent registry<br/>[agent.go]"]
  node_identitysvc["Identity service<br/>[identity.go]"]
  node_delegation["Delegation service<br/>[delegation.go]"]
end

subgraph group_oauth["OAuth credentials"]
  node_oauthhandler["OAuth endpoints<br/>[oauth.go]"]
  node_oauthsvc["OAuth service<br/>[oauth.go]"]
  node_clients["OAuth client management<br/>[oauth_client.go]"]
  node_backchannel["CIBA approval<br/>[backchannel.go]"]
end

subgraph group_trust["Trust and revocation"]
  node_attestation["Attestation<br/>[attestation.go]"]
  node_proof["Proof verification<br/>[proof.go]"]
  node_signals["Signals and revocation<br/>[signal.go]"]
  node_audit["Audit trail<br/>[audit.go]"]
end

subgraph group_state["Persistence and verification"]
  node_postgres[("PostgreSQL repositories<br/>[oauth_client.go]")]
  node_signing["Signing keys<br/>[jwks.go]"]
  node_tokenverify["JWT verification<br/>[verifier.go]"]
  node_dpop["DPoP verification<br/>[verifier.go]"]
end

node_operator(("Operator or agent"))
node_relying(("Relying system"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"calls API"| node_http
node_operator -->|"administers"| node_http
node_http -->|"dispatches OAuth"| node_oauthhandler
node_http -->|"dispatches management"| node_agent
node_http -->|"dispatches registration"| node_clients
node_http -->|"dispatches attestation"| node_attestation
node_http -->|"dispatches signals"| node_signals
node_http -->|"dispatches audit"| node_audit
node_oauthhandler -->|"invokes"| node_oauthsvc
node_oauthsvc -->|"reads and writes"| node_postgres
node_clients -->|"reads and writes"| node_postgres
node_agent -->|"persists identity"| node_postgres
node_identitysvc -->|"persists identity"| node_postgres
node_delegation -->|"persists delegation"| node_postgres
node_backchannel -->|"persists requests"| node_postgres
node_attestation -->|"persists attestations"| node_postgres
node_signals -->|"persists signals"| node_postgres
node_audit -->|"persists audit"| node_postgres
node_oauthsvc -->|"signs credentials"| node_signing
node_oauthsvc -->|"exchanges authority"| node_delegation
node_oauthsvc -->|"handles CIBA"| node_backchannel
node_oauthsvc -->|"checks proofs"| node_proof
node_oauthsvc -->|"uses trust"| node_attestation
node_oauthsvc -->|"revokes credentials"| node_signals
node_relying -->|"verifies tokens"| node_tokenverify
node_relying -->|"checks DPoP proofs"| node_dpop
node_signing -->|"publishes JWKS"| node_relying

click node_cli "https://github.com/highflame-ai/zeroid/blob/main/cli/src/index.ts"
click node_http "https://github.com/highflame-ai/zeroid/blob/main/internal/handler/routes.go"
click node_agent "https://github.com/highflame-ai/zeroid/blob/main/internal/service/agent.go"
click node_identitysvc "https://github.com/highflame-ai/zeroid/blob/main/internal/service/identity.go"
click node_delegation "https://github.com/highflame-ai/zeroid/blob/main/internal/service/delegation.go"
click node_oauthhandler "https://github.com/highflame-ai/zeroid/blob/main/internal/handler/oauth.go"
click node_oauthsvc "https://github.com/highflame-ai/zeroid/blob/main/internal/service/oauth.go"
click node_clients "https://github.com/highflame-ai/zeroid/blob/main/internal/service/oauth_client.go"
click node_backchannel "https://github.com/highflame-ai/zeroid/blob/main/internal/service/backchannel.go"
click node_attestation "https://github.com/highflame-ai/zeroid/blob/main/internal/service/attestation.go"
click node_proof "https://github.com/highflame-ai/zeroid/blob/main/internal/service/proof.go"
click node_signals "https://github.com/highflame-ai/zeroid/blob/main/internal/service/signal.go"
click node_audit "https://github.com/highflame-ai/zeroid/blob/main/internal/service/audit.go"
click node_postgres "https://github.com/highflame-ai/zeroid/blob/main/internal/store/postgres/oauth_client.go"
click node_signing "https://github.com/highflame-ai/zeroid/blob/main/internal/signing/jwks.go"
click node_tokenverify "https://github.com/highflame-ai/zeroid/blob/main/pkg/authjwt/verifier.go"
click node_dpop "https://github.com/highflame-ai/zeroid/blob/main/pkg/dpop/verifier.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_http toneBlue
class node_agent,node_identitysvc,node_delegation toneAmber
class node_oauthhandler,node_oauthsvc,node_clients,node_backchannel toneMint
class node_attestation,node_proof,node_signals,node_audit toneRose
class node_postgres,node_signing,node_tokenverify,node_dpop,node_operator,node_relying toneIndigo
```

## Components

### Entry points

- [ZeroID CLI](https://github.com/highflame-ai/zeroid/blob/main/cli/src/index.ts): `cli/src/index.ts`
- [HTTP API routes](https://github.com/highflame-ai/zeroid/blob/main/internal/handler/routes.go): `internal/handler/routes.go`

### Identity and delegation

- [Agent registry](https://github.com/highflame-ai/zeroid/blob/main/internal/service/agent.go): `internal/service/agent.go`
- [Identity service](https://github.com/highflame-ai/zeroid/blob/main/internal/service/identity.go): `internal/service/identity.go`
- [Delegation service](https://github.com/highflame-ai/zeroid/blob/main/internal/service/delegation.go): `internal/service/delegation.go`

### OAuth credentials

- [OAuth endpoints](https://github.com/highflame-ai/zeroid/blob/main/internal/handler/oauth.go): `internal/handler/oauth.go`
- [OAuth service](https://github.com/highflame-ai/zeroid/blob/main/internal/service/oauth.go): `internal/service/oauth.go`
- [OAuth client management](https://github.com/highflame-ai/zeroid/blob/main/internal/service/oauth_client.go): `internal/service/oauth_client.go`
- [CIBA approval](https://github.com/highflame-ai/zeroid/blob/main/internal/service/backchannel.go): `internal/service/backchannel.go`

### Trust and revocation

- [Attestation](https://github.com/highflame-ai/zeroid/blob/main/internal/service/attestation.go): `internal/service/attestation.go`
- [Proof verification](https://github.com/highflame-ai/zeroid/blob/main/internal/service/proof.go): `internal/service/proof.go`
- [Signals and revocation](https://github.com/highflame-ai/zeroid/blob/main/internal/service/signal.go): `internal/service/signal.go`
- [Audit trail](https://github.com/highflame-ai/zeroid/blob/main/internal/service/audit.go): `internal/service/audit.go`

### Persistence and verification

- [PostgreSQL repositories](https://github.com/highflame-ai/zeroid/blob/main/internal/store/postgres/oauth_client.go): `internal/store/postgres/oauth_client.go`
- [Signing keys](https://github.com/highflame-ai/zeroid/blob/main/internal/signing/jwks.go): `internal/signing/jwks.go`
- [JWT verification](https://github.com/highflame-ai/zeroid/blob/main/pkg/authjwt/verifier.go): `pkg/authjwt/verifier.go`
- [DPoP verification](https://github.com/highflame-ai/zeroid/blob/main/pkg/dpop/verifier.go): `pkg/dpop/verifier.go`

### Other components

- **Operator or agent**
- **Relying system**

## Connections

- Operator or agent → ZeroID CLI: runs commands
- ZeroID CLI → HTTP API routes: calls API
- Operator or agent → HTTP API routes: administers
- HTTP API routes → OAuth endpoints: dispatches OAuth
- HTTP API routes → Agent registry: dispatches management
- HTTP API routes → OAuth client management: dispatches registration
- HTTP API routes → Attestation: dispatches attestation
- HTTP API routes → Signals and revocation: dispatches signals
- HTTP API routes → Audit trail: dispatches audit
- OAuth endpoints → OAuth service: invokes
- OAuth service → PostgreSQL repositories: reads and writes
- OAuth client management → PostgreSQL repositories: reads and writes
- Agent registry → PostgreSQL repositories: persists identity
- Identity service → PostgreSQL repositories: persists identity
- Delegation service → PostgreSQL repositories: persists delegation
- CIBA approval → PostgreSQL repositories: persists requests
- Attestation → PostgreSQL repositories: persists attestations
- Signals and revocation → PostgreSQL repositories: persists signals
- Audit trail → PostgreSQL repositories: persists audit
- OAuth service → Signing keys: signs credentials
- OAuth service → Delegation service: exchanges authority
- OAuth service → CIBA approval: handles CIBA
- OAuth service → Proof verification: checks proofs
- OAuth service → Attestation: uses trust
- OAuth service → Signals and revocation: revokes credentials
- Relying system → JWT verification: verifies tokens
- Relying system → DPoP verification: checks DPoP proofs
- Signing keys → Relying system: publishes JWKS