BlueGit

timfa filemanager

Files

filemanager / .github / technical-reference.md

technical-reference.md

technical-reference.md 6.4 KiB Download Raw

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'>.
  • loadThumbnails() - Loads per-file image thumbnails into file SVG icons after grid rendering.
  • loadOneThumbnail(iconEl) - Injects clipped in-icon thumbnails: real previews for image/video/text where feasible and generated badges for other file types.
  • getThumbnailKind(name) - Classifies files into thumbnail strategy buckets (image/video/text/audio/pdf/badge).
  • buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (blob URL/data URL) for icon injection.
  • detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
  • prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
  • highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
  • fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
  • animatePreviewOpen(sourceSvgEl, sheetEl) - Animates a cloned file icon from its tile position into the full preview sheet.
  • openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
  • fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
  • downloadOrView(item, sourceSvgEl) - Opens preview; prefers in-place expanded tile preview when invoked from a file icon, falls back to overlay when no source tile is available.
  • renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
  • animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
  • openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
  • closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
  • closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
  • isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
  • makeFileItem(item) - Builds a .file-item element; sets data-isdir attribute on folders and calls makeDraggable(el, item) from drag-move.js.

public/drag-move.js

  • makeDraggable(el, item) - Attaches pointerdown to a .file-item; starts drag after threshold movement. Depends on: api(), canWrite(), navigateTo(), STATE, closeSidebar(), toast() from app.js.
  • (internal) _beginDrag(e, el, item) - Lifts and re-parents the real .file-item to body, inserts hidden placeholder, records drag state.
  • (internal) _moveDrag(e) - Moves the real dragged item, hit-tests .file-item[data-isdir] targets, toggles drop-target class.
  • (internal) _endDrag() - On valid target: runs drop animation on real tile then calls POST /api/files/move, refreshes dir. Otherwise snap-back.
  • (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success.

public/drag-move.css

  • .file-item.dragging - Lifted style for real dragged tile.
  • .file-item.drop-target - Glows folder icon when drag hovers over it.
  • @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
  • @keyframes folder-bounce - Target folder bounces down then back on accept.
  • .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window).

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.
Source
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- fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
44- animatePreviewOpen(sourceSvgEl, sheetEl) - Animates a cloned file icon from its tile position into the full preview sheet.
45- openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
46- fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
47- downloadOrView(item, sourceSvgEl) - Opens preview; prefers in-place expanded tile preview when invoked from a file icon, falls back to overlay when no source tile is available.
48- renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
49- animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
50- openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
51- closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
52- closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
53- isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
54- makeFileItem(item) - Builds a .file-item element; sets data-isdir attribute on folders and calls makeDraggable(el, item) from drag-move.js.
55
56## public/drag-move.js
57- makeDraggable(el, item) - Attaches pointerdown to a .file-item; starts drag after threshold movement. Depends on: api(), canWrite(), navigateTo(), STATE, closeSidebar(), toast() from app.js.
58- (internal) _beginDrag(e, el, item) - Lifts and re-parents the real .file-item to body, inserts hidden placeholder, records drag state.
59- (internal) _moveDrag(e) - Moves the real dragged item, hit-tests .file-item[data-isdir] targets, toggles drop-target class.
60- (internal) _endDrag() - On valid target: runs drop animation on real tile then calls POST /api/files/move, refreshes dir. Otherwise snap-back.
61- (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success.
62
63## public/drag-move.css
64- .file-item.dragging - Lifted style for real dragged tile.
65- .file-item.drop-target - Glows folder icon when drag hovers over it.
66- @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
67- @keyframes folder-bounce - Target folder bounces down then back on accept.
68- .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window).
69
70## tests/auth.routes.test.js
71- session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
72- session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.