Documentation · Roadmap · Release notes · 한국어
A single-binary identity provider for zero-trust gateways, written in Rust.
Hopae (호패) is named after the Joseon-era state-issued identity tag. It signs
people in through OAuth/OIDC or LDAP providers, keeps their sessions, and
answers a gateway's "who is this request from?" question so that the gateway
can inject verified identity into upstream requests. It is packaged around the
Hangang gateway's external
authentication check, and it stays usable behind any gateway that can forward
such a check.
Status: v0.0.5 released; native zero-trust gateway integration. OIDC/LDAP login, service API authentication, mTLS HOP1, delegated management, TOTP and external MFA browser step-up are implemented. Internal v6 dogfooding is active. Remaining scope is listed below and in the roadmap.
- A browser requests a protected route on the gateway without a session.
- The gateway's forward-authentication check asks Hopae; Hopae answers with a redirect to its login portal, which runs on its own host and is itself a route on the same gateway.
- The user signs in with a provider or email; Hopae creates a session and redirects back to the application.
- On every following request the gateway asks Hopae again, receives verified identity headers, injects them into the upstream request and strips any copies the client sent.
This is close to a standard OAuth deployment; the difference is that the gateway already owns routing, header injection and stripping, so Hopae provides only the portal, providers, sessions and policy.
The base is one complete path: Google sign-in, server-side sessions and Hangang forward-authentication, with a minimal management console on top of it.
-
Sign-in — OpenID Connect against Google (authorization code flow with PKCE, ID-token validation, discovery and key caching). Providers are defined in the JSON configuration file; a provider whose secret variable is missing is disabled, not fatal.
-
Sessions — server-side sessions stored in SQLite, per-host handle cookies bound to the browser, configurable idle and absolute timers and client IP/User-Agent binding per application, logout, and explicit account linking by verified email.
-
Gateway integration — the verify endpoint (
/_hopae/verify) of the gateway contract: caller-key authentication with rotation, fail-closed answers, identity headers for the gateway to inject, and cross-domain single sign-on between registered hosts through a browser-bound handoff. -
Operations —
hopae --checkpreflight (prints the route fragment and redirect URIs to register), single-instance lock, backup before a schema migration, graceful shutdown, structured event log with transactional audit events,/healthz. See operations. -
Management console (M4-min) — an optional third listener, reached through its own protected gateway route, with pages and a JSON API to list and search users, disable and enable a user, end one or all sessions, browse the login history and the audit trail, and read the status of applications, providers, store and build. Administrators are granted with
hopae admin grantoradmin.users[]; console freshness is a provider-verified reauthentication where the provider supports it and Hopae login age otherwise (Google). See administration. -
Second factors — encrypted TOTP enrollment and approved HTTPS external MFA, browser choice/response forms, durable single-use proof consumption, credential rotation and elevated handoff. Service credentials remain AAL 0. Second factors records exact qualification and open lifecycle work.
-
LDAP — direct credential login alongside OIDC, LDAPS/mandatory StartTLS, immutable directory identity and password reauthentication. LDAP.
-
Packaging — a static binary and a hardened Docker Compose template in
deploy/.
Production use needs a gateway that sends the caller key (Hangang change HC-3); an unmodified gateway works for development only with caller authentication turned off. See the compatibility matrix in the contract.
Everything here is planned, not shipped; see the roadmap.
- Other providers (Kakao, Naver, email magic link, email and password), additional factor types, full lifecycle and Lua adapters.
- Blacklists and throttling beyond the per-IP bounds, shared state for several instances (PostgreSQL, Redis/Valkey), complete provider/application management, recovery, fleet and production-user MFA qualification.
- Lua hooks, webhooks, Prometheus metrics, configuration reload, signed self-update.
Build (Rust 1.96 or newer) or use the container image, write a configuration file, and check it before running:
cargo build --release --locked
export HOPAE_GATEWAY_KEY=change-me # the caller key shared with the gateway
export HOPAE_PROVIDER_GOOGLE_CLIENT_SECRET=change-me # Google OAuth client secret
target/release/hopae --check --config deploy/hopae.example.json
target/release/hopae run --config deploy/hopae.example.json--check prints what to register elsewhere: the gateway route auth
fragment, the return origins and the provider redirect URI
(<portal.public_url>/callback/google). Then register the portal route and
your protected routes on the gateway (examples in
deploy/hangang-routes.example.json) and
open a protected host in a browser. For a hardened container deployment follow
deploy/README.md.
- Documentation index
- Gateway contract — the verify protocol, headers, cookies and route fragments
- Configuration reference — every key, default and CLI command
- Administration — the management console, its API, administrator grants and freshness
- Operations — running, state, backups, key rotation, logs, health, failure behavior
- Development process — roles, phase gates, scenario-based TDD, release and security rules
- Documentation system — layout, translation rules, style, required documents
- Architecture decision records
- Scenario specifications
- Roadmap
Every change follows the development process: a design record, an adversarial review, a scenario specification, a failing test, then the implementation. English documents are canonical; Korean translations are updated in the same change.
MIT © 2026 Jioh Jung
Native Hangang integration adds bounded persistent verification and trusted console menus while retaining Hopae provider/session authority.
Pumgye owns service-scoped roles, permissions, information classes and user/network assignments. Hopae's native verification establishes identity and assurance; Hangang delegates authorization to the independent Pumgye authority and enforces access with Sumunjang network evidence. Successful authentication alone does not grant service access: unassigned users remain guest and the auth-proxy refuses protected requests. Hopae retains provider, user and session ownership; native console grants remain distinct from service permissions.
gRPC gateway verification shares the HTTP/HOP1 authentication pipeline and Hangang server runtime. Building requires protoc.
HOP1 connection admission and task ownership use the pinned hangang-runtime
0.1.2 base, shared with bounded management HTTPS. Hopae retains its 256-connection
limit, immediate shutdown, TLS/ALPN checks, caller authentication, frame limits
and authentication pipeline. This extraction does not merge domain cores or
change the independent-server deployment model.
Release preparation defaults to Linux amd64 static musl. Musl binaries with an
ELF interpreter are refused before staging. For signed distribution, pass both
--signer and --seed to tools/prepare_release.py; the private seed must remain
separate from the output directory. The tool checks the repository signing pin
before writing assets and independently verifies Ed25519 signatures with OpenSSL.
Unsigned staging is for qualification only and must not be published as a signed
release. Each additional platform requires separate current-source qualification.
v0.0.5 is published at 8ce0b8a with five independently verified Linux amd64 musl assets. All-feature tests passed 919 cases (42 existing ignored), with strict Clippy, six release boundary tests, actual native/gRPC four-process chains and operational DB-clone credential publication/withdrawal checks. Internal replacement preserved identity, provider, session, MFA and profile state and environment, verified refusal over HTTP/native mTLS, exact signed executable and container restart. The console package was installed with updated pins and its actual delegated status response was verified. Rollback backups are retained. This version has not yet been qualified in Kubernetes; signed projection delivery and full provider/fleet qualification remain unfinished.
Native service receipts bind profile and application generations. The opt-in mTLS ValidateService RPC verifies signatures against live owners; shared key registry extraction also rejects retired material at higher epochs. Actual Pumgye/Sumunjang endpoint fixtures passed on debug and static candidates. Newly versioned assets still require qualification before publication; operating issuer resources remain separately configured. Permit/projection/fleet integration is incomplete. GitHub Actions remains disabled.
v0.0.7 is now
published at 00684199ed5f63d1cec47b8669623ea681aca745. Exact newly versioned static three-authority endpoint
qualification, source regression/Clippy and release boundary checks passed.
All downloaded assets matched originals; pinned signatures, version/target/URL
bindings and static ELF were independently verified. Internal adoption and
Kubernetes combined-endpoint qualification remain subsequent gates.
Internal deployment preserved users/providers/sessions/grants/MFA/profile owner data and the existing environment. Actual operating clones and clone-only credential publication/withdrawal qualified the new executable before replacement. HTTP/HOP1 mTLS expired/invalid denial, exact signed running bytes and second container restart passed. Receipt issuer remains separately unconfigured.