Files

77 lines
5.3 KiB
Markdown
Raw Permalink Normal View History

# ZitPlane — Central Account Portal (P04)
**Status:** Source foundation implemented, **not built, tested, started or deployed**. The UI is compact and responsive, but its visual redesign is reserved for P06.
This is a separate Next.js 16 + React 19 App Router frontend using Auth.js / NextAuth.js 5.0.0-beta.32 and the built-in **ZITADEL OIDC provider**. No passwords, token-management UI, fake sessions or credentials are stored by this application. It does not replace the official ZITADEL Admin Console or the Login V2 frontend.
## Simple folder guide
| Folder | Change here for |
| --- | --- |
| `src/app/signin/` | Public sign-in entry (redirects to ZITADEL) |
| `src/app/(protected)/account/` | Overview, read-only profile and security landing pages |
| `src/components/` | Navigation shell, buttons and reusable display components |
| `src/styles/globals.css` | Mobile, light/dark styling and design tokens |
| `src/auth.ts` | **Protected** OIDC/auth configuration. Never edit for visual tasks |
| `src/lib/env.ts` | **Protected** runtime configuration validation |
| `src/lib/identity.ts` | **Protected** mandatory server-side identity checks |
| `src/app/api/` | Auth.js OIDC callback route and a protected, read-only `/api/account/me` |
| `src/types/` | Auth.js session type (immutable ZITADEL user ID) |
## Routes and what works in source
- `/` redirects to `/account`.
- `/signin` offers **real Auth.js OIDC sign-in**, no mock login.
- `/account` is server-side protected.
- `/account/profile` displays OIDC name/email/immutable subject **read-only**.
- `/account/security` explains credential ownership and links to ZITADEL self-service **if enabled for this user**. No local password/MFA editing is claimed.
- `/api/account/me` returns the authenticated user's ID/name/email only, or 401; no-store, no privileged ZITADEL API.
- `Sign out of portal` ends the local Auth.js session, **not necessarily global ZITADEL/other SaaS SSO**.
- The portal **never** manages app billing, subscriptions, license keys or product permissions.
Access is checked in the protected layout **and individually in sensitive pages/API routes** using a nonempty verified session.user.id. Token expiry is tracked; if expiry is absent or past, the user ID is cleared (fail closed). Identity comes from the OIDC `sub`/providerAccountId, not mutable email. Refresh tokens, explicit global SSO logout, session revocation and account edit workflows are NOT implemented in P04.
## Future development settings (DOCUMENTATION ONLY)
Choose a dedicated **confidential ZITADEL Web/OIDC client**, authorization code + PKCE, with client secret held only on the account server. Do NOT reuse the official Login V2 service PAT, the ZITADEL master key, an arbitrary public client secret, or another SaaS app's client credentials.
In development, register the exact callback:
`http://localhost:3001/api/auth/callback/zitadel`
For production, register the exact callback:
`https://account.vib.tools/api/auth/callback/zitadel`
Enable HTTP redirect dev mode **only on disposable local ZITADEL**. The production OIDC issuer and `AUTH_URL` must be HTTPS.
Provide runtime variables (see `.env.example`):
| Variable | Purpose |
| --- | --- |
| `ZITADEL_ISSUER` | External, browser-accessible ZITADEL issuer URL, e.g. https://auth.vib.tools |
| `ZITADEL_CLIENT_ID` | Dedicated Account Portal OIDC client ID |
| `ZITADEL_CLIENT_SECRET` | Dedicated server-side confidential client secret |
| `AUTH_SECRET` | Unique random secret, at least 32 characters |
| `AUTH_URL` | Exact public Account Portal origin (no trailing path) |
| `AUTH_TRUST_HOST` | `true` only behind a correctly configured, trusted reverse proxy |
Neither P02 Docker nor a production domain is wired to this portal in P04. An isolated Gitea CI phase will first need to create a **reviewed deterministic lockfile** (this phase did not install dependencies), install dependencies, validate Auth.js beta/Next.js compatibility, typecheck/build, perform security checks and test OIDC callbacks against disposable ZITADEL. **Until those gates pass, do not deploy or claim production readiness.**
## Source-only dependency notes
Pinned versions are declared in `package.json` without package-manager invocation. Auth.js 5.0.0-beta.32 is the patched version for GHSA-8fpg-xm3f-6cx3; both route protection and API access additionally require `session.user.id`, not just a truthy session. Future CI must review new security advisories and create a locked dependency graph. `npm ci` cannot work until the lockfile is created and approved.
## Security notes for AI UI editors
- Allowed visual edits in later P06: `src/components/**`, `src/styles/**` and approved page JSX only.
- Do not touch `src/auth.ts`, credential validation, OIDC callbacks, token expiration, protected layout or API routes without separate approval.
- No `mockUser`, hardcoded JWT, localStorage token, browser-side master key or administrative API calls.
- ZITADEL user self-service link is an interim navigation aid; route access/feature availability is policy-dependent.
- Auth.js uses browser redirects and server actions, never direct browser calls to token endpoints.
Sources:
- https://zitadel.com/docs/sdk-examples/nextjs
- https://authjs.dev/getting-started/installation?framework=Next.js
- https://authjs.dev/getting-started/session-management/protecting
- https://github.com/nextauthjs/next-auth/security/advisories/GHSA-8fpg-xm3f-6cx3