Files
ZitPlane/project/SETUP-AND-DEPENDENCIES.md
T

13 KiB

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.

P05-SEC-01 Gitea verification result: Run #87 on 752d243 proved both frozen installs and production builds, and the Login upstream unit suite 1219/1219 PASS. Account production audit returned 0 vulnerabilities. Login production audit returned 2 Moderate transitive issues (glob 14.x and minimatch 11.x patch lines require compatible override/parent work) and zero High/Critical. The strict Moderate gate failed as intended. Do not interpret the patched manifest/lockfile as full vulnerability clearance; P05-SEC-02 needs a newly approved change to the read-only PNPM workspace overrides.

P05-SEC-02 — targeted PNPM workspace security patch

Pre-change source and registry metadata identified two direct glob@10.5.0 parents and five direct minimatch@10.2.5/10.2.6 parents. The seven parent-specific root workspace overrides point to published glob@14.0.6 and minimatch@11.0.9 (Node 22 supported). Pinned PNPM 10.30.3 install --lockfile-only --ignore-scripts --no-frozen-lockfile generated only lock metadata without app installation/build/tests. glob@14 now depends on patched minimatch@11; minimatch@3/5 are unaffected by the reported GHSA version ranges.

These are major dependency migrations underneath older parents, not an upstream source edit. Only a green Gitea Login Nx production build and upstream unit tests, frozen PNPM install and registry audit can certify compatibility and advisory clearance. The existing security workflow has a manual login_only=true focused mode; previously accepted Account results remain from Run #87.

P05-SEC-02 actual acceptance boundary: Run #88 pnpm audit --prod found 0 known Moderate/High/Critical advisories for the 7 scoped patched parent resolutions. But new CI helper matching >= as parent override stopped Login frozen install before any app build/unit case ran. Post-run regex fix to recognize only >glob and >minimatch is not CI-verified. The dependency migration is not yet production-accepted. Do not run local app builds/tests or silently replace the pinned PNPM lock; use separately approved Login-only Gitea acceptance.

Final A01 evidence: Gitea Run #89 on ff4c58e verified exactly seven scoped patches and frozen PNPM 10.30.3 install (1121 packages), official Login proto/client/Next 16.4.6 standalone production build, upstream Vitest 84/84 files + 1219/1219 unit tests, and zero live Moderate/High/Critical Login production advisory records. The Account and backend jobs were deliberately not rerun. This was CI-only, without local application dependency installation, local build/test or deployment. Product user authentication integration still requires separate live disposable OIDC acceptance.

P05-OIDC-01 — isolated browser test tooling and why

CI only: official ZITADEL v4.20.4, official Login V2 v4.20.4, PostgreSQL 17.10/Traefik 3.7.7 from P02; existing portless Compose override; new alpine:3.21 namespace-local socat loopback forwarder, python:3.12-alpine stdlib API provisioner, pinned mcr.microsoft.com/playwright:v1.58.2-noble (Chromium), pinned playwright@1.58.2 and the Account Portal's existing npm ci lock inside an ephemeral browser container. No manifests or lockfiles changed, no local PC builds/tests, and no host HTTP port published. Dynamic IAM_OWNER bootstrap PAT expires in two hours and all token/password/client data are destroyed with owned volumes after the run. P02 issuer HTTP localhost requires Account NODE_ENV=development inside CI only; production HTTPS remains unverified. Detailed topology and cleanup: project/OIDC-E2E-ARCHITECTURE.md.

P05-OIDC-02 CI forwarding dependency: Uses the published, version-selected alpine/socat:1.8.1.3 image rather than installing packages inside alpine:3.21 at container startup. The disposable runner checks the image has ["socat"] entrypoint, resolves RepoDigests and launches the immutable pulled sha256 reference; never latest. Existing python:3.12-alpine probe containers check no-host-port proxy and private forwarding readiness. This is Gitea-only and must not be run on developer PC or production. No package manifests/lockfiles modified.

P05-OIDC-02 runtime status: Gitea Run #91 verified alpine/socat:1.8.1.3 image metadata and immutable digest selection, but the image process exited code 1 after start. The underlying private proxy:80/Host route was healthy; no OIDC provisioning or browser E2E executed. There was no local application install/build. All CI-owned resources were cleaned. Image metadata verification does not prove the forwarding process works or that authenticated OIDC is ready.