Skip to main content

Security

Authentication​

Dashboard. Email and password owned by the app. Passwords are hashed with PBKDF2-HMAC-SHA256 at 200,000 rounds. Sessions are HMAC-signed cookies signed with MATILDA_DASHBOARD_SECRET, valid for 14 days by default. Cookies are marked Secure automatically when MATILDA_PUBLIC_URL is https.

Web chat. Leads verify a phone number and email with a six-digit emailed code. Codes are stored as HMACs, expire in ten minutes, burn after five wrong attempts, and are rate limited per phone and per IP. The sign-in endpoint always responds identically so it cannot be used to enumerate contacts. The session cookie is signed with MATILDA_CUSTOMER_SECRET.

Worker. Each device has a bearer key stored as a SHA-256 hash. The key is minted on the Mac and kept in its login Keychain, so the raw key never reaches the server. Removing the Mac on Devices revokes it instantly.

Webhook. Incoming BlueBubbles posts are gated by a token generated on Setup. Generate one before the instance is reachable from the internet.

Secrets​

  • Only *.example templates are committed. Real values live in .env on the host or in the settings table.
  • Default values for the two signing secrets are refused on an https deployment.
  • Only Owners can view or save API keys, passwords, and the webhook token. Admins see set or not set. Viewers see connected or not.
  • The audit log records which settings keys changed, never their values.

IP allowlist​

MATILDA_DASHBOARD_ALLOW_CIDRS restricts every dashboard route to listed source ranges, layered under the login. It is open by default. Behind Caddy the client's real IP is read from X-Forwarded-For, which is trusted only from MATILDA_FORWARDED_ALLOW_IPS, by default loopback.

MATILDA_DASHBOARD_ALLOW_CIDRS=203.0.113.0/24,127.0.0.0/8,::1/128

Network exposure​

In the reference deployment Matilda binds to loopback behind Caddy. Port 8000 is never public. Locally, Docker publishes on 127.0.0.1 only, because the dashboard shows lead PII.

Audit log​

Every administrative change lands in the audit log with the actor, a dotted action name, the target, and detail. It is visible under Recent activity on the organization page.

Lead sheets​

Lead sheet URLs contain a long unguessable token and require no login. Treat them as sensitive links. Deleting a lead invalidates its sheet.

Data at rest​

Everything is in the SQLite file and the sessions directory under MATILDA_DATA_DIR. Protect that directory with filesystem permissions and back it up. See Operations.