docs: establish ZitPlane notes project and user documentation governance
This commit is contained in:
1 parent
40af500750
commit
7ecf531697
22 files changed
+1507
No files matched your search
@@ -0,0 +1,27 @@
|
||||
# ZitPlane — Actual feature availability / limitations
|
||||
|
||||
Snapshot: 2026-11-22, baseline `40af500`. **SOURCE EXISTS != RUNNING != VERIFIED != PRODUCTION**.
|
||||
|
||||
| Feature | Source present | CI/build verified | Live/deployed |
|
||||
| --- | --- | --- | --- |
|
||||
| Official ZITADEL Go backend image configuration | Yes, P02 | No | No |
|
||||
| Local PostgreSQL and loopback Traefik stack | Yes, P02 | No | No |
|
||||
| Official prebuilt Login V2 service in local Compose | Yes, P02 configuration | No | No |
|
||||
| Official Login V2 customisable source | Yes, P03 v4.20.4 | No | No |
|
||||
| Login V2 signup/password/OTP/MFA/passkey/IDP source routes | Present upstream | No | No |
|
||||
| Custom Account Portal Next.js app | Yes, P04 | No | No |
|
||||
| Portal login OIDC and Auth.js callbacks | Yes, P04 source | No | No |
|
||||
| Portal Overview / Profile / Security pages | Yes, P04 | No | No |
|
||||
| Read-only `GET /api/account/me` | Yes, P04 | No | No |
|
||||
| Password/MFA/passkey changes *inside* Account Portal | No | N/A | No |
|
||||
| Mutable profile editing / device sessions / identity deletion | No | N/A | No |
|
||||
| Global ZITADEL SSO logout | No | N/A | No |
|
||||
| Subscriptions, payments and SaaS billing | Outside ZitPlane scope | N/A | No |
|
||||
| Gitea Actions CI and isolated integration tests | No | No | No |
|
||||
| Coolify production stack, TLS, routing and backups | No | No | No |
|
||||
| Public `auth.vib.tools/login` URL | Proposed only | No | No |
|
||||
| Public `account.vib.tools` account website | Proposed only | No | No |
|
||||
|
||||
Prior historical **P02 source-only Python static tests** passed 3/3 in earlier work, and P03 upstream imported Git blobs matched 638/638. These are **not equivalent** to a running authentication system.
|
||||
|
||||
Future feature additions need an evidence-backed status update here, an exact developer implementation record in `project/`, a pre-change scope entry in `notes/`, and corresponding user guide updates.
|
||||
@@ -0,0 +1,20 @@
|
||||
# docs/ manifest
|
||||
|
||||
Every file listed below is a direct child of `docs/`. Add/remove rows whenever this folder changes. `MINIFEST.md` is the requested literal filename, not a typo to be renamed.
|
||||
|
||||
| File | Purpose | Phase / status |
|
||||
| --- | --- | --- |
|
||||
| [README.md](README.md) | Documentation responsibilities, audience, navigation and change rules | DOCS-01 / active |
|
||||
| [MINIFEST.md](MINIFEST.md) | Direct-file manifest and phase ownership | DOCS-01 / active |
|
||||
| [USER-GUIDE.md](USER-GUIDE.md) | Source-grounded Account Portal page/button-by-button manual | DOCS-01 / active; runtime 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 |
|
||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Existing architecture outline and security boundaries | P01-P04 / existing |
|
||||
| [DEVELOPMENT.md](DEVELOPMENT.md) | Existing developer setup notes and phase status | P01-P04 / existing |
|
||||
| [PHASES.md](PHASES.md) | P01-P07 plans, allowed scopes and progress | P01-P04 / existing |
|
||||
| [P02-EVIDENCE.md](P02-EVIDENCE.md) | Development Compose implementation and unverified runtime | P02 / existing |
|
||||
| [P03-SOURCE-IMPORT.md](P03-SOURCE-IMPORT.md) | Exact ZITADEL upstream import source/blob audit and CI backlog | P03 / existing |
|
||||
| [P04-ACCOUNT-PORTAL.md](P04-ACCOUNT-PORTAL.md) | Account Portal source, security assumptions and pending CI | P04 / existing |
|
||||
|
||||
No new subfolders in `docs/` at DOCS-01. Future subfolders need their own `README.md` and `MINIFEST.md` if project-owned; do not rewrite upstream vendor directories merely to add documentation.
|
||||
@@ -0,0 +1,26 @@
|
||||
# docs/ — ZitPlane User & Operator Documentation
|
||||
|
||||
**Purpose:** the Git-tracked, **user-facing** knowledge base: real functions, pages, controls, account behavior, prerequisites, how to use each available capability, troubleshooting and limitations.
|
||||
|
||||
**Current product status:** P02 local backend Compose, P03 imported Login V2 source, P04 account portal source. No integrated deployed product yet; Account Portal dependency installs/builds, login and health checks remain unverified. **Do not claim pages/buttons are working in production merely because source exists.**
|
||||
|
||||
## What to read
|
||||
|
||||
1. [USER-GUIDE.md](USER-GUIDE.md) — every currently first-party Account Portal page, button and link, security/login semantics.
|
||||
2. [SETUP-GUIDE.md](SETUP-GUIDE.md) — current dev stack prerequisites, account OIDC setup plan, configuration variables and boundaries.
|
||||
3. [FEATURES-STATUS.md](FEATURES-STATUS.md) — implemented vs not yet integrated/tested/available.
|
||||
4. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common observable issues and *safe* diagnosis.
|
||||
5. [DEVELOPMENT.md](DEVELOPMENT.md) — existing developer quick start; includes pending CI/testing warnings.
|
||||
6. [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview (technical context).
|
||||
7. [PHASES.md](PHASES.md), [P02-EVIDENCE.md](P02-EVIDENCE.md), [P03-SOURCE-IMPORT.md](P03-SOURCE-IMPORT.md), [P04-ACCOUNT-PORTAL.md](P04-ACCOUNT-PORTAL.md) — historical implemented source details and acceptance limits.
|
||||
8. [MINIFEST.md](MINIFEST.md) — exact files and purposes.
|
||||
|
||||
## Rules for every future developer/AI agent
|
||||
|
||||
- Update the **corresponding user guide and button/page instructions in the same approved phase** as code changes.
|
||||
- For each feature: name, who can use it, URL, action/button, what data it shows or changes, errors/permissions, prerequisites, exact current status and verified evidence.
|
||||
- Do **not** copy implementation internals here as the only explanation; put developer file/function details under `project/`.
|
||||
- Do not omit known restrictions or advertise planned abilities as live.
|
||||
- Never publish real personal user data, passwords, access tokens or secrets.
|
||||
|
||||
Full update policy is in root [AGENTS.md](../AGENTS.md). A list of available docs is in [MINIFEST.md](MINIFEST.md).
|
||||
@@ -0,0 +1,64 @@
|
||||
# ZitPlane — Development & Deployment Setup Guide
|
||||
|
||||
**State:** This is a guide to the **current source and planned integration gates**, not proof a live install is available. No public Coolify deployment or Gitea Actions CI exists at P04.
|
||||
|
||||
## System pieces
|
||||
|
||||
- Official Go ZITADEL backend v4.20.4 (Docker image), PostgreSQL 17.10 and Traefik 3.7.7 configured in `deployment/docker/compose.backend.dev.yaml`.
|
||||
- Prebuilt official ZITADEL Login V2 image for that **local-only Compose**.
|
||||
- Imported, unchanged official Login V2 Next.js source under `auth/ui/v2/` (not wired to Compose).
|
||||
- Next.js Account Portal source under `users/ui/` (not started or wired to Compose).
|
||||
|
||||
## Requirements for optional local development (future; do not use production user data)
|
||||
|
||||
- Windows/macOS/Linux host with a supported **Docker engine + Docker Compose** (Docker Desktop with Linux containers on Windows).
|
||||
- Git, Python 3.10+ for P02 `dev.py`.
|
||||
- Account Portal requires Node.js meeting `users/ui/package.json` engine constraint (Node 22+) and dependencies **after a reviewed lockfile is created**.
|
||||
- Login V2 requires its own upstream Node/pnpm/Nx toolchain; exact frozen-install compatibility has **not** been established.
|
||||
- Local loopback TCP 8080 for the development ZITADEL proxy. Account Portal intended local port 3001 after a dev integration step.
|
||||
|
||||
## P02 local-only bootstrap commands
|
||||
|
||||
The `core/backend/zitadel/README.md` is the authoritative current helper guide. The following commands are **instructions only** (not executed in this documentation task):
|
||||
|
||||
```powershell
|
||||
cd C:\Users\Administrator\Desktop\Projects\ZitPlane
|
||||
py core/backend/zitadel/dev.py init
|
||||
py core/backend/zitadel/dev.py config
|
||||
py core/backend/zitadel/dev.py up
|
||||
py core/backend/zitadel/dev.py check
|
||||
py core/backend/zitadel/dev.py ps
|
||||
py core/backend/zitadel/dev.py down
|
||||
```
|
||||
|
||||
- `init`: generates and preserves a private, ignored root `.env`; do not put its contents in Git, docs or chat.
|
||||
- `config`: validates Compose *when Docker is available*.
|
||||
- `up`: requests detached startup and readiness; **not yet validated on this host**.
|
||||
- `check`: probes `http://localhost:8080/debug/ready`.
|
||||
- `down`: stops Compose without deliberately deleting database/bootstrap volumes; never run `down -v` on data you need.
|
||||
- The local identity seed email/username is described in `core/backend/zitadel/README.md`, but actual initial sign-in has never been verified.
|
||||
- Self-signed/local HTTP is for local development only; no public network ports or production data.
|
||||
|
||||
## Account Portal OIDC client setup (NOT performed in P04)
|
||||
|
||||
1. Create a **dedicated confidential Web/OIDC app** in a disposable ZITADEL environment, using Authorization Code + PKCE.
|
||||
2. Register the exact intended callback `http://localhost:3001/api/auth/callback/zitadel` for local development, or `https://account.vib.tools/api/auth/callback/zitadel` when production is explicitly deployed. Do not mix localhost callbacks into production.
|
||||
3. Inject secure runtime-only settings from `users/ui/.env.example`: `ZITADEL_ISSUER`, `ZITADEL_CLIENT_ID`, `ZITADEL_CLIENT_SECRET`, `AUTH_SECRET`, `AUTH_URL`, `AUTH_TRUST_HOST`.
|
||||
4. Keep confidential client secret and `AUTH_SECRET` server-side. Never use the backend master key, the official Login Client PAT or a browser-shared client secret as substitutes.
|
||||
5. CI must create/approve a deterministic Account Portal dependency lockfile and check Auth.js beta/Next.js compatibility, then build/typecheck on an isolated runner.
|
||||
6. Only after source/build acceptance, integrate Account Portal runtime, OIDC callbacks, HTTPS proxy headers and session behavior in a separately approved scope.
|
||||
7. Confirm end-to-end login, expiry, logout semantics, API 401/200 response and account self-service permissions in disposable staging.
|
||||
|
||||
**Production domains `auth.vib.tools` and `account.vib.tools` are design targets only.** Coolify configuration, TLS, persistent backup/restore, secure secret handling and production rollbacks are not implemented.
|
||||
|
||||
## User account / password / MFA management
|
||||
|
||||
The Account Portal's profile page is currently **read-only**, and security page displays guidance/links. If ZITADEL self-service is enabled, users may be redirected to its built-in Console location; access is policy-dependent and not live-verified. Do not expect local Save Password, Enroll MFA, revoke device or account deletion buttons.
|
||||
|
||||
## Administrator boundaries
|
||||
|
||||
ZITADEL Admin Console is distinct from the Account Portal. Never expose administrative API tokens or secrets to the browser. Identity administration should follow roles/policies, while billing/subscriptions/product permissions belong to individual SaaS applications.
|
||||
|
||||
## Acceptance and configuration troubleshooting
|
||||
|
||||
Refer to [FEATURES-STATUS.md](FEATURES-STATUS.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md), `docs/P02-EVIDENCE.md` and `docs/P04-ACCOUNT-PORTAL.md`. Do not claim success on a missing-run check. Future changes must update all affected docs and developer records.
|
||||
@@ -0,0 +1,25 @@
|
||||
# ZitPlane — Troubleshooting and safe diagnostics
|
||||
|
||||
**Scope:** Only describe issues the current source or recorded phase evidence supports. No live environment has been verified.
|
||||
|
||||
| Symptom | Known possible cause | Safe next action |
|
||||
| --- | --- | --- |
|
||||
| `docker` command not found | Docker CLI/Desktop was missing on the previously inspected Windows host during P02 | Install supported Docker Engine/Desktop and run only in a local disposable environment; do not treat a source manifest as runtime acceptance |
|
||||
| `docker compose config` / `up` fails | Dev Compose, h2c proxy, dependencies and image pulls were never integration-tested | Review Compose output after an approved isolated CI/dev verification, without revealing secrets; inspect P02 evidence |
|
||||
| Admin Console login fails | First-instance bootstrap, Login V2 container/PAT, auth proxy or credentials not validated | Verify local health, first-init logs and policy in a secret-safe environment; do not reinitialize volumes casually |
|
||||
| Account Portal shows no page | App dependencies are not installed; no Account Portal image, runtime or domain is configured | Complete reviewed lockfile/build/CI and explicit integration phase before troubleshooting live UI |
|
||||
| Redirect/callback error after future login | OIDC issuer/callback URL, client type/secret, proxy headers, PKCE/state or allowed redirect may mismatch | Compare exact configured origins and registered callback; never weaken checks or wildcard redirects |
|
||||
| Unauthorized on `/api/account/me` | Designed result for absent/expired user identity | Authenticate through ZITADEL; if unexpected in a future runtime, inspect token expiry and session trace securely |
|
||||
| Profile Save button missing | Portal source has read-only fields only | Use permitted ZITADEL self-service (if configured) or wait for an approved custom edit feature |
|
||||
| MFA/passkey settings not editable in portal | Portal only shows informational cards and a link | Use the identity provider's policy-supported controls; do not paste secrets into support messages |
|
||||
| Sign-out seems to leave other applications signed in | Portal `signOut` is **portal-local**, not federated logout | Close respective sessions via app/identity provider; global logout requires a future dedicated implementation |
|
||||
| `auth.vib.tools` / `account.vib.tools` unavailable | They are **planned** hostnames, no production deployment configured | Do not assume DNS/SSL/Coolify service exists; await P07 |
|
||||
| Login V2 custom source appears unchanged when starting P02 Compose | P02 Compose uses prebuilt official Login UI, not P03 imported code | Later P05 must build and wire custom image after CI and explicit approval |
|
||||
|
||||
## How to report a safe issue
|
||||
|
||||
Include environment (local disposable vs CI vs production), exact phase/commit, which page/action, a **redacted** error and reproduction conditions. Never publish `.env`, client secret, passwords, access tokens, cookies, private keys or user data. Link to relevant phase note; record the fix and updated user guidance together.
|
||||
|
||||
## Known limitations
|
||||
|
||||
No live integration verification, Account Portal lockfile, CI pipeline, Coolify production deployment, tested authentication redirects or production support guarantees exist as of P04. Before adding any diagnostic workaround, consult the Scope Lock in `notes/` and preserve ZITADEL's security boundaries.
|
||||
@@ -0,0 +1,83 @@
|
||||
# ZitPlane — Account and Login User Guide
|
||||
|
||||
**Documentation baseline:** 2026-11-22, source through P04 `40af500`.
|
||||
**Current availability:** Account Portal source exists but is **NOT built, integrated, tested or publicly deployed**. URLs and button outcomes below describe the reviewed **intended behavior of current source**. Do not treat this guide as proof the site is accessible today.
|
||||
|
||||
## Who uses which interface?
|
||||
|
||||
| Interface | URL / current status | Purpose |
|
||||
| --- | --- | --- |
|
||||
| ZITADEL identity/login (official prebuilt in P02 dev Compose) | Intended `http://localhost:8080/ui/v2/login/` in local development, not live-tested | Sign in/registration/challenge and account recovery according to ZITADEL policies |
|
||||
| ZITADEL management Console | Intended `http://localhost:8080/ui/console` locally, not live-tested | Identity administration and, if enabled, user self-service |
|
||||
| ZitPlane Account Portal | Intended `http://localhost:3001` *after* future OIDC setup/build, not running yet | Read-only account profile and security navigation |
|
||||
| Production login / account domain | `https://auth.vib.tools`, `https://account.vib.tools` are **planned only** | No production deployment, TLS or routing yet |
|
||||
|
||||
## Sign in to Account Portal
|
||||
|
||||
**Page:** `/signin` — `users/ui/src/app/signin/page.tsx`
|
||||
|
||||
1. Open the future Account Portal URL after its deployment and configuration.
|
||||
2. Choose **Continue with ZITADEL**. The form starts Auth.js sign-in with ZITADEL OIDC. Your browser is sent to the central ZITADEL login service.
|
||||
3. Authenticate using the identity methods available to your organization (password, MFA, passkey or external IdP as configured there).
|
||||
4. On successful OIDC callback, the portal is intended to redirect to `/account`. Unauthenticated or expired users should return to `/signin`.
|
||||
5. **Back to account home** links to `/`; that route redirects to `/account`. If not signed in, the protected layout redirects back to `/signin`.
|
||||
|
||||
**Signup and Forgot Password:** The Account Portal's `/signin` page has **no local registration/reset form**. Those flows belong to the official ZITADEL Login V2 service, where availability and labels depend on ZITADEL policy. ZitPlane imported the source but has not modified or tested those flows.
|
||||
|
||||
## Account Center: overview
|
||||
|
||||
**Page:** `/account` — guarded by server-side account layout.
|
||||
- **Overview** sidebar link: returns here.
|
||||
- Greeting: displays name from your OIDC session; falls back to email and then `there`.
|
||||
- **Personal information** card -> **View profile** opens `/account/profile`.
|
||||
- **Password & security** card -> **Security options** opens `/account/security`.
|
||||
- **Review account details** text link -> `/account/profile`.
|
||||
- Informational block explains one central identity can serve multiple apps; billing/product access is not controlled from this portal.
|
||||
|
||||
## Personal information
|
||||
|
||||
**Page:** `/account/profile`
|
||||
- **Profile** sidebar link: opens this page.
|
||||
- **Display name:** OIDC name claim if present, otherwise “Not provided”.
|
||||
- **Email address:** OIDC email claim if present; read-only.
|
||||
- **ZITADEL User ID:** immutable provider subject saved in the session; read-only. This is not an email address.
|
||||
- **Open ZITADEL account settings:** links to the configured issuer `/ui/console/users/me`; actual availability requires the ZITADEL Console/policies and is **unverified**.
|
||||
- **No Save/Edit/Delete buttons:** profile editing via a custom portal API is not implemented.
|
||||
|
||||
## Security settings
|
||||
|
||||
**Page:** `/account/security`
|
||||
- **Security** sidebar link: opens this page.
|
||||
- **Password:** descriptive row, not a local password editor.
|
||||
- **Multi-factor authentication:** descriptive row, not an MFA enrollment/disable button.
|
||||
- **Passkeys and security keys:** descriptive row, not a local passkey editor.
|
||||
- **Open central security settings:** takes user to the same issuer-derived ZITADEL self-service location. Available controls depend on ZITADEL version, org policy and permissions.
|
||||
- **No in-portal device sessions/revocation interface** exists at P04.
|
||||
|
||||
## Navigation, indicator and sign out
|
||||
|
||||
- **ZitPlane / Account Center** brand: navigates to `/account`.
|
||||
- Sidebar: **Overview**, **Profile**, **Security** navigation.
|
||||
- Identity tile: displays first character of name/email, name and email or generic fallback.
|
||||
- **Signed in** status indicator: derived from the authenticated layout; do not treat it as an independent security-status check.
|
||||
- **Sign out of portal:** submits Auth.js server action, clears the **portal-local** session and returns to `/signin`. **It does not promise global sign-out** from ZITADEL or other SaaS apps.
|
||||
- Footer explains this portal's identity purpose.
|
||||
- On narrow screens, navigation becomes a horizontal row and identity tile is hidden for space; sign-out remains accessible.
|
||||
- Light/dark appearance follows operating system preference via CSS `prefers-color-scheme`; no manual theme switch button exists.
|
||||
|
||||
## Account API (for authorized integrations, not a user button)
|
||||
|
||||
`GET /api/account/me` is a protected, **read-only** endpoint in the Account Portal source:
|
||||
- After a valid session: intended JSON `{ "user": { "id": "...", "name": "...", "email": "..." } }`, with nullable name/email and private/no-store.
|
||||
- Without valid user ID: intended HTTP 401 `Unauthorized`.
|
||||
- No endpoint to change password, update user fields or access administrative information is implemented in P04.
|
||||
|
||||
The behavior above has **not** been E2E verified. Do not rely on it in production before Gitea CI/staging acceptance.
|
||||
|
||||
## What to expect from official Login V2
|
||||
|
||||
Imported Login V2 source contains registration, password, verification, MFA/OTP, passkey, identity-provider, device and logout routes under `auth/ui/v2/apps/login/src/app/`. ZitPlane has **not** verified their external URL mappings, exact labels, working buttons or policy-dependent availability; do not infer enabled features from source folders. They are separate from this Account Portal.
|
||||
|
||||
## If a page does not open
|
||||
|
||||
This is expected until environment, OIDC client, dependencies, Docker integration, proxy and domains are configured in future approved phases. Consult [SETUP-GUIDE.md](SETUP-GUIDE.md), [FEATURES-STATUS.md](FEATURES-STATUS.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md). Do not share passwords or screenshots containing tokens.
|
||||
Reference in new issue
Block a user