Auth: hbf-bot

How this service handles authentication. Full flows: docs/architecture/auth-flows.md

Tokens This Service Accepts

Token type	Where validated	Guard / middleware
Shared secret (HBF_SECRET)	tenants.ts controller, inline body check	Body field secret must equal HBF_SECRET env var
None (channel-verified)	N/A	Webhook endpoints for Facebook, WhatsApp, Viber, Slack, Microsoft Teams, Microsoft Web Chat, Instagram, LiveChat, Monitoring, Unity, and generic API are public; each channel validates its own payload signatures

hbf-bot is an Express HTTP server that exposes two categories of endpoints.

Webhook endpoints (public, no auth): One route per inbound channel. Each channel's platform validates the request independently (e.g., Facebook hub verification, Viber HMAC). hbf-bot does not re-validate signatures on these paths; it relies on the upstream platform.

Route	Channel
GET/POST /api/fb-events	Facebook
POST /api/whatsapp-events	WhatsApp
POST /api/viber-events/	Viber
GET/POST /api/slack-events	Slack
POST /api/msteams-events	Microsoft Teams
POST /api/webchat-events	Microsoft Web Chat
GET/POST /api/instagram-events	Instagram
POST /api/livechat-events	LiveChat Gateway
POST /api/monitoring-events	UptimeRobot monitoring
POST /api/unity-events	Unity
POST /api/events	Generic API channel

Management endpoints (shared secret): The TenantsController is mounted at /api/tenants (and the legacy alias /api/projects). Every request must include secret: <HBF_SECRET> in the JSON body. Requests with a wrong or missing secret receive 401.

Method	Route	Purpose
POST	/api/tenants	Reload or force-reload a tenant from hbf-core into memory
DELETE	/api/tenants/cache	Evict a specific tenant from cache, or flush all

Tokens This Service Sends

Calling	Token used	How attached
hbf-core (via hbf-core-api library)	CORE_TOKEN env var	Bearer header
hbf-nlp (via ExternalNlu.ts)	CORE_TOKEN env var	Bearer header
Other downstream services	CORE_TOKEN env var	Bearer header

Tokens This Service Issues

None.

Roles / Scopes Enforced

Endpoint pattern	Required role
/api/tenants, /api/projects	HBF_SECRET shared secret (body field)
/api/*-events	None (channel-side signature validation only)

End-User OIDC Authentication

hbf-bot authenticates end-users (chat subscribers) via OIDC. Two strategies exist, both orchestrated by AuthenticateUserAction:

Strategy	Trigger	Token source	Config
OidcAuthStrategy	authenticate_user conversation node	IDP authorization code flow	TenantSettings.security.oidc
PreAuthTokenStrategy	channelData.auth.token on any inbound activity	Pre-authenticated JWT from host page	TenantSettings.security.preAuthTokenProviders[]

Auth store: Claims are stored in a dedicated auth store on the session blackboard via setAuthData()/getAuthData()/clearAuthData(). The setSessionValue() method throws if called with an auth.* key to prevent accidental overwrites. Auth claims are exposed to workflow templates via the Auth.* namespace (e.g., {{Auth.email}}, {{Auth.sub}}), resolved by AuthVariablesResolver. Internal fields (Auth.isAuthenticated, Auth.rawToken, Auth.refreshToken) are blocked from template resolution.

Pre-auth on-change-only: PreAuthTokenStrategy compares the incoming token against the stored auth.rawToken and skips re-validation if unchanged.

OIDC callback: GET /auth/oidc/callback handles the authorization code redirect from the IDP. OidcService exchanges the code for tokens and verifies the ID token via JWKS (1hr cache).

Logout: AuthEventStep in the lifecycle pipeline intercepts auth/logout event activities (sent from webchat) before they reach ConversationFlowStep. On receipt, it clears the auth store via blackboard.clearAuthData() and sends an auth/status { authenticated: false } event back to webchat via sendLogoutStatusEvent(). The lifecycle halts after this step (returns false), so auth/logout events are never processed as regular messages.

Auth Notes

• hbf-bot is an Express HTTP server. It optionally consumes a Bull queue via @helvia/hbf-dispatcher-client (DispatcherManager mocks it when disabled).
• Inbound webhook routes are public by design. Channel platforms (Facebook, WhatsApp, etc.) validate their own request signatures before delivery.
• The /api/tenants management routes are protected by a shared secret passed in the request body. There is no Bearer token or session-based auth on these routes.
• All outbound calls to hbf-core and hbf-nlp use CORE_TOKEN as a Bearer token.
• Redis is used for subscriber state persistence; the Redis connection itself is the trust boundary.