HerdOS Security Decisions

Goal
- Keep HerdOS strong against tampering, backdoors, data leaks, and code theft without making farm work slow, confusing, or unreliable offline.

Controls selected now
- Tenant isolation: keep every farm, ranch, user, Field device, RFID reader, work record, sync batch, and audit entry tied to organization_id.
- Managed auth: use Auth0, Clerk, Supabase Auth, or equivalent for passwords, MFA, email reset, sessions, and account recovery.
- JWT tenant claims: production tokens must include organization_id and role; request headers cannot override token organization.
- PostgreSQL RLS: keep row-level security as the final database wall between Client A, B, and C.
- Production storage adapter: use HERDOS_STORAGE_ADAPTER=postgres with HERDOS_ALLOW_JSON_STORE=false for hosted customers; keep JSON only for local demos and smoke tests.
- HTTPS and exact-domain CORS: production traffic must use TLS, and the API must only accept the approved app domain.
- Browser CSP and hosting headers: block foreign scripts, plugin/object execution, framing, unsafe form targets, and content-type confusion.
- File integrity checks: keep HERDOS-SECURITY-CHECKSUMS.json and herdos-security-guard.js for tamper evidence.
- API rate limiting: throttle auth, reset, admin, sync, RFID, and general request abuse.
- Private secrets: .env stays out of downloadable packages and public hosting.
- Backups and restore drills: production databases must have daily managed snapshots and tested restore.
- Audit logging: security events, sync batches, field devices, user roles, and record changes must remain timestamped.
- Code review and branch protection: production changes should require MFA, protected branches, review, and checksum rebuild.
- Dependency discipline: keep dependencies minimal, scan package manifests, pin production versions, and avoid abandoned packages.

Controls selected for native mobile/desktop releases
- Apple code signing and notarization for macOS builds.
- Apple Developer signing and TestFlight/App Store review for iOS builds.
- Android App Signing for Android builds.
- Store production signing keys only in secure developer accounts/keychains or CI secrets, not in the repository.

Controls intentionally not used in the current web/PWA package
- Hard device binding to one CPU, MAC address, or MacBook: rejected for now because real farms use multiple tablets, replace broken devices, and work offline. Use device enrollment, JWTs, and Field device names instead.
- Aggressive anti-debugging/RASP in the web app: rejected for now because it creates false positives, breaks support, and can stop legitimate offline work. Keep monitoring, audit, and server controls instead.
- Heavy JavaScript obfuscation as a security boundary: not relied on. It can make support harder and does not protect secrets once code is delivered to a browser. Keep proprietary logic and secrets on the server; use production minification later for packaging.
- Binary compilation for the current API: not required now because the API runs server-side and is not shipped to clients as browser code. A future Go/Rust service is possible if enterprise deployment demands it.
- Locking customer operations to your MacBook Pro: rejected. Your Mac is the owner/developer workstation, not the runtime lock for customers.

Production release rule
- When HerdOS changes are approved, update code, run syntax/security checks, regenerate HERDOS-SECURITY-CHECKSUMS.json, rebuild herdos-ready-package.zip, record the package SHA-256, and deploy only through the trusted domain or signed mobile stores.

Client experience rule
- Security should block only risky actions: wrong tenant, invalid token, expired session, impossible data, excessive request abuse, tampered files, or unauthorized admin/finance/security actions. Normal scanning, offline work, cow lookup, health records, and sync should stay fast.
