# 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 `TS2345` at `src/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`/`minimatch` transitive 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.