# Backend Reference > Read-only reference for the backend contracts that the frontend depends on, including routing, APIs, auth, layers, and module resolution. - Skill: `agent0ai/backend-reference` (Agent Skill) - Install (CLI): `npx skillmds@latest add agent0ai/backend-reference` - Raw SKILL.md: https://api.skillmd.com/api/skills/agent0ai/backend-reference/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: agent0ai (https://skillmd.com/u/agent0ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agent0ai/backend-reference --- Use this skill when frontend work depends on understanding backend behavior. This skill is read-only context, not authorization to change backend files. ## Hard Boundary - Do not edit `server/`, `commands/`, or `packaging/` from this skill set. - If the task truly requires backend changes, stop and ask instead of treating this skill as permission. - Backend changes are non-standard in this project. Only ask for them when frontend-only work cannot safely enforce security, integrity, cross-user isolation, or runtime stability. - When you ask, explain why the frontend solution would be insufficient and describe the narrow backend change required. ## Page And Request Flow Current request order is: 1. API preflight handling 2. `/api/proxy` 3. `/api/` 4. `/mod/...` 5. `/~/...` and `/L0/...`, `/L1/...`, `/L2/...` 6. page shells and page actions The browser app mounts through page shells in `server/pages/`. `/login` is public. `/` and `/admin` require authentication. ## API Families Important frontend-facing endpoint families are: - app files: `file_list`, `file_paths`, `file_read`, `file_write`, `file_delete`, `file_copy`, `file_move`, `file_info`, `folder_download` - local history: `git_history_list`, `git_history_diff`, `git_history_preview`, `git_history_rollback`, `git_history_revert` - modules: `module_list`, `module_info`, `module_install`, `module_remove` - runtime and identity: `extensions_load`, `password_generate`, `password_change`, `user_crypto_session_key`, `user_self_info` These endpoints are thin wrappers over shared helpers in `server/lib/customware/` and `server/lib/auth/`. `file_write` still defaults to whole-file replacement, but it also supports `operation: "append"`, `"prepend"`, and `"insert"`. Insert writes accept exactly one anchor through `line`, `before`, or `after`, use the first literal `before` or `after` match, treat `line` as a 1-based insertion point, and require `utf8`. `file_list` and `file_paths` support `access: "write"` or `writableOnly: true` for writable-only discovery. They also support `gitRepositories: true`; with a pattern such as `**/.git/`, `file_paths` returns local-history owner roots like `L1/team/` and `L2/alice/` without exposing reserved `.git` metadata paths. `folder_download` supports `HEAD` for permission-only validation and `GET` or `POST` for the streamed ZIP attachment. It creates the archive in `server/tmp/` only for the actual download response, after the shared file-access layer approves the requested folder path. `git_history_list`, `git_history_diff`, `git_history_preview`, `git_history_rollback`, and `git_history_revert` are enabled by `CUSTOMWARE_GIT_HISTORY`. The backend maps the requested path to a writable `L1//` or `L2//` owner repo, enforces permissions, paginates list metadata with optional file filters, reads per-file diffs separately, previews travel or revert affected files with optional operation-specific file patches, suppresses history scheduling during rollback, preserves ignored L2 auth files, preserves forward-travel refs during rollback when possible, and creates inverse commits for revert. `user_self_info` is the frontend-facing identity snapshot. Frontend callers derive writable app roots from `username`, `managedGroups`, and `_admin` membership in `groups` without authorizing backend edits. `password_change` is the authenticated self-service password-rotation endpoint for the current user. Frontend code should call it instead of writing `~/meta/password.json` directly, because the backend validates the current password, seals the replacement verifier, clears sessions, and clears the current auth cookie. `user_crypto_session_key` is the authenticated localStorage-restore endpoint. It returns the current session-derived wrapping key by hashing the live backend `sessionId` with the server-held session secret, so the browser can decrypt or encrypt the one persisted `userCrypto` `localStorage` blob without the server persisting that wrapping key or the user master key. ## Module And Extension Resolution - `/mod/...` resolution goes through the layered customware model. - `maxLayer` constrains module and extension resolution and defaults to `2`. - `/admin` effectively clamps module and extension resolution to `L0`. - Frontend HTML extensions resolve through `ext/html/...`. - Frontend JS hooks resolve through `ext/js/...`. - Frontend modules may also enumerate other extension-owned assets such as `ext/panels/*.yaml` through `file_paths` plus `file_read` when they only need readable logical file discovery and contents. `extensions_load` remains the backend contract for HTML and JS extension resolution, keeping `maxLayer` at the top level, ordered `patterns` groups in the request, and ordered grouped results with matching `patterns` plus resolved `extensions`. ## Auth And User Storage - The server issues the `space_session` cookie and validates it by hashing it with a backend-held secret. - When the current login may auto-restore `userCrypto` on the same browser profile, the browser stores one encrypted `userCrypto` blob in `localStorage`, and authenticated browser code fetches the current session-derived wrapping key from `/api/user_crypto_session_key`. - User metadata lives at `L2//user.yaml`. - `L2//meta/password.json` stores a server-sealed SCRAM verifier envelope, not a self-sufficient plaintext verifier. - `L2//meta/logins.json` stores backend-keyed session verifiers plus signed session metadata. - Authenticated self-service password changes still stay backend-owned through `/api/password_change`; browser code may edit `L2//user.yaml` directly, but not the password verifier file. - User-owned modules live under `L2//mod/`. - Backend auth keys come from shared environment injection through `SPACE_AUTH_PASSWORD_SEAL_KEY` and `SPACE_AUTH_SESSION_HMAC_KEY` for multi-instance deployments, or from the local fallback `server/data/auth_keys.json` during single-instance development. ## Why Frontend Developers Need This - to understand why a frontend file API call succeeds or fails - to understand where module and extension inheritance comes from - to understand why admin UI is firmware-clamped while normal app routing is layered - to understand the user and group storage model without editing backend logic - to identify the small set of cases where backend ownership is mandatory instead of merely convenient ## Mandatory Doc Follow-Up - If backend contracts that the frontend depends on change, update the mirrored backend docs and the `development` skill subtree in the same session, even though this skill remains read-only guidance.