fix(ci): pin and diagnose private OIDC forwarder readiness

This commit is contained in:
victorsteele428 committed 2026-11-22 17:45:36 +00:00
1 parent b78270e9d4
commit 4831165548
22 files changed
+231 -27

No files matched your search

+1
View File
@@ -14,6 +14,7 @@ Compact, developer-friendly monorepo for a central identity service, a branded l
- **P05-SEC-02:** Seven parent-scoped PNPM overrides resolved `glob`/`minimatch` advisories. Gitea Run #88 Login production audit **0 Moderate/High/Critical PASS**, but Login frozen install/build/units **NOT RUN** because a new CI override validator misparsed existing `>=` version ranges; post-run regex correction **not CI-verified**. Full acceptance **BLOCKED** pending a separately approved focused CI run. Account jobs intentionally skipped. See `docs/P05-SEC-02.md`.
- **P05-SEC-02-A01:** **Gitea Run #89 SUCCESS** on `ff4c58e`: corrected exact override contract PASS, pinned PNPM frozen install PASS, official Login V2 standalone build PASS, upstream Vitest **1219/1219 PASS**, Login production audit **0 Moderate/High/Critical**; Account jobs skipped. **Dependency security/build unit acceptance complete; real user OIDC/MFA E2E and production integration NOT verified**. See `docs/P05-SEC-02-A01.md`.
- **P05-OIDC-01:** Gitea **Run #90 FAILED**: disposable four-service ZITADEL stack healthy and host-portless, but private `localhost:8080` loopback forwarding was not ready. Provisioning aborted before OIDC client/human/browser creation; real callback/session **NOT verified**. Owned database/bootstrap/secret/network cleanup **PASS**. No app/auth source change or deployment. See `docs/P05-OIDC-01.md`.
- **P05-OIDC-02:** Approved targeted CI-only forwarder remediation after Run #90: versioned prebuilt socat verified and digest-pinned on runner, private proxy and listener status/HTTP 200 gate, correct provisioner status-only readiness; **real OIDC CI pending**, no app/auth source changes. See `docs/P05-OIDC-02.md`.
- **Production / Coolify:** not configured or deployed.
## Documentation and project knowledge
+3
View File
@@ -33,3 +33,6 @@ Future feature additions need an evidence-backed status update here, an exact de
**P05-OIDC-01 terminal status:** Gitea Run #90 (`cbcd60e`) is **overall FAILURE**: disposable backend 4/4 healthy and portless PASS, but private localhost:8080 forwarder unready, blocking all OIDC project/client/human and real browser callback/session/negative tests. **Nothing authenticated was verified.** `always()` cleanup succeeded and verified no owned containers/volumes/network/credentials remained. Future P05-OIDC-02 needed; production/MFA remains untested.
**P05-OIDC-02 source prepared:** CI-only prebuilt/digest-pinned socat, isolated proxy/Host and forwarded HTTP readiness gates, and strict status-only provisioner readiness have been added after the Run #90 blocker. **Full browser/OIDC acceptance is still UNVERIFIED until one new terminal Gitea CI**. Backend and previous Login build/unit/security PASS are not real authenticated session proof.
+1
View File
@@ -14,6 +14,7 @@ Every file listed below is a direct child of `docs/`. Add/remove rows whenever t
| [P05-SEC-02.md](P05-SEC-02.md) | Seven scoped PNPM parent overrides, patched lock and manual Login-only security CI evidence | P05-SEC-02 / Run #88 partial: security zero, build unverified |
| [P05-SEC-02-A01.md](P05-SEC-02-A01.md) | Gitea-only Login V2 full frozen-install/build/units/zero-advisory acceptance and status | P05-SEC-02-A01 / Run #89 SUCCESS |
| [P05-OIDC-01.md](P05-OIDC-01.md) | How isolated real OIDC Login V2 browser/session checks work; real CI status/limitations | P05-OIDC-01 / Run #90 BLOCKED before provisioning; cleanup PASS |
| [P05-OIDC-02.md](P05-OIDC-02.md) | CI-only pinned prebuilt forwarder, safe private localhost readiness diagnostics and actual real-OIDC acceptance evidence | P05-OIDC-02 / source prepared, CI pending |
| [SETUP-GUIDE.md](SETUP-GUIDE.md) | Operator/developer prerequisites, configs, activation and safety | DOCS-01 / active; runtime pending |
| [FEATURES-STATUS.md](FEATURES-STATUS.md) | Exact implemented/unavailable/unverified feature matrix | DOCS-01 / active |
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Known blockers and safe diagnosis based on source status | DOCS-01 / active |
+3
View File
@@ -33,3 +33,6 @@ Authorize and dispatch the **one** manual workflow under Gitea [ZitPlane Actions
**Safety verified:** `always()` step #3 succeeded: `ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS` and `ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS`, removing only owned database/bootstrap/containers/credentials/volumes/network. No production deployment, real accounts or host ports used.
**Next:** The precise reason the forwarder failed is **not yet known** because package installation/logs were suppressed. A separately approved P05-OIDC-02 should instrument the *CI-only* sidecar's safe health/exit diagnostics and use a pinned prebuilt forwarding image, then repeat **one** isolated Gitea browser/provisioning acceptance. No Login/Auth.js source edit, IAM bypass, production HTTP or claims of verified browser authentication. Full job IDs, evidence and Scope Lock: `notes/P05-OIDC-01.md`.
**Follow-up:** P05-OIDC-02 is the approved, CI-only private forwarder diagnostics/prebuilt-image and status-only readiness remediation; see [P05-OIDC-02.md](P05-OIDC-02.md). Until the new Gitea CI actually executes real client/user/Chromium/callback stages successfully, this historical Run #90 failure remains unchanged.
+24
View File
@@ -0,0 +1,24 @@
# P05-OIDC-02 — Private Loopback Forwarder & Real OIDC Acceptance
**Date:** 2026-11-22
**Baseline:** `b78270e9d45c1764c5642024b8147885deaacde3`
**Gitea Run #90:** overall **FAILURE** on `cbcd60e76ec909df4f9c5826adf7a3e2a899c73e`: four disposable services healthy, no host ports; private loopback localhost:8080 not ready; no client/user/browser test executed. **Owned cleanup PASS.**
**P05-OIDC-02 status:** narrow CI-only source remediation implemented; **actual new Gitea run pending**. No claim of fixed runtime or authenticated OIDC prior to terminal evidence.
## Source changes
The existing manual Gitea workflow `.gitea/workflows/p05-oidc-acceptance.yml` is reused; original backend, P02 developer Compose, official Login V2 application, Account Portal Auth.js/source, and all manifests/lockfiles stay unchanged.
In `tests/ci/oidc_e2e/run.sh` only, the runner now distinguishes:
1. **Private proxy/Host readiness**: a disposable Python container sharing Traefik's isolated network namespace makes `GET /debug/ready` on `127.0.0.1:80` with the exact `Host: localhost:8080`; HTTP 200 required before the forwarder.
2. **Verified prebuilt forwarding binary**: Docker Hub versioned `alpine/socat:1.8.1.3` (preinstalled `socat`; no runtime `apk add`). The CI runner verifies the `socat` entrypoint, resolves the pulled version to its immutable registry `sha256` image digest and starts the run-owned sidecar **by digest**; no `latest` image. This image is published by the `alpine/socat` project; see [Docker Hub repository](https://hub.docker.com/r/alpine/socat), [exact versioned tags](https://hub.docker.com/r/alpine/socat/tags).
3. **Private forwarder readiness and failure evidence**: the sidecar shares only the CI proxy network namespace and binds **127.0.0.1:8080**, forwarding to namespace-local Traefik:80. The runner checks exact labeled Docker sidecar state/exit code and makes a bounded no-secret `/debug/ready` HTTP 200 probe on forwarded port 8080 using `Host: localhost:8080`. A failed probe stops **before** provisioning and prints only safe stage/status, not token/cookie/query/sensitive HTTP bodies.
4. **Provisioner status-only readiness**: `tests/ci/oidc_e2e/provision.py::wait_until_ready()` checks HTTP 200 from the private issuer. It no longer attempts to parse the readiness body as JSON. Actual official API project/client/human creation continues to parse validated JSON and must not bypass authentication.
5. **Cleanup**: unchanged existing `tests/ci/oidc_e2e/cleanup.sh` still enforces numeric Gitea run ownership, exact sidecar/secret labels, backend Compose cleanup, and complete absence verification. No host published ports.
## How acceptance is determined
The single already-approved manual Gitea workflow `p05-oidc-acceptance.yml` must prove private proxy/forwarder readiness **and then** actual official client/user provisioning, original Login V2 Chromium password flow, genuine Auth.js authorization-code PKCE/state/nonce callback, protected Account session and API user ID, anonymous and invalid callback rejection, local sign-out, and successful mandatory owned cleanup.
If any check is blocked, document exact job/run/stage and **do not claim PASS for unexecuted steps**. One Gitea cycle only; no repeat or local tests. No screenshots, real accounts, private secrets, production deployment, MFA/passkey or production HTTPS acceptance. Detailed plan/evidence: `notes/P05-OIDC-02.md`. Developer design: `project/OIDC-E2E-ARCHITECTURE.md`.
+6
View File
@@ -76,6 +76,12 @@ Implement one explicitly approved phase at a time. Keep out-of-scope files, exis
- 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.
- **Exactly ONE manual Gitea CI run** to verify real disposable project/client/human + original Login V2 Chromium → Auth.js PKCE/state/nonce/callback/session/negative checks + mandatory owned cleanup. No local app tests, no production, no unsafe logging or guessed PASS. Actual result must be documented. Operator guide `docs/P05-OIDC-02.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.
+1 -1
View File
@@ -26,4 +26,4 @@
Full update policy is in root [AGENTS.md](../AGENTS.md). A list of available docs is in [MINIFEST.md](MINIFEST.md).
For the P05-OIDC-01 isolated real-user/Chromium login callback acceptance harness, actual CI outcome and safety boundaries see [P05-OIDC-01.md](P05-OIDC-01.md). For Gitea Run #89 final Login frozen build/unit/zero-advisory acceptance see [P05-SEC-02-A01.md](P05-SEC-02-A01.md). For Run #88 historical blocker and corrected helper see [P05-SEC-02.md](P05-SEC-02.md). For Gitea Run #87 findings see [P05-SEC-01.md](P05-SEC-01.md). For backend-only isolated runtime verification see [P05-CI-03.md](P05-CI-03.md); for initial full workflow and its limitations see [P05-CI-01.md](P05-CI-01.md). A green backend discovery smoke is not an authenticated user-login result.
For the current P05-OIDC-02 private loopback forwarding acceptance and actual Gitea evidence see [P05-OIDC-02.md](P05-OIDC-02.md). For the previous Run #90 blocker and cleanup see [P05-OIDC-01.md](P05-OIDC-01.md). For Gitea Run #89 final Login frozen build/unit/zero-advisory acceptance see [P05-SEC-02-A01.md](P05-SEC-02-A01.md). For Run #88 historical blocker and corrected helper see [P05-SEC-02.md](P05-SEC-02.md). For Gitea Run #87 findings see [P05-SEC-01.md](P05-SEC-01.md). For backend-only isolated runtime verification see [P05-CI-03.md](P05-CI-03.md); for initial full workflow and its limitations see [P05-CI-01.md](P05-CI-01.md). A green backend discovery smoke is not an authenticated user-login result.
+3
View File
@@ -108,3 +108,6 @@ In Gitea `vibtools/ZitPlane` → Actions → **ZitPlane P05-OIDC-01 Disposable R
**P05-OIDC-01 actual Gitea evidence:** [Run #90](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/90) started the original ZITADEL/PostgreSQL/Login V2/Traefik stack healthy without publishing host ports, but could not establish private `localhost:8080` forwarding. Official OIDC project/client/user setup and real browser callback **did not execute**; overall CI FAILED. Mandatory owned-only resource cleanup **PASSED**. The run did not impact production or user accounts. A separately scoped P05-OIDC-02 CI network-forwarder acceptance is needed before claiming interactive OIDC works.
**P05-OIDC-02 procedure:** Reuse the existing manual `ZitPlane P05-OIDC-01 Disposable Real Browser Acceptance` Gitea workflow (file `.gitea/workflows/p05-oidc-acceptance.yml`) with the newly patched CI-only forwarder. A good run first validates private proxy Host routing, prebuilt `alpine/socat:1.8.1.3` image digest and forwarded localhost:8080 HTTP 200, then provisions disposable OIDC client/user and tests a real Chromium/Account Portal callback before always-run cleanup. No host ports, no real credentials, no local tests. Actual PASS/BLOCKED will be recorded in `docs/P05-OIDC-02.md` and `notes/P05-OIDC-02.md`.
+3
View File
@@ -60,3 +60,6 @@ The new manual Gitea `p05-oidc-acceptance.yml` is **not a production deployment*
## P05-OIDC-01 Run #90 — private loopback forwarder NOT ready
Job #197 in [Run #90](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/90) failed after four healthy backend services. The CI-only forwarding sidecar never made `localhost:8080` reachable within the 70-second provisioner wait. The sidecar suppresses its `apk add socat` startup diagnostics, so its **exact failure cause is not confirmed**. **Do not** disable issuer checks, expose port 8080, reuse an IAM_LOGIN_CLIENT token as admin or modify protected Auth.js/Login V2 source. The proper next step is a separately approved narrow CI-only forwarder diagnostics/pinning fix, followed by one isolated run. `always()` cleanup **PASS**; no CI-owned Docker resources remained. No real client/user/browser OIDC assertions ran.
**P05-OIDC-02 diagnostic separation:** If private Traefik:80 returns a non-200 status with `Host: localhost:8080`, the **proxy/Host route** gate fails before launching the sidecar. If the pinned prebuilt socat container exits or is not running, the CI job records a nonsecret container state and exit code. If the process stays running but localhost:8080 HTTP 200 fails, only the HTTP status or fixed socket marker is printed. None of these is a real login/MFA issue until client/user/browser stages execute. Do not enable host ports, disable PKCE or print secret URLs; require successful owned cleanup on every run. Actual evidence: `notes/P05-OIDC-02.md`.
+1
View File
@@ -16,5 +16,6 @@ This is the chronological **index**. Phase-specific scope/implementation evidenc
| 2026-11-22 | P05-SEC-02 | Seven scoped parent overrides for glob/minimatch, pinned PNPM lock; one focused Gitea run | Run #88: Login security 0 findings PASS, build gate FAIL before frozen install on CI helper false-positive. Post-run regex fix unverified; [evidence](P05-SEC-02.md) |
| 2026-11-22 | P05-SEC-02-A01 | One-run final acceptance of corrected CI parser and unchanged Login lockfile/seven overrides | **Run #89 SUCCESS** on `ff4c58e`: frozen install, standalone build and upstream 1219/1219 tests PASS; audit 0 Moderate/High/Critical; Account jobs skipped. [Evidence](P05-SEC-02-A01.md) |
| 2026-11-22 | P05-OIDC-01 | CI-only official ZITADEL OIDC project/client/user and Chromium original Login V2/Auth.js acceptance harness with owned cleanup | **Run #90 FAILED**: 4 services healthy, no host ports; private localhost:8080 forwarder not ready, no user/client/browser created; cleanup VERIFIED PASS. [Evidence](P05-OIDC-01.md) |
| 2026-11-22 | P05-OIDC-02 | Pin prebuilt socat image by verified digest in CI, check private proxy/Host/forwarder state, correct status-only readiness | Pre-change scoped plan and source prepared; [evidence](P05-OIDC-02.md), one Gitea run pending |
Rules: Append new phases or fixes; never silently rewrite a past result. Separate **implemented**, **verified**, **blocked**, and **proposed**. Never log a user secret or personal data.
+1
View File
@@ -12,6 +12,7 @@
| [P05-SEC-02.md](P05-SEC-02.md) | Exact root chain, seven PNPM parent overrides, one focused Gitea CI and closure evidence | P05-SEC-02 / Run #88 security PASS, build blocked; parser post-run patch unverified |
| [P05-SEC-02-A01.md](P05-SEC-02-A01.md) | Single-run Login-only final frozen/build/unit/security acceptance, scope lock and evidence | P05-SEC-02-A01 / Run #89 SUCCESS, accepted |
| [P05-OIDC-01.md](P05-OIDC-01.md) | Pre-change real browser OIDC Scope Lock, provision/redirect/session/negative tests and one CI run evidence | P05-OIDC-01 / Run #90 FAILED at forwarder readiness; cleanup PASS; acceptance BLOCKED |
| [P05-OIDC-02.md](P05-OIDC-02.md) | Pre-change exact loopback-forwarder blocker scope, pinned image/diagnostic plan and one real Gitea acceptance run | P05-OIDC-02 / source prepared, CI pending |
| [CHANGELOG.md](CHANGELOG.md) | Short append-only chronological phase log and links to detailed reports | DOCS-01 / active |
Update this manifest whenever any direct child file or directory changes. Use **actual source state**; a planned file must be labeled planned, not present.
+39
View File
@@ -0,0 +1,39 @@
# P05-OIDC-02 — Private Loopback Forwarder Remediation & Real OIDC Acceptance
**Date:** 2026-11-22
**Approved baseline (Gitea main/local main):** `b78270e9d45c1764c5642024b8147885deaacde3`
**Run #90 tested SHA:** `cbcd60e76ec909df4f9c5826adf7a3e2a899c73e`
**Pre-edit state:** APPROVED — PRE-IMPLEMENTATION PLAN / EXACT SCOPE LOCK. This record was created BEFORE any P05-OIDC-02 source edits.
## Last actual CI evidence (Gitea Run #90, job #197)
- Official disposable PostgreSQL/ZITADEL API/official Login V2/Traefik four services became healthy under the portless Compose override; no host ports exposed: **PASS**.
- Previous `run.sh` started an `alpine:3.21` sidecar using `sh -ec 'apk add --no-cache socat >/dev/null 2>&1; exec socat ...'`, sharing the private proxy network namespace. Start command returned container ID, but no sidecar **running/exit code/socket/proxy** diagnostics were recorded. `provision.py::wait_until_ready()` timed out on private `localhost:8080` after 70 seconds: **BLOCKED**. **There is no evidence establishing whether package install, sidecar exit, socket bind or proxy routing caused it**.
- Provisioning did not create any project/client/human and the actual Chromium/PKCE/state/nonce/callback/protected API/negative checks did not execute: **UNVERIFIED**.
- Mandatory `always()` cleanup step **PASS**: `ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS`; `ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS`. Run overall **FAILURE**. No second run performed in P05-OIDC-01.
## Scope Lock — exact approved writes
- `tests/ci/oidc_e2e/run.sh`: old runtime-installed Alpine forwarder replacement; private listener, proxy, lifecycle, safe error markers; do not publish host port.
- `tests/ci/oidc_e2e/provision.py` **only as necessary**: ensure `/debug/ready` readiness is HTTP status-based, without JSON assumptions; preserve issuer/metadata checks, real APIs and secret isolation.
- `tests/ci/oidc_e2e/cleanup.sh` **only if necessary**: preserve exact numeric-run owner checks and verified cleanup.
- `.gitea/workflows/p05-oidc-acceptance.yml` **only if justified**: preserve manual-only, single job and `always()` teardown.
- `notes/**`, `project/**`, relevant `docs/**`, associated README/MINIFEST and root navigation only if necessary.
**Read-only:** `core/backend/zitadel/**`, `deployment/docker/**`, `auth/ui/v2/**` original Login auth/UI/application source, `users/ui/**` Account Auth.js/UI/source, package manifests/lockfiles, production infrastructure/secrets, other tests/helpers and all unrelated files. **Preserve untracked `AI_INSTRUCTIONS.md`.**
No local builds/tests/dev servers/Docker, no real users/accounts or secrets, no production deployment/tags/releases. **Exactly one focused Gitea Actions acceptance cycle**, then source/security diff, evidence/docs sync, Git commit, main push and exact remote SHA verification. No repeated CI loops or false PASS.
## Targeted implementation plan
1. **Deterministic preflight:** With unchanged run-owned P02 four-service Compose healthy, use a short-lived official Python (existing CI image `python:3.12-alpine`) probe in the SAME Docker proxy network namespace to make an HTTP `GET /debug/ready` with exact `Host: localhost:8080` to **127.0.0.1:80** first. Distinguish proxy/Host routing blocker from sidecar failure. Output safe statuses only (no request/response body, URLs with query, tokens).
2. **Version-pinned prebuilt socat:** Docker Hub `alpine/socat:1.8.1.3` is a published, versioned image with `socat` already installed. Replace `alpine:3.21 + apk add` entirely with `alpine/socat:1.8.1.3` and run `TCP-LISTEN:8080,bind=127.0.0.1,reuseaddr,fork TCP:127.0.0.1:80` with no installer, shell, host exposure, credentials or extra privileges. Record Docker image architecture/digest metadata (nonsecret) and keep image version explicit rather than `latest`.
3. **Bounded start and fail-closed diagnostics:** Before provisioning, check `docker inspect` for exact run-labeled container, state and exit code; test local **127.0.0.1:8080** TCP socket and HTTP `/debug/ready` with `Host: localhost:8080` from a new disposable proxy-namespace probe. If not ready, report only a fixed-stage diagnostic marker and nonsecret state/exit code; **do not** dump container logs, JWTs, cookies or HTTP bodies. Do not mislabel the cause without actual observation.
4. **Narrow provisioner readiness:** Previously `request('GET','/debug/ready')` assumed JSON, though readiness is a status-only HTTP endpoint. If proxy becomes reachable, this assumption might cause a false readiness failure. Change only this `wait_until_ready()` to check status 200 on exact local origin/Host, no body interpretation or secret emission. Leave strict JSON parsing for official project/app/user APIs intact.
5. Keep original disposable secret volume, IAM_OWNER PAT and original Login V2/Account Portal browser flows unchanged. Retain `cleanup.sh` unless inspection demonstrates a narrow ownership bug.
6. Record source-only contract/Scope Lock audit and docs. Commit, push and verify source SHA. Dispatch **one manual Gitea run**. Accept real OIDC only if actual project/client/user provisioning, genuine Chromium password + Auth.js PKCE/state/nonce/callback, protected session and anonymous/invalid negative tests, and `always()` teardown all succeed. A new provisioning/browser failure is an exact **BLOCKED** outcome, not a reason for a second run.
7. Update `notes/project/docs` with actual run ID/jobs/stages, cleanup, explicit verified/deferred status and follow-up tight Scope Lock. One closure commit, push and exact remote main SHA check.
**Source review does NOT prove runtime compatibility.** No claim that old Alpine `apk add` was the root cause; Run #90 did not log sidecar state. Confirm only from the next run's safe observations.
**Expected source-level changes (pre-run):** exactly `run.sh`, `provision.py` plus narrow docs. `cleanup.sh` and workflow kept identical unless a specific justified defect is observed.
+1
View File
@@ -16,6 +16,7 @@ This is the **developer-focused implementation history**. `notes/CHANGELOG.md` i
| 2026-11-22 | P05-SEC-02 | Seven parent-targeted glob/minimatch patched resolutions, PNPM lockfile metadata-only, manual Login-only CI and post-run validator fix | Run #88: strict Login audit 0 findings PASS, Login build job blocked before install by parser false-positive; post-run fix untested. `notes/P05-SEC-02.md` |
| 2026-11-22 | P05-SEC-02-A01 | Verify existing corrected helper, exact seven PNPM scoped overrides, frozen Login Nx build and upstream Vitest; no source/lock changes | **Gitea Run #89 SUCCESS** on `ff4c58e`, 84/84 files, 1219/1219 tests, Login audit 0 Moderate/High/Critical; `notes/P05-SEC-02-A01.md` |
| 2026-11-22 | P05-OIDC-01 | Added manual disposable IAM_OWNER/client/human/browser OIDC acceptance harness, secret isolation and cleanup | Run #90 FAIL before provisioning: private loopback forwarder unready; 4 backend services healthy, owned cleanup PASS. `notes/P05-OIDC-01.md` |
| 2026-11-22 | P05-OIDC-02 | CI-only prebuilt socat tag+immutable digest startup, proxy/private forwarder HTTP readiness/exit diagnostics, status-only "/debug/ready" provisioner | Source prepared, one Gitea acceptance pending; `notes/P05-OIDC-02.md` |
## Required entry for each future change
+5
View File
@@ -134,3 +134,8 @@ New manual workflow `.gitea/workflows/p05-oidc-acceptance.yml` executes **one**
**P05-OIDC-01 real CI evidence:** Manual Gitea Run #90 (tested `cbcd60e`) had healthy 4-service portless backend PASS, **CI-only localhost:8080 namespace forwarder readiness FAIL**, no disposable OIDC project/client/user or Chromium browser launched; `always()` cleanup job step PASS, no leftover CI resources. Overall job FAILED; **not** an authenticated login test PASS. Next narrowly scoped P05-OIDC-02 must instrument/repair private forwarder lifecycle and reverify the full browser acceptance, without changing original application or backend code.
## P05-OIDC-02 scoped follow-up
New source in `tests/ci/oidc_e2e/run.sh`: test namespace-local Traefik proxy Host route before creating sidecar, resolve published `alpine/socat:1.8.1.3` to immutable digest, validate prebuilt `socat` entrypoint, create no-host-port loopback sidecar, check running state/exit plus bounded private forwarded HTTP 200. `provision.py` now treats `/debug/ready` as HTTP status-only; official management provisioning and all browser/auth assertions unchanged. Existing manual Gitea workflow and always-run owned cleanup unchanged. One separate Gitea acceptance run needed; never mark a static stage check as an actual real OIDC browser PASS.
+3
View File
@@ -168,3 +168,6 @@ Official Login V2 user/auth source, user Account Portal, backend Compose and pro
## P05-OIDC-01 — disposable real OIDC acceptance source map
`.gitea/workflows/p05-oidc-acceptance.yml`: one manual Gitea isolated Docker job and mandatory `always()` cleanup. `tests/ci/oidc_e2e/compose.owner.override.yaml`: only ephemeral IAM_OWNER PAT bootstrap; original P02 Compose untouched. `tests/ci/oidc_e2e/run.sh`: ownership preflight, portless backend startup, private loopback routing and original-app browser harness. `tests/ci/oidc_e2e/provision.py`: official ZITADEL API client/project/verified human creation and 0600 temporary secret fixture. `tests/ci/oidc_e2e/browser.sh`: CI-only pinned Playwright/Account npm dependencies. `tests/ci/oidc_e2e/browser.cjs`: actual Chromium Auth.js/OIDC/password/callback/session and fail-closed checks. `tests/ci/oidc_e2e/cleanup.sh`: owned-only containers, volume, bootstrap/database data cleanup. New directory `README.md` and `MINIFEST.md` document all modules. Detailed boundaries: `project/OIDC-E2E-ARCHITECTURE.md`; actual test outcomes pending Gitea.
**P05-OIDC-02 updated CI functions only:** `tests/ci/oidc_e2e/run.sh` stage between four-service readiness and provisioning now explicitly validates proxy Host/HTTP status, pulls version-pinned prebuilt socat, checks its entrypoint/immutable image digest and checks the private 8080 listener plus sidecar running/exit state. `tests/ci/oidc_e2e/provision.py::wait_until_ready()` checks HTTP 200 without JSON decoding. `cleanup.sh`, browser scripts and all application/backend/auth source remain read-only.
+3
View File
@@ -130,3 +130,6 @@ Existing `tests/ci/security_advisory_gate.py` remains the independent **live reg
**P05-OIDC-01 runtime evidence:** `run.sh` reached four-service readiness in Run #90, then `provision.py::wait_until_ready()` timed out on private `localhost:8080` before `request()` could provision any client, project or user. Thus `browser.cjs::main()` and its positive/negative real login/session checks **were not executed**. The only other completed operation was `cleanup.sh`, which verified removal of owned state. The sidecar's precise root cause is unknown; avoid runtime/PASS claims for unexecuted browser functions.
**P05-OIDC-02 narrow source audit:** Shell orchestration in `tests/ci/oidc_e2e/run.sh` now probes private Traefik `/debug/ready` with exact `Host: localhost:8080`, verifies prebuilt socat image entrypoint/digest, and stops before credential provisioning when the loopback forwarder state, socket or HTTP response is not ready. Python `provision.py::wait_until_ready()` now checks only `HTTP 200` for `/debug/ready` without interpreting an arbitrary body as JSON. No user API, token, session, IAM policy, Auth.js or official Login V2 code changed.
+7
View File
@@ -50,3 +50,10 @@ Gitea manual [Run #90](https://dev.ivib.cc/vibtools/ZitPlane/actions/runs/90), t
The mandatory `cleanup.sh` step #3 succeeded and printed `ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS` + `ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS`. It removed only run #90-owned proxy namespace forwarder, separate ephemeral secrets volume, Compose containers, Postgres/bootstrap volumes and fixed CI network. **Backend bootstrap/cleanup PASS; full end-to-end OIDC acceptance BLOCKED.**
Next P05-OIDC-02 should narrowly instrument/check forwarder startup before provisioning, use an approved pinned prebuilt image to avoid silent runtime package installation, verify exact **private** loopback listener/Host routing without any host port exposure, preserve original Go backend/Compose/Login/Auth.js and credentials isolation, then run **one separately authorized** Gitea acceptance cycle. No CI-only patch in P05-OIDC-01 was executed after Run #90.
## P05-OIDC-02 — isolated private forwarder reliability (source prepared)
The previous Gitea Run #90 verified a healthy, portless P02 stack but did not capture the private socat sidecar's exit status or verify the 127.0.0.1:80 proxy independently; the true forwarder failure cause is **unknown**. The new narrow `run.sh` checks the private Traefik:80 `/debug/ready` with `Host: localhost:8080` first, then uses the published version-specific `alpine/socat:1.8.1.3` image (preinstalled `socat`), checks `Entrypoint == ["socat"]`, resolves the pulled tag to its immutable sha256 registry digest and **runs by digest**. There is no `apk add` at runtime. Container state/exit code and bounded local forwarded HTTP 200 readiness are checked **before official OIDC project/user provisioning**. Only safe stage/status markers are printed on failure; no HTTP bodies, cookies, callbacks or passwords.
`provision.py::wait_until_ready()` now independently verifies HTTP 200 rather than attempting to parse the `/debug/ready` response as JSON; **all official management/client/human creation requests remain strictly parsed JSON and authenticated with the ephemeral IAM_OWNER PAT**. No other protected code, developer Compose, original Login V2 or Account auth source changed. The existing `cleanup.sh` continues to remove only run-labeled/owned resources. **New Gitea real-browser acceptance pending; this is not a verified login yet**. Exact plan/evidence: `notes/P05-OIDC-02.md`.
+3
View File
@@ -84,3 +84,6 @@ These are **major** dependency migrations underneath older parents, not an upstr
## P05-OIDC-01 — isolated browser test tooling and why
CI only: official ZITADEL v4.20.4, official Login V2 v4.20.4, PostgreSQL 17.10/Traefik 3.7.7 from P02; existing portless Compose override; new `alpine:3.21` namespace-local `socat` loopback forwarder, `python:3.12-alpine` stdlib API provisioner, pinned `mcr.microsoft.com/playwright:v1.58.2-noble` (Chromium), pinned `playwright@1.58.2` and the Account Portal's existing `npm ci` lock inside an ephemeral browser container. No manifests or lockfiles changed, no local PC builds/tests, and no host HTTP port published. Dynamic IAM_OWNER bootstrap PAT expires in two hours and all token/password/client data are destroyed with owned volumes after the run. P02 issuer HTTP localhost requires Account `NODE_ENV=development` **inside CI only**; production HTTPS remains unverified. Detailed topology and cleanup: `project/OIDC-E2E-ARCHITECTURE.md`.
**P05-OIDC-02 CI forwarding dependency:** Uses the published, version-selected `alpine/socat:1.8.1.3` image rather than installing packages inside `alpine:3.21` at container startup. The disposable runner checks the image has `["socat"]` entrypoint, resolves `RepoDigests` and launches the immutable pulled sha256 reference; never `latest`. Existing `python:3.12-alpine` probe containers check no-host-port proxy and private forwarding readiness. This is Gitea-only and must not be run on developer PC or production. No package manifests/lockfiles modified.
+18 -16
View File
@@ -1,27 +1,27 @@
# ZitPlane ? exact tracked source inventory
**Snapshot:** 2026-11-22, P05-OIDC-01 source tested on Gitea Run #90 at `cbcd60e76ec909df4f9c5826adf7a3e2a899c73e`: backend/portless PASS, private localhost forwarder BLOCKED; no client/user/browser E2E executed, cleanup PASS. Final results-only documentation commit is NOT a new runtime test.
**Snapshot:** 2026-11-22, P05-OIDC-02 focused source candidate on approved baseline `b78270e`. Run #90 backend/cleanup PASS, private loopback FAIL; **new OIDC acceptance CI not yet executed**.
**Git-tracked file paths: 746.** Untracked `AI_INSTRUCTIONS.md` and ignored local secrets excluded.
**Git-tracked file paths: 748.** Untracked `AI_INSTRUCTIONS.md` and ignored local secrets excluded.
This is an exact Git file-path locator, not a claim of source-built Login runtime, browser authentication or deployment. See `notes/P05-OIDC-01.md` and `project/OIDC-E2E-ARCHITECTURE.md`.
This inventory records exact Git paths, not live browser authentication. See `notes/P05-OIDC-02.md` and `project/OIDC-E2E-ARCHITECTURE.md`.
| Group | Paths | Responsibility |
| --- | ---: | --- |
| `(repository root)` | 6 | Tracked repository root |
| `.gitea` | 8 | Manual Gitea CI-only workflows |
| `auth` | 639 | Original official ZITADEL Login V2 source/locked dependencies |
| `core` | 2 | Local backend helper |
| `.gitea` | 8 | Manual Gitea CI-only verification workflows |
| `auth` | 639 | Pinned official Login V2 source and dependency lock |
| `core` | 2 | Development backend |
| `deployment` | 2 | Read-only developer Compose |
| `docs` | 19 | User/operator guides |
| `notes` | 11 | Prechange plans/evidence |
| `packages` | 1 | Placeholder |
| `project` | 12 | Developer architecture/source/security maps |
| `scripts` | 1 | Placeholder |
| `tests` | 21 | CI verification scripts and disposable OIDC browser harness |
| `users` | 24 | Read-only Account Portal |
| `docs` | 20 | Operator and user guides |
| `notes` | 12 | Phase plans and real CI evidence |
| `packages` | 1 | First-party placeholder |
| `project` | 12 | Architecture, function maps, security and source inventory |
| `scripts` | 1 | First-party placeholder |
| `tests` | 21 | Gitea CI-only contracts and browser harness |
| `users` | 24 | Read-only Account Portal source |
## Exact Git-tracked paths
## Exact tracked paths
### (repository root) ? 6 files
@@ -695,7 +695,7 @@ This is an exact Git file-path locator, not a claim of source-built Login runtim
- `deployment/README.md`
- `deployment/docker/compose.backend.dev.yaml`
### docs ? 19 files
### docs ? 20 files
- `docs/ARCHITECTURE.md`
- `docs/DEVELOPMENT.md`
@@ -708,6 +708,7 @@ This is an exact Git file-path locator, not a claim of source-built Login runtim
- `docs/P05-CI-02.md`
- `docs/P05-CI-03.md`
- `docs/P05-OIDC-01.md`
- `docs/P05-OIDC-02.md`
- `docs/P05-SEC-01.md`
- `docs/P05-SEC-02-A01.md`
- `docs/P05-SEC-02.md`
@@ -717,7 +718,7 @@ This is an exact Git file-path locator, not a claim of source-built Login runtim
- `docs/TROUBLESHOOTING.md`
- `docs/USER-GUIDE.md`
### notes ? 11 files
### notes ? 12 files
- `notes/CHANGELOG.md`
- `notes/DOCS-01.md`
@@ -726,6 +727,7 @@ This is an exact Git file-path locator, not a claim of source-built Login runtim
- `notes/P05-CI-02.md`
- `notes/P05-CI-03.md`
- `notes/P05-OIDC-01.md`
- `notes/P05-OIDC-02.md`
- `notes/P05-SEC-01.md`
- `notes/P05-SEC-02-A01.md`
- `notes/P05-SEC-02.md`
+5
View File
@@ -13,3 +13,8 @@ The environment is a temporary `zitplane-p05-{GITHUB_RUN_ID}` Compose stack cont
**Privacy:** never log user password, owner PAT, OIDC client secret, Auth.js cookies, codes, nonce, state, request query or screenshots. Browser diagnostics contain only safe stage IDs. No credentials/recordings uploaded as CI artifacts. The actual CI run and individual pass/blocked status are recorded in `notes/P05-OIDC-01.md` and `docs/P05-OIDC-01.md`; source existence alone is not runtime acceptance.
**Phase limitations:** MFA/passkeys, production HTTPS issuer, deployment, full Admin Console human login and global SSO logout are outside this phase. Only a real successful browser callback + verified teardown is enough for its narrower user/password OIDC acceptance.
## P05-OIDC-02 private forwarder remediation (pending real Gitea CI)
`run.sh` first verifies private Traefik on 127.0.0.1:80 responds HTTP 200 with `Host: localhost:8080`, then pulls versioned `alpine/socat:1.8.1.3`, verifies prebuilt socat entrypoint, resolves the image's immutable digest and starts by digest in the same private proxy network namespace. No `apk add` inside container and no public host binding. A bounded health probe checks the listener/socket and exact Host/issuer route; on failure it logs only stage/state/exit/HTTP status, not secrets. `provision.py` readiness probes HTTP status-only; official IAM_OWNER project/client/human APIs and Chromium login unchanged. Run #90 never tested client/user/browser flows; **next single Gitea run pending**.
+18 -6
View File
@@ -62,14 +62,26 @@ def request(method: str, path: str, token: str | None = None, payload: dict | No
def wait_until_ready() -> None:
deadline = time.monotonic() + 70
"""HTTP 200 /debug/ready is a status probe, not a JSON API response.
Keep all official management/user provisioning endpoints strictly JSON.
The runner already proves the run-owned proxy/forwarder before this point.
"""
deadline = time.monotonic() + 35
probe = Request(
ORIGIN + "/debug/ready",
headers={"Host": "localhost:8080", "Accept": "*/*"},
method="GET",
)
while time.monotonic() < deadline:
try:
request("GET", "/debug/ready")
return
except RuntimeError:
time.sleep(2)
raise RuntimeError("Disposable localhost issuer port forwarding was not ready")
with OPENER.open(probe, timeout=6) as reply:
if reply.status == 200:
return
except (HTTPError, URLError, TimeoutError, OSError):
pass # No response body, URL, session details, or credentials logged.
time.sleep(2)
raise RuntimeError("Private issuer readiness HTTP 200 not established")
def required_string(data: dict, name: str) -> str:
+82 -4
View File
@@ -79,12 +79,90 @@ proxy_id="$(dc ps -q proxy)"
test -n "$proxy_id"
bootstrap_volume="${project}_zitadel-bootstrap"
# Everything below shares the private proxy network namespace (not the host).
# Loopback-8080 preserves ZITADEL's P02 external issuer and Host routing.
# Distinguish an unhealthy private proxy/Host route from a broken forwarder.
# The probing container shares ONLY the disposable proxy network namespace;
# no host-published port, credentials, response body or user HTTP query.
docker run --rm --network "container:$proxy_id" python:3.12-alpine \
python -c '
import http.client, sys
try:
conn = http.client.HTTPConnection("127.0.0.1", 80, timeout=9)
conn.request("GET", "/debug/ready", headers={"Host": "localhost:8080"})
response = conn.getresponse()
if response.status != 200:
print("OIDC_CI_PRIVATE_PROXY_HOST_ROUTE_HTTP_STATUS=" + str(response.status), file=sys.stderr)
sys.exit(1)
except (OSError, http.client.HTTPException):
print("OIDC_CI_PRIVATE_PROXY_SOCKET_OR_HTTP_BLOCKED", file=sys.stderr)
sys.exit(1)
print("ZITPLANE_OIDC_PRIVATE_PROXY_HOST_ROUTE_PASS")
'
# Docker Hub alpine/socat has socat preinstalled, with an explicit versioned
# published tag; no shell and no package installation during container start.
# Resolve to a verified digest and run that IMMUTABLE digest, never latest.
forwarder_tag="alpine/socat:1.8.1.3"
docker pull "$forwarder_tag" >/dev/null
entrypoint="$(docker image inspect --format '{{json .Config.Entrypoint}}' "$forwarder_tag")"
if [ "$entrypoint" != '["socat"]' ]; then
echo OIDC_CI_FORWARDER_PREBUILT_ENTRYPOINT_NOT_VERIFIED >&2
exit 1
fi
forwarder_image="$(docker image inspect --format '{{index .RepoDigests 0}}' "$forwarder_tag")"
case "$forwarder_image" in
alpine/socat@sha256:*) echo ZITPLANE_OIDC_PINNED_FORWARDER_DIGEST_VERIFIED_PASS ;;
*) echo OIDC_CI_FORWARDER_IMAGE_DIGEST_MISSING >&2; exit 1 ;;
esac
# NetNS-local listener 127.0.0.1:8080 -> netNS-local Traefik 127.0.0.1:80.
# The original P02 external issuer remains exactly http://localhost:8080.
docker run -d --name "$forwarder" \
--label "zitplane.oidc.run=$GITHUB_RUN_ID" \
--network "container:$proxy_id" alpine:3.21 \
sh -ec 'apk add --no-cache socat >/dev/null 2>&1; exec socat TCP-LISTEN:8080,bind=127.0.0.1,reuseaddr,fork TCP:127.0.0.1:80' >/dev/null
--network "container:$proxy_id" "$forwarder_image" \
TCP-LISTEN:8080,bind=127.0.0.1,reuseaddr,fork TCP:127.0.0.1:80 >/dev/null
# Bounded socket+exact Host HTTP probe. Container existence is NOT readiness.
ready=0
attempt=0
while [ "$attempt" -lt 12 ]; do
attempt=$((attempt + 1))
state="$(docker inspect -f '{{.State.Status}}' "$forwarder")"
if [ "$state" != running ]; then
exitcode="$(docker inspect -f '{{.State.ExitCode}}' "$forwarder")"
echo "OIDC_CI_FORWARDER_NOT_RUNNING_STATE=$state EXIT_CODE=$exitcode" >&2
exit 1
fi
if docker run --rm --network "container:$proxy_id" python:3.12-alpine \
python -c '
import http.client
conn = http.client.HTTPConnection("127.0.0.1", 8080, timeout=5)
conn.request("GET", "/debug/ready", headers={"Host": "localhost:8080"})
assert conn.getresponse().status == 200
' >/dev/null 2>&1; then
ready=1
break
fi
sleep 2
done
if [ "$ready" -ne 1 ]; then
state="$(docker inspect -f '{{.State.Status}}' "$forwarder")"
exitcode="$(docker inspect -f '{{.State.ExitCode}}' "$forwarder")"
echo "OIDC_CI_FORWARDER_HTTP_NOT_READY_STATE=$state EXIT_CODE=$exitcode" >&2
# One redacted diagnostic: print only an HTTP status or a fixed socket marker.
docker run --rm --network "container:$proxy_id" python:3.12-alpine \
python -c '
import http.client, sys
try:
conn = http.client.HTTPConnection("127.0.0.1", 8080, timeout=5)
conn.request("GET", "/debug/ready", headers={"Host": "localhost:8080"})
print("OIDC_CI_FORWARDER_HTTP_STATUS=" + str(conn.getresponse().status), file=sys.stderr)
except (OSError, http.client.HTTPException):
print("OIDC_CI_FORWARDER_LISTENER_CONNECTION_BLOCKED", file=sys.stderr)
' || true
exit 1
fi
echo ZITPLANE_OIDC_PRIVATE_LOOPBACK_FORWARDER_READY_PASS
docker volume create --name "$secret_volume" \
--label "zitplane.oidc.run=$GITHUB_RUN_ID" >/dev/null