7.7 KiB
ZitPlane — Troubleshooting and safe diagnostics
Scope: Only describe issues the current source or recorded phase evidence supports. Run #86 verified an isolated disposable backend, but no developer-PC environment or production deployment has been verified.
| Symptom | Known possible cause | Safe next action |
|---|---|---|
docker command not found |
Docker CLI/Desktop was missing on the previously inspected Windows host during P02 | Install supported Docker Engine/Desktop and run only in a local disposable environment; do not treat a source manifest as runtime acceptance |
docker compose config / up fails |
Local machine Docker/config differences or occupied port may differ from validated CI stack | Gitea Run #86 verified isolated portless CI Compose; check environment-specific logs with secrets redacted; do not confuse its portless override with P02 local loopback Compose |
| Admin Console login fails | First-instance bootstrap, Login V2 container/PAT, auth proxy or credentials not validated | Verify local health, first-init logs and policy in a secret-safe environment; do not reinitialize volumes casually |
| Account Portal shows no page | App dependencies are not installed; no Account Portal image, runtime or domain is configured | Complete reviewed lockfile/build/CI and explicit integration phase before troubleshooting live UI |
| Redirect/callback error after future login | OIDC issuer/callback URL, client type/secret, proxy headers, PKCE/state or allowed redirect may mismatch | Compare exact configured origins and registered callback; never weaken checks or wildcard redirects |
Unauthorized on /api/account/me |
Designed result for absent/expired user identity | Authenticate through ZITADEL; if unexpected in a future runtime, inspect token expiry and session trace securely |
| Profile Save button missing | Portal source has read-only fields only | Use permitted ZITADEL self-service (if configured) or wait for an approved custom edit feature |
| MFA/passkey settings not editable in portal | Portal only shows informational cards and a link | Use the identity provider's policy-supported controls; do not paste secrets into support messages |
| Sign-out seems to leave other applications signed in | Portal signOut is portal-local, not federated logout |
Close respective sessions via app/identity provider; global logout requires a future dedicated implementation |
auth.vib.tools / account.vib.tools unavailable |
They are planned hostnames, no production deployment configured | Do not assume DNS/SSL/Coolify service exists; await P07 |
| Login V2 custom source appears unchanged when starting P02 Compose | P02 Compose uses prebuilt official Login UI, not P03 imported code | Later P05 must build and wire custom image after CI and explicit approval |
How to report a safe issue
Include environment (local disposable vs CI vs production), exact phase/commit, which page/action, a redacted error and reproduction conditions. Never publish .env, client secret, passwords, access tokens, cookies, private keys or user data. Link to relevant phase note; record the fix and updated user guidance together.
P05-CI-02 verification and error boundaries
- Prior Account Portal
TS2345atsrc/auth.ts(14,61)in Gitea Run #81 was fixed by verified JWT subject narrowing; Gitea Run #83 Account Portal typecheck/build PASS. - Previous Alpine backend checkout missed Git; Run #83 verified the fix. Run #83 also exposed an occupied shared-runner host TCP 8080. Run #86 verified the portless CI Compose overlay: all four services ready, disposable Postgres restart persistence, ZITADEL ready/OIDC discovery/JWKS and complete CI-only cleanup PASS. This does not prove the separate P02 local PC Compose or real user login.
- A green HIGH/CRITICAL advisory audit gate still allows Moderate findings. P05-SEC-01 updates only approved Next.js/OTel dependency manifests and lockfiles and adds an independent zero Moderate/High/Critical acceptance gate. Potential
glob/minimatchtransitive major-version issues remain open until a real registry CI audit proves otherwise; no suppressions or forced compatibility-breaking overrides. - CI negative access tests do not simulate real login; actual OIDC app registration/authorized login/MFA must receive separate approval.
Known limitations
Account Portal and Login V2 build CI passed in Run #83, disposable backend acceptance passed in Run #86, and dependency lockfiles/workflows exist. Real authenticated OIDC callback/positive session, MFA/passkey, Admin Console human login, production Coolify/TLS/backup and production support remain UNVERIFIED. Preserve the Scope Lock in notes/ and ZITADEL security boundaries.
P05-SEC-01 exact security-blocker troubleshooting
Gitea Run #87 produced 3 PASS and 1 FAIL. The FAILED security_login job is a deliberate fail-closed Moderate threshold: GHSA-3g3m-2fjr-6pw4 in glob (fix >=14.0.2) and GHSA-g3hv-75wg-m249 in minimatch (fix >=11.0.1). Account npm audit returned 0. Login's earlier Next.js/OTel advisories no longer reproduce, its frozen build and 1219 tests PASS, and High/Critical remain 0. Do not turn off auditing, ignore Moderate reports, modify protected auth code or force incompatible package majors. A separate P05-SEC-02 exact Scope Lock must allow controlled PNPM workspace overrides or verified compatible parent upgrades; only a new focused CI run can close security acceptance.
P05-SEC-02 — scoped major transitive override troubleshooting
If a frozen Login install, Nx build or unit suite fails after this patch, verify the seven exact parent@version>dependency selectors in auth/ui/v2/pnpm-workspace.yaml and the matching pnpm-lock.yaml snapshots; compare with notes/P05-SEC-02.md. glob@14 and minimatch@11 are semver-major transitive substitutions, so historical parents expecting v10 APIs may need a separately approved compatible parent upgrade. Do not apply global overrides, blanket pnpm audit --fix, disable the strict zero-Moderate gate, or edit protected Login authentication code. Full security acceptance requires current CI frozen install/build/Vitest and registry audit, not just a clean lockfile.
P05-SEC-02 Run #88: false-positive override validation (not a runtime failure)
Run #88 Login build job #190 stopped before pnpm install --frozen-lockfile when the new transitive_override_contract.py classified old axios@>=... / brace-expansion@>=... / esbuild@>=... selectors as extra parent overrides. The regex was narrowed after the run to accept only direct >glob or >minimatch overrides. This fix has not been tested by CI. Independent Login production security audit job #192 passed with 0 Moderate, 0 High, 0 Critical; do not confuse that security result with an authenticated login, a production deployment, or a successful frozen build. A separate, explicitly approved Gitea CI run is required for complete Login dependency compatibility acceptance.
P05-SEC-02-A01 — Run #88 validator false-positive closed in Run #89
The earlier Run #88 CI helper misread axios@>= and similar version-range keys as parent overrides. The already-committed suffix-only >glob / >minimatch correction passed in Gitea Run #89, followed by successful frozen PNPM install, original Login Nx production build and 1219/1219 unit tests. The production registry vulnerability audit also passed with 0 Moderate/High/Critical. The prior false-positive is now CI-verified resolved; no repeat local test or production deployment. If future login failures occur, distinguish CI build/unit success from still-untested authenticated OIDC/callback/MFA integration.