8.8 KiB
ZitPlane
Compact, developer-friendly monorepo for a central identity service, a branded login frontend and an independent user self-service account portal.
Current phase status
- P01 Foundation: complete, initial commit
8f54ccb. - P02 ZITADEL local backend: pinned official images, development Compose and secure local bootstrap helper. Gitea Run #86 verified disposable four-service startup, PostgreSQL persistence and OIDC metadata/JWKS. Admin Console human login and local PC startup remain unverified.
- P03 Login V2 source: official v4.20.4 source and matching client/proto workspace imported under
auth/ui/v2/; original UI unchanged. Gitea Run #83 verified frozen install, production build and 1,219/1,219 unit tests; interactive login not verified. - P04 Account Portal: Next.js + ZITADEL OIDC Auth.js source, protected overview/profile/security pages and responsive foundation under
users/ui/. Gitea Run #83 verified TypeScript/production build and anonymous API 401/redirect tests; real authenticated session still unverified. - P05-CI-01: Manual Gitea Run #81 overall FAILURE: Login V2 build + 1219 unit tests PASS, high/critical gate PASS (18 Moderate Login findings), Account Auth.js TS2345 and Docker checkout FAIL. Details:
docs/P05-CI-01.md. - P05-CI-02: Gitea Run #83 3 PASS / 1 FAIL. Account Portal typecheck/build and negative identity checks PASS; Login V2 build + 1219/1219 tests PASS; High/Critical security threshold PASS (18 Moderate Login records + 1 Moderate Account package OPEN). Docker Postgres/ZITADEL API/Login healthy, but shared runner port 8080 blocked Traefik; cleanup PASS. CI-only portless override added afterward not CI-verified; full OIDC E2E deferred. See
docs/P05-CI-02.md. - P05-CI-03: Gitea Run #86 SUCCESS on
03fb589: portless Docker Compose, four healthy/running services, PostgreSQL restart persistence, ZITADEL readiness, OIDC discovery/JWKS, negative contracts and complete CI cleanup verified. No repeated Account/Login suites. Full interactive OIDC E2E and Moderate dependency fixes remain pending. Seedocs/P05-CI-03.md. - P05-SEC-01: Gitea Run #87 3 PASS / 1 FAIL. Account and Login patched Next.js
16.4.6builds PASS, Login 1219/1219 upstream unit tests PASS, Account audit 0. Login OpenTelemetry patched dependencies reduced prior 18 Moderate to 2 remaining (glob/minimatch); strict Moderate security gate correctly FAILS. Current dependency patch retained; complete security acceptance requires a separate narrow transitive remediation phase. Seedocs/P05-SEC-01.md. - P05-SEC-02: Seven parent-scoped PNPM overrides resolved
glob/minimatchadvisories. Gitea Run #88 Login production audit 0 Moderate/High/Critical PASS, but Login frozen install/build/units NOT RUN because a new CI override validator misparsed existing>=version ranges; post-run regex correction not CI-verified. Full acceptance BLOCKED pending a separately approved focused CI run. Account jobs intentionally skipped. Seedocs/P05-SEC-02.md. - P05-SEC-02-A01: Gitea Run #89 SUCCESS on
ff4c58e: corrected exact override contract PASS, pinned PNPM frozen install PASS, official Login V2 standalone build PASS, upstream Vitest 1219/1219 PASS, Login production audit 0 Moderate/High/Critical; Account jobs skipped. Dependency security/build unit acceptance complete; real user OIDC/MFA E2E and production integration NOT verified. Seedocs/P05-SEC-02-A01.md. - P05-OIDC-01: Gitea Run #90 FAILED: disposable four-service ZITADEL stack healthy and host-portless, but private
localhost:8080loopback forwarding was not ready. Provisioning aborted before OIDC client/human/browser creation; real callback/session NOT verified. Owned database/bootstrap/secret/network cleanup PASS. No app/auth source change or deployment. Seedocs/P05-OIDC-01.md. - P05-OIDC-02: Gitea Run #91 FAILURE: original four backend services and no-host-port private Traefik Host routing PASS, prebuilt socat version/digest PASS; forwarder immediately exited with code 1, so client/user/browser/Auth.js callback NOT EXECUTED. Cleanup PASS. No application/auth/backend edits; real OIDC remains BLOCKED. See
docs/P05-OIDC-02.md. - P05-OIDC-03 / A02 final: Gitea Run #93 COMPLETED FAILURE, source
7b80f41. Job #206 executed (runner queue resolved). Four backend services and private Traefik routing PASS; socatSOCKET_BIND_ERROR, digest-pinned Python fallbackADDRESS_IN_USEon private TCP127.0.0.1:8080. No OIDC client/human or real Chromium/Auth.js callback/session reached. Mandatory cleanup PASS. Actual 8080 listener identity still UNKNOWN; no production/secret changes. Seedocs/P05-OIDC-03-A02.md. - P05-OIDC-04: Single Gitea Run #95 FAILURE on
79dac4f5bb76e1cee4dfaf61657c6e84268b3dfb, job #209. Source adds private socket owner forensics and isolated loopback forwarder, but CI stopped before these executed: 4 healthy backend services PASS, direct private proxy Host HTTP readinessOIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKEDFAIL. Real ZITADEL client/human/Chromium/PKCE/Auth.js session NOT EXECUTED; owned cleanup PASS. Real OIDC remains BLOCKED; listener owner UNKNOWN. Seedocs/P05-OIDC-04.md. - P05-OIDC-04-A01: Gitea Run #96 SUCCESS on
670e225db477f180ff14ffa62e6654860a166f17, job #210. Real disposable ZITADEL project/client/verified test-human, original Login V2 Chromium password+PKCE/state/nonce/Auth.js callback, authenticated Account session/API/page, negative access, local logout and mandatory cleanup PASS. Proxy TCP6:8080 listener Traefik PID1 identified; separate private Socat forwarding verified. Production HTTPS/MFA/passkeys/custom imported Login V2/multi-app SSO/deployment remain unverified. See A01 acceptance. - Production / Coolify: not configured or deployed.
Documentation and project knowledge
ZitPlane uses three Git-tracked Markdown areas. For every future feature, change or fix, create the plan before editing code and update all affected documentation in the same phase:
| Folder | Who reads it | What's inside |
|---|---|---|
notes/ |
Developers / AI agents during work | Scope locks, pre-change plans, phase/fix logs, decisions, verification outcomes |
project/ |
Maintainers / developers / AI agents | Real file/function map, feature/page details, architecture, modules, dependencies, change history and full source index |
docs/ |
End users / operators / developers | Page and button usage, onboarding, status, setup steps, troubleshooting and known limitations |
Each of these folders contains README.md and the requested literal MINIFEST.md (direct-child list, purpose, phase and status). The root MINIFEST.md indexes top-level content. Rules are mandatory in AGENTS.md. Imported official Login V2 source remains untouched.
Responsibility map
| Path | Purpose |
|---|---|
core/backend/zitadel/ |
Official ZITADEL backend integration and local helper |
deployment/docker/compose.backend.dev.yaml |
Loopback-only developer stack |
auth/ui/v2/ |
Official Login V2 monorepo subset (Next.js source in apps/login/, matched client/proto and pnpm/Nx workspace) |
users/ui/ |
P04 account portal source: separate Next.js app, protected pages, OIDC, server-side user API (CI pending) |
packages/ |
Shared packages only when needed |
tests/ |
Focused P02 contracts and P05 isolated CI smoke scripts |
.gitea/ |
Gitea Actions manual CI verification configuration |
docs/ |
Architecture, scopes and developer instructions |
Local development (requires Docker Desktop Linux containers)
py core/backend/zitadel/dev.py init
py core/backend/zitadel/dev.py config
py core/backend/zitadel/dev.py up
When the backend stack is actually running, the local Admin Console is expected at http://localhost:8080/ui/console. This is not a currently verified working URL. See backend setup and developer guide.
Intended public architecture (not deployed)
auth.vib.tools: eventual ZITADEL API, official Console, customized login.account.vib.tools: future custom account portal.- Individual SaaS applications own their own billing, subscriptions and business databases.
- One Git repo, isolated containers; ZITADEL Go source remains upstream.
Working agreements
Read AGENTS.md, architecture, P03 source import, Login V2 workspace guide, P04 account evidence, Account Portal guide and phase scopes. Use separate, expressly approved phases; no production secrets or user data in Git.