jellytau/docs/architecture/09-security.md

Security

Authentication Token Storage

Access tokens are not stored in the SQLite database. Instead, they are stored using platform-native secure storage:

flowchart TB
    LoginSuccess["Login Success"]
    KeyringCheck{"System Keyring<br/>Available?"}
    OSCredential["Store in OS Credential Manager<br/>- Linux: libsecret/GNOME Keyring<br/>- macOS: Keychain<br/>- Windows: Credential Manager<br/>- Android: EncryptedSharedPrefs"]
    EncryptedFallback["Encrypted File Fallback<br/>(AES-256-GCM)"]

    LoginSuccess --> KeyringCheck
    KeyringCheck -->|"Yes"| OSCredential
    KeyringCheck -->|"No"| EncryptedFallback

Key Format:

jellytau::{server_id}::{user_id}::access_token

Rationale:

• Tokens in SQLite would be readable if the database file is accessed
• System keyrings provide OS-level encryption and access control
• Fallback ensures functionality on minimal systems without a keyring daemon

Secure Storage Module

Location: src-tauri/src/secure_storage/ (planned)

pub trait SecureStorage: Send + Sync {
    fn store(&self, key: &str, value: &str) -> Result<(), SecureStorageError>;
    fn retrieve(&self, key: &str) -> Result<Option<String>, SecureStorageError>;
    fn delete(&self, key: &str) -> Result<(), SecureStorageError>;
}

// Platform implementations
pub struct KeyringStorage;      // Uses keyring crate
pub struct EncryptedFileStorage; // AES-256-GCM fallback

Network Security

Aspect	Implementation
Transport	HTTPS required for all Jellyfin API calls
Certificate Validation	System CA store (configurable for self-signed)
Token Transmission	Bearer token in Authorization header only
Token Refresh	Handled by Jellyfin server (long-lived tokens)
Android cleartext	res/xml/network_security_config.xml blocks cleartext everywhere except 127.0.0.1 (the loopback media server, DR-137/DR-138). The manifest's usesCleartextTraffic is ignored once the config is present, so the config is the single authority
Android WebView	mixedContentMode = COMPATIBILITY with allowFileAccess/allowContentAccess both false (DR-199). These are the second half of the cleartext policy: ALWAYS_ALLOW re-opened by hand what the network security config closes. Change the two together

Webview Content Security Policy

app.security.csp in tauri.conf.json (TRACES: UR-012, UR-071 | DR-198). It was null — CSP disabled — which meant any script that reached the web layer inherited the full IPC surface. Tauri computes the header from this value when it serves the embedded HTML, injecting a nonce for SvelteKit's inline bootstrap script, so script-src needs no 'unsafe-inline'.

default-src 'self';
script-src  'self';
style-src   'self' 'unsafe-inline';
font-src    'self' data:;
img-src     'self' data: blob: asset: http://asset.localhost http: https:;
media-src   'self' blob: asset: http://asset.localhost http://127.0.0.1:* http: https:;
connect-src 'self' ipc: http://ipc.localhost http: https:;
worker-src  'self' blob:;
object-src 'none'; frame-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'

Directive	Why
default-src 'self'	Everything not named below is same-origin only.
script-src 'self'	The genuinely restrictive half. Bundled JS only; Tauri's build-time nonce covers the one inline <script> in index.html. Adding 'unsafe-inline' here would silently do nothing anyway — a nonce in a directive voids it.
style-src 'self' 'unsafe-inline'	Svelte compiles style="…" attributes into markup, including app.html's display: contents wrapper, and CSP treats a style attribute as inline. Safe only while no <style> element survives into index.html: Tauri would nonce it, and the nonce would then void 'unsafe-inline'. The production build extracts all CSS to files, so it currently has none.
img-src	Thumbnails come from two places: the asset protocol (asset://localhost/… on Linux/macOS, http://asset.localhost/… on Windows/Android — the same protocol, named differently by convertFileSrc) and, on a cache miss, straight from the Jellyfin server. data:/blob: cover inline and generated images.
media-src	<video>/<audio> sources: HLS transcodes and progressive streams from the server, the token-guarded loopback media server on http://127.0.0.1:<random port> (DR-137), and blob: for the MSE object URL hls.js attaches.
connect-src	ipc: / http://ipc.localhost is Tauri's invoke transport (custom scheme on Linux/macOS, http host on Windows/Android) — without it every command is blocked. http:/https: is hls.js fetching manifests and segments; ordinary API traffic goes through Rust and is not subject to CSP.
worker-src 'self' blob:	hls.js runs its demuxer in a worker built from a blob (enableWorker: true). Without blob: it falls back to main-thread demuxing — playback survives but costs more CPU.
object-src, frame-src = 'none'	No plugins, no iframes; both are classic injection sinks.
base-uri 'self', form-action 'self', frame-ancestors 'none'	Block <base> hijacking, form exfiltration and framing. frame-ancestors is only honoured when the policy is delivered as a header, which is platform-dependent; it is harmless where it is not.

img-src/media-src/connect-src are deliberately permissive. The Jellyfin origin is typed in by the user at run time and is routinely plain http on a LAN, so it cannot be enumerated at build time. http: https: is a wide grant for data — but it still bars file:, filesystem: and scripting schemes, and it does not touch script-src, which is where an injected origin would actually hurt. A run-time policy naming the server exactly was considered and rejected: Tauri derives the header from immutable config at the moment it serves the HTML, so it would mean rebuilding the config and reloading the webview whenever the user adds or switches a server, to constrain a destination the user chooses anyway.

devCsp mirrors the policy with 'unsafe-inline' 'unsafe-eval' on script-src and ws:/wss: on connect-src, because the Vite dev server injects styles and code and drives HMR over a websocket. It applies only to tauri dev.

Asset protocol scope

app.security.assetProtocol.scope is $APPDATA/thumbnails/** — not the storage root. imageCache.ts is the only convertFileSrc caller left in the frontend: downloaded media moved to the loopback media server in DR-137, and downloaded audio is opened by MPV/ExoPlayer directly from its path. The old $APPDATA/** grant let the webview read the SQLite database and the encrypted-token fallback file alongside the thumbnails it actually needs.

If a new feature hands the webview a local file, widen this scope to that subdirectory specifically; a path outside it resolves to nothing and the webview reports NETWORK_NO_SOURCE (which is exactly how DR-134's failure presented).

Local Data Protection

Data Type	Protection
Access Tokens	System keyring or encrypted file
Database (SQLite)	Plaintext (metadata only, no secrets)
Downloaded Media	Filesystem permissions only
Cached Thumbnails	Filesystem permissions only

Path Confinement and Input Binding

Two classes of defect, both of the same shape: a value that arrived from outside decided something it should not, at a site whose neighbours a few lines away already did it correctly.

Filesystem path confinement

Surface	Rule	TRACES
Thumbnail cache	The filename is built from item_id, image_type and tag; all three are sanitised (non-alphanumerics → _), and the resolved path is checked with starts_with(cache_dir) at the point of use	DR-210
Downloads	file_path and target_dir are sanitised inside download_item itself, not only in download_item_and_start — the latter is what made the existing guard bypassable rather than absent	DR-211

Two mechanics worth remembering, because both are easy to get subtly wrong:

• Path::join neither folds .. nor keeps the base when handed an absolute path. Confinement therefore has to be checked after the join, not before.
• Sanitising is per path component. Whole-string sanitising would rewrite downloads/x.mp3 to downloads_x.mp3 and relocate every existing download.

The database keeps both the raw key and the resolved path, so lookups still match and pre-existing rows still resolve.

Query and URL construction

Caller-supplied values are bound or encoded, never interpolated (DR-212):

• The offline get_items item-type filter uses parameter placeholders rather than formatting IN ('a','b').
• build_get_items_endpoint encodes ParentId / IncludeItemTypes / SortBy / SortOrder. Encoding is per element and list separators stay unencoded, because Jellyfin splits these parameters on the comma.
• player_set_volume clamps at the command boundary — it previously accepted NaN and out-of-range floats even though every backend clamps internally.

Security Considerations

1. No Secrets in SQLite: The database contains only non-sensitive metadata
2. Token Isolation: Each user/server combination has a separate token entry
3. Logout Cleanup: Token deletion from secure storage on logout
4. No Token Logging: Tokens are never written to logs or debug output
5. IPC Security: Tauri's IPC uses structured commands, not arbitrary code execution
6. Webview Containment: A restrictive script-src keeps injected script off the IPC surface; the asset protocol is scoped to the thumbnail cache only (see above)