Files
ZitPlane/project/FUNCTIONS.md
T

6.5 KiB

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.