# Technical Reference

## server/db.js
- initDb() - Initializes SQLite schema for users, file metadata, and auth_sessions (idle timeout/revocation support).
- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
- closeDb() - Closes singleton DB handle to release file locks.

## server/auth.js
- createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
- requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
- requireAdmin(req, res, next) - Requires authenticated admin user.
- revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
- getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
- getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
- SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).

## server/routes/auth.js
- extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
- makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
- POST /api/auth/setup - Creates first admin and issues token.
- POST /api/auth/login - Authenticates user and issues token.
- GET /api/auth/me - Returns current authenticated user profile.
- POST /api/auth/logout - Revokes the active session.

## public/app.js
- getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
- performLogout() - Explicit logout path that revokes server session and clears local session state.
- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
- showConfirm(title, message) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm().
- showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
- showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.

## tests/auth.routes.test.js
- session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
- session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
