66 lines
8.2 KiB
Markdown
66 lines
8.2 KiB
Markdown
# Setup, modules and dependency rationale
|
|
|
|
Baseline: P04 source, Git `40af500`; runtime not verified.
|
|
|
|
| Technology / module | Actual source location | Why it exists / configured version |
|
|
| --- | --- | --- |
|
|
| ZITADEL Go server | Official Docker image in `deployment/docker/compose.backend.dev.yaml` | Central IAM/OIDC/security policy server, pinned `v4.20.4`; **Go source is not vendored** |
|
|
| ZITADEL Login V2 | `auth/ui/v2/apps/login/` | Original customisable Next.js login/recovery/MFA frontend, upstream tag `v4.20.4`; import-only |
|
|
| ZITADEL JS client/protos | `auth/ui/v2/packages/zitadel-client`, `zitadel-proto`, `proto` | Matched Login V2 generated API types/client and source protocol definitions |
|
|
| pnpm + Nx | `auth/ui/v2/package.json`, lockfile, `nx.json` | Original upstream Login V2 multi-package build chain; root workspace pins `pnpm@10.30.3`, imported Login package pins a different `pnpm@10.28.2` in its manifest; compatibility to verify in future CI |
|
|
| Next.js / React | `users/ui/package.json` | Account Portal App Router and server components; `next@16.4.3`, `react@19.2.6` |
|
|
| Auth.js 5 / ZITADEL provider | `users/ui/src/auth.ts`, `package.json` | OIDC Authorization Code + PKCE, state, nonce and portal-local JWT sessions; `next-auth@5.0.0-beta.32`; compatibility/security CI pending |
|
|
| PostgreSQL | P02 Compose | ZITADEL storage, `postgres:17.10-alpine` |
|
|
| Traefik | P02 Compose | Local HTTP/2 h2c proxy, `traefik:v3.7.7` |
|
|
| Python stdlib helper | `core/backend/zitadel/dev.py` | Secure local secret generator, Compose wrapper, ready check; requires Python 3.10+ according to prior docs |
|
|
|
|
## Exact local development entrypoint (P02 only; no claim it ran)
|
|
|
|
From project root: `py core/backend/zitadel/dev.py init` (writes ignored `.env` once); `config`, `up`, `ps`, `check`, `down` subcommands require Docker. The production configuration is **not** built or deployed.
|
|
|
|
In `deployment/docker/compose.backend.dev.yaml`, named volumes `postgres-data` and `zitadel-bootstrap` preserve DB and bootstrap token. Proxy only publishes `127.0.0.1:8080:80`. Local ZITADEL admin username is `zitadel-admin@zitadel.localhost`, initial password generated in ignored `.env`; no real user account setup has been verified.
|
|
|
|
## Account portal environments (not provisioned)
|
|
|
|
`users/ui/.env.example` documents `ZITADEL_ISSUER`, `ZITADEL_CLIENT_ID`, `ZITADEL_CLIENT_SECRET`, `AUTH_SECRET`, `AUTH_URL`, `AUTH_TRUST_HOST`. All must be securely provisioned before a live OIDC session can work. Proposed callback: `/api/auth/callback/zitadel`, matching dedicated confidential ZITADEL Web client.
|
|
|
|
The Account Portal has **no dependency lockfile** yet. `npm ci`/reproducible build is unavailable until a separately approved lockfile/CI phase. The P03 slim workspace retains the original upstream `pnpm-lock.yaml` with unverified frozen-install compatibility.
|
|
|
|
## Why modules live where they do
|
|
|
|
- `core/` contains ZitPlane orchestration, *not a ZITADEL Go fork*; updates to Go backend are done by deliberate image upgrades.
|
|
- `auth/` retains upstream source-relative layout to avoid breaking shared imports and make merge/supply-chain audits possible.
|
|
- `users/ui/` is a separate product surface because account self-service is not the same as login/challenge flows.
|
|
- `deployment/` separates local infrastructure from a future production Compose/Coolify stack.
|
|
- `packages/` is a placeholder for future ZitPlane-owned reusable UI; do not confuse with `auth/ui/v2/packages/` which are pinned upstream dependencies.
|
|
- `notes/` = phase plans/evidence; `project/` = developer truth; `docs/` = user guides.
|
|
|
|
## P05-CI-01 dependency reconciliation and CI
|
|
|
|
The P03 upstream `pnpm-lock.yaml` contained 8 importer metadata records but the slim ZitPlane workspace only contains 4. P05 removes absent importers while preserving all original resolution package snapshots; `pnpm-workspace.yaml` explicitly lists imported Login/Client/Proto packages. The `users/ui/package-lock.json` is npm v3, generated with metadata-only package-lock command (no local installs). Gitea `.gitea/workflows/p05-ci.yml` uses `ubuntu-latest` containers to verify frozen install, build, high/critical advisory gate, and disposable backend smoke. Gitea Run #81 proved Login frozen install/build/unit (1219/1219) and high/critical advisory threshold; Account dependencies installed but TypeScript failed; the Docker checkout had no Git before the action, so live backend was not exercised. Login's audit also reported 18 MODERATE findings. The checkout fix was committed after the run and remains unverified; see `docs/P05-CI-01.md`.
|
|
|
|
## Pending checks before any release
|
|
|
|
Version security review, reproducible installs, TypeScript/typecheck, Next.js build, OIDC state/PKCE, callback, token expiry, local vs global logout, self-service access, routing, secrets handling, production TLS, backup/restore, monitoring, and isolated Gitea CI verification. No current public deployment exists per recorded phase evidence.
|
|
|
|
|
|
## P05-CI-02 current checked results (2026-11-22)
|
|
|
|
Gitea Run #83 proved Account Portal TypeScript and Next.js production build, anonymous identity API 401/no-store and protected route redirect. Login V2 frozen build/standalone and upstream unit tests 1219/1219 passed. Dependency audits exposed 1 Moderate Account `next` vulnerable package (npm recommends Next.js 16.4.6) and 18 Moderate Login workspace records (seven Next.js GHSA IDs, eight OpenTelemetry driver instrumentation records, one OpenTelemetry HTTP, `glob`, `minimatch`). No dependency package/lock versions were changed.
|
|
|
|
The runner's published TCP 8080 was already in use, so P02's local-only Traefik mapping prevented the CI proxy from starting even though PostgreSQL, ZITADEL API and Login V2 became healthy. A **CI-only** two-file Compose merge uses `tests/ci/compose.portless.override.yaml` to clear `proxy.ports`; config asserts that no host ports will be published. This was added after Run #83 and remains **unverified**. Live DB restart/data persistence and discovery checks have not passed. No production secrets or volumes were accessed.
|
|
|
|
|
|
## P05-CI-03 backend acceptance — proven in Gitea only
|
|
|
|
Run #86 on commit `03fb589` executed a backend-only manual Gitea Actions job and verified the original pinned P02 container images on a disposable Docker v29.9.3 / Compose v5.7.2 runner. The P05 portless CI override removed the developer-only host binding, all four containers came up, PostgreSQL retained a synthetic row across a restart, and ZITADEL ready/issuer/OIDC discovery/JWKS passed. Owned network/containers/volumes were verified removed by the always-run cleanup step. No local PC/docker startup, release or production deployment occurred. Remaining steps before deployment: review/patch 18 Moderate Login findings and 1 Moderate Account `next` package, then disposable authenticated OIDC and Admin Console/MFA tests plus production TLS/Coolify/backup readiness.
|
|
|
|
|
|
## P05-SEC-01 — Frozen dependency security resolution
|
|
|
|
- Account: direct `next@16.4.6` and npm v3 lock metadata created with `npm install --package-lock-only --ignore-scripts --no-audit --no-fund`; no local application install/build/test.
|
|
- Imported Login V2: direct `next@16.4.6`, `@next/eslint-plugin-next@16.4.6`; `@opentelemetry/auto-instrumentations-node@^0.80.0`, `@opentelemetry/sdk-node@^0.222.0`, `@opentelemetry/api-logs@^0.222.0` to align the telemetry release family. PNPM v10.30.3 ran metadata-only `install --lockfile-only --ignore-scripts --no-frozen-lockfile`; no project `node_modules` was created.
|
|
- The imported PNPM lock previously retained snapshots from an upstream monorepo larger than the 4-member ZitPlane workspace. Regeneration pruned many no-longer-reachable snapshots, with only metadata file changes inside approved scope; root workspace `pnpm-workspace.yaml` and imported code unchanged. The Gitea **frozen install** is the required proof of consistency.
|
|
- Advisory resolution cannot be claimed merely from versions. `glob@10.5.0` and `minimatch@10.2.x` remain in the lockfile through tooling parents with older major ranges, and the workspace override file is read-only. Their Moderate advisories stay OPEN until proven fixed or separately approved.
|
|
- Dedicated manual Gitea `p05-security-acceptance.yml` performs Account/Login frozen builds and a strict High/Critical + Moderate gate. Prior P05 backend Run #86 was successful and was **not** deployed.
|