# Functions, API handlers and important logic — reviewed first-party source **Scope:** ZitPlane-owned P02 backend helper and P04 Account Portal at baseline `40af500`. Imported Login V2 upstream functions are **not invented or paraphrased**; consult the exact paths in `auth/ui/v2/` and the full tracked-file inventory in `SOURCE-INVENTORY.md`. On an approved future Login UI change, add a reviewed function entry here with signature, inputs/outputs and caller. ## Python backend helper: `core/backend/zitadel/dev.py` | Function / entry | Purpose / input-output | Used from / protection | | --- | --- | --- | | `random_chars(alphabet, length)` | Uses Python `secrets.choice` to create unpredictable strings | Called when generating initial local dev credentials | | `create_dev_env()` | Creates ignored root `.env` **once** with random Postgres password, 32-char ZITADEL master key, initial admin password and Login session cookie secret; refuses overwrites; returns created flag | `main init`; never print secrets or use for production | | `validate_env()` | Reads local `.env`, asserts four required settings and minimum lengths; raises on invalid/missing values | Invoked before running Compose helper actions | | `docker_compose(*args)` | Ensures Docker CLI exists, then executes Compose with explicit dev YAML and local env; raises if nonzero | `main` for `up`, `down`, `ps`, `config` | | `check_ready()` | GET `http://localhost:8080/debug/ready`, requires HTTP 200, otherwise raises; prints expected Admin Console URL | `main check` or after `up` | | `main()` | CLI dispatcher with `init`, `up`, `check`, `down`, `ps`, `config`; prints BLOCKED on RuntimeError | Script entrypoint | | `if __name__ == "__main__"` | Calls `main()` and exits with its status | Python execution entrypoint | **Related YAML:** `deployment/docker/compose.backend.dev.yaml` defines Postgres readiness via `pg_isready`, ZITADEL health command `/app/zitadel ready`, official Login V2 health, and Traefik path routing. These are container declarations, **not Python functions**. ## OIDC: `users/ui/src/auth.ts` | Function / callback | Actual responsibility | Caveat | | --- | --- | --- | | `NextAuth(() => {...})` configuration callback | Creates `handlers`, `auth`, `signIn`, `signOut` with dedicated ZITADEL OIDC provider; PKCE, state and nonce requests; Auth.js-managed JWT sessions | Config and dependency compatibility unverified | | `callbacks.signIn({account,profile})` | Accepts only provider `zitadel` and nonempty OIDC `profile.sub` | Does not implement external account permissions | | `callbacks.jwt({token,account})` | Stores OIDC provider account subject and provider access-token expiry in Auth.js JWT metadata; expiry absent => 0 | No token refresh implementation | | `callbacks.session({session,token})` | Sets `session.user.id` only if subject exists and stored expiry is future; otherwise sets empty ID | All protected actions must check nonempty `user.id`, not mere session presence | ## Config + identity helpers | Function | Source | Inputs, use and guard | | --- | --- | --- | | `required(name)` | `users/ui/src/lib/env.ts` | Server-only required environment lookup; rejects blank/example placeholders | | `validatedUrl(name)` | Same | Parses URL and checks scheme, credentials, query/hash/path; production requires HTTPS; dev allows HTTP localhost | | `oidcSettings()` | Same | Loads valid issuer, client ID/secret, Auth.js secret (length 32+), portal URL and trusted-host boolean | | `requireIdentity()` | `users/ui/src/lib/identity.ts` | Reads `auth()`; no valid `session.user.id` => `redirect("/signin")`; otherwise returns current user | | `zitadelSelfServiceUrl()` | Same | Builds issuer-origin `/ui/console/users/me` link. Route/permission availability **not tested**; never accepts a browser-supplied redirect URL | ## Next.js pages and server actions | Export/function | File | Action / user impact | | --- | --- | --- | | `RootLayout({children})` | `src/app/layout.tsx` | Renders `html` / `body` wrapper and imports global stylesheet | | `Home()` | `src/app/page.tsx` | Server-side redirect from `/` to `/account` | | `SignInPage()` | `src/app/signin/page.tsx` | Calls `auth()`; sends valid users to `/account`; otherwise renders sign-in form | | `startLogin()` | Same, nested server action | Calls `signIn("zitadel", {redirectTo:"/account"})` on button submission | | `ProtectedLayout({children})` | `src/app/(protected)/layout.tsx` | Guards all routes in this route group using `requireIdentity()` | | `AccountPage()` | `src/app/(protected)/account/page.tsx` | Protected overview greeting and profile/security action cards | | `ProfilePage()` | `src/app/(protected)/account/profile/page.tsx` | Protected, read-only display name/email/subject plus self-service link | | `SecurityPage()` | `src/app/(protected)/account/security/page.tsx` | Protected informational password/MFA/passkeys page plus link | | `AccountShell({user,children})` | `src/components/account-shell.tsx` | Nav, authenticated identity tile, sign-out form, topbar and footer | | `portalLogout()` | Same, nested server action | Calls Auth.js `signOut({redirectTo:"/signin"})`; not global SSO logout | | `AccountCard({title,description,href,action})` | `src/components/account-card.tsx` | Reusable linked overview card | | `DataRow({label,value})` | Same | Read-only `dt/dd` identity field with Not provided fallback | ## Next.js HTTP/API handlers | Export | File | Security and behavior | | --- | --- | --- | | `GET`, `POST` (Auth.js handlers) | `src/app/api/auth/[...nextauth]/route.ts` | Delegated to Auth.js `handlers`; callback and session endpoints | | `GET()` | `src/app/api/account/me/route.ts` | Calls `auth()`; nonempty `session.user.id` required; 401 otherwise; returns current id/name/email with private/no-store | | `generateMetadata` | No first-party custom implementation present | Do not invent one; static metadata objects exist in pages | | `next.config.ts async headers()` | `users/ui/next.config.ts` | Declares response security headers via Next config; not an account API | ## Previous first-party unit test functions (prior phase) `tests/test_backend_dev.py`: `BackendDevContract.test_initialization_is_private_and_idempotent`, `test_compose_local_only_and_version_pinned`, `test_secrets_ignored`. They validate **static P02 contracts**, not real authentication or Docker. ## 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.