TOJI TOJI
ARCHITECTURE · lymphhub

lymphhub architecture

lymphhub is the IAM (Identity and Access Management) service for the entire neunexus ecosystem — six Go binaries (core/oidc/tokenhub/federation/ldap-sync plus a CLI) with SpiceDB-based fine-grained authorization, covering the full identity-and-access lifecycle from login and session verification to short-lived credential elevation (tokenhub).

Project overview →

Why

We tried wiring SSO for our existing projects with off-the-shelf IAM services, but ran into cases where LLDAP wouldn't work or OIDC support was incomplete — so we built our own IAM service, tuned to be as compatible as possible with our own stack (LLDAP, K8s, web, OIDC, SSH). The goal is true SSO that covers not just web logins but OS-level account access too. We're extending it with tokenhub into a full approval system to make it a genuinely complete IAM service.

00

What this project is, and why it exists

authored from source

lymphhub is neunexus's IAM/identity service — six Go binaries (core/oidc/federation/tokenhub/ldap-sync plus a CLI) handling login, session verification, and privilege elevation for internal neunexus-ecosystem services like whoami, goquest, and brain.

lymphhub overview: client calls lymphhub, lymphhub authenticates and manages sessions backed by Postgres/Redis/SpiceDB

lymphhub / overview.yaml

01

Who reaches lymphhub, and how

README.md ~L26-32 (Repository ownership)

The real callers were confirmed from the README's "Repository ownership" table — four in total: whoami (session verify), whoami-ui (login/signup), metaviewer (admin UI), and lymphhub-iim (MCP/tool server). lymphhub-mcp has been fully migrated to lymphhub-iim, so it is not drawn as a separate node.

lymphhub context: whoami, whoami-ui, metaviewer, lymphhub-iim call lymphhub and tokenhub; lymphhub calls SpiceDB, Vault, LDAP; tokenhub notifies via Telegram

lymphhub / context.yaml

02

How the internal modules are decomposed

cmd/ + internal/

Reflects cmd/'s actual six binaries (the README mentions only three modes — stale) and a curated subset of internal/'s 17 packages. cmd/lymphhub is a CLI client, not a server, so it's excluded from this diagram.

lymphhub component structure: core binary hosts identity/session modes, routes through tenant middleware to spicedb/jwt/tokenhub/ratelimit/audit packages

lymphhub / structure.yaml

03

Which namespace, which path it ships through

toji-cd/bots/lymphhub-*/

toji/business.toml's claimed four namespaces don't match reality — only two are actually confirmed: the shared iam namespace (core+oidc) and lymphhub-iim. tokenhub/federation/ldap-sync have CI images but aren't deployed yet (Phase B pending).

lymphhub network topology: external clients reach Traefik IngressRoute for oidc, and in-cluster DNS for identity/session; namespace iam hosts core services, namespace lymphhub-iim hosts a separate deployment; tokenhub is flagged as not yet deployed

lymphhub / network.yaml

04

What tables the data lives in, and how they connect

internal/db/migrations/0001-0034 (부분)

Based on internal/db/migrations (0001-0034) — only migrations whose columns were actually read are reflected. SpiceDB manages containers' detailed permissions/membership so Postgres has no separate membership table, except organizations, which has a real membership table (org_memberships).

lymphhub ERD: 14 real Postgres tables (actors, containers, sessions, credentials, tokens, organizations, org_memberships, elevation_requests, and more) connected by 17 foreign-key edges

lymphhub / erd.yaml

05

How a commit becomes a deployment

toji-ci/ci-repos/{lymphhub,lymphhub-mcp}.yaml

Two tracks exist: toji-ci/ci-repos/lymphhub.yaml (the main repo, five images sharing one Dockerfile) and lymphhub-mcp.yaml (a separate repo). Only core/oidc have a manifest_writeback target.

lymphhub CI/CD pipeline: git push triggers toji-ci, builds 5 images from one shared Dockerfile, writes back manifests for core/oidc only

lymphhub / cicd.yaml

06

Where secrets come from, and how they reach a pod

internal/config/config.go (os.Getenv)

Based on an exhaustive grep of os.Getenv in internal/config/config.go, distinguishing real secret-bearing env vars from tuning knobs. JWT signing is delegated to Vault Transit, so the private key never exists in process memory.

lymphhub secrets flow: env vars carry DB/Redis/SpiceDB credentials into the pod; JWT signing key never leaves Vault Transit

lymphhub / secrets.yaml

07

Which layers a single request passes through

internal/services/identity/server.go:97-118

Reflects the actual middleware registration order in internal/services/identity/server.go — tenant.Middleware is outermost, and only the /admin/v1 group adds adminAuth.

lymphhub API request pipeline: request passes through tenant middleware and rate-limit before reaching a handler; /admin/v1 additionally requires adminAuth

lymphhub / api-layers.yaml

08

How the API surface is grouped

proto/{identity,session}/v1/*.proto + server.go routes

Draws both the real proto service blocks (six rpcs total) and the chi-router HTTP/JSON routes together — most of the surface is REST, with gRPC reserved for a handful of cross-service lookups.

lymphhub API surface: a small gRPC service (IdentityService/SessionService) alongside a larger REST surface for login, session, and admin endpoints

lymphhub / api-endpoints.yaml

09

Where a login/session-creation request goes

internal/services/identity/login.go:30-131

Summarizes the real code path of handleLogin in internal/services/identity/login.go. Covers only the local (password) backend path, and folds the original 14 steps down to 8 for readability.

lymphhub login dataflow: a login request is rate-limited, the actor looked up, password verified via the local backend, a session token minted and written to Postgres and Redis, then a cookie set

lymphhub / dataflow-login.yaml

10

How a tokenhub elevation request gets processed

internal/tokenhub/handler_{elevation,telegram}.go

The real code path through internal/tokenhub/handler_elevation.go and handler_telegram.go — independently re-confirmed against how this session's own CLAUDE.md documents the same flow from the client side.

lymphhub tokenhub elevation dataflow: an elevation request triggers a Telegram approval notification, and once approved a short-lived credential is issued

lymphhub / dataflow-elevation.yaml

rendered via archview · d2lang/d2 · ELK layout