Hosted chat is an integration boundary, not a module

The useful lesson from yesterday's work was not “add a chat iframe.” That is the easy part. The real architecture question is how to let hosted chat help inside a private product without giving it the same authority as the product itself.

The answer I trust is to treat hosted chat as an integration boundary. It may live visually inside the page, but operationally it is closer to a partner system than a local component. It needs a contract, a readiness handshake, origin checks, typed messages, and a narrow context envelope.

The iframe is not inside your trust boundary

An embedded chat surface can feel first-party because it is framed inside the product UI. That is a dangerous mental shortcut. The parent app and the hosted chat runtime have different credentials, release cycles, failure modes, and responsibilities.

The parent app should not hand the iframe OAuth tokens, API keys, embed secrets, presigned document URLs, or raw private records through query strings, logs, or postMessage payloads. If the chat needs context, pass identifiers and capability flags that the hosted side is explicitly allowed to interpret. Keep the actual source of truth behind the product server and its own authorization rules.

Use a small host contract

A good host contract has a few boring pieces:

1. Server-built URL: construct the iframe URL on the server, not by sprinkling secrets through client code.
2. Non-secret context: include only context such as an active workspace identifier, an embed configuration identifier, and the parent origin when those values are safe to expose.
3. Origin and source gates: accept messages only from the expected hosted-chat origin and the specific iframe window.
4. Readiness handshake: wait for a clear READY signal, then respond with sanitized host capabilities instead of assuming the iframe is interactive.
5. Typed proposal events: accept narrow message shapes, validate them, and normalize provenance before anything reaches product state.

That contract is intentionally smaller than the product. It gives the chat enough context to be useful without making it a privileged runtime extension.

Parent tools should still produce drafts

When hosted chat can call a parent tool, the tool should not be “write the official record.” It should be “propose a draft with evidence, uncertainty, and a diff.” The parent application can then sanitize the result, record provenance, and route it through the same review form as any manually imported draft.

This keeps the user experience smooth without collapsing the audit boundary. The model can help translate messy conversation into structured intent. The product still owns schemas, validation, status downgrades, persistence, and final approval.

Make unavailable states explicit

Embedded systems fail in ordinary ways: an origin is not allowed, a scope is missing, a hosted session is not ready, or the iframe has loaded but cannot yet send the expected event. Those states should be visible. The product should keep a manual fallback available and say what is not ready, rather than pretending the assistant is connected or silently dropping work.

This also makes OAuth and API-scope problems easier to debug. Hosted sign-in success does not prove that the product can call the APIs it needs afterward. The app's requested scopes, the marketplace registration, and the API response shapes all have to line up. That is setup work, not something the iframe should paper over.

The rule I am taking forward

Embedding hosted AI chat safely is less about the chat UI and more about respecting boundaries. Keep secrets out of the iframe URL. Keep context narrow. Verify who sent each message. Let typed proposal events enter a review lane, not the source of truth.

Treat hosted chat as an integration boundary. Let it propose useful work, then make the product prove what becomes state.

That pattern applies beyond registers. It fits any product where an assistant helps with intake, triage, drafting, or interpretation while the product remains accountable for durable facts.