# 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.
| 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 |
| `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.
| `fail(message)` | `tests/ci/source_contract.py` | Raise a source-contract assertion with a clear reason |
| `check_account_lock()` | Same | Check npm lock v3 root dependency snapshot against Account Portal manifest |
| `check_login_importers()` | Same | Require exact 4-importer pnpm lockfile and existing 3 upstream workspace members |
| `check_security_boundaries()` | Same | Static source markers for PKCE/state/nonce, expiry and nonempty protected user ID; **not** a behavioral auth test |
| `main()` | Same | Execute CI structural checks and return clear process success/failure |
| `fetch(path)` | `tests/ci/oidc_discovery.py` | HTTP read-only probe of disposable proxy with expected localhost Host header |
Workflow service orchestration is in `.gitea/workflows/p05-ci.yml`, not Python. It executes only in Gitea CI; no local tests were requested. A green source check does not certify real authentication.