@helpai/elements 1.9.0 → 1.10.0

package/docs/api-reference.md

@@ -139,6 +139,7 @@ interface ChatWidgetInstance {
 
   // Lifecycle
   reset(): void; // start over as a new anonymous visitor (on logout)
+  login(userToken: UserTokenSource): void; // sign the visitor in as your logged-in user (a signed token, or a function returning one)
   destroy(): void;
 
   // Events
@@ -332,6 +333,20 @@ visitor, their current conversation (draft and queued messages included), prefer
 `setUserContext`, then reconnects as a first visit. Listeners added with `on()` stay, and the handle keeps working.
 On `<web-ai-chat>`, also remove a `user-context` attribute you set.
 
+### `login(userToken)`
+
+Signs the visitor in as your logged-in user. `userToken` is a JWT your server signs with the deployment's secret key,
+or a function returning a fresh one (called again when the server rejects the current token as expired). The widget
+reconnects as that user: their conversations on this browser move to them, and they reach their conversations on any
+device where they're signed in. Call `reset()` when they sign out; switching to another user's token starts over the
+same way. Also `HelpAI('login', userToken)`, `element.login(userToken)` on `<web-ai-chat>` (not an attribute, so the
+token stays out of the DOM), the `userToken` option at `init()`, and `<HelpAI userToken={…} />`. Signing and the
+guarantees: [Security → Verified users](./security-privacy.md#verified-users-usertoken).
+
+```ts
+chat.login(() => fetch('/api/help-ai-token').then((res) => res.text()));
+```
+
 ---
 
 ## Events

package/docs/configuration.md

@@ -102,6 +102,19 @@ Override if you use:
 - A custom domain (`your-company.com`).
 - A local dev backend.
 
+### `userToken`
+
+`string | () => string | Promise<string>` · default: none (anonymous)
+
+Signs the visitor in as your logged-in user: a JWT your server signs with the deployment's secret key, or a function
+returning a fresh one. Their conversations then follow them to any device, and the AI gets their name and email as
+verified facts. Runtime-only: not an attribute or `data-*` option, so the token stays out of the page's markup. See
+[Security → Verified users](./security-privacy.md#verified-users-usertoken) for signing it.
+
+```ts
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken: () => fetch('/api/help-ai-token').then((res) => res.text()) });
+```
+
 ### `userContext`
 
 `object | undefined`

package/docs/frameworks.md

@@ -97,6 +97,9 @@ function PricingHelp() {
 - **One import path.** The kit carries the whole widget API (`getInstance`, `hook`, the types), so import everything
   from `@helpai/elements/react`; the package's other entries are separate copies with their own widgets.
 - **Two widgets** on one page: give each `<HelpAI widgetId='support' … />` and read it with `useHelpAI('support')`.
+- **Signed-in users:** pass `userToken`, a function that fetches the token your server signs
+  ([Verified users](./security-privacy.md#verified-users-usertoken)). Keep it stable for one user (a module function, or
+  `useCallback` keyed on your user id): a different function signs in afresh, and dropping it signs out.
 
 The kit bundles the widget and imports only React from your app, so you don't need Preact installed.
 

package/docs/security-privacy.md

@@ -340,7 +340,8 @@ the pinned version URL (`/v1.2.0/`) supports SRI — the floating URL
 ## Authentication
 
 Browser access is scoped by `aiAgentDeploymentId`; a `publicKey` adds
-workspace authorization. There is **no per-end-user token.**
+workspace authorization. Visitors are anonymous unless your server signs a
+[user token](#verified-users-usertoken) for your logged-in user.
 
 ### public key (default)
 
@@ -365,6 +366,64 @@ What your public key does NOT grant:
 Omit `publicKey` but keep `aiAgentDeploymentId`; the widget connects to
 that public deployment as a guest without an auth header.
 
+### Verified users (`userToken`)
+
+To show a logged-in user their own conversations on any device, and to let the AI rely on who they are, your
+server signs a short-lived JWT for them with the deployment's **secret key** (on the deployment's Install page;
+never put it in the browser):
+
+| Claim   | Required | What it is                                                 |
+| ------- | -------- | ---------------------------------------------------------- |
+| `sub`   | yes      | Your own id for the user (a string, up to 255 characters)  |
+| `exp`   | yes      | Expiry, in seconds since the epoch; keep it short (1 hour) |
+| `name`  | no       | Their name, given to the AI as a verified fact             |
+| `email` | no       | Their email, given to the AI as a verified fact            |
+
+Sign it with HS256:
+
+```js
+// Node (jose)
+import { SignJWT } from 'jose';
+
+const secret = new TextEncoder().encode(process.env.HELPAI_SECRET_KEY);
+const userToken = await new SignJWT({ name: user.name, email: user.email }).setProtectedHeader({ alg: 'HS256' }).setSubject(String(user.id)).setExpirationTime('1h').sign(secret);
+```
+
+```python
+# Python (PyJWT)
+import os, time, jwt
+
+user_token = jwt.encode({"sub": str(user.id), "exp": int(time.time()) + 3600, "name": user.name, "email": user.email}, os.environ["HELPAI_SECRET_KEY"], algorithm="HS256")
+```
+
+```php
+// PHP (firebase/php-jwt)
+use Firebase\JWT\JWT;
+
+$userToken = JWT::encode(['sub' => (string) $user->id, 'exp' => time() + 3600, 'name' => $user->name, 'email' => $user->email], getenv('HELPAI_SECRET_KEY'), 'HS256');
+```
+
+Serve it from an endpoint only your signed-in user can reach, and hand the widget a function that fetches it:
+
+```ts
+const userToken = () => fetch('/api/help-ai-token').then((res) => res.text());
+
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken }); // signed in at load
+chat.login(userToken); // or after your sign-in (`HelpAI('login', userToken)`, `<HelpAI userToken={userToken} />`)
+chat.reset(); // on sign-out (`HelpAI('reset')`)
+```
+
+- The widget sends the token only to the agent API, as the `x-user-token` header. The function is called when a token
+  is first needed and again when the server answers `401 USER_TOKEN_INVALID` (expired or rejected); the request is
+  then sent once more. A fixed string can't be refreshed, so an expired one fails until you call `login()` again.
+- A token the server can't verify is refused; it never falls back to an anonymous visitor.
+- Signing in moves the visitor's conversations on that browser to the user. From then on they reach them on any device
+  where they're signed in, and nobody else does, the signed-out browser included.
+- Signing out (`reset()`, or dropping the token) or switching to another user starts over as a new visitor: nothing of
+  the previous user stays in the browser.
+- Keep the function's identity stable for one user (a module function, or `useCallback` keyed on your user id): a
+  different function counts as a different user.
+
 ### user / page context is NOT auth
 
 ```ts
@@ -406,13 +465,13 @@ flowchart TB
     direction TB
     B1["Authenticates the HOST's agent deployment<br/>(NOT the end user)"]
     B2["Treats userContext / pageContext as<br/>informational + untrusted"]
-    B3["Never registers / authenticates end users"]
+    B3["Never registers end users; verifies a signed userToken when the host sends one"]
   end
 
   Host -->|"context (untrusted)"| Widget
   Widget -->|"HTTPS/TLS + headers + context field"| Backend
 
-  note["publicKey + aiAgentDeploymentId auth the host's agent, NOT the end user — no end-user token anywhere."]
+  note["publicKey + aiAgentDeploymentId auth the host's agent; only a userToken signed by the host's server identifies the end user."]
   Backend -.-> note
 ```
 
@@ -430,6 +489,8 @@ and anyone can base64url-decode it. Never put a secret in context.
 
 - **public keys** — rotate from the dashboard. Old keys are deactivated
   instantly; update your embeds.
+- **secret key** — user tokens signed with a replaced secret key stop verifying, so every verified user is signed out
+  until your server signs new ones with the new key.
 
 ---