66 lines
8.2 KiB
Markdown
66 lines
8.2 KiB
Markdown
# 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. See `docs/P05-CI-03.md`.
|
|
- **P05-SEC-01:** Gitea Run #87 **3 PASS / 1 FAIL**. Account and Login patched Next.js `16.4.6` builds 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. See `docs/P05-SEC-01.md`.
|
|
- **P05-SEC-02:** Seven parent-scoped PNPM overrides resolved `glob`/`minimatch` advisories. 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. See `docs/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**. See `docs/P05-SEC-02-A01.md`.
|
|
- **P05-OIDC-01:** Gitea **Run #90 FAILED**: disposable four-service ZITADEL stack healthy and host-portless, but private `localhost:8080` loopback 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. See `docs/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; socat `SOCKET_BIND_ERROR`, digest-pinned Python fallback `ADDRESS_IN_USE` on private TCP `127.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. See `docs/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 readiness `OIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKED` FAIL. Real ZITADEL client/human/Chromium/PKCE/Auth.js session NOT EXECUTED; owned cleanup PASS. Real OIDC remains BLOCKED; listener owner UNKNOWN. See `docs/P05-OIDC-04.md`.
|
|
- **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/`](notes/README.md) | Developers / AI agents during work | Scope locks, pre-change plans, phase/fix logs, decisions, verification outcomes |
|
|
| [`project/`](project/README.md) | Maintainers / developers / AI agents | Real file/function map, feature/page details, architecture, modules, dependencies, change history and full source index |
|
|
| [`docs/`](docs/README.md) | 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](MINIFEST.md) indexes top-level content. Rules are mandatory in [AGENTS.md](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)
|
|
|
|
```powershell
|
|
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](core/backend/zitadel/README.md) and [developer guide](docs/DEVELOPMENT.md).
|
|
|
|
## 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](AGENTS.md), [architecture](docs/ARCHITECTURE.md), [P03 source import](docs/P03-SOURCE-IMPORT.md), [Login V2 workspace guide](auth/ui/v2/README.md), [P04 account evidence](docs/P04-ACCOUNT-PORTAL.md), [Account Portal guide](users/ui/README.md) and [phase scopes](docs/PHASES.md). Use separate, expressly approved phases; no production secrets or user data in Git.
|