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:

```mermaid
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)

```rust
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)