Security model

The rest of the bridge's internal API (/v1, /uploads and /otel) is never forwarded: the edge answers 404. The edge also refuses any path with a . or .. segment, drops every client-sent X-Hubzoid-* identity header and any X-Forwarded-Prefix, and keeps no cookie between visitors.

With sign-in off, hubzoid run refuses to listen on anything but loopback unless HUBZOID_ALLOW_UNAUTHENTICATED_NETWORK=true. hubzoid doctor warns (exposure.bind) when the public port listens on every interface, and reports exposure.local_mode when it does so with sign-in off.

People. Hubzoid owns accounts and sessions. Passwords are hashed with Argon2id. A session cookie holds random bytes, and the database keeps only their digest. Sessions last at most 30 days and end after 7 idle days. Administrators must use two-step sign-in by default, and failed sign-ins are rate limited per address and per email. Changes from a browser must come from the deployment's own address. See authentication.

Settings. It uses the same session, validated on the server. Every signed-in person can open /settings, and people who manage no agent see only the personal sections: Account, Connected accounts, Sources, Memory and My schedules. Administration needs manage_access, organization-wide or in an agent. Settings ignores identity headers sent by a browser, and the management API (/portal/api) accepts no API keys. Changing agent files from the browser is off by default, so Settings shows connectors, channels, settings, approval rules and budgets read-only with where to change them. A development bypass (HUBZOID_PORTAL_DEV) exists and must never be set on a shared deployment.

Bridges. Hubzoid's own processes call a bridge with a key from BRIDGE_API_KEYS. The key alone does not vouch for who is asking: identity headers count only with an assertion signed by the deployment key for this Hub in the last 60 seconds. The default key dev is public, and hubzoid doctor fails auth.bridge_keys when it is in use or no key is set.

MCP clients. The hosted MCP server accepts only OAuth credentials that Hubzoid issues after the person signs in and consents (scope hub:access). Access tokens last up to 10 minutes, and refresh tokens and grants up to 30 days. A person revokes a connection at /mcp/oauth/connections. Account status and the person's use_hub grant are checked on every request, and tools they may not use are hidden and refused if called. See connect an assistant.

Connected accounts. With a connector each person signs in to, Hubzoid stores their token encrypted with the deployment key and uses it only on that person's turns, on surfaces allowed to reach controlled tools, and only where they hold the connector's connector_<id> grant. A shared channel mention never carries the mentioner's token. A Shared key connector holds one company key, encrypted, used for the people granted it. See tools and connectors.

Inbound channels. WhatsApp requests must carry a valid X-Hub-Signature-256 HMAC of the raw body, Telegram requests the configured secret token, and webhooks a shared secret or HMAC signature. A WhatsApp or Telegram sender whose number neither Settings nor the Hub's roster knows gets a fixed reply and never reaches the model, the tools or any data. See webhooks.

Download links. Links carry an HMAC over the chat, the file name and the expiry, keyed with the Hub's own secret in .hubzoid/artifact_secret, never with the bridge key. A link expires after 7 days, and HUBZOID_ARTIFACT_LINK_TTL changes that. Deleting the secret revokes every issued link.

The subject is taken only from a verified session, token or signed assertion, never from a field the caller supplies. A bridge call without a verified person is refused, and a blocked person is refused on every surface.

HUBZOID_RESTRICTED_SURFACES replaces the surface list. slack-dm is safe to add, and slack-channel must never be added, because a shared thread is answered under one person's identity.

Workflow runs. Scheduled workflows and markdown tasks run as an ordinary account: run_as, else HUBZOID_WORKFLOW_USER, else the owner recorded at setup. That account's grants decide what the run may do, rechecked before every protected call, and never swapped for another account.

Proposed changes. An agent cannot change access. A manager granted Manage access from chat can ask it to propose a change, and nothing applies until that manager confirms the exact plan in Settings. A proposal works once and expires.

Offboarding. Delete user removes every grant and ends the person's sessions, API keys and assistant connections. Activity history, usage records and published artifacts are kept, and the email is marked as removed, so a later account with it inherits nothing. The last organization administrator can never be removed, demoted or deleted.

Usage records hold tokens, cost, model, surface, user and timing, never message content. A conversation opens only for the person who owns it, and Settings has no conversation reader. A shared conversation link opens read-only for signed-in people of the deployment. Webhook event and alert records have no automatic retention yet. See topologies for each store's file.