Files
ZitPlane/docs/PHASES.md
T

23 KiB

Phase register and scope locks

Implement one explicitly approved phase at a time. Keep out-of-scope files, existing authentication machinery and production systems unchanged.

P01 - Foundation (COMPLETE)

  • Baseline commit 8f54ccb30426f2955472c0cd40fb94d0b18e86ac.
  • Initial monorepo folder structure, docs, project Git identity and clean commit completed.

P02 - ZITADEL local backend (APPROVED 2026-11-22)

  • Allowed source writes: core/backend/zitadel/**, deployment/docker/compose.backend.dev.yaml, .env.example, backend-focused tests/**, and narrow docs/** / README.md.
  • Official versioned ZITADEL v4 backend image, local PostgreSQL persistence, secure random dev secret generation, first-admin bootstrap and health checks.
  • Official prebuilt Login V2 image as a runtime dependency only (v4 Admin Console login requires it); no Login V2 source import.
  • No backend Go source vendoring, UI redesign, public domain, Coolify deploy, production keys, remote push or changes to unrelated files.
  • Verify: static focused test/patch audit; with Docker available, live startup/ready/Admin Console, persistent DB after restart and shutdown.
  • Execution evidence: Docker CLI/Desktop absent on connected Windows PC; live Compose startup, admin login and persistence remain NOT VERIFIED. Prior P02 static checks are recorded in docs/P02-EVIDENCE.md.
  • P02-RUNTIME-ACCEPTANCE-01 instruction update (2026-11-22): user explicitly deferred all local test/dev execution to a future Gitea Actions phase; this is a source handoff, not runtime acceptance. Existing source is committed; authorized push to vibtools/ZitPlane is in scope. CI workflow creation and UI import remain outside P02.
  • Existing unrelated untracked AI_INSTRUCTIONS.md must remain untouched.

P03 - Official Login V2 source import (APPROVED 2026-11-22; SOURCE IMPLEMENTED)

  • Baseline: eadd0e558b459061e48583192badfc0579e95140.
  • Write Scope: auth/ui/v2/** (Login V2 and required upstream workspace files), narrow README.md and docs/** (P03 source/phase notes). No other files.
  • Upstream tag: v4.20.4 at 384bb9ec96b501ad39dc232ee2061a40fe180bbd, matching P02 Go backend image.
  • Import apps/login, packages/zitadel-client, packages/zitadel-proto, proto, root pnpm/Nx/build files and licensing nested under auth/ui/v2/. Preserve auth/UI behavior. Exclude upstream environment files; never commit secrets.
  • User explicitly requested no local builds, tests, dev servers or deployments. Only source/provenance/patch audit, documentation, Git commit and approved Gitea push. CI deferred.
  • P02 prebuilt Login UI remains configured in the development Compose; do not replace it or call runtime acceptance complete.
  • Evidence and known gaps: docs/P03-SOURCE-IMPORT.md. CI workflow not part of this scope.

P04 - User Account Portal foundation (APPROVED 2026-11-22; SOURCE IMPLEMENTED)

  • Baseline: 4404849fc4bd30c7b4b7cabe7caed54cbd7cd37d.
  • Exact Write Scope: users/ui/**, narrow project README.md and relevant docs/** (phase/evidence/architecture/developer guide). P02/P03 source read-only.
  • Separate compact Next.js portal, ZITADEL OIDC/PKCE authentication, server-protected user routes, read-only profile and security settings structure.
  • Real OIDC only; no fake production auth, browser admin credentials, billing or user-management mutation endpoints. Existing ZITADEL core/Login V2 untouched.
  • Explicitly no local builds, tests, dev server, Docker or deployment. Source-level audit only, Git commit and approved Gitea main push. Gitea Actions testing deferred; no CI workflow in this scope.
  • Evidence and pending runtime acceptance: docs/P04-ACCOUNT-PORTAL.md.

P05-CI-01 - Gitea Actions Verification Foundation (APPROVED 2026-11-22)

  • Baseline 7ecf53169776cc7f08af3dde6fe4b4492acf3ea1.
  • Approved paths .gitea/**, tests/ci/**, narrow users/ui/package.json and lockfile, auth/ui/v2/pnpm-workspace.yaml and lockfile, notes/**, project/**, relevant docs/** and README.md; root MINIFEST.md is a documentation-maintenance exception. Backend/Account auth/UI source READ-ONLY.
  • Manual Gitea workflow: account reproducible build, Login frozen build, dependency audit, disposable Docker backend readiness/discovery. No local tests/build/dev server.
  • Full OIDC login/session/MFA/Admin Console interactive acceptance is not covered without disposable app/user provisioning; status remains BLOCKED/PENDING, not fabricated PASS.
  • Gitea Run #81: 2 PASS (Login V2 frozen build + 1219/1219 unit tests; high/critical audit) and 2 FAIL (Account Auth.js TypeScript TS2345; Docker Alpine checkout missing Git). 18 moderate advisories unresolved. Pre-checkout Git source fix applied after the run, not rerun. See notes/P05-CI-01.md and docs/P05-CI-01.md. No production deployment/release.

P05-CI-02 - Targeted Root-Cause Remediation (APPROVED 2026-11-22)

  • Baseline 42adaba0044ee5cb86e6e6bcfd4e00e5fe96ad00 (Gitea main).
  • Narrow write scope: users/ui/src/auth.ts, optional src/types/next-auth.d.ts, .gitea/workflows/p05-ci.yml, tests/ci/**, notes/**, project/**, relevant docs/**, associated CI README/MINIFEST, root navigation only if required.
  • B01 Auth.js TypeScript TS2345: real subject string narrowing, preserve PKCE/state/nonce, expiry and protected identity guard. B02: verify in-CI Docker checkout, disposable ZITADEL, PostgreSQL restart persistence and OIDC discovery/JWKS. B03: report real Moderate advisory IDs/package/fix; HIGH+ security threshold remains a failure gate. B04: negative OIDC metadata and anonymous Account Portal checks, with interactive user E2E explicitly deferred.
  • One manual Gitea Run #83: Account Portal, Login V2, security gates PASS; Docker health progressed to PostgreSQL/ZITADEL API/Login V2 healthy, but runner host 8080 collision blocked proxy, database persistence and discovery. Full CI acceptance BLOCKED. Post-run CI-only tests/ci/compose.portless.override.yaml clears inherited host port, not CI-verified. 18 Moderate Login + 1 Moderate Account audit record still open, no package changes. Exact evidence in notes/P05-CI-02.md, docs/P05-CI-02.md.

P05-CI-03 - Backend Runtime Final Acceptance (APPROVED 2026-11-22)

  • Baseline 485755800504a7dea6e4c303e6b39ec9cc610b54; prior Run #83 had 3 job PASS and backend FAIL due to runner host TCP 8080 collision.
  • Exact Write Scope: optional .gitea/workflows/p05-backend-acceptance.yml, narrow existing P05 workflow if justified, focused tests/ci/**, notes/project/docs, associated workflow README/MINIFEST and root navigation if needed. Core backend, developer Compose, Login V2, Account Portal, dependencies/locks and production config all READ ONLY.
  • Manual backend-only Gitea Actions acceptance: effective Compose proxy portless check, four-service health, disposable Postgres restart marker persistence, ZITADEL readiness/discovery/JWKS, malformed issuer/JWKS negative contracts and verified CI-only cleanup.
  • One focused isolated run after source commit/push, no local test/build/Docker, no repeated Account/Login suites, no real users/secrets or production deployment. Full interactive login/MFA remains a separate phase.
  • Gitea Actions Run #86 SUCCESS on 03fb58954dec886128a4011b6121754cbcdd79ff: portless effective config PASS, all four services ready, disposable PostgreSQL marker persisted after restart, ZITADEL ready/OIDC issuer/discovery/JWKS and negative contracts PASS, CI-owned network/containers/volumes cleanup verified PASS. No Account/Login build rerun, no local build/Docker. Full interactive OIDC login/MFA and Moderate dependencies remain outside this phase. Evidence: notes/P05-CI-03.md, docs/P05-CI-03.md.

P05-SEC-01 - Dependency Security Remediation (APPROVED 2026-11-22)

  • Baseline 1a602551ad9a791efcc594834f2fa6ce748339ae. Previous Run #83 security: 18 Moderate Login advisory records and 1 Moderate Account vulnerable Next.js package; Run #86 backend-only SUCCESS.
  • Narrow approved manifest writes: users/ui/{package.json,package-lock.json}, auth/ui/v2/apps/login/package.json, root auth/ui/v2/{package.json,pnpm-lock.yaml} only if justified; new .gitea/workflows/p05-security-acceptance.yml, focused tests/ci/**, notes/project/docs and associated README/MINIFEST. pnpm-workspace.yaml, application source, Go backend, developer Compose, production and unrelated files remain read-only.
  • Direct Next.js pinned 16.4.6; Login coordinated OTel auto-instrumentation 0.80.0 / SDK 0.222.0 family, PNPM/npm metadata-only lockfile reconciliation. Root overrides are read-only, so glob14/minimatch11 major transitive remediation remains an explicit blocker if registry audit reproduces it.
  • Gitea Run #87, tested SHA 752d243ae8fb24ce3cfa990343082e2d0431306b: 3 job PASS (Account npm frozen typecheck/build/anonymous regressions, Login pnpm frozen Nx build + 1219/1219 unit tests, Account security 0), Login security FAIL on 2 Moderate transitive advisories (glob and minimatch), High/Critical 0. Prior 19 reported records reduced to 2; full security acceptance BLOCKED. Only one CI run, no local app build/test/dev server, no backend/production change. Exact result: notes/P05-SEC-01.md, docs/P05-SEC-01.md.

P05-SEC-02 - Final Transitive Dependency Remediation (APPROVED 2026-11-22)

  • Baseline 43eee54e7ad6b647e38491ac4dc28703547cf410; prior Gitea Run #87: 3 PASS/1 FAIL, only 2 Login Moderate GHSA (glob/minimatch) remaining, Account audit 0.
  • Exact Scope Lock: auth/ui/v2/pnpm-workspace.yaml, pnpm-lock.yaml, justified root or Login dependency manifests only, .gitea/workflows/p05-security-acceptance.yml, focused tests/ci/**, notes/project/docs and associated README/MINIFEST. Login/auth/UI source, users/ui/, Go backend, developer Compose, other packages and production READ-ONLY.** Preserve untracked AI_INSTRUCTIONS.md.
  • Seven exact parent-scoped overrides: two glob10 parents → glob14.0.6, five minimatch10 parents → minimatch11.0.9. No broad global major override; pinned PNPM 10.30.3 metadata-only lockfile regeneration; compatibility subject to CI proof.
  • Actual Gitea Run #88, tested source SHA 66cfed5a8b6bd5845b229c9934695e307f9a0775, overall FAILURE: Account jobs correctly SKIPPED, Login live production audit 0 Moderate/High/Critical PASS; Login build job FAIL before frozen install because new contract helper falsely treated existing >= semver ranges as parent overrides. No frozen install/build/units executed in this run. Corrected parser to recognize exact >glob or >minimatch selectors after the run, not CI-verified. Full security/compatibility acceptance BLOCKED pending separately approved focused CI; one run only, no local app builds/tests or deployment. Exact evidence: notes/P05-SEC-02.md, docs/P05-SEC-02.md.

P05-SEC-02-A01 — Login Build & Security Final Acceptance (APPROVED 2026-11-22)

  • Baseline 7655dbdcb48c49aab8f3bf97aab8f1867f129531. Previous Run #88 security 0 Moderate/High/Critical; Login frozen/build/unit unexecuted due CI helper >= selector false-positive. Corrected parser is committed but not yet CI-verified.
  • Exact Scope Lock: tests/ci/transitive_override_contract.py and .gitea/workflows/p05-security-acceptance.yml only if a NEW exact validator/CI defect is reproduced; notes/**, project/**, relevant docs/**, associated README/MINIFEST for evidence. All PNPM lock/config/manifests, original Login/UI/auth, Account Portal, ZITADEL backend, Compose, production and unrelated files read-only. Preserve untracked AI_INSTRUCTIONS.md.
  • Run #89 ACCEPTED/SUCCESS: tested SHA ff4c58ed861474061c8f045be3a9f0752caf6ca0. Existing corrected override validator PASS, seven parent pins + patched lock contract PASS; PNPM 10.30.3 frozen install PASS; Nx proto/client/Login 16.4.6 standalone production build PASS; upstream Vitest 84/84 files and 1219/1219 tests PASS. Live production pnpm audit --prod: 0 Moderate/High/Critical. Login jobs #194/#196 SUCCESS; Account jobs #193/#195 SKIPPED intentionally. One CI run, no local app test/build, no source/lock/deploy changes. Interactive OIDC/MFA/Admin Console login still unverified. Exact evidence: notes/P05-SEC-02-A01.md, docs/P05-SEC-02-A01.md.

P05-OIDC-01 — Disposable Real OIDC Login/Session Acceptance (APPROVED 2026-11-22)

  • Baseline f423c696544f28a42d6a5d1ad0acfd88a3b6f56d, prior Run #86 disposable backend, Run #87 Account and Run #89 Login build/security PASS. Real OIDC positive callback/session still unverified.
  • Exact Write Scope: new .gitea/workflows/p05-oidc-acceptance.yml, focused tests/ci/oidc_e2e/** and narrow CI-only helpers, notes/**, project/**, relevant docs/**, associated README/MINIFEST and root navigation. Original P02 Compose/backend, original Login V2/auth UI, Account Portal Auth.js/UI, all package manifests/locks, production and unrelated files READ ONLY. Preserve untracked AI_INSTRUCTIONS.md.
  • Pre-change plan notes/P05-OIDC-01.md documents official IAM_OWNER bootstrap PAT (not the Login-client PAT), disposable project/real OIDC Web client and human, original Login V2 Chromium password flow, Auth.js PKCE/state/nonce, positive Account API/session and anonymous/invalid negatives, and mandatory run-owned secret/Compose cleanup. No public host ports. Existing HTTP localhost issuer requires development only in the disposable CI container, not a production TLS acceptance.
  • One manual Gitea Actions CI cycle; no local app installs/builds/tests/dev servers or production deployment, no fake login/session or identity bypass. Exact real job results required for PASS. docs/P05-OIDC-01.md, project/OIDC-E2E-ARCHITECTURE.md.

P05-OIDC-02 — Private Loopback Forwarder Remediation & Real Browser OIDC Acceptance (APPROVED 2026-11-22)

  • Baseline b78270e9d45c1764c5642024b8147885deaacde3. Run #90 tested cbcd60e, four backend services healthy and host portless, but CI-only localhost:8080 sidecar not ready; project/client/user/browser tests NOT RUN; owned teardown PASS. Root cause not established by previous logs.
  • Exact Write Scope: tests/ci/oidc_e2e/run.sh, justified provision.py and optional cleanup.sh, optional .gitea/workflows/p05-oidc-acceptance.yml, notes/**, project/**, relevant docs/**, associated README/MINIFEST only if required. Original backend/dev Compose, Login V2, Account Portal, manifests/locks, production and unrelated files READ-ONLY. Preserve untracked AI_INSTRUCTIONS.md.
  • Pre-change notes/P05-OIDC-02.md: before provisioning probe private 127.0.0.1:80 proxy/Host HTTP 200; replace runtime apk add with published versioned alpine/socat:1.8.1.3, verify preinstalled entrypoint + digest and run by immutable digest; inspect sidecar state/exit and require private forwarded 127.0.0.1:8080 HTTP 200; fix only the provisioner's status-only readiness without touching official API/secret checks. Existing owned-only cleanup unmodified.
  • Actual single Gitea Run #91: tested 4831165548feabc2c0a0d39d25c40e0d1bc23bb2, overall FAILURE. 4-service backend health, no-host-ports, private Traefik:80 Host-routing HTTP 200, socat version/entrypoint/digest checks PASS. socat sidecar exited (code 1) before localhost:8080 readiness; no project/client/human or real Chromium/PKCE/callback/session tests executed. Always-run owned cleanup PASS. Root cause inside socat process not proven without safe startup stderr diagnostics. NO rerun, local app tests or production changes. Follow-up P05-OIDC-03 requires separate exact approval, not auth bypass. notes/P05-OIDC-02.md, docs/P05-OIDC-02.md.

P05-OIDC-03 — Forwarder Process Diagnosis and Real OIDC Acceptance (APPROVED 2026-11-23)

  • Baseline 5f542a6aa376d06ba2c1fd3d46835baae9b8654e. Gitea Run #91 proved 4 healthy services, private proxy Host route and prebuilt socat digest PASS, but socat exited 1; project/client/human/browser NOT EXECUTED; cleanup PASS. Actual socat stderr root cause unverified.
  • Exact write scope: tests/ci/oidc_e2e/run.sh, optional new forwarder.py because Run #91 proved socat unreliable; provision.py / cleanup.sh ONLY if a separately reproduced narrow defect; notes/**, project/**, relevant docs/** and associated README/MINIFEST navigation. Original backend/Compose, Login V2, Account Portal, browser scripts, manifests/lockfiles and production READ-ONLY. Preserve untracked AI_INSTRUCTIONS.md.
  • Actual dispatch: one manual Gitea Run #93, tested SHA 7b80f411b2981e2274d171c12596301ed757b768, job #206 QUEUED at last inspection, no job start, no steps/cleanup and no conclusion. Nothing authenticated verified yet. Source prepared with allowlisted socat startup error classification and one same-run immutable official Python TCP fallback; original provisioning/Chromium/PKCE/state/nonce/Account and cleanup untouched. No second dispatch, local app tests or production deployment. Read-only terminal evidence from this same run must determine PASS/FAIL. notes/P05-OIDC-03.md, docs/P05-OIDC-03.md.

P05 - Full Integration (proposed, NOT approved)

Shared design system, production-safe Compose topology and verified Login/Account OIDC wiring. No live deployment; separate approval.

P06 - UI redesign (proposed, NOT approved)

Compact login and account UI, accessibility, responsive design and scoped regressions. Protected authentication semantics unchanged.

P07 - Production deployment (proposed, NOT approved)

Coolify, HTTPS, secrets, backups, durable storage and focused production readiness; explicit approval required.

P05-OIDC-01 actual acceptance result — 2026-11-22

  • Approved baseline f423c696544f28a42d6a5d1ad0acfd88a3b6f56d; tested source commit cbcd60e76ec909df4f9c5826adf7a3e2a899c73e.
  • One Gitea Actions Run #90, job #197, overall FAILURE. Repo checkout/Docker preflight PASS, no published host ports PASS, official four-container disposable backend startup/health PASS.
  • Blocker: private run-owned localhost:8080 forwarder did not become ready in bounded 70 seconds; no admin API project/client/human provisioning or Chromium PKCE/state/nonce/callback/session/negative tests were executed. Exact sidecar cause unknown with current suppressed diagnostics. Interactive OIDC acceptance BLOCKED.
  • Safety PASS: mandatory always() cleanup step succeeded: ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS, ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS. No production users/secrets/ports/deployment affected.
  • No local application tests/builds, no second Gitea run, no original backend/Login/Auth.js source/manifest edits. Next P05-OIDC-02 requires separate exact scope approval limited to CI-only forwarder readiness/observability, then one new isolated full OIDC run. Full evidence notes/P05-OIDC-01.md, operator guidance docs/P05-OIDC-01.md.

P05-OIDC-03-A01 — Existing Run #93 Terminal Acceptance & Queue Audit (APPROVED 2026-11-23)

  • Exact approved baseline 09add5345abc5cef676ab7f5d3220eaa641310b4; existing Run #93 tested candidate 7b80f411b2981e2274d171c12596301ed757b768, job #206. Read-only Gitea run/job status QUEUED with no steps or true timestamps; job log returned 404 job not started. Manual workflow is active with ubuntu-latest label, but current runner registration/online/capacity cannot be read through available connector. Historic Run #91 succeeded in being scheduled, not proof of current availability.
  • Only existing Run #93 may be checked; no additional dispatch, rerun, cancellation, runner config updates, workflow/backend/Login/Auth.js/CI source edits, local builds or production/real accounts. Exact write scope only notes/**, project/**, relevant docs/**, associated README/MINIFEST and navigation when necessary.
  • Every Run #93 gate is NOT EXECUTED: Git checkout, disposable backend/forwarder/provisioning, browser PKCE/state/nonce/Auth.js callback/session, positive/negative authorization, logout and mandatory owned cleanup. The only correct acceptance statement is PENDING / NOT VERIFIED, not test FAILURE or PASS.
  • Next narrow task: read-only check whether this same Run #93 is scheduled/completed and inspect authorized Gitea runner online/label/capacity state, without modifying runners or dispatching more jobs. Terminal evidence, if it becomes available, must be documented before claiming positive OIDC acceptance. Evidence: notes/P05-OIDC-03-A01.md, operator guidance: docs/P05-OIDC-03-A01.md.

P05-OIDC-03-A02 — Existing Run #93 terminal RCA (APPROVED; 2026-11-23)

  • Baseline 88911c5d685ed4d068e6361d5e920108c217046f. One existing Run #93, immutable tested SHA 7b80f411b2981e2274d171c12596301ed757b768, job #206 eventually scheduled/executed, overall FAILURE at 18:37:47 UTC on 2026-11-22. Earlier A01 queued snapshot was true then, but is superseded by this terminal result. Workflow requests ubuntu-latest; current runner online/labels/capacity details still unavailable through connector, but job pickup proved for this run.
  • PASS: checkout and Docker preflight, no host ports, four healthy backend/Postgres/Login V2/Traefik services, direct private proxy Host HTTP 200, pinned image/digests and mandatory owned-only cleanup.
  • FAIL: socat process exited 1, SOCKET_BIND_ERROR; same-run Python forwarder exited 1, ADDRESS_IN_USE on private TCP 127.0.0.1:8080. Exact listener identity/port owner not yet established. NOT EXECUTED: real client/project/human, Chromium original Login V2, PKCE/state/nonce/Auth.js callback/session, protected identity, negatives and logout. Full authenticated OIDC BLOCKED.
  • Exact A02 write scope only notes/**, project/**, relevant docs/**, associated README/MINIFEST; all CI/auth/backend/Compose/workflow/runner/source/locks/production strictly read-only. No local app tests, second run, tags/releases, real users or production. Evidence notes/P05-OIDC-03-A02.md, operator guide docs/P05-OIDC-03-A02.md. Next proposed P05-OIDC-04: disposable namespace-local port-8080 listener RCA, separately approved narrow CI-only remediation and one fresh isolated full OIDC acceptance.

P05-OIDC-04 — Private socket forensics and isolated forwarder (terminal 2026-11-23)

  • Baseline 89bc3f2; scoped pre-source note and CI-only source 79dac4f5bb76e1cee4dfaf61657c6e84268b3dfb in tests/ci/oidc_e2e/{run.sh,forwarder.py} were pushed. No original backend/Compose/Login/Auth.js/workflow/dependency modifications, no public host port.
  • Single authorized Gitea Run #95 / job #209 FAILURE after checkout, portless config and four healthy backend services PASS. Direct proxy:80 Host readiness failed with OIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKED before the 8080 listener inspector or new forwarder ran. Real project/client/human/browser/Auth.js/negatives/logout NOT EXECUTED. Mandatory owned-only teardown PASS.
  • The exact Run #93 8080 listener owner remains UNKNOWN. No retry. Next proposed P05-OIDC-04-A01 strictly diagnoses direct private proxy socket/HTTP readiness first in another separately approved disposable cycle. Evidence: notes/P05-OIDC-04.md, operator guide: docs/P05-OIDC-04.md.