Bridges nSelf's built-in auth service to the ɳChat bundle. Handles session-scoped tokens, channel membership enforcement, and user identity sync — so your chat respects your existing access controls without duplicating them.
The nSelf stack includes a built-in auth service (nhost Auth) that handles signup, login, and JWTs. This plugin is a ɳChat-specific adapter that maps nSelf auth identities to chat-level permissions and tokens. You need both.
nself license set nself_pro_...
nself plugin install auth
nself build
nself startWhen a user signs into your app via the nSelf auth service and navigates to chat, nself-auth issues a short-lived chat session token scoped to that user's role and channel membership. This token is used by nself-realtime for WebSocket authentication and by nself-chat for message attribution.
Channel access is enforced based on Hasura roles and the np_chat_members table. Private channels require explicit membership; the auth plugin checks membership on every token issue and refuses to grant access to channels the user is not a member of. This prevents enumeration attacks where a client crafts a channel ID to eavesdrop.
User profile changes (display name, avatar) are synced from the nSelf users table to the chat identity on login. The sync is one-directional: nself-chat reads identity from nSelf auth, not the other way around.
| Variable | Required | Description |
|---|---|---|
AUTH_ENCRYPTION_KEY | Yes | 32-byte hex key for encrypting chat session tokens. Generate with openssl rand -hex 32 |
DATABASE_URL | Yes | Postgres connection string (auto-set by nself) |
AUTH_TOKEN_TTL_SECONDS | No | Chat session token lifetime. Default: 3600 |
AUTH_SYNC_PROFILE_ON_LOGIN | No | Sync display name and avatar on each login. Default: true |
| Endpoint | Method | Description |
|---|---|---|
/auth/chat-token | POST | Exchange a nSelf JWT for a scoped chat session token |
/auth/verify | POST | Verify a chat session token (used internally by nself-chat and nself-realtime) |
/auth/sync | POST | Force-sync a user's profile from nSelf auth to chat identity |
/health | GET | Plugin health check |
| Table | Purpose |
|---|---|
np_chat_auth_sessions | Active chat session tokens with user ID, expiry, and scope |
np_chat_identities | Cached user identity data (display name, avatar) synced from nSelf auth |
| Event | Payload |
|---|---|
auth.chat.session.created | User ID, token expiry, channel scope |
auth.chat.session.expired | User ID, session duration |
nself-auth is a required companion for the ɳChat bundle when your app has authenticated users. Without it, chat messages are not user-attributed and channel access is not enforced. Install it with nself-chat and nself-realtime — all three work together on the same nSelf JWT claim.
Token exchange failing with 401: The incoming nSelf JWT must have a valid sub claim and must not be expired. Verify your app is setting the Authorization: Bearer header correctly on the /auth/chat-token request.
User profile not syncing: Set AUTH_SYNC_PROFILE_ON_LOGIN=true and ensure the nSelf auth service is reachable from the plugin container. Run nself plugin logs auth for the sync error detail.
Port conflict: This plugin runs on port 3821 (moved from 3014 in S00b-T04 to resolve conflict with the web/install dev server). Update any hard-coded references in your config.
Port: 3821 (moved from 3014 — update operator configs) | Bundle: ɳChat ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13