Files

9.8 KiB

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.

One authorized CI acceptance — actual terminal Gitea Run #91

Date: 2026-11-22, Run: #91, job: #198, tested Gitea source SHA 4831165548feabc2c0a0d39d25c40e0d1bc23bb2. Triggered once with workflow_dispatch on main, started 17:46:39 UTC, terminal 17:47:44 UTC. Overall status completed, conclusion FAILURE. There was no second Gitea run.

Stage Evidence Terminal result
Checkout and Git prerequisite, job steps #0/#1 Both finished success PASS
Numeric run ownership, Docker daemon ZITPLANE_OIDC_DOCKER_PREFLIGHT_PASS PASS
Strict no published host ports and IAM_OWNER config ZITPLANE_OIDC_NO_PUBLISHED_PORT_AND_OWNER_CONFIG_PASS PASS
Four disposable P02 services started and healthy ZITPLANE_OIDC_FOUR_SERVICES_READY_PASS PASS
Namespace-local direct Traefik:80 /debug/ready with exact Host: localhost:8080 ZITPLANE_OIDC_PRIVATE_PROXY_HOST_ROUTE_PASS PASS — eliminates the previously unverified private proxy/Host routing hypothesis
Versioned prebuilt socat binary/entrypoint and pulled registry SHA256 digest ZITPLANE_OIDC_PINNED_FORWARDER_DIGEST_VERIFIED_PASS PASS — image identity/entrypoint checked, process still not proven healthy
Private sidecar startup/lifecycle OIDC_CI_FORWARDER_NOT_RUNNING_STATE=exited EXIT_CODE=1 FAIL — the socat process exited immediately before the bounded HTTP readiness test. The precise internal startup error remains unknown because container stderr was not retained in CI output. Do not claim which socat option, bind error or runtime caused it
Forwarded localhost:8080 HTTP ready / separate provision.py status-only check Not reached NOT EXECUTED
Disposable official OIDC project, client, verified human provisioning Not reached NOT EXECUTED, no client/user created
Original Login V2 Chromium password/PKCE/state/nonce/Auth.js callback/subject/API/protected page/negative/logout Not reached NOT EXECUTED, no real user authenticated
Always-run owned-resource cleanup, job step #3 ZITPLANE_BACKEND_CLEANUP_VERIFIED_PASS; ZITPLANE_OIDC_ALL_RESOURCES_CLEANED_PASS PASS — run-owned containers, network, bootstrap/database and disposable credentials removed; cleanup step succeeded

Forensic conclusion: Run #91 proves the underlying proxy/Host routing works and the version-specific socat image has a verified prebuilt entrypoint and digest; it isolates failure to the forwarder process startup (exited with code 1). It does not prove why the process failed. Initial Run #90 package-install hypothesis was not confirmed by this run. The status-only Python readiness code and all subsequent browser/auth/provision tests remain unexecuted. Do not mark real OIDC accepted.

One-run boundary: P05-OIDC-02 performed one manual Gitea CI run. No local application installs/builds/tests/dev servers, real users, production deployment or another CI run. Original users/ui/**, auth/ui/v2/**, backend/Compose, package manifests/locks and existing owner-only cleanup were unchanged. The committed result-only documentation is not the tested source commit.

Next candidate P05-OIDC-03 (not approved): a narrowly scoped tests/ci/oidc_e2e/run.sh startup remediation should first capture safe, redacted sidecar startup diagnostics (only this run-owned process, before any credentials exist, with allowlisted error class/errno and no raw log output), verify socat argument parsing and localhost bind semantics, and if justified replace it with an immutable/digest-pinned official Python stdlib TCP forwarding process. Ensure exact private proxy:80 and forwarded 8080 Host HTTP 200 before provisioning. No extra host ports or secret exposure. Then one new, separately approved Gitea acceptance for genuine client/user/browser flow and complete cleanup; actual failures remain BLOCKED.