docs(oidc): scope lock P05-OIDC-04 before source remediation

This commit is contained in:
victorsteele428 committed 2026-11-22 19:39:08 +00:00
1 parent 89bc3f21af
commit 1cf6d65f04
1 file changed
+29
+29
View File
@@ -0,0 +1,29 @@
# P05-OIDC-04 — Private Port-8080 Listener RCA & Real OIDC Acceptance
**Date:** 2026-11-23 (Asia/Dhaka)
**Approved baseline:** `89bc3f21af53e481c68ee06c8eb120e30b855038`
**Prior CI evidence:** Gitea [Run #93](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/93), job #206, source `7b80f411b2981e2274d171c12596301ed757b768` — completed FAILURE. Healthy backend/proxy PASS; socat `SOCKET_BIND_ERROR`, Python fallback `ADDRESS_IN_USE` on private port 8080; client/user/browser NOT EXECUTED; owned-only cleanup PASS.
## PRE-SOURCE-CHANGE Scope Lock and plan
This note is committed **before the P05-OIDC-04 source edit**.
- **Source write:** `tests/ci/oidc_e2e/run.sh`; `tests/ci/oidc_e2e/forwarder.py` only for necessary target selection; at most one isolated helper in `tests/ci/oidc_e2e/` if justified.
- **Docs write:** `notes/**`, relevant `project/**`, `docs/**`, associated README/MINIFEST where necessary.
- **Strict read-only:** `.gitea/workflows/**`, `core/backend/zitadel/**`, `deployment/docker/**`, `auth/ui/v2/**`, `users/ui/**`, original Account/Auth.js, package manifests and locks, Gitea runner configuration, production and secrets, unrelated files.
- Preserve untracked root `AI_INSTRUCTIONS.md`. No local build, app tests, dev servers, real humans, production deployments, tags, releases or auth bypass.
- **CI budget:** one newly approved manual isolated workflow dispatch, no rerun/repeat, and mandatory existing `always()` owned-only cleanup.
## Read-only RCA baseline
The CI-only run script starts both its socat and fallback sidecars with `--network container:$proxy_id`; each binds IPv4 `127.0.0.1:8080`. Because they reuse the **same Traefik network namespace**, a pre-existing listener there makes *both* impossible to start. The original developer Compose routes Traefik web at `:80` and ZITADEL API at `:8080` in **a different service namespace**; which process, if any, owned proxy-local TCP 8080 in Run #93 is UNKNOWN. Run #93 resource teardown is already verified, so a retrospective namespace socket/proc inspection is impossible.
## Approved focused implementation
1. Before any forwarder bind, inspect `/proc/net/tcp{,6}` inside the disposable proxy network namespace, and correlate TCP LISTEN port 8080 socket inodes with `/proc/*/fd` and `/proc/*/comm` inside the same proxy PID namespace. Emit only bounded numeric inodes/PIDs and sanitized process name/status; no argv, environment, HTTP requests, tokens, payloads or raw logs. Record `NONE` or `UNKNOWN` faithfully; don't invent an owner.
2. Resolve confirmed **shared namespace bind contention** by using the already-disposable private Compose Docker network for a dedicated run-labeled forwarder namespace (not the proxy's namespace). Forward opaque bytes from its loopback `127.0.0.1:8080` to private DNS `proxy:80`, never a host-published port. This preserves original `http://localhost:8080` issuer/Host requirements. Provisioning and Chromium/Account containers join the forwarder's namespace instead of Traefik's. Unmodified original Compose, Login V2, Auth.js and negative-test contract remain in effect.
3. Validate exact private HTTP 200 *before* ephemeral credentials/client/user creation; check image immutable digest/entrypoint, isolated resource ownership and mandatory teardown.
4. One focused source/security/diff audit and Gitea main commit/push. Dispatch ONE authorized Gitea workflow acceptance run on exact tested SHA. Inspect actual run/job log and PASS/FAIL/NOT EXECUTED gates for Docker, socat/fallback, private 200, official project/client/user, real Chromium Login V2, S256 PKCE/state/nonce, genuine Auth.js session/protected page/API, negative cases, logout and all owned cleanup.
5. Final docs-only synchronization and Git main/remote SHA verification without new CI. If blocked, distinguish the exact failure and downstream unexecuted gates; do not claim authenticated acceptance or a listener owner absent reliable evidence.
**Pre-run disposition:** Not yet executed in P05-OIDC-04; real authenticated OIDC remains BLOCKED pending one terminal disposable CI result.