Files
ZitPlane/users/ui/README.md
T

5.3 KiB

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: