Skip to main content

Security Summary

Last Updated: April 7, 2026 | Version 2.0.0

This document provides a high-level overview of the security architecture and practices implemented in Llamafin. For detailed technical information, refer to the relevant documentation sections.

1. Security Philosophy

Llamafin is built on three core security principles:

  • Privacy First: Your data stays on your device and your server. We don't collect, store, or transmit personal information.
  • Zero Trust Network: Every connection is authenticated and encrypted. Nothing is trusted by default.
  • Defence in Depth: Multiple layers of security controls ensure that a single point of failure does not compromise the system.

2. Authentication Security

2.1 User Authentication

  • Token-Based Auth: Authentication tokens issued by your Jellyfin server are stored locally with expiration dates
  • Password Protection: Passwords are never stored locally. Authentication occurs directly with your Jellyfin server
  • Quick Connect: Supports Jellyfin's Quick Connect feature for code-based authentication without password entry
  • Session Rehydration: On app launch, stored tokens are validated; invalid or expired tokens trigger secure logout
  • Auto-Logout: Authentication failures (HTTP 401) automatically terminate the session and clear stored credentials

2.2 User Identity Hashing

  • SHA-256 Hashing: A SHA-256 hash of the Jellyfin User ID is computed locally for use in P2P device pairing
  • Irreversible: The hash cannot be reversed to reveal the original User ID
  • Privacy-Preserving: The hashed identity is used for device discovery and ownership verification without exposing personal information

3. Network Security

3.1 HTTP Communication

All HTTP requests to your Jellyfin server pass through a 6-layer interceptor pipeline:

  • Layer 1 — Server URL Injection: Ensures requests route to the correct server
  • Layer 2 — Error Handling: Global error management prevents information leakage
  • Layer 3 — Authentication Token Injection: Automatically attaches valid auth tokens to requests
  • Layer 4 — Retry Logic: Automatic retry on transient failures prevents data inconsistency
  • Layer 5 — Cache Prevention: Timestamps prevent stale data from being served
  • Layer 6 — Unauthorized Handler: 401 responses trigger secure logout and session cleanup

3.2 WebSocket Security

  • WebSocket connections to your Jellyfin server are authenticated
  • Encrypted when using WSS (WebSocket Secure over HTTPS)
  • Automatic reconnection with exponential backoff on failure
  • Connection status tracking and event buffering during outages

3.3 HTTPS Support

All communication between Llamafin and your Jellyfin server supports HTTPS encryption. We strongly recommend configuring your Jellyfin server with a valid TLS certificate (e.g., via Let's Encrypt).

4. P2P Security (Llamafin Connect)

4.1 Cryptographic Security

  • Key Exchange: Elliptic Curve Diffie-Hellman (ECDH) for secure key negotiation between devices
  • Encryption: AES-256-GCM (Advanced Encryption Standard with Galois/Counter Mode) for all P2P communication
  • Key Pairs: Each device generates a unique cryptographic key pair on first launch of Llamafin Connect
  • Forward Secrecy: Session keys are ephemeral and not reused

4.2 Device Discovery & Ownership

  • mDNS/Bonjour: Local network device discovery uses multicast DNS, which does not traverse the internet
  • Hashed Identity: Devices are identified by SHA-256 hashes, not personal information
  • Single-Owner Model: Only the device owner can initiate and control playback on connected devices
  • Auto-Reconnect: Exponential backoff (5s → 10s → 20s → 40s) prevents brute-force reconnection attempts

4.3 Remote Control Security

  • Full remote control (play/pause/stop/seek/volume/queue) is only available to the authenticated owner
  • State broadcasting occurs every 500ms over the encrypted channel
  • System notifications include a disconnect action for immediate revocation
  • All remote commands are validated before execution

5. Data Protection

5.1 Local Storage Security

  • IndexedDB: Primary storage for downloads and app data uses browser-based IndexedDB with access controlled by the browser's same-origin policy
  • File System: Native file system access (on mobile) is sandboxed to the app's own storage area
  • Queued Operations: Storage calls are queued until the database is ready, preventing race conditions
  • Version Migration: Database version tracking (currently v49) ensures safe schema migrations

5.2 Downloaded Content

  • Downloaded music files are stored in the app's sandboxed storage area
  • On Android, files can be stored on internal storage or external SD card (user choice)
  • Download metadata includes file paths, sizes, and sonic analysis data — all stored locally
  • Deleted content is removed from storage and metadata is purged

5.3 Authentication Data

  • Auth tokens are stored with expiration timestamps
  • Tokens are automatically invalidated and removed on logout
  • Failed authentication attempts trigger secure session termination

6. Application Security

6.1 Code Security

  • Closed Source: The application is closed-source to prevent unauthorized modification
  • TypeScript Strict Mode: Zero tolerance for type errors prevents common runtime vulnerabilities
  • ESLint: Automated code quality checks catch potential security issues
  • Template Type Checking: Strict template compilation prevents injection attacks

6.2 State Management Security

  • Unidirectional Data Flow: All data flows through NgRx store in one direction, preventing state manipulation attacks
  • Immutable State: State changes create new objects, preventing in-place modification
  • Memoized Selectors: Data extraction is controlled and cached, preventing unauthorized data access
  • Feature Isolation: 45+ isolated state slices prevent cross-feature data leakage

6.3 Route Protection

  • Authentication route guards prevent unauthenticated access to protected pages
  • Session validation occurs on every route change
  • Invalid sessions are redirected to secure logout

7. Platform-Specific Security

7.1 Mobile (iOS/Android via Capacitor)

  • Sandboxed file system access
  • Native permissions model (camera, storage, notifications)
  • Background audio playback with silent audio technique
  • Network awareness (WiFi vs. cellular optimisation)
  • Haptic feedback without data collection

7.2 Desktop (Electron)

  • Frameless window with custom title bar (prevents UI spoofing)
  • System tray integration with secure IPC
  • Native file dialogs (no direct file system access without user consent)
  • Window state persistence without data leakage

7.3 Web (PWA)

  • Service Worker caching with cache invalidation
  • Same-origin policy enforcement
  • Push notification permission required
  • HTTPS required for production deployment

8. Network Resilience

  • Network Detection: Dual-source detection (browser API + Capacitor) for accurate connectivity status
  • Speed Testing: Automatic and manual network speed testing with history (10,000 entries)
  • Offline Operation: Full offline capability with local search, DJ mode, and library browsing
  • Automatic Recovery: Graceful recovery on network reconnection

9. Known Limitations

No security system is perfect. Known limitations include:

  • P2P connections on the same local network are discoverable by other devices on that network (mitigated by hashed identities)
  • Downloaded content is accessible to anyone with physical access to the unlocked device (mitigated by device-level security: PIN, biometrics)
  • WebSocket connections are only as secure as the TLS configuration of your Jellyfin server
  • iOS sideloading requires trusting your Apple ID developer certificate

10. Security Best Practices for Users

To maximise your security when using Llamafin:

  • Use HTTPS for your Jellyfin server
  • Keep your Jellyfin server software updated
  • Use strong, unique passwords for your Jellyfin server
  • Enable device-level security (PIN, biometrics) on mobile devices
  • Only connect to Jellyfin servers you own or trust
  • Only use Llamafin Connect on trusted local networks
  • Keep Llamafin updated to the latest version
  • Regularly review and clear downloaded content on shared devices

11. Vulnerability Reporting

If you discover a security vulnerability in Llamafin, please report it responsibly through official Llamafin support channels. We take security seriously and will investigate all legitimate reports.

12. Security Audit Status

As of the last update, Llamafin has not undergone an independent third-party security audit. However, the architecture follows industry best practices, and all security-relevant implementation details are documented in the technical documentation sections.

13. Document History

  • April 7, 2026: Initial security summary published (v2.0.0)