docs(oidc): scope lock A01 direct private readiness RCA before CI source edit

This commit is contained in:
victorsteele428 committed 2026-11-22 20:12:37 +00:00
1 parent 443dfcf5d1
commit 53b258d571
1 file changed
+30
+30
View File
@@ -0,0 +1,30 @@
# P05-OIDC-04-A01 — Direct Private Proxy Readiness RCA & Real OIDC Acceptance
**Date:** 2026-11-23 (Asia/Dhaka)
**Approved immutable baseline:** `443dfcf5d1ecb6f6f5c04cada32aafa17d7d823e`
**Previous tested source:** `79dac4f5bb76e1cee4dfaf61657c6e84268b3dfb`
**Previous evidence:** [Gitea Run #95](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/95), job #209, terminal `failure`. Docker/config and four backend health PASS; direct private Traefik readiness emitted `OIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKED`; 8080 socket forensic probe, forwarder and official authenticated user/browser flow NOT EXECUTED; owned-only mandatory cleanup PASS.
## PRE-SOURCE-CHANGE EXACT Scope Lock
This scope note MUST be committed **before any A01 source change**.
- **Source WRITE:** `tests/ci/oidc_e2e/run.sh` only; at most one new tightly focused `tests/ci/oidc_e2e/` diagnostic helper if technically necessary.
- **Documentation WRITE:** `notes/**`, relevant `project/**` and `docs/**`, associated README/MINIFEST/navigation as strictly required.
- **STRICT READ-ONLY:** `tests/ci/oidc_e2e/forwarder.py`, every other existing `tests/ci/**` file, `.gitea/workflows/**`, `core/backend/zitadel/**`, `deployment/docker/**`, `auth/ui/v2/**`, `users/ui/**`, original Account/Auth.js, package manifests and lockfiles, runner configuration, production/secrets, and unrelated paths.
- Preserve existing untracked root `AI_INSTRUCTIONS.md`. No local application build, test or server; no real human, production deployment, tag, release, workflow modification or privileged/public port.
- **ONE** approved manual disposable Gitea CI run after focused source/security diff audit; no additional dispatch or rerun, and mandatory original `always()` owned-only cleanup. Source-test SHA must be distinguished from later docs-only SHA.
## Focused read-only RCA before edits
The direct pre-forwarder probe in `run.sh` currently executes `python:3.12-alpine` in `--network container:$proxy_id`, issues `GET /debug/ready` to private `127.0.0.1:80` with exact `Host: localhost:8080`, and maps **every** `OSError` and `http.client.HTTPException` to the single `OIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKED` marker. It already distinguishes a returned **non-200 HTTP status** numerically, but not connection refusal, network timeout, reset, permission, protocol failure or which exception occurred. Therefore Run #95 establishes **a failed direct private readiness check** but not an exact listener/port root cause, actual 8080 owner, failed Docker network or authentication defect. Four healthy services do not prove this exact network-namespace HTTP route; prior Run #93 did pass the same direct route, so intermittency is possible but not established. Avoid claiming any specific culprit.
## Locked minimal change and verification plan
1. Replace *only* this bounded pre-forwarder probe with explicit, secret-safe exception categories (CONNECTION_REFUSED, TIMEOUT, CONNECTION_RESET, NETWORK_UNREACHABLE, PERMISSION_DENIED, SOCKET_OTHER, HTTP_PROTOCOL_ERROR); print only enumerated class or integer HTTP status, never exception text, URL, response body, secrets, tokens, cookies, argv/env or raw logs. Close the HTTP connection in all branches.
2. Permit at most a short, strictly bounded retry only **after** a first *classified transient socket failure*, never on explicit HTTP non-200, permission, unknown or protocol failure. Preserve a deterministic single success/failure marker and exact Host/issuer, same isolated network, unchanged user/client/auth flows and existing ownership/cleanup.
3. Audit the exact diff: only `tests/ci/oidc_e2e/run.sh`; validate bounded control flow, no logging sensitive values, no public ports or auth weakening; Gitea main source commit and verify exact SHA. No local app run/test/build.
4. Dispatch **one** authorized existing `p05-oidc-acceptance.yml` workflow on `main` and confirm immutable tested SHA. Record verified Run/Job, all gate-level PASS/FAIL/NOT EXECUTED, pre-bind socket attribution if actually reached, forwarder, issuer, official client/user creation, Chromium/Login V2/PKCE/state/nonce/Auth.js session/API/negative/logout, mandatory exact-owned cleanup.
5. Final documentation-only update in `notes/**`, `project/**`, `docs/**` and manifests/navigation, a focused git diff/safety/inventory audit, documentation commit and exact remote main SHA verification. No second run even if the first fails. Supply next narrow exact scope and copyable approval text based on actual evidence.
**Initial A01 acceptance:** NOT EXECUTED. Real authenticated OIDC remains BLOCKED pending the one new real terminal Gitea result.