| 1 | # Technical Reference |
| 2 | |
| 3 | ## server/db.js |
| 4 | - initDb() - Initializes SQLite schema for users, file metadata, and auth_sessions (idle timeout/revocation support). |
| 5 | - getDb() - Returns singleton DB handle with WAL and foreign key pragmas. |
| 6 | - closeDb() - Closes singleton DB handle to release file locks. |
| 7 | |
| 8 | ## server/auth.js |
| 9 | - createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id. |
| 10 | - requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user. |
| 11 | - requireAdmin(req, res, next) - Requires authenticated admin user. |
| 12 | - revokeSession(sessionId) - Revokes a session row so future token use fails immediately. |
| 13 | - getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases). |
| 14 | - getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback. |
| 15 | - SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour). |
| 16 | |
| 17 | ## server/routes/auth.js |
| 18 | - extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup. |
| 19 | - makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise. |
| 20 | - POST /api/auth/setup - Creates first admin and issues token. |
| 21 | - POST /api/auth/login - Authenticates user and issues token. |
| 22 | - GET /api/auth/me - Returns current authenticated user profile. |
| 23 | - POST /api/auth/logout - Revokes the active session. |
| 24 | |
| 25 | ## public/app.js |
| 26 | - getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation. |
| 27 | - getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes. |
| 28 | - saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage. |
| 29 | - loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window. |
| 30 | - api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls. |
| 31 | - performLogout() - Explicit logout path that revokes server session and clears local session state. |
| 32 | - initAuth() - Restores prior session when valid and auto-logins without credential prompt. |
| 33 | - showConfirm(title, message) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm(). |
| 34 | - showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt(). |
| 35 | - showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>. |
| 36 | - loadThumbnails() - Loads per-file image thumbnails into file SVG icons after grid rendering. |
| 37 | - loadOneThumbnail(iconEl) - Injects clipped in-icon thumbnails: real previews for image/video/text where feasible and generated badges for other file types. |
| 38 | - getThumbnailKind(name) - Classifies files into thumbnail strategy buckets (image/video/text/audio/pdf/badge). |
| 39 | - buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (blob URL/data URL) for icon injection. |
| 40 | - detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension. |
| 41 | - prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering. |
| 42 | - highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans. |
| 43 | - fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows. |
| 44 | - downloadOrView(item) - Opens the in-app file-preview overlay and attaches bottom download action. |
| 45 | - renderPreviewBody(item, blob, objectUrl) - Renders preview content (image/video/audio/pdf/text) or unsupported message. |
| 46 | - closePreview() - Closes preview overlay and revokes active preview object URL. |
| 47 | - isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension. |
| 48 | |
| 49 | ## tests/auth.routes.test.js |
| 50 | - session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately. |
| 51 | - session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement. |