​

Widget Identity

​

Modes

​

How Verification Is Enforced

• Anonymous visitors with no identify call, or identify with no email, can always chat as leads. Turning on verification never blocks them.
• Identified visitors must carry a valid HMAC hash or JWT when they pass an email. An identity claim without a valid proof is rejected, so a browser user can never impersonate another account.
• Strict mode blocks anonymous visitors entirely. Turn on Require verified identity only when everyone must be verified before chatting.

​

Install Contract

• After login or session load.
• When https://woes.dev/widget.js finishes loading.
• On window focus.
• When the page becomes visible again.

​

Verify an Install

1. Select the agent widget key installed on the site.
2. Open the site page where the widget script is installed.
3. In Woes, click Refresh in Install check. The site origin should appear with a recent last seen time.
4. Generate a real identity proof from your application backend.
5. Paste the customer email and email_hash for HMAC mode, or paste the JWT for JWT mode, into Test an identity proof.
6. Click Verify proof before testing a live chat message.

​

HMAC Email

import { createHmac } from "node:crypto";

function getWoesIdentitySecret() {
  const secret = process.env.WOES_WIDGET_IDENTITY_SECRET?.trim();
  if (!secret || !/^[a-f0-9]{64}$/i.test(secret)) {
    throw new Error("Woes identity secret is not configured");
  }
  return Buffer.from(secret, "hex");
}

export async function GET() {
  const user = await requireCurrentUser();
  const email = user.email.trim().toLowerCase();
  const emailHash = createHmac("sha256", getWoesIdentitySecret())
    .update(email)
    .digest("hex");

  return Response.json(
    {
      id: user.id,
      email,
      email_hash: emailHash,
      name: user.name,
      company: user.accountName,
    },
    { headers: { "Cache-Control": "no-store" } },
  );
}

window.Woes("identify", {
  id: identity.id,
  email: identity.email,
  email_hash: identity.email_hash,
  name: identity.name,
  company: identity.company,
});

​

JWT

import jwt from "jsonwebtoken";

export async function GET() {
  const user = await requireCurrentUser();
  const now = Math.floor(Date.now() / 1000);
  const token = jwt.sign(
    {
      email: user.email.trim().toLowerCase(),
      name: user.name,
      account_external_id: user.accountId,
      contact_external_id: user.id,
      aud: process.env.WOES_AGENT_WIDGET_PUBLIC_KEY,
      iat: now,
      exp: now + 10 * 60,
    },
    process.env.WOES_WIDGET_IDENTITY_SECRET,
    { algorithm: "HS256" },
  );

  return Response.json(
    { jwt: token },
    { headers: { "Cache-Control": "no-store" } },
  );
}

window.Woes("identify", {
  jwt: identity.jwt,
});

​

Browser Integration Checklist

• Load https://woes.dev/widget.js with the selected public widget key in data-public-key.
• Create or rely on the Woes command queue before calling window.Woes(...).
• Fetch your authenticated identity endpoint with same-origin credentials and no-store caching.
• Treat 401 from the identity endpoint as anonymous mode unless strict verified identity is required.
• Call window.Woes("identify", identity) every time a valid signed identity is returned.
• Verify a logged-in test visitor sends a message and appears in Woes with their email/name and identity_source of widget-token.

​

Copy Prompt for AI Install

• The public widget key for the selected agent.
• The selected verification mode.
• Server-only environment variable guidance.
• The authenticated no-store identity endpoint contract.
• The required browser window.Woes("identify", ...) call and retry behavior.

• The private identity secret.
• Workspace API keys.
• Supabase or Stripe keys.
• Operator-only account data.

​

Security Rules

• Generate signatures server-side.
• Never expose identity secrets to the browser.
• Use stable customer identifiers.
• Do not include raw secrets in identity metadata.
• Confirm the widget install uses the correct workspace or agent key.
• Treat unsigned browser identity fields as untrusted metadata.