177 lines
15 KiB
Markdown
177 lines
15 KiB
Markdown
# File and module ownership map
|
|
|
|
**Baseline:** commit `40af500` with documentation phase DOCS-01 in progress. This is an **exact first-party role map** plus pointers to the complete upstream source inventory. See [SOURCE-INVENTORY.md](SOURCE-INVENTORY.md) for the individual paths of **all Git-tracked files**, including the imported upstream.
|
|
|
|
## Repository root / governance
|
|
|
|
| Path | Purpose / when to change |
|
|
| --- | --- |
|
|
| `README.md` | Entry point, project status, quick navigation; update whenever phase/status changes |
|
|
| `AGENTS.md` | Mandatory coding/AI rules, scope, docs-first updates and security boundaries |
|
|
| `.gitignore` | Prevent local secrets/build data from being staged; change only with explicit review |
|
|
| `.editorconfig` | Editor line ending/indentation defaults |
|
|
| `.env.example` | Non-secret sample keys for P02 backend helper; **never commit actual root `.env`** |
|
|
| `notes/` | Pre-change plans, decisions, chronological implementation and evidence logs |
|
|
| `project/` | Developer explanations, module/function/page map and actual source inventory |
|
|
| `docs/` | End-user how-to, setup, features, existing phase/evidence documents |
|
|
|
|
## P02 backend + deployment
|
|
|
|
| Path | What it actually owns | Phase |
|
|
| --- | --- | --- |
|
|
| `core/backend/zitadel/dev.py` | Python stdlib helper `init`, `config`, `up`, `check`, `ps`, `down`; creates ignored local secrets and invokes Compose, readiness probe | P02 |
|
|
| `core/backend/zitadel/README.md` | Dev-only infrastructure setup guidance, assumptions and warnings | P02 |
|
|
| `deployment/docker/compose.backend.dev.yaml` | Named `postgres`, `zitadel-api`, `zitadel-login` (prebuilt), `proxy`; Postgres/Bootstrap volumes, Docker network, local port, health checks | P02 |
|
|
| `deployment/README.md` | Deployment scope/hardening placeholder; no production Compose exists | P01 |
|
|
| `tests/test_backend_dev.py` | Prior three focused Python stdlib static/secret-generation checks; NOT a live Docker acceptance test | P02 |
|
|
| `tests/README.md` | Test folder introduction | P01 |
|
|
| `scripts/README.md` | Placeholder for future scripts; no standalone project scripts yet | P01 |
|
|
|
|
## P03 imported official ZITADEL Login V2
|
|
|
|
| Path | Responsibility | What to change |
|
|
| --- | --- | --- |
|
|
| `auth/ui/v2/apps/login/src/app/` | Official Next.js login route/page implementation; login, registration, challenges, IDP and recovery | Only within approved Login UI phase; auth behavior protected |
|
|
| `auth/ui/v2/apps/login/src/components/` | Official reusable form/UI components | Later visual phase with regression checks |
|
|
| `auth/ui/v2/apps/login/src/styles/` | Official Login presentation styling | Later visual phase |
|
|
| `auth/ui/v2/apps/login/public/` | Login static assets, logos, favicons | Later branding phase |
|
|
| `auth/ui/v2/apps/login/locales/` | Upstream translations | Later translation phase |
|
|
| `auth/ui/v2/apps/login/src/lib/` | Protected login backend/session helpers | Separate security-scoped approval |
|
|
| `auth/ui/v2/apps/login/src/proxy.ts` | Official Next.js request/proxy route handling | Protected routing code |
|
|
| `auth/ui/v2/apps/login/package.json` | Login scripts/dependencies, workspace linkages | Version/security phase only |
|
|
| `auth/ui/v2/apps/login/project.json` | Nx targets and dependencies | Build infrastructure phase |
|
|
| `auth/ui/v2/apps/login/Dockerfile` | Official Login UI image definition | Image-build integration phase |
|
|
| `auth/ui/v2/packages/zitadel-client/` | Upstream ZITADEL JS client | Do not edit for visual UI |
|
|
| `auth/ui/v2/packages/zitadel-proto/` | Upstream generated API type project | Generated output; not hand-edit |
|
|
| `auth/ui/v2/proto/` | Upstream protocol definitions | No UI edit |
|
|
| `auth/ui/v2/pnpm-lock.yaml` | Original upstream dependency graph; frozen-build compatibility pending CI | Dependency phase only |
|
|
| `auth/ui/v2/pnpm-workspace.yaml`, `nx.json`, `package.json` | Original workspace structure/tooling | Dependency/build phase |
|
|
| `auth/ui/v2/LICENSING.md`, `LICENSE` | Upstream licensing terms; preserve | Legal compliance |
|
|
| `auth/ui/v2/README.md` | ZitPlane import/user-maintainer guide | When upstream login source changes |
|
|
|
|
Upstream import: official ZITADEL `v4.20.4` / Git `384bb9ec96b501ad39dc232ee2061a40fe180bbd`. Imported files are intentionally byte-for-byte identical except two excluded upstream environment files. **No source edit was performed in P03.** See `docs/P03-SOURCE-IMPORT.md`.
|
|
|
|
## P04 Account Portal (first-party) — complete source file map
|
|
|
|
| Source | Purpose |
|
|
| --- | --- |
|
|
| `users/ui/package.json` | Next.js/React/Auth.js dependency versions and dev/build/start/typecheck scripts; lockfile not yet generated |
|
|
| `users/ui/tsconfig.json` | TypeScript strict configuration and `@/*` alias |
|
|
| `users/ui/next-env.d.ts` | Next.js TypeScript references |
|
|
| `users/ui/next.config.ts` | Standalone output, security-related response headers, strict React mode |
|
|
| `users/ui/.env.example` | Configuration key names only; never real secrets |
|
|
| `users/ui/.gitignore` | Ignore Next.js build output, node_modules, and env data |
|
|
| `users/ui/src/auth.ts` | Auth.js ZITADEL provider/callbacks and encrypted cookie session integration; protected security logic |
|
|
| `users/ui/src/lib/env.ts` | Validates OIDC issuer/portal origin/client credentials/secret |
|
|
| `users/ui/src/lib/identity.ts` | `requireIdentity()` and issuer-derived ZITADEL self-service link |
|
|
| `users/ui/src/types/next-auth.d.ts` | Session user ID and JWT subject/expiry type augmentation |
|
|
| `users/ui/src/app/layout.tsx` | Root page shell, metadata, global stylesheet import |
|
|
| `users/ui/src/app/page.tsx` | `/` redirects to `/account` |
|
|
| `users/ui/src/app/signin/page.tsx` | Sign-in form; server action triggers Auth.js ZITADEL OIDC redirect |
|
|
| `users/ui/src/app/(protected)/layout.tsx` | Mandatory server-side account identity gate + sidebar shell |
|
|
| `users/ui/src/app/(protected)/account/page.tsx` | Account overview cards and identity greeting |
|
|
| `users/ui/src/app/(protected)/account/profile/page.tsx` | Read-only profile fields and ZITADEL account link |
|
|
| `users/ui/src/app/(protected)/account/security/page.tsx` | Password/MFA/passkey informational rows and ZITADEL security link |
|
|
| `users/ui/src/app/api/auth/[...nextauth]/route.ts` | Auth.js handlers for sign-in/callback/session support |
|
|
| `users/ui/src/app/api/account/me/route.ts` | GET current user ID/name/email, or 401 |
|
|
| `users/ui/src/components/account-shell.tsx` | Responsive sidebar/topbar/footer/sign-out form |
|
|
| `users/ui/src/components/account-card.tsx` | Reusable overview Card and profile DataRow |
|
|
| `users/ui/src/styles/globals.css` | Design tokens, compact layout, responsive/mobile/light-dark styling |
|
|
| `users/ui/README.md` | Beginner maintainer guide, routes/config/security contract |
|
|
|
|
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 |
|
|
|
|
## P05-CI-02 file ownership update
|
|
|
|
| Path | Verified narrow function |
|
|
| --- | --- |
|
|
| `users/ui/src/auth.ts` | `callbacks.session` optional JWT subject type narrowing; no change to provider, policy or PKCE/state/nonce |
|
|
| `.gitea/workflows/p05-ci.yml` | CI-only Account negative smoke, Postgres restart persistence, registry advisory JSON collection, portless Compose config and cleanup status |
|
|
| `tests/ci/compose.portless.override.yaml` | Post-run CI-only removal of inherited developer Traefik host port 8080; unverified until next CI run |
|
|
| `tests/ci/account_negative.py` | Anonymous API 401 and protected route redirect CI probe |
|
|
| `tests/ci/advisory_triage.py` | Nonmutating npm/pnpm vulnerability inventory with IDs and patch availability |
|
|
| `tests/ci/oidc_discovery.py` | Read-only disposable issuer/JWKS negative validation and live metadata smoke |
|
|
| `notes/P05-CI-02.md`, `docs/P05-CI-02.md` | Pre-change Scope Lock, actual Gitea CI results and user/operator limitations |
|
|
|
|
## Other first-party folders
|
|
|
|
`packages/README.md`: intentionally empty shared-package placeholder, not the upstream `auth/ui/v2/packages/`.
|
|
`users/ui/public/`: currently no public assets registered. `project/` and `docs/` files are indexed by their own `MINIFEST.md`.
|
|
|
|
## Exact-file maintenance workflow
|
|
|
|
For any approved update:
|
|
1. Find target in this map, then open the actual source file and verify current behavior.
|
|
2. Record before/after and Scope Lock in `notes/`.
|
|
3. Change only approved files. Update relevant function/feature and user docs in the same phase.
|
|
4. Add change record to `project/CHANGELOG.md` and sync `MINIFEST.md` / source inventory if structure changes.
|
|
5. Do not rewrite or claim knowledge of every upstream function without examining it. Imported source internals stay officially sourced until audited for an approved edit.
|
|
|
|
|
|
## P05-CI-03 backend-only CI map
|
|
|
|
| Path | Actual role / ownership |
|
|
| --- | --- |
|
|
| `.gitea/workflows/p05-backend-acceptance.yml` | New manual backend-only Gitea job; excludes redundant Account/Login suites; bounded Alpine Git/Docker prerequisite, acceptance and always cleanup |
|
|
| `tests/ci/backend_acceptance.sh` | CI project collision checks, portless effective Compose, four services, disposable PostgreSQL restart, OIDC/JWKS smoke; **CI only** |
|
|
| `tests/ci/backend_cleanup.sh` | Cleanup gated on CI-generated ownership marker; down -v for that Compose project and orphan/volume/network checks |
|
|
| `tests/ci/compose.portless.override.yaml` | Existing P05-CI-02 CI-only reset of inherited P02 Traefik host binding; read-only in this phase |
|
|
| `tests/ci/oidc_discovery.py` | Existing negative and live metadata/JWKS verification; read-only in this phase |
|
|
| `docs/P05-CI-03.md`, `notes/P05-CI-03.md` | Public-facing CI procedure and accurate implementation/run evidence |
|
|
|
|
P02 dev Compose, core backend helper, Login V2 source, Account Portal and all dependency manifests remain unmodified.
|
|
|
|
|
|
## P05-SEC-01 — Dependency security file ownership
|
|
|
|
| Path | Exact authorized behavior |
|
|
| --- | --- |
|
|
| `users/ui/package.json` and `users/ui/package-lock.json` | Account Portal direct Next.js 16.4.6 security pin and npm v3 metadata-only lock |
|
|
| `auth/ui/v2/apps/login/package.json` | Official Login V2 dependency **declaration only**: Next.js/ESLint plugin and coordinated OpenTelemetry SDK/auto instrumentation; original app/auth source untouched |
|
|
| `auth/ui/v2/pnpm-lock.yaml` | Reproducible PNPM v10.30.3 resolution with pruned unreachable snapshots from former large upstream workspace |
|
|
| `.gitea/workflows/p05-security-acceptance.yml` | Manual four-job CI: independent Account/Login frozen builds and Account/Login production advisory gates |
|
|
| `tests/ci/security_advisory_gate.py` | Rejects malformed npm/pnpm JSON or any Moderate/High/Critical audit record; never suppresses or changes packages |
|
|
| `project/DEPENDENCY-SECURITY.md` | Detailed GHSA/group/parent/versions/patch/risk and CI disposition |
|
|
| `notes/P05-SEC-01.md`, `docs/P05-SEC-01.md` | Pre-change plan, source patch provenance, actual run results and operator guidance |
|
|
|
|
**Read-only:** `auth/ui/v2/pnpm-workspace.yaml`, all `users/ui/src/**`, original Login V2 components/logic, backend/Compose and unrelated monorepo packages.
|
|
|
|
|
|
## P05-SEC-02 — focused transitive dependency file map
|
|
|
|
| Path | Exact responsibility |
|
|
| --- | --- |
|
|
| `auth/ui/v2/pnpm-workspace.yaml` | Seven exact **parent-targeted** glob/minimatch major fixes; previous workspace overrides unchanged |
|
|
| `auth/ui/v2/pnpm-lock.yaml` | Pinned PNPM v10.30.3 lock metadata, patched transitive versions, original four importers |
|
|
| `.gitea/workflows/p05-security-acceptance.yml` | Optional `login_only=true` manual dispatch, no Account rerun; Login install/build/unit and independent production strict security audit |
|
|
| `tests/ci/transitive_override_contract.py` | CI checks only seven exact parent overrides; old affected package versions absent; parents resolve patched version |
|
|
| `notes/P05-SEC-02.md`, `docs/P05-SEC-02.md` | Pre-edit parent-chain evidence, exact patch and actual run outcome |
|
|
|
|
Official Login V2 user/auth source, user Account Portal, backend Compose and production infrastructure remain unmodified.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
**P05-OIDC-03:** `tests/ci/oidc_e2e/forwarder.py` new CI-only asyncio stdlib opaque TCP localhost relay. `tests/ci/oidc_e2e/run.sh` now first classifies existing socat startup stderr into fixed safe error classes and, on unhealthy socat, switches only once to immutable-digest official Python within the same run-owned container name/network namespace. `cleanup.sh` and `provision.py` untouched; `browser.cjs`, `users/ui/**`, `auth/ui/v2/**` and the original P02 Compose untouched.
|