aimeat 1.38.0 → 1.39.0

package/dist/.env.example

@@ -104,6 +104,53 @@ AIMEAT_PORT=40050
 # AIMEAT_FEDERATION_AUTH_POLICY=disabled       # disabled | all_peers | specific_peers
 # AIMEAT_FEDERATION_DEFAULT_SCOPES=memory:read,catalogue:read
 
+# ── Security Posture (localhost-flexible → public-strict) ──────
+# AIMEAT runs the SAME code wide-open on localhost AND hardened on the public internet.
+# Security is DRIVEN BY CONFIG, never a code fork. The profile sets safe DEFAULTS for the
+# knobs below; any explicit AIMEAT_* var always overrides it. Full rationale + the ten
+# security invariants: docs/coding-guidelines/security-development-dna.md
+#
+# AIMEAT_SECURITY_PROFILE — local | public
+#   The master switch. Default: `local` when AIMEAT_BASE_URL is http://localhost /
+#   127.0.0.1 / an RFC1918 host, OR AIMEAT_NODE_TYPE=personal; otherwise `public`.
+#   Set it explicitly on a real deployment. `public` flips the two egress knobs below to
+#   their strict values and arms the startup self-check.
+# AIMEAT_SECURITY_PROFILE=public
+#
+# AIMEAT_ALLOW_PRIVATE_EGRESS — may SERVER-SIDE fetches target LOOPBACK (127.0.0.1 / ::1 / localhost)?
+#   Governs every outbound fetch whose URL is user/owner/agent/peer-influenced: the AI-provider
+#   baseUrl, agent/board webhooks, extension ctx.fetch, federation download URLs.
+#   local  default: true  — so the node can reach a LOCAL model server (Ollama / LM Studio at
+#                           http://127.0.0.1:11434 etc.). This is why localhost stays flexible.
+#   public default: false — blocks loopback SSRF (localhost-bound services). NOTE: RFC1918
+#                           (10./172.16./192.168.*), link-local + cloud-metadata (169.254.169.254)
+#                           are ALWAYS blocked server-side regardless of this flag. Redirects are
+#                           re-validated per hop. (AIMEAT_DEV_MODE=true is a back-compat alias.)
+# AIMEAT_ALLOW_PRIVATE_EGRESS=false
+#
+# AIMEAT_AI_PROVIDER_ALLOWLIST — comma-separated HOST allowlist an AI `baseUrl` may point at.
+#   Empty = any host (local dev / self-hosted models). On a public multi-tenant node, restrict
+#   WHERE a decrypted AI key may be sent so a poisoned baseUrl can't exfiltrate it.
+#   Example: openrouter.ai,api.openai.com,api.anthropic.com,api.groq.com
+# AIMEAT_AI_PROVIDER_ALLOWLIST=""
+#
+# Startup self-check: when the resolved profile is `public`, the node warns loudly (or refuses
+# to start) on an unsafe combination — AIMEAT_ANONYMOUS=true, AIMEAT_ALLOW_PRIVATE_EGRESS=true,
+# AIMEAT_FEDERATION_OPEN_JOIN=true, missing AIMEAT_ENCRYPTION_KEY, AIMEAT_CORS_ALLOWED_ORIGINS=*,
+# or AIMEAT_STATS_ACCESS=public. Being insecure on the internet must be a conscious override.
+#
+# ── Reserved-key write guard (NOT a knob — always-on code invariant) ──
+# A role-'app' token (H-2 app grant) has memory:write over the OWNER's namespace. It must NOT
+# be able to write keys the SERVER reads and trusts for behavior, or a granted app could redirect
+# the owner's AI key, reset their spend cap, or force a public directory listing. Denylisted
+# prefixes for non-owner-session principals on POST/PUT /v1/memory (mirrors the ecosystem path's
+# ecoMayWriteKey — see DNA invariant #2):
+#   openrouter.*   → AI provider config incl. the baseUrl the decrypted key is sent to
+#   ai-usage.*     → the daily AI-spend ledger that enforces the budget cap
+#   profile.*      → public directory-listing flag + matchmaking inputs
+# (Enforcement of this guard and the three posture knobs above lands in config.ts + the memory
+#  write path together with the security fixes; documented here as the config/security surface.)
+
 # ── Auth & Tokens ──────────────────────────────────────────────
 # AIMEAT_JWT_TTL=3600              # Legacy / agent JWT lifetime in seconds (default: 1h)
 # Owner sessions: short access token + rotating httpOnly refresh cookie (no key re-signing).