Skip to content

security.md

Latest commit

 

History

History
79 lines (50 loc) · 3.44 KB

security.md

File metadata and controls

79 lines (50 loc) · 3.44 KB
Raw

Security Model

Calendula is designed for personal use with no built-in authentication. As of April 2026, identity and authentication are not implemented in the application itself.

All external access is restricted through network-level controls: VPN, reverse-proxy whitelists, or firewall rules.

To report a security vulnerability, see SECURITY.md. This document covers the threat model and hardening; SECURITY.md covers the private disclosure channel.

Access Restriction

In production, run Calendula behind a reverse proxy that enforces IP-based access control. Allow only your LAN and/or VPN/overlay ranges; reject everything else with HTTP 403.

Typical allow-list:

  • Your LAN ranges (e.g. 10.0.0.0/8, 192.168.0.0/16)
  • Your VPN/overlay network (e.g. WireGuard, Tailscale, NetBird)
  • /.well-known/acme-challenge/* for Let's Encrypt

Optional hardening: CrowdSec or fail2ban for log-based DDoS/brute-force mitigation.

Example: Caddy block

The following Caddy configuration block demonstrates the IP whitelisting approach:

calendula.example.com {
    log

    @not_lan {
        not remote_ip 10.0.0.0/8 192.168.0.0/16
        not path /.well-known/acme-challenge/*
    }
    respond @not_lan 403

    reverse_proxy /api/* backend:8000
    reverse_proxy /health backend:8000
    reverse_proxy * frontend:3000
}

How it works:

  • The matcher @not_lan identifies requests from outside the allowed IP ranges, excluding ACME challenges.
  • respond @not_lan 403 closes the door on those requests with a 403 Forbidden response.
  • All other traffic is proxied to the backend (port 8000) or frontend (port 3000).

Mobile Access

To access Calendula from mobile devices outside the LAN, connect via your VPN or overlay network (WireGuard, Tailscale, NetBird, etc.) so the device's source IP is part of the reverse-proxy allow-list.

Roadmap

Issue #156 tracks native authentication (username/password or OIDC). Once merged, Calendula will carry its own identity layer and can be exposed to the internet without external gatekeeping.

Issue #109 covers semantic versioning and OSS release packaging. Security improvements will be bundled into regular releases.

Network-layer access control remains a valid hardening layer even with native auth enabled — defense in depth.

Native Auth (since 0.4.0)

Calendula ships with native password authentication (scrypt-hashed password + HMAC-signed session cookie). APP_AUTH_ENABLED defaults to true since 0.4.0 (#205).

Generate the session secret

Before first start, generate a persistent session secret:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Set this as CALENDULA_SESSION_SECRET in your .env. The cookie loses its HMAC signature state if the secret changes between restarts — all existing sessions are immediately invalidated. The secret must not be rotated after the first rollout unless a deliberate session wipe is acceptable.

Setup flow

  1. First container start → frontend redirects to /setup
  2. Set a password (one-time, blocked after first use via setup token, see #215)
  3. Subsequent visits land on /login

Disabling app auth (not recommended)

Set APP_AUTH_ENABLED=false in .env and restart. The middleware is no longer registered; /login and /setup endpoints stay reachable but the API is open. Ensure an external protection layer (e.g. reverse-proxy IP-whitelist + VPN) is active before relying on this.