Skip to content
ziozzangPublic

About

Hopae — OAuth/OIDC identity provider and zero-trust auth backend for the hangang gateway

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Hopae

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.

How it fits

  1. A browser requests a protected route on the gateway without a session.
  2. 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.
  3. The user signs in with a provider or email; Hopae creates a session and redirects back to the application.
  4. 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.

What works today

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 --check preflight (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 grant or admin.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.

Not yet

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.

Quick start

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

Contributing

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.

License

MIT © 2026 Jioh Jung

Native Hangang integration adds bounded persistent verification and trusted console menus while retaining Hopae provider/session authority.

Service authorization ownership

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 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.

v0.0.7 release preparation

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.

0.0.7 Internal adoption — 2026-10-15

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.

About

Hopae — OAuth/OIDC identity provider and zero-trust auth backend for the hangang gateway

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages