ci: introduce ZitPlane P05 verification foundation
This commit is contained in:
1 parent
7ecf531697
commit
42b79362c1
32 files changed
+1731
-471
No files matched your search
@@ -9,6 +9,7 @@ This is the **developer-focused implementation history**. `notes/CHANGELOG.md` i
|
||||
| 2026-11-22 | P03 | `auth/ui/v2/` official v4.20.4 source and matching client/proto/pnpm/Nx dependencies | `4404849`; `docs/P03-SOURCE-IMPORT.md`; no build |
|
||||
| 2026-11-22 | P04 | `users/ui/` Account Portal OIDC, pages, styling, read-only identity API | `40af500`; `docs/P04-ACCOUNT-PORTAL.md`; no build/CI |
|
||||
| 2026-11-22 | DOCS-01 | Documentation governance; developer architecture, reviewed first-party function/file/page mapping and 701-path source inventory; user manual/setup/status/troubleshooting | Documentation complete; manifest/link/source-scope audit PASS; `notes/DOCS-01.md`, local commit SHA via Git history |
|
||||
| 2026-11-22 | P05-CI-01 | `.gitea/workflows/p05-ci.yml`, `tests/ci/**`, Account Portal npm lock and Login V2 slim pnpm importer reconciliation; source-only CI verification preparation | CI not yet accepted; see `notes/P05-CI-01.md` and `project/CI-ARCHITECTURE.md` |
|
||||
|
||||
## Required entry for each future change
|
||||
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# ZitPlane P05-CI-01 — Gitea Actions verification architecture
|
||||
|
||||
**Status:** source implemented, CI run result pending. **Approved baseline:** `7ecf53169776cc7f08af3dde6fe4b4492acf3ea1` (2026-11-22).
|
||||
|
||||
## Exact job map
|
||||
|
||||
| Job | Runner / source | What PASS means | Not covered |
|
||||
| --- | --- | --- | --- |
|
||||
| `account` | `ubuntu-latest`, `node:22-bookworm`; `users/ui/` | Structural guard + `npm ci`, `tsc --noEmit`, Next standalone production build | Real login/redirect, live Account Portal |
|
||||
| `login` | `ubuntu-latest`, `node:22-bookworm`; `auth/ui/v2/` | Frozen pnpm install, Nx proto/client/login build and original Login unit suite | Interactive admin/password/MFA/SSO integration |
|
||||
| `security` | `ubuntu-latest`, `node:22-bookworm` | NPM and pnpm production dependency advisories at HIGH+ thresholds triaged by runner registry | License/legal or full application security proof |
|
||||
| `backend` | `ubuntu-latest`, `node:22-alpine`; `deployment/docker/compose.backend.dev.yaml` read-only | Docker daemon preflight, Python helper contracts, disposable ZITADEL stack, readiness, OIDC discovery and JWKS | Portal OIDC callback, MFA, live account session, production TLS |
|
||||
|
||||
All jobs use the previously seen Gitea standard `ubuntu-latest` runner label; no separate runner is created or installed. A failed runner capability is a **BLOCKED** gate, never a PASS. Docker job must not run from an untrusted pull request; the workflow is `workflow_dispatch` only.
|
||||
|
||||
## Dependency/root cause fixes
|
||||
|
||||
- `auth/ui/v2/pnpm-workspace.yaml` has only the 3 actually imported packages. P03's original `pnpm-lock.yaml` retains exact `packages:/snapshots:` resolution graph; 4 missing-upstream importers were removed, 4 present importers retained.
|
||||
- Account Portal package-lock v3 generated using local `npm install --package-lock-only --ignore-scripts --no-audit --no-fund --engine-strict`, **not** an install/test/build. Root package manifest matches lock manifest.
|
||||
- Login CI sets up pinned pnpm `10.30.3`, runs `--frozen-lockfile` and the upstream Nx dependency graph; no upstream UI/auth logic was modified.
|
||||
- Account CI uses `npm ci` only from committed lock, plus TS + production Next build. No automatically loosened package versions or npm install fallback.
|
||||
- Security jobs audit dependency advisory metadata on the runner. Any failure is reported verbatim with severity/package/version; no blind package updates.
|
||||
|
||||
## Disposable backend safety and behavior
|
||||
|
||||
The P02 Compose has a fixed named network `zitplane-backend-dev-internal` and loopback-only `127.0.0.1:8080`. CI **refuses** to start if that network already exists. It generates independent random `.env` in runner checkout and uses unique Compose project name `zitplane-p05-${GITHUB_RUN_ID}`. A marker is written only after the network absence check; cleanup uses that exact Compose project, deletes its ephemeral volumes, and removes its temporary credentials. It never connects to `auth.vib.tools`, `account.vib.tools` or any production database.
|
||||
|
||||
`tests/ci/oidc_discovery.py` probes ready/discovery/JWKS inside disposable Docker network only, avoiding exposing admin PATs. **OIDC full user-session acceptance is explicitly NOT VERIFIED**: P05 does not provision a disposable confidential OIDC app, fake user or Session API script. A 200 readiness/discovery alone does not constitute user login, MFA, PKCE callback, protected account route or logout acceptance.
|
||||
|
||||
## Future gates
|
||||
|
||||
1. Document actual Gitea runner job results and exact failure/line in `notes/P05-CI-01.md` and `docs/P05-CI-01.md`.
|
||||
2. If any job fails, keep immutable logged evidence; fix only reproduced narrow defects with separate approval if outside P05 Scope Lock.
|
||||
3. Provide disposable OIDC client/user provisioning and Account Portal auth/session lifecycle tests in a narrow separately approved integration phase.
|
||||
4. Production Docker/Coolify/TLS and DNS are out of scope.
|
||||
|
||||
Reference: `notes/P05-CI-01.md`, `docs/PHASES.md`, `.gitea/workflows/p05-ci.yml`, `tests/ci/`.
|
||||
@@ -44,3 +44,8 @@ Custom profile edits, password/MFA/passkey changes inside the portal, sessions/d
|
||||
## Feature-update contract
|
||||
|
||||
For every future page/feature change, record exact route/file, action, data source, guards, validation, errors, dependency version, accessibility details, status (proposed/source/CI verified/deployed), and phase/commit. Update user button-by-button guidance in `docs/USER-GUIDE.md` alongside this register.
|
||||
|
||||
|
||||
## P05 CI verification (not a UI feature)
|
||||
|
||||
New manually dispatched workflow `.gitea/workflows/p05-ci.yml` defines four isolated runner gates: Account Portal reproducible dependency install/build, official Login V2 frozen install/build/unit, dependency security advisory triage, and disposable Docker ZITADEL/OIDC discovery smoke. Exact verification scripts reside at `tests/ci/source_contract.py` and `tests/ci/oidc_discovery.py`. The full Account Portal interactive OIDC callback/session/SSO flow is **not implemented as a CI test**; it remains a pending acceptance gate. Status must be updated from the actual Gitea run report in `notes/P05-CI-01.md`.
|
||||
@@ -81,6 +81,21 @@ Upstream import: official ZITADEL `v4.20.4` / Git `384bb9ec96b501ad39dc232ee2061
|
||||
|
||||
These paths describe **source**, not a verified running app. Do not infer API compatibility or production availability from files existing.
|
||||
|
||||
## P05 CI verification files
|
||||
|
||||
| Path | Purpose / scope |
|
||||
| --- | --- |
|
||||
| `.gitea/workflows/p05-ci.yml` | Manual Gitea Actions workflow with Account, Login, dependency security and disposable backend jobs |
|
||||
| `.gitea/README.md`, `.gitea/MINIFEST.md`, `.gitea/workflows/README.md`, `.gitea/workflows/MINIFEST.md` | Ownership, controls and file register for new CI configuration |
|
||||
| `tests/ci/source_contract.py` | CI-only lockfile/importer and first-party security guard structural assertions |
|
||||
| `tests/ci/oidc_discovery.py` | CI-only disposable ZITADEL readiness, discovery and public JWKS probes (not interactive login) |
|
||||
| `tests/ci/README.md`, `tests/ci/MINIFEST.md` | CI tool scope and direct-child register |
|
||||
| `users/ui/package-lock.json` | P05 account npm lock v3, generated metadata-only; reconciles `users/ui/package.json` |
|
||||
| `auth/ui/v2/pnpm-workspace.yaml` | P05 selected 3 imported workspace members only, no source logic changes |
|
||||
| `auth/ui/v2/pnpm-lock.yaml` | P05 retained 4 matching importers (root, Login, Client, Proto), package snapshots preserved |
|
||||
| `project/CI-ARCHITECTURE.md` | Runner/CI security and runtime-verification boundaries |
|
||||
| `notes/P05-CI-01.md`, `docs/P05-CI-01.md` | Pre-change plan and operator-facing CI evidence |
|
||||
|
||||
## Other first-party folders
|
||||
|
||||
`packages/README.md`: intentionally empty shared-package placeholder, not the upstream `auth/ui/v2/packages/`.
|
||||
|
||||
@@ -68,3 +68,18 @@
|
||||
## Future update minimum for each function
|
||||
|
||||
Record: exact path, function name/signature, callers, inputs/outputs, error behavior, security assumptions, user-visible effect, tests/CI reference, phase + commit. Do not speculate from a filename alone.
|
||||
|
||||
|
||||
## P05-CI-01 — CI-only verification helpers
|
||||
|
||||
| Function | Exact path | Purpose / security boundary |
|
||||
| --- | --- | --- |
|
||||
| `fail(message)` | `tests/ci/source_contract.py` | Raise a source-contract assertion with a clear reason |
|
||||
| `check_account_lock()` | Same | Check npm lock v3 root dependency snapshot against Account Portal manifest |
|
||||
| `check_login_importers()` | Same | Require exact 4-importer pnpm lockfile and existing 3 upstream workspace members |
|
||||
| `check_security_boundaries()` | Same | Static source markers for PKCE/state/nonce, expiry and nonempty protected user ID; **not** a behavioral auth test |
|
||||
| `main()` | Same | Execute CI structural checks and return clear process success/failure |
|
||||
| `fetch(path)` | `tests/ci/oidc_discovery.py` | HTTP read-only probe of disposable proxy with expected localhost Host header |
|
||||
| `main()` | Same | Check ZITADEL readiness, issuer discovery metadata and JWKS shape; print explicit interactive OIDC E2E BLOCKED |
|
||||
|
||||
Workflow service orchestration is in `.gitea/workflows/p05-ci.yml`, not Python. It executes only in Gitea CI; no local tests were requested. A green source check does not certify real authentication.
|
||||
@@ -5,6 +5,7 @@
|
||||
| [README.md](README.md) | Purpose, ownership and update rules for internal developer knowledge | DOCS-01 / active |
|
||||
| [MINIFEST.md](MINIFEST.md) | Exact direct-child file inventory | DOCS-01 / active |
|
||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Verified component boundaries, identity flows, future integration boundary | DOCS-01 / active |
|
||||
| [CI-ARCHITECTURE.md](CI-ARCHITECTURE.md) | Gitea runner jobs, dependency reconciliation, disposable infrastructure and remaining auth gates | P05-CI-01 / prepared |
|
||||
| [FILE-MAP.md](FILE-MAP.md) | First-party file + module explanation; upstream source references | DOCS-01 / active |
|
||||
| [FUNCTIONS.md](FUNCTIONS.md) | First-party function/route map, safeguards and responsibilities | DOCS-01 / active |
|
||||
| [FEATURES-AND-PAGES.md](FEATURES-AND-PAGES.md) | Every ZitPlane-owned Account Portal page/API and backend/login capability status | DOCS-01 / active |
|
||||
|
||||
@@ -26,3 +26,8 @@ Use this folder for **architecture, behavior and maintainers' internal details**
|
||||
The upstream ZITADEL Login V2 was imported unmodified from a pinned revision. Its own read-only internals should be referenced with exact file paths (and added to this knowledge base when modified in an approved later phase), not silently replaced with guessed descriptions.
|
||||
|
||||
**Security:** This is public-repository-appropriate documentation. Never include credentials, session cookies, real account IDs, tokens, production data or sensitive configuration values.
|
||||
|
||||
|
||||
## P05 CI developer entrypoint
|
||||
|
||||
Read [CI-ARCHITECTURE.md](CI-ARCHITECTURE.md) for workflow responsibilities, dependency lockfile reconciliation, smoke coverage and outstanding full OIDC gates. CI executes only on Gitea, not the developer PC.
|
||||
@@ -35,6 +35,10 @@ The Account Portal has **no dependency lockfile** yet. `npm ci`/reproducible bui
|
||||
- `packages/` is a placeholder for future ZitPlane-owned reusable UI; do not confuse with `auth/ui/v2/packages/` which are pinned upstream dependencies.
|
||||
- `notes/` = phase plans/evidence; `project/` = developer truth; `docs/` = user guides.
|
||||
|
||||
## P05-CI-01 dependency reconciliation and CI
|
||||
|
||||
The P03 upstream `pnpm-lock.yaml` contained 8 importer metadata records but the slim ZitPlane workspace only contains 4. P05 removes absent importers while preserving all original resolution package snapshots; `pnpm-workspace.yaml` explicitly lists imported Login/Client/Proto packages. The `users/ui/package-lock.json` is npm v3, generated with metadata-only package-lock command (no local installs). Gitea `.gitea/workflows/p05-ci.yml` uses `ubuntu-latest` containers to verify frozen install, build, high/critical advisory gate, and disposable backend smoke. These paths are source configuration until Gitea jobs prove them.
|
||||
|
||||
## Pending checks before any release
|
||||
|
||||
Version security review, reproducible installs, TypeScript/typecheck, Next.js build, OIDC state/PKCE, callback, token expiry, local vs global logout, self-service access, routing, secrets handling, production TLS, backup/restore, monitoring, and isolated Gitea CI verification. No current public deployment exists per recorded phase evidence.
|
||||
+38
-21
@@ -1,26 +1,27 @@
|
||||
# Source inventory ? all Git-tracked paths
|
||||
|
||||
**Snapshot:** 2026-11-22, P04 baseline `40af500` + staged DOCS-01 documentation changes. Paths read from the local Git **index**; the pending documentation commit preserves the same tracked file set.
|
||||
**Snapshot:** 2026-11-22, P05-CI-01 staging based on baseline `7ecf531`. Files listed from the local Git index; final Git commit records the snapshot.
|
||||
|
||||
**Tracked paths in this snapshot: 701.** Ignored `.env` secrets and unrelated untracked `AI_INSTRUCTIONS.md` are **not included**.
|
||||
**Tracked paths: 714.** Excludes ignored secrets, local builds and untracked `AI_INSTRUCTIONS.md`.
|
||||
|
||||
This is an **exact path and ownership locator**, not a claim that every imported function has been reviewed. For first-party behavior see `project/FILE-MAP.md` and `project/FUNCTIONS.md`. The upstream Login V2 subtree is preserved from v4.20.4.
|
||||
This is an exact **source location inventory**, not an audit of each upstream Login V2 function or proof of CI success. For behavior see `project/FILE-MAP.md`, `project/FUNCTIONS.md` and the phase evidence.
|
||||
|
||||
| Group | Files | Ownership / history |
|
||||
| Group | Files | Ownership |
|
||||
| --- | ---: | --- |
|
||||
| `(repository root)` | 6 | First-party root configuration and entrypoints |
|
||||
| `auth` | 639 | P03 pinned upstream Login V2 import |
|
||||
| `core` | 2 | P02 ZITADEL orchestration, not Go backend source |
|
||||
| `deployment` | 2 | P02 local-only Compose |
|
||||
| `docs` | 12 | P01-P04 user/phase evidence + DOCS-01 |
|
||||
| `notes` | 4 | DOCS-01 phase plans and records |
|
||||
| `packages` | 1 | P01 future shared package placeholder |
|
||||
| `project` | 9 | DOCS-01 developer knowledge and inventory |
|
||||
| `scripts` | 1 | P01 future script placeholder |
|
||||
| `tests` | 2 | P02 backend helper contracts |
|
||||
| `users` | 23 | P04 Account Portal Next.js source |
|
||||
| `(repository root)` | 6 | Main Git/project config and documentation navigation |
|
||||
| `.gitea` | 5 | Gitea CI workflows and owner documentation |
|
||||
| `auth` | 639 | Pinned upstream Login V2 and dependency workspace |
|
||||
| `core` | 2 | Official backend orchestration; not Go core source |
|
||||
| `deployment` | 2 | Local-only P02 Compose |
|
||||
| `docs` | 13 | User/operator docs and evidence |
|
||||
| `notes` | 5 | Phase plans and logs |
|
||||
| `packages` | 1 | Future first-party shared component placeholder |
|
||||
| `project` | 10 | Developer knowledge and source inventory |
|
||||
| `scripts` | 1 | Future development script placeholder |
|
||||
| `tests` | 6 | P02 static and P05 CI-only verification scripts |
|
||||
| `users` | 24 | P04 Account Portal and P05 lockfile |
|
||||
|
||||
## Exact tracked paths
|
||||
## Exact Git-tracked paths
|
||||
|
||||
### (repository root) ? 6 files
|
||||
|
||||
@@ -31,6 +32,14 @@ This is an **exact path and ownership locator**, not a claim that every imported
|
||||
- `MINIFEST.md`
|
||||
- `README.md`
|
||||
|
||||
### .gitea ? 5 files
|
||||
|
||||
- `.gitea/MINIFEST.md`
|
||||
- `.gitea/README.md`
|
||||
- `.gitea/workflows/MINIFEST.md`
|
||||
- `.gitea/workflows/README.md`
|
||||
- `.gitea/workflows/p05-ci.yml`
|
||||
|
||||
### auth ? 639 files
|
||||
|
||||
- `auth/ui/v2/.npmrc`
|
||||
@@ -683,7 +692,7 @@ This is an **exact path and ownership locator**, not a claim that every imported
|
||||
- `deployment/README.md`
|
||||
- `deployment/docker/compose.backend.dev.yaml`
|
||||
|
||||
### docs ? 12 files
|
||||
### docs ? 13 files
|
||||
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/DEVELOPMENT.md`
|
||||
@@ -692,27 +701,30 @@ This is an **exact path and ownership locator**, not a claim that every imported
|
||||
- `docs/P02-EVIDENCE.md`
|
||||
- `docs/P03-SOURCE-IMPORT.md`
|
||||
- `docs/P04-ACCOUNT-PORTAL.md`
|
||||
- `docs/P05-CI-01.md`
|
||||
- `docs/PHASES.md`
|
||||
- `docs/README.md`
|
||||
- `docs/SETUP-GUIDE.md`
|
||||
- `docs/TROUBLESHOOTING.md`
|
||||
- `docs/USER-GUIDE.md`
|
||||
|
||||
### notes ? 4 files
|
||||
### notes ? 5 files
|
||||
|
||||
- `notes/CHANGELOG.md`
|
||||
- `notes/DOCS-01.md`
|
||||
- `notes/MINIFEST.md`
|
||||
- `notes/P05-CI-01.md`
|
||||
- `notes/README.md`
|
||||
|
||||
### packages ? 1 files
|
||||
|
||||
- `packages/README.md`
|
||||
|
||||
### project ? 9 files
|
||||
### project ? 10 files
|
||||
|
||||
- `project/ARCHITECTURE.md`
|
||||
- `project/CHANGELOG.md`
|
||||
- `project/CI-ARCHITECTURE.md`
|
||||
- `project/FEATURES-AND-PAGES.md`
|
||||
- `project/FILE-MAP.md`
|
||||
- `project/FUNCTIONS.md`
|
||||
@@ -725,18 +737,23 @@ This is an **exact path and ownership locator**, not a claim that every imported
|
||||
|
||||
- `scripts/README.md`
|
||||
|
||||
### tests ? 2 files
|
||||
### tests ? 6 files
|
||||
|
||||
- `tests/README.md`
|
||||
- `tests/ci/MINIFEST.md`
|
||||
- `tests/ci/README.md`
|
||||
- `tests/ci/oidc_discovery.py`
|
||||
- `tests/ci/source_contract.py`
|
||||
- `tests/test_backend_dev.py`
|
||||
|
||||
### users ? 23 files
|
||||
### users ? 24 files
|
||||
|
||||
- `users/ui/.env.example`
|
||||
- `users/ui/.gitignore`
|
||||
- `users/ui/README.md`
|
||||
- `users/ui/next-env.d.ts`
|
||||
- `users/ui/next.config.ts`
|
||||
- `users/ui/package-lock.json`
|
||||
- `users/ui/package.json`
|
||||
- `users/ui/src/app/(protected)/account/page.tsx`
|
||||
- `users/ui/src/app/(protected)/account/profile/page.tsx`
|
||||
|
||||
Reference in new issue
Block a user