Web Widget, SSE, and Origin allowlists

A Chat Entry publishes one route as an embeddable web interface. Its entry_key is visible in page source by design. Protection comes from entry state, rate limits, the Origin allowlist, trusted identity tickets, and final backend authorization—not from hiding the key.

Minimal embed

<script src="https://<your-hub>/widget.js" data-entry="<entry_key>" async></script>

Bind the entry to a route and configure its title, greeting, appearance, uploads, and allowed sites. An anonymous browser can continue a conversation, but its generated visitor_id is not a trusted business identity. To expose subject-bound tools, the business backend must issue a short-lived ticket from the current login.

Origin allowlist

Each item is an exact scheme://host[:port], with no path, query, user info, or wildcard.
An empty array means browser origins are unrestricted; it does not mean “deny all.”
A browser request with a non-matching Origin is rejected with 403 before a business job is created.
Mini-program and server-side requests often have no browser Origin, so this gate does not cover them; use signatures, tickets, or server authentication for those callers.

The Origin allowlist prevents direct embedding from another website. It is not login, tenant isolation, or business authorization.

Default-open behavior

appearance.default_open defaults to false, so the page loads a launcher bubble. Setting it to true opens an existing official embed on load without changing the host page. data-open="1" remains an explicit per-embed override.

SSE result stream

POST /chat/:entry_key creates a job and returns job_id.
The client connects to GET /chat/:entry_key/events/:job_id.
open/status/phase/delta can drive temporary UI; reset means discard unfinished text.
Only done.reply is authoritative. timeout ends this connection window but does not prove the job failed.
Reconnects can use Last-Event-ID; durable recovery still comes from the server-side job and conversation ledgers.

A custom client must implement reset and must not present received delta text as proof of business completion.