# Security

Threat model and the hardening already in place. Read before exposing the portal
on a hostile network.

---

## What we are protecting

Voicemail is sensitive: it contains callers' names, numbers, and the content of
their messages — often personal or commercial. The portal also proves who
*isn't* a mailbox owner (knowing a PIN is the only gate). Breaches of concern:

1. An attacker reads someone else's voicemail (broken authz or IDOR).
2. An attacker brute-forces a 4-digit PIN at scale.
3. A stored credential (MySQL password, Telegram token, contacts export) leaks.
4. XSS / injection poisons the HTML/JSON shown to a user.
5. The recording audio leaks off-box.

---

## What is already done

**Authentication — mailbox PIN from voicemail.conf.**
No new password store to breach; the portal trusts Asterisk's PINs. Sessions are
MySQL-backed (random token, `Secure`+`HttpOnly`+`SameSite=lax`, 12 h). Logout
and expiry are enforced server-side, not merely by dropping the cookie.

**Authorization — every query is mailbox-scoped.**
`vm_store` and `vm_api` filter every read and delete by the session's mailbox.
Cross-mailbox reads/deletes return **404**. There is a test that asserts this
([TESTING.md](TESTING.md)). A mailbox owner can only ever see their own messages
(and their own contacts).

**Brute-force lockout.**
5 failed attempts per `(mailbox, IP)` → 15-minute lockout. The correct PIN is
also refused while locked. State is in-memory (single worker per service); a
restart clears it.

**Transport — TLS terminated at Apache, with headers.**
`Strict-Transport-Security`, `X-Frame-Options: DENY`,
`X-Content-Type-Options: nosniff`, `Referrer-Policy`, and a CSP:

```text
default-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data:; font-src 'self';
media-src 'self'; connect-src 'self' http://127.0.0.1:8098;
script-src 'self' 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'
```

**The portal now ships JavaScript** (a React SPA), so the CSP is *relaxed* from
the original `script-src 'none'` to `script-src 'self' 'unsafe-inline'`. Inline
scripts in the built bundle are still same-origin; `base-uri 'none'` and
`frame-ancestors 'none'` remain to blunt injection / framing. If you can build
the frontend without inline scripts, tighten this back to `'self'` only.

**Network exposure is minimal.**
Both uvicorn backends bind **loopback only**
(`IPAddressAllow=127.0.0.1` / `localhost` in the units). The only ingress is
Apache. The `vm-api` unit also sets `ProtectSystem=full`, `ProtectHome=read-only`,
`NoNewPrivileges`, `PrivateTmp`; `vm-portal` adds `ProtectKernelTunables`,
`ProtectControlGroups`, `RestrictSUIDSGID`, `IPAddressDeny=any`, and writable
paths limited to `/var/lib/vm-transcribe` and `/var/log/asterisk`.

**Secrets are separated and git-ignored.**
`telegram.conf`, `contacts.conf`, `db_secret`, `api.env`, `*.db`, `audio/` are
in `.gitignore`. The repo ships `*.example` templates only. `db_secret` and
`telegram.conf` are mode `640 root:asterisk`; `api.env` is mode `640`
root:root.

**Fail-safe preserves mail.**
A pipeline exception relays the original Asterisk message unchanged — we never
lose a notification to a bug we introduced.

---

## Residual risks and how to close them

**(R1) 4-digit PINs.** Lockout helps but a distributed attack from many IPs
defeats per-IP throttling. If the portal is on a hostile network, put it behind
your VPN (there is already a `t01.vpn.conf` on this host) or fail2ban the Apache
access log. Recommended.

**(R2) No TLS on the loopback hop.** Apache→uvicorn is plain HTTP on localhost.
Acceptable (same host, no network path), but if you ever run uvicorn on another
host, use a unix socket or mTLS.

**(R3) Session token in MySQL.** If the DB is stolen, sessions are replayable
until they expire. The `asterisk` DB is not web-served and the `asterisk` user is
least-privilege; keep `db_secret` at `640 root:root`. For higher assurance,
shorten `VM_SESSION_HOURS` or store sessions in a server-side cache with short
TTLs.

**(R4) Contact data.** Contacts now live in the MySQL `contacts` table (no live
Google/CardDAV token at all — the old OAuth/app-password backends were removed).
The only secret around contacts is the DB password. Prefer the MySQL backend
(which we are already on) — there is no external address-book token to leak.

**(R5) Telegram bot token.** Whoever holds it can post as your bot. Keep
`telegram.conf` `640 root:asterisk`; rotate via @BotFather if leaked.

**(R6) Content-addressed audio filenames.** The sha256 of the audio is used to
locate the blob. The portal checks the session's mailbox *owns* that message
before serving, so this is not directly exploitable — but consider a random
per-message token instead of the content hash if you want defence in depth.

**(R7) CDN / edge.** If `vm.txt3.net` is orange-clouded at Cloudflare, recording
audio streams through the edge. Grey-cloud it (DNS only) to keep voice data off
the CDN. Your call.

**(R8) who-called.co.uk lookups.** The *Lookup number* action opens a new browser
tab to who-called.co.uk using the caller's sanitised digits. This is a
user-initiated click from the UI — no data is sent server-side. It does mean the
user's browser (and the caller's number) reach a third-party site; acceptable for
a manual reverse-lookup, but worth knowing.

---

## Past Google-contacts note (no longer applicable)

The old `file` / `google` / `carddav` contact backends were removed in favour of
the MySQL `contacts` table. Historically, Google disabled basic auth for
CardDAV/CalDAV/IMAP on **2024-09-30**, so an app-password read of Google
Contacts never worked — that is moot now that contacts are a local MySQL table.