Harden API-key model: per-key scoping + revocable keys, and configurable/whitelist-aware rate limiting (#16)

* API scope and rate limiting

* improvements from review

.env.example

@@ -15,12 +15,28 @@ VAULTWARDEN_EMAIL=you@example.com
 # Your Vaultwarden master password
 VAULTWARDEN_PASSWORD=your-master-password
 
-# API key for authenticating to this service (min 32 chars)
+# API key for authenticating to this service (min 32 chars).
+# This single key has FULL access to every secret the account can decrypt.
 # Generate one: openssl rand -base64 32
+# At least one of API_KEY / API_KEYS / API_KEYS_FILE is required.
 API_KEY=
 
 # --- Optional ---
 
+# Multiple, individually-revocable keys, each scoped to specific organizations
+# and/or collections. Scope is enforced SERVER-SIDE regardless of query filters,
+# so a scoped key can only read secrets within its scope. Each key needs >= 32 chars.
+# Refs may be friendly names or UUIDs (UUIDs recommended — names are case-insensitive,
+# break on rename, and a duplicate name binds to the lowest matching UUID). A key with
+# no organizations/collections is unscoped (full access). Note: an org-scoped key cannot
+# read personal/no-org items.
+#
+# Inline JSON (string env var):
+# API_KEYS=[{"name":"dev-team","key":"<32+ chars>","organizations":["MyOrg"],"collections":["Secrets - DEV"]}]
+#
+# Or a mounted JSON file (takes precedence over API_KEYS; ideal as a Docker secret):
+# API_KEYS_FILE=/run/secrets/api-keys.json
+
 # Restrict access to specific IPs/CIDRs
 # ALLOWED_IPS=192.168.1.0/24,10.0.0.1
 
@@ -33,6 +49,11 @@ API_KEY=
 # How often to re-sync the vault (default: 5m)
 # SYNC_INTERVAL=5m
 
+# Rate limiting (per client IP). Whitelisted IPs (ALLOWED_IPS / TRUSTED_PROXY_IP)
+# bypass the limiter entirely. Defaults: 30 requests per 1m window.
+# RATE_LIMIT_MAX=30
+# RATE_LIMIT_WINDOW=1m
+
 # Environment (development shows detailed errors, production hides them)
 # ENVIRONMENT=production