Security & Admin
HomeForce security model
HomeForce uses server-side Hono routes, Railway Postgres, HTTP-only session cookies, encrypted provider secrets, and owner-gated administrative actions.
Authentication and roles
- Sessions are stored server-side as hashed tokens and sent to browsers in HTTP-only
hf_sessioncookies. - Session lookup requires an active user and active workspace membership.
- Owner-only routes cover provider administration/config reads, provider-control actions, team administration, debug/queue tools, integration secrets, Google service OAuth, Gmail provider creation, portal-link creation, conversation deletion, and canonical operator-state mutation.
- Outbound SMS, email, call, and group-send routes are explicitly role-gated to
owner,agent,isa, andtc. - Unsafe cookie-authenticated requests must include an allowed
Originheader.
Rate limits and egress
- Auth, public portal/media, provider inbound, compatibility callback, public booking, and public funnel submission routes are rate-limited.
- Rate limits use Redis through
REDIS_URLwhen configured. Non-sensitive routes fall back to in-memory counters if Redis is unavailable; auth credential checks, public writes, and provider callbacks fail closed while Redis is configured but unavailable. - Proxy IP headers are not trusted unless
HOMEFORCE_TRUST_PROXY_HEADERS=trueis explicitly configured behind a trusted edge. - When proxy headers are not trusted, provider callback rate limits use a hashed provider secret or bearer token bucket when one is present.
- Public booking calendars resolve from the actual request host in production instead of trusting caller-supplied host query parameters.
- Outbound provider and webhook URLs must use HTTPS by default, cannot target local/private hosts, are DNS-checked before fetch, reject redirects, and cap response bodies. Stored n8n webhook URLs are validated before save.
Provider secrets and callbacks
- Provider configs encrypt secret-like values at rest and recursively redact secrets from owner admin reads and logs.
- Provider inbound callbacks require
X-HomeForce-Provider-Secret. - Provider inbound events use explicit provider IDs or deterministic fallback idempotency guards so duplicate external events do not create duplicate messages.
- Status callbacks are bound to the matching provider account metadata before HomeForce updates canonical message status.
- Active conversation-provider inbound secrets are guarded by a database uniqueness index.
Portal links
- Portal tokens must be active, unrevoked, and unexpired.
- New contact portal links expire after 30 days by default.
- Portal tokens are only issued by workspace owners and are not returned to non-owner contact detail reads.
Security scans and migrations
- Rafter is used for GitHub-backed security scans of the HomeForce repo and can also run local secret scans before commits.
- The migration runner resolves the real path of each SQL file and rejects migration files whose real path escapes
server/migrations. - Do not commit Rafter API keys, provider secrets, database URLs, session cookies, or real customer identifiers into docs, examples, or repo files.