Identity & signing

The problem

A visitor can type any address into a chat widget. If the agent treated that as identification, anyone could ask for anyone’s order history by knowing their email address — which is not a secret.

So Zealoop separates the two. An unverified visitor gets grounded answers from your documentation. A verified visitor also gets their own rows and their own actions. Nothing gated ever runs for the first kind.

How signing works

Your workspace has a widget secret. You compute an HMAC-SHA256 of the customer’s email using that secret, on your server, and pass the result to the widget alongside the address. The backend recomputes the same HMAC and compares in constant time. Matching means your server vouched for this person.

import crypto from "node:crypto";

// Server-side only. This secret never reaches a browser.
const WIDGET_SECRET = process.env.ZEALOOP_WIDGET_SECRET;

export function zealoopSignature(email) {
  return crypto
    .createHmac("sha256", WIDGET_SECRET)
    .update(email)
    .digest("hex");
}

Render it into the page for the signed-in user, then hand it to the widget:

Zealoop("identify", {
  email: 'customer@example.com',
  signature: 'a3f1…'   // computed on your server, above
});

Rotating the secret

Configuration → rotate. The previous secret remains valid for 48 hours to let you update your server without interrupting signed-in visitors. Deploy the new secret during that window. After it expires, old signatures fall back to anonymous and the agent declines identity-gated requests.

What identity unlocks

• Table lookups. A row is matched by its identity key column — usually the email. A verified visitor reads their row and no other. See Tables.
• Gated actions. Any action marked requiresIdentity is not even offered to the model for an anonymous visitor, so it cannot be talked into calling it.
• Continuity. Conversations attach to a known customer, so your team sees history instead of a stranger.

What it does not unlock

Identity is not authorisation for writes. A verified customer still cannot trigger a refund inside the generation loop — writes are proposed, confirmed, then executed on a later turn. See Actions.

Failure modes

• Wrong or missing signature — the visitor stays anonymous. There is no error toast, by design: an attacker probing signatures learns nothing from the response.
• Signature over the wrong string — the HMAC covers the email exactly as sent. Trailing whitespace or a different case changes the digest.
• Called before load — use the queue stub in the installation snippet. It stores early Zealoop("identify", payload) calls and replays them when the loader is ready.

The Inbox marks each conversation’s customer as verified or temporary, which is the quickest way to confirm your integration is actually working in production.