dewee-webchat 0.4.1 → 0.5.0-beta.1

package/README.md

@@ -56,7 +56,7 @@ first three values below.
 | `DEWEE_CCP_CHAT_URL` | The ingress URL, `https://<ccp>/api/public/webchat/v1/wci_…`. https only (plain http to `localhost` for development). |
 | `DEWEE_WEBCHAT_INTEGRATION_ID` | `wci_…`; must match the end of `DEWEE_CCP_CHAT_URL` |
 | `DEWEE_WEBCHAT_INTEGRATION_SECRET` | `dwc_…`. **Server only.** Sent only to the `DEWEE_CCP_CHAT_URL` origin, never across a redirect. |
-| `DEWEE_WEBCHAT_SECRET` | 32+ random chars to sign visitor sessions (`openssl rand -base64 32`) |
+| `DEWEE_WEBCHAT_SECRET` | At least 32 random UTF-8 bytes to sign visitor sessions (`openssl rand -base64 32`) |
 | `DEWEE_ALLOWED_ORIGINS` | Extra origins for cross-origin embedding (same origin always works) |
 | `TURNSTILE_SITE_KEY` / `TURNSTILE_SECRET_KEY` | Optional Cloudflare Turnstile check for new visitors (with `ccp`, a returning visitor's hourly refresh is not challenged) |
 | `DEWEE_WEBCHAT_TRANSPORT` | Optional: `ccp` or `legacy-gateway`. Without it, the variables that are set decide (gateway variables alone select `legacy-gateway`, with a deprecation warning); set it to pin the transport explicitly. |
@@ -85,8 +85,26 @@ The two sets cannot be mixed: with CCP and gateway variables both set, or `trans
 the other's variables set, the handler refuses to start rather than send a credential to an origin
 you did not pick. `agents`, `defaultAgent` and `allowClientCredentials` are refused with `ccp`.
 
+Both transports need a stable `secret` shared by every backend instance. For local development only,
+the legacy transport can opt in to a generated process-local secret with `allowEphemeralSecret: true`.
+Sessions and identity bindings then stop working after a restart or when a request reaches another
+instance. CCP always requires a configured secret of at least 32 bytes.
+
 ## 2. Add the widget
 
+### Optional current-page context
+
+Page context is off by default. Set `page-context="metadata"` or `page-context="content"` on the
+widget (or `pageContext` in framework configuration) to offer it. The visitor previews the page
+and explicitly chooses whether to share it for each message. Only a supported Gateway/CCP version
+receives the attachment; ordinary chat continues when support is absent. For content, the default
+source is `main`, `article` or `[role=main]`; `contextSelector` and `excludeSelectors` narrow it.
+Form controls, editable areas and hidden content are excluded. Configure a client-side
+`contextProvider` for host-filtered data when needed; the host is responsible for excluding private
+data from its provider. In Astro, set that function with `element.configure()` in a client script,
+not as a serialized component prop. The preview contains the data to be sent: review it before
+sharing. See the [HTTP contract](https://github.com/nextlevelbuilder/dewee-webchat/blob/main/docs/http-contract.md#page-context-attachment).
+
 **Script tag** (no build step):
 
 ```html
@@ -140,6 +158,7 @@ Attributes use kebab-case (`show-reasoning="false"`), `data-*` on the script tag
 | `title`, `subtitle`, `greeting`, `intro`, `placeholder` | | Texts |
 | `suggestions` | | Quick replies (`a|b` or JSON array as attribute) |
 | `avatar`, `launcherAvatar` | | Image URL; also use it on the launcher |
+| `imageOrigins` | `[]` | Additional trusted HTTPS origins for Markdown images |
 | `mode` | `floating` | `floating` (bubble + panel) or `inline` (fills its container) |
 | `position` | `bottom-right` | or `bottom-left` |
 | `theme` | `light` | `light`, `dark`, `auto` |
@@ -153,6 +172,8 @@ Attributes use kebab-case (`show-reasoning="false"`), `data-*` on the script tag
 | `actions`, `confirm`, `getPageContext` | | [Page actions](#agent-page-actions) (JS/props only) |
 | `maxActionRounds` | `5` | Automatic action turns per visitor message |
 | `actionTimeoutMs` | `30000` | Per-handler timeout |
+| `domActions` | `false` | [Built-in DOM actions](#built-in-dom-actions): snapshot, scroll, click, fill |
+| `domActionsRoot` | `document.body` | Selector or element the built-in DOM actions are limited to |
 | `headers` | | Extra request headers, object or `() => object \| Promise<object>` called before every request (JS/props only) |
 | `fetch` | `globalThis.fetch` | Custom fetch for every widget request (JS/props only) |
 
@@ -162,6 +183,33 @@ Methods: `open()`, `close()`, `toggle()`, `send(text)`, `stop()`, `newConversati
 Events: `dewee:ready`, `dewee:open`, `dewee:close`, `dewee:send`, `dewee:reply`, `dewee:error`, `dewee:action`, `dewee:link`.
 CSS variables: `--dw-accent`, `--dw-font`, `--dw-radius`, `--dw-width`, `--dw-height`, `--dw-z`.
 
+## Markdown images
+
+Replies may include `![Product](https://cdn.example.com/photo.jpg)` or a same-origin relative image
+URL. Images are disabled until HTTPS directory prefixes are approved in the backend. Configure the backend
+with `imageSources: ["https://cdn.example.com/products/", "https://qr.example.com/images/"]` (or the comma-separated
+`DEWEE_IMAGE_SOURCES` environment variable). Include a safe image directory on your site's HTTPS origin for relative images.
+For external origins, also configure the widget:
+
+```html
+<dewee-chat image-origins='["https://cdn.example.com", "https://qr.example.com"]'></dewee-chat>
+```
+
+The script-tag equivalent is `data-image-origins`; vanilla JS uses
+`chat.configure({ imageOrigins: ["https://cdn.example.com"] })`, and React, Vue and Astro accept the
+`imageOrigins` prop. Unapproved or broken images fall back to alt text. The widget loads images from
+`{endpoint}/image` using a short-lived encrypted ticket issued to the visitor session; the backend makes the request without cookies or Gateway credentials, rejects
+redirects, and accepts PNG, JPEG, GIF and WebP only after validating the content type and file
+signature. Node and PHP pin a checked public DNS address; Cloudflare Workers use the platform's
+network boundary. Workers conservatively refuse sources sharing the endpoint's last two hostname
+labels (including sibling subdomains), to avoid bypassing Cloudflare's own-zone protections; host
+images on a separate approved domain there. Files are limited to 2 MiB and 4096
+pixels per edge, and responses are not cached. Animated GIF/PNG/WebP are refused. Raw HTML,
+SVG, unsafe schemes, credentials in URLs and unapproved origins are rejected.
+
+The proxy URL contains an encrypted, short-lived ticket, not the source URL or the visitor session.
+Avoid secrets in image URLs: the ticket request contains the source URL in its body.
+
 ## Custom headers and fetch
 
 Behind a same-origin BFF that wants a CSRF header, cookies or tracing:
@@ -178,12 +226,12 @@ Vanilla: `chat.configure({ headers, fetch })` or the `chat.headers` / `chat.fetc
 every request to `endpoint` (config, session, history, link, chat). It cannot override `content-type`,
 `authorization` (which carries the anonymous or signed-in session token), `x-dewee-gateway-url` or
 `x-dewee-gateway-token` (case-insensitive; such keys are dropped). Header names are sent lower-cased. For a
-cross-origin `endpoint`, the backend's CORS preflight must allow the extra headers; the built-in handlers only
-allow their own. A custom `fetch` receives every request as sent, including the session bearer token of a
+cross-origin `endpoint`, configure the backend's `allowedOrigins` and `allowedHeaders: ["x-csrf-token"]`.
+The built-in TS and PHP handlers accept header names containing letters, digits and hyphens. A custom `fetch` receives every request as sent, including the session bearer token of a
 signed-in user, so only the trusted host page should supply it.
 
 Anonymous visitor sessions are reused until less than 10% of the token lifetime remains (at most 24 h, at least
-30 s), so backends with short session TTLs do not mint a new session on every request. With `transport: "ccp"`,
+30 s, and no more than half the lifetime), so backends with short session TTLs do not mint a new session on every request. With `transport: "ccp"`,
 `/session` reports the end of the CCP edge session sealed in the token as `expiresAt` (and `expiresIn`), so the
 widget asks `/session` again before it lapses, about once an hour, although the token itself lives 30 days. That
 refresh keeps the visitor id and re-seals a refreshed edge session, so a host that keeps no memory between
@@ -253,6 +301,43 @@ or inserts it as HTML, caps calls per answer and automatic turns per message, an
 `mutate`/`destructive` handler without approval. Page context and results are labelled as data for the
 agent, but prompt injection through page content is still possible — do not put secrets in either.
 
+### Built-in DOM actions
+
+Without writing handlers, a page can let the agent scroll, click and type on it. They are off by
+default:
+
+```html
+<script src="https://webchat-cdn.dewee.sh/v/latest/dewee-webchat.js"
+  data-endpoint="/api/dewee" data-dom-actions="true" data-dom-actions-root="#app" defer></script>
+```
+
+```tsx
+<DeweeChat endpoint="/api/dewee" domActions domActionsRoot="#app" />
+```
+
+| Action | Sensitivity | What it does |
+|---|---|---|
+| `page.snapshot` | `read` | Lists visible links, buttons and form fields as `e3 textbox "Email" value="…"`, with a `generation` |
+| `page.scroll` | `read` | Scrolls one screen up/down, to the top/bottom, or an element (`ref`) into view |
+| `page.click` | `mutate` | Clicks an element by `ref` + `generation` |
+| `page.fill` | `mutate` | Sets the value of a text field, textarea, select or editable area, then fires `input` and `change` |
+
+- `page.click` and `page.fill` always ask the visitor first; the dialog (or your `confirm` hook, as
+  `args.target`) names the element, e.g. `button "Delete run"`.
+- Refs come only from the latest snapshot. A ref from an older snapshot, or an element that is gone,
+  hidden or now sensitive, is refused, and the agent is told to take a new snapshot.
+- Never listed or touched: password, payment card and one-time-code fields (by `type`, `autocomplete`
+  and name), hidden elements, the widget itself, and anything inside `[data-dewee-ignore]`. Put
+  `data-dewee-ignore` on whatever else the agent must not reach.
+- `page.fill` uses the native value setter, so React and Vue controlled inputs see the change. Events are
+  synthetic (`isTrusted` is false): pages that require trusted events, file pickers and popups opened by a
+  click will not react.
+- Your own actions keep working; registering an action with a built-in name (say `page.click`)
+  replaces the built-in one.
+- The built-ins operate the DOM, not your app's permissions: the agent can do whatever the visitor's
+  clicks can, after approval. Narrow it with `domActionsRoot` and `data-dewee-ignore`, and keep the server
+  as the authority.
+
 ## Signed-in users
 
 When your site knows who the visitor is, the agent can know it too, with private tools that act for
@@ -355,7 +440,7 @@ How it behaves:
   memory, have the logout page send the widget's hint (`chat.reuseHint()`) along: the session in it
   is revoked when it belongs to that subject. Pass the logout request so CCP sees the visitor's
   origin (an integration with an origin allowlist needs it; without a request, the origin the
-  session was issued for is used). Sessions held only by other instances end when they expire. The
+  session was issued for is used). Without a shared store, sessions held only by other instances end when they expire. The
   legacy gateway has no revoke call, so there it only forgets them.
 
   ```ts
@@ -367,6 +452,14 @@ How it behaves:
     // …then clear your own session cookie
   }
   ```
+- For multiple handler instances, supply `identity.sessionStore` implementing the exported
+  `IdentitySessionStore` interface. Share the same protected store and visitor secret across those
+  instances. The default is a bounded, per-handler in-memory store. Store records contain bearer
+  credentials: encrypt them at rest, restrict access and never log values. The interface requires
+  atomic revision checks and updates across instances, unique non-reused revisions even after
+  eviction, conditional token deletion, and expiry by `deadline`; a simple non-atomic KV get/set is
+  insufficient. Keys use scoped HMAC digests, not raw host user IDs. Store failures refuse session
+  issuance; logout remains best effort, logs store failure and still attempts the supplied hint.
 - Fail closed. If `authenticate` returns `null`, the visitor chats anonymously, exactly as without
   `identity`, unless `required` is set, in which case no session is issued. If it throws, the answer
   is `503 SOURCE_UNAVAILABLE` and no session is issued. If the exchange for a signed-in user fails, no
@@ -412,8 +505,8 @@ links on its own. `dewee:link` fires with `{ expiresAt, deepLinks }`. A link tha
 progress answers `409 link_in_progress`, a reused idempotency key `409 idempotency_key_reused`, and a
 gateway with linking switched off `503 linking_unavailable`; the widget shows its own text for each.
 
-The PHP backend does not support signed-in users (it has no JWS signing), with either transport; use
-the Node/Workers handler. It refuses tokens that carry an identity session.
+The PHP backend also supports signed-in users and a server-side logout hook; see the
+[PHP identity setup](../../php/README.md#signed-in-users). Its stateless reuse uses the CCP reuse hint.
 
 ## Security model
 
@@ -429,6 +522,9 @@ the Node/Workers handler. It refuses tokens that carry an identity session.
 - Only allowed agents are reachable (the integration's, legacy: `agents`); origin allowlist, rate limits (20 messages/min per visitor, 10
   new sessions/10 min per IP by default — pass `rateLimit` for a shared store), 4000-char messages,
   optional Turnstile.
+- The default rate limiter is in memory and applies per handler instance, not across replicas or
+  serverless invocations. For a shared backend limit, provide an atomic shared-store `rateLimit`
+  implementation; do not rely on the default as a cluster-wide limit.
 - The Dewee gateway enforces the shared admission limits on every message. A refusal reaches the widget
   as a typed SSE error (`POLICY_DENIED`, or `RATE_LIMITED` with `retryAfterMs`) with a fixed message, never
   the gateway's own text. The widget shows a localized error and disables sending until `retryAfterMs`

package/astro/DeweeChat.astro

@@ -2,11 +2,11 @@
 // Astro component: <DeweeChat endpoint="/api/dewee" title="Support" showReasoning={false} />
 import type { DeweeChatConfig } from "dewee-webchat";
 
-type Props = Partial<DeweeChatConfig> & { class?: string };
+type Props = Omit<Partial<DeweeChatConfig>, "contextProvider"> & { class?: string };
 const { class: className, ...config } = Astro.props;
 const attrs: Record<string, string> = {};
 for (const [key, value] of Object.entries(config)) {
-  if (value === undefined || value === null) continue;
+  if (value === undefined || value === null || typeof value === "function") continue;
   const name = key.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
   attrs[name] = Array.isArray(value) ? JSON.stringify(value) : String(value);
 }