dewee-webchat 0.4.2 → 0.5.0-beta.2

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` |
@@ -164,6 +183,49 @@ 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. For
+same-origin static files in the Worker's own Assets binding, a host can explicitly opt in:
+
+```ts
+createDeweeHandler({
+  // ... other handler options
+  imageSources: ["https://chat.example.com/public-chat-images/"],
+  cloudflarePublicImageAssets: { binding: env.ASSETS, prefixes: ["/public-chat-images/"] },
+});
+```
+
+Only exact same-origin paths in both lists use the binding. This reads the Assets collection directly,
+**bypassing Worker middleware, Cloudflare Access, and cookie-based authorization**. Every file under
+the configured prefixes must be public to any valid chat visitor; keep private files elsewhere,
+inspect the build output, and exclude sensitive files using `.assetsignore`. The URL query is not
+passed to the binding. Sibling domains still require a separate approved image domain.
+
+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:
@@ -180,12 +242,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
@@ -394,7 +456,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
@@ -406,6 +468,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
@@ -451,8 +521,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
 
@@ -468,6 +538,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);
 }

package/dist/{chunk-SAUDVPFH.js → chunk-KXW4EWXA.js}

@@ -21,7 +21,7 @@ function isLinkErrorCode(code) {
 }
 var HEADER_GATEWAY_URL = "x-dewee-gateway-url";
 var HEADER_GATEWAY_TOKEN = "x-dewee-gateway-token";
-var VERSION = "0.4.2";
+var VERSION = "0.5.0-beta.2";
 
 // src/actions/page-block.ts
 var ACTION_NAME_RE = /^[a-z][a-z0-9_.-]{0,63}$/;