TOJI TOJI
ARCHITECTURE · lymphhub

lymphhub architecture

lymphhub은 neunexus 생태계 전체의 IAM(Identity and Access Management) 서비스입니다 — 6개 Go 바이너리(core/oidc/tokenhub/federation/ldap-sync + CLI)와 SpiceDB 기반 세분화 권한으로 로그인·세션 인증·단기 자격증명 승격(tokenhub elevation)까지 신원·접근 관리 전 과정을 담당합니다.

프로젝트 개요 →

왜 필요한가

기존에 만든 프로젝트들을 IAM 서비스로 SSO 하려고 시도했지만, LLDAP이 안 되거나 일부 OIDC가 안 되는 경우가 있어 자체 서비스들과 가장 호환이 잘 되는 IAM 서비스를 직접 만들었습니다. LLDAP·K8s·웹·OIDC·SSH 등 웹뿐 아니라 OS 진입 계정까지 아우르는 진정한 의미의 SSO를 이루기 위한 서비스입니다. tokenhub를 활용해 승인(approval) 시스템까지 확장해 진정한 IAM 서비스로 발전시킬 예정입니다.

00

이 프로젝트는 무엇이고 왜 존재하는가

authored from source

lymphhub은 neunexus 생태계의 IAM/Identity 서비스입니다 — Go로 작성된 6개 바이너리(core/oidc/federation/tokenhub/ldap-sync + CLI)로 구성되며, whoami/goquest/brain 등 neunexus 생태계 내부 서비스의 로그인·세션 검증·권한 상승을 담당합니다.

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

lymphhub / overview.yaml

01

누가, 어떻게 lymphhub에 닿는가

README.md ~L26-32 (Repository ownership)

실제 호출 주체는 README의 "Repository ownership" 테이블로 확인했습니다 — whoami(세션 검증), whoami-ui(로그인/가입), metaviewer(운영자 admin UI), lymphhub-iim(MCP/tool 서버) 4개. lymphhub-mcp는 lymphhub-iim으로 완전히 이관 완료되어 별도 노드로 그리지 않았습니다.

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

내부 모듈은 어떻게 나뉘는가

cmd/ + internal/

cmd/의 실제 6개 바이너리(README는 3개 모드만 언급 — stale)와 internal/의 17개 패키지 중 대표만 큐레이션했습니다. cmd/lymphhub는 서버가 아니라 CLI 클라이언트라 이 다이어그램에서는 제외했습니다.

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

lymphhub / structure.yaml

03

어느 네임스페이스, 어느 경로로 뜨는가

toji-cd/bots/lymphhub-*/

toji/business.toml이 주장하는 4개 네임스페이스는 실제와 다릅니다 — 실제로 확인된 건 공유 네임스페이스 iam(core+oidc)과 lymphhub-iim 둘뿐입니다. tokenhub/federation/ldap-sync는 CI 이미지는 있으나 아직 배포되지 않았습니다(Phase B 대기).

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

데이터는 어떤 테이블로, 어떻게 연결되는가

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

internal/db/migrations(0001~0034) 기준 — 실제로 컬럼까지 읽은 마이그레이션만 반영했습니다. SpiceDB가 containers의 상세 권한/멤버십을 관리해 Postgres에는 별도 멤버십 테이블이 없지만, organizations는 예외로 실제 멤버십 테이블(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

커밋이 어떻게 배포로 이어지는가

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

toji-ci/ci-repos/lymphhub.yaml(메인 레포, 5개 이미지가 하나의 Dockerfile을 공유) + lymphhub-mcp.yaml(별도 레포) 두 트랙이 존재합니다. core/oidc만 manifest_writeback 대상이 있습니다.

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

시크릿은 어디서 와서 어떻게 파드에 들어가는가

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

internal/config/config.go의 os.Getenv 전수 grep 기준 — 실제 시크릿 값을 담는 env var와 튜닝 값을 구분했습니다. JWT 서명은 Vault Transit에 위임해 개인키가 프로세스 메모리에 존재하지 않습니다.

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

lymphhub / secrets.yaml

07

요청 하나가 어떤 계층을 통과하는가

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

internal/services/identity/server.go의 실제 미들웨어 등록 순서 그대로입니다 — tenant.Middleware가 최외곽이고, /admin/v1 그룹만 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

API 서비스는 어떤 그룹으로 나뉘는가

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

proto의 실제 service 블록(총 6개 rpc) + chi router HTTP/JSON 라우트를 함께 그렸습니다 — REST가 대부분이고 gRPC는 cross-service 조회용 소수 rpc만 씁니다.

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

로그인/세션 생성 요청은 어디를 거치는가

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

internal/services/identity/login.go의 handleLogin 실제 코드 흐름을 요약했습니다. local(비밀번호) 백엔드 경로만 다루며, 원본 14단계를 핵심 8단계로 접었습니다.

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

tokenhub 권한 상승 요청은 어떻게 처리되는가

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

internal/tokenhub/handler_elevation.go + handler_telegram.go 실제 코드 흐름입니다. 이 세션 CLAUDE.md가 클라이언트 관점에서 문서화한 것과 동일한 흐름임을 코드로 재확인했습니다.

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