@stigmer/sdk 3.1.7 → 3.1.9

package/sharing.js

@@ -0,0 +1,117 @@
+/**
+ * Agent-sharing helpers — the single source of truth for the hosted chat
+ * URL shape, the embed snippet, and client-side `allowed_origins`
+ * validation. Framework-free by design: consumed by the web console and
+ * desktop app (via `@stigmer/react`), the `stigmer` CLI, and any platform
+ * builder that wants to construct share links or embed snippets itself.
+ *
+ * The canonical URL shape is `<app-origin>/chat/<org>/<slug>` (a T01
+ * design decision), and `embed.js` is served from the root of that same
+ * app origin (T04). Callers supply the origin — resolving it is a host
+ * concern (the console knows its `appUrl`, the CLI resolves it from the
+ * backend type) — while the path and snippet shapes live here so every
+ * surface emits byte-identical output.
+ */
+/** Maximum number of allowed origins (proto: `repeated.max_items = 32`). */
+export const MAX_ALLOWED_ORIGINS = 32;
+/**
+ * Exact web origin: scheme://host[:port] — no path, query, fragment, or
+ * trailing slash. Mirrors the CEL expression `allowed_origins.format` on
+ * `AgentShareSpec` (`apis/ai/stigmer/agentic/agentshare/v1/spec.proto`).
+ *
+ * The proto is the source of truth — if the CEL expression changes, this
+ * pattern must change with it. Mirroring it client-side gives immediate
+ * feedback instead of a round-trip rejection.
+ */
+const ORIGIN_PATTERN = /^https?:\/\/[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*(:[0-9]{1,5})?$/;
+/**
+ * Validate a single `allowed_origins` entry.
+ *
+ * Returns `null` when valid, or a user-facing message explaining what
+ * to fix (DD-006: errors state what happened and what to do).
+ */
+export function validateOrigin(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "Enter an origin, like https://example.com";
+    if (!ORIGIN_PATTERN.test(trimmed)) {
+        return "Must be an exact web origin like https://example.com — no path, query, or trailing slash";
+    }
+    return null;
+}
+/**
+ * Query parameter carrying the share-link token on a locked link:
+ * `/chat/<org>/<slug>?k=<token>`. Short by design — the token rides every
+ * copied link, and `k` (for "key") is the platform's one-character
+ * convention, mirrored by the hosted page and the embed widget.
+ */
+export const LINK_TOKEN_PARAM = "k";
+/**
+ * The hosted chat page path for a shared agent: `/chat/<org>/<slug>`
+ * (the AgentShare's org and slug — the slug defaults to the agent's),
+ * plus `?k=<token>` when the share link is locked with a rotatable
+ * token (`AgentShareStatus.share_link_token`).
+ *
+ * Useful on its own when the caller renders relative to the current
+ * origin (e.g. a host that never configured an absolute app URL).
+ */
+export function chatPath(org, slug, linkToken) {
+    const path = `/chat/${org}/${slug}`;
+    return linkToken
+        ? `${path}?${LINK_TOKEN_PARAM}=${encodeURIComponent(linkToken)}`
+        : path;
+}
+/**
+ * The absolute hosted chat URL for a shared agent:
+ * `<appOrigin>/chat/<org>/<slug>[?k=<token>]`.
+ *
+ * A trailing slash on `appOrigin` is tolerated so callers can pass
+ * user-configured values verbatim. An empty `appOrigin` degrades to the
+ * relative {@link chatPath} — the same graceful fallback a host without a
+ * configured public origin gets in the share dialog.
+ */
+export function buildChatUrl(appOrigin, org, slug, linkToken) {
+    return stripTrailingSlash(appOrigin) + chatPath(org, slug, linkToken);
+}
+/**
+ * Append the share-link token to an already-built chat URL.
+ *
+ * For hosts that construct the base URL through their own callback (the
+ * share dialog's `buildShareUrl` prop) rather than {@link buildChatUrl}.
+ * A `null`/empty token returns the URL unchanged, so callers can pass
+ * `share.status?.shareLinkToken` straight through. Emits the identical
+ * `?k=` shape as {@link chatPath} — one URL grammar across every surface.
+ */
+export function appendLinkToken(url, linkToken) {
+    if (!linkToken)
+        return url;
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}${LINK_TOKEN_PARAM}=${encodeURIComponent(linkToken)}`;
+}
+/**
+ * The embed loader URL: `embed.js` lives at the root of the app origin
+ * (the loader derives the chat-page origin from its own script URL, so
+ * the two must share an origin). An empty `appOrigin` degrades to the
+ * relative `/embed.js`.
+ */
+export function buildEmbedLoaderUrl(appOrigin) {
+    return `${stripTrailingSlash(appOrigin)}/embed.js`;
+}
+/**
+ * The two-line embed snippet an owner pastes into any website: the
+ * loader script plus the `<stigmer-agent>` element where the widget
+ * renders. A locked share link adds the `token` attribute, which the
+ * widget forwards as `?k=` on its iframe URL. Every surface (share
+ * dialog, CLI, docs) emits exactly this.
+ */
+export function buildEmbedSnippet(appOrigin, org, slug, linkToken) {
+    const tokenAttribute = linkToken ? ` token="${linkToken}"` : "";
+    return [
+        `<script src="${buildEmbedLoaderUrl(appOrigin)}" async></script>`,
+        `<stigmer-agent org="${org}" agent="${slug}"${tokenAttribute}></stigmer-agent>`,
+    ].join("\n");
+}
+function stripTrailingSlash(origin) {
+    return origin.endsWith("/") ? origin.slice(0, -1) : origin;
+}
+//# sourceMappingURL=sharing.js.map

package/sharing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.js","sourceRoot":"","sources":["../src/sharing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,cAAc,GAClB,8GAA8G,CAAC;AAEjH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,2CAA2C,CAAC;IACjE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,0FAA0F,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAY,EAAE,SAAkB;IACpE,MAAM,IAAI,GAAG,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IACpC,OAAO,SAAS;QACd,CAAC,CAAC,GAAG,IAAI,IAAI,gBAAgB,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE;QAChE,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiB,EACjB,GAAW,EACX,IAAY,EACZ,SAAkB;IAElB,OAAO,kBAAkB,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,SAAoC;IAC/E,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3B,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,OAAO,GAAG,GAAG,GAAG,SAAS,GAAG,gBAAgB,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,GAAG,kBAAkB,CAAC,SAAS,CAAC,WAAW,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,GAAW,EACX,IAAY,EACZ,SAAkB;IAElB,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC,WAAW,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,OAAO;QACL,gBAAgB,mBAAmB,CAAC,SAAS,CAAC,mBAAmB;QACjE,uBAAuB,GAAG,YAAY,IAAI,IAAI,cAAc,mBAAmB;KAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7D,CAAC"}

package/src/__tests__/errors.test.ts

@@ -11,6 +11,62 @@ import {
   type ErrorCategory,
 } from "../errors";
 
+/**
+ * Guest launch-gate refusal contract (shared-agent abuse controls).
+ *
+ * The cloud backend resolves owner-customizable refusal copy server-side and
+ * carries it in the gRPC status description; the SDK must surface that copy
+ * VERBATIM through getUserMessage — no client-side mapping exists by design.
+ * These tests pin the two halves of that contract:
+ *
+ * 1. RESOURCE_EXHAUSTED / FAILED_PRECONDITION descriptions pass through
+ *    getUserMessage untouched.
+ * 2. The platform-default copy (mirrors GuestLimitReason in the cloud
+ *    backend) never collides with the sanitizer's rewrite patterns.
+ */
+describe("guest launch-gate refusal copy passthrough", () => {
+  // Mirrors GuestLimitReason default copy in the cloud stigmer-service.
+  // If those strings change, update here — this guardrail exists to catch a
+  // default that a sanitizer pattern would silently rewrite.
+  const platformDefaultCopy = [
+    "You\u2019re sending messages too quickly. Please wait a moment before sending another.",
+    "This agent is currently unavailable. Please check back later.",
+    "This conversation has ended. Please start a new conversation to continue.",
+    "This agent can\u2019t be embedded on this site.",
+  ];
+
+  const refusalCodes: Array<[string, Code]> = [
+    ["ResourceExhausted (rate limit)", Code.ResourceExhausted],
+    ["FailedPrecondition (fail-closed / bounds)", Code.FailedPrecondition],
+    ["PermissionDenied (embed origin)", Code.PermissionDenied],
+  ];
+
+  it.each(refusalCodes)(
+    "surfaces a %s status description verbatim",
+    (_label, code) => {
+      for (const copy of platformDefaultCopy) {
+        expect(getUserMessage(new ConnectError(copy, code))).toBe(copy);
+      }
+    },
+  );
+
+  it("surfaces owner-customized copy verbatim", () => {
+    const ownerCopy = "Whoa, slow down! Try again in a minute or two.";
+    expect(
+      getUserMessage(new ConnectError(ownerCopy, Code.ResourceExhausted)),
+    ).toBe(ownerCopy);
+  });
+
+  it("classifies rate-limit refusals as retryable and bounds refusals as not", () => {
+    expect(
+      isRetryableError(new ConnectError("copy", Code.ResourceExhausted)),
+    ).toBe(true);
+    expect(
+      isRetryableError(new ConnectError("copy", Code.FailedPrecondition)),
+    ).toBe(false);
+  });
+});
+
 describe("classifyError", () => {
   const stigmerMappings: Array<[string, ErrorCategory]> = [
     ["unauthenticated", "auth"],

package/src/__tests__/guest-auth.test.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { MintGuestTokenResponseSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { ConnectError, Code } from "@connectrpc/connect";
+
+// Intercept the token client so no transport is exercised. The mock
+// preserves the real module (create/Code/ConnectError) and only stubs
+// createClient, which GuestAuth uses to build its RPC client.
+const mintGuestToken = vi.fn();
+vi.mock("@connectrpc/connect", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@connectrpc/connect")>();
+  return {
+    ...actual,
+    createClient: () => ({ mintGuestToken }),
+  };
+});
+
+import { createGuestAuth, GuestAuth, type GuestIdStorage } from "../guest-auth";
+
+const CONFIG = {
+  baseUrl: "https://api.stigmer.ai",
+  org: "acme",
+  slug: "support-agent",
+};
+
+function createMemoryStorage(): GuestIdStorage & { store: Map<string, string> } {
+  const store = new Map<string, string>();
+  return {
+    store,
+    getItem: (key) => store.get(key) ?? null,
+    setItem: (key, value) => {
+      store.set(key, value);
+    },
+  };
+}
+
+function mintResponse(overrides?: {
+  accessToken?: string;
+  expiresIn?: number;
+  guestCookieId?: string;
+}) {
+  return create(MintGuestTokenResponseSchema, {
+    accessToken: overrides?.accessToken ?? "guest-jwt-1",
+    tokenType: "Bearer",
+    expiresIn: overrides?.expiresIn ?? 900,
+    guestCookieId: overrides?.guestCookieId ?? "cookie-abc",
+  });
+}
+
+beforeEach(() => {
+  mintGuestToken.mockReset();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("createGuestAuth", () => {
+  it("throws when baseUrl is missing", () => {
+    expect(() =>
+      createGuestAuth({ ...CONFIG, baseUrl: "" }),
+    ).toThrow("baseUrl is required");
+  });
+
+  it("throws when org is missing", () => {
+    expect(() => createGuestAuth({ ...CONFIG, org: "" })).toThrow(
+      "org is required",
+    );
+  });
+
+  it("throws when slug is missing", () => {
+    expect(() => createGuestAuth({ ...CONFIG, slug: "" })).toThrow(
+      "slug is required",
+    );
+  });
+
+  it("returns a GuestAuth instance with valid config", () => {
+    expect(createGuestAuth(CONFIG)).toBeInstanceOf(GuestAuth);
+  });
+});
+
+describe("GuestAuth.getAccessToken", () => {
+  it("mints on first call and sends an empty guest id", async () => {
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    const token = await auth.getAccessToken();
+
+    expect(token).toBe("guest-jwt-1");
+    expect(mintGuestToken).toHaveBeenCalledTimes(1);
+    expect(mintGuestToken.mock.calls[0][0]).toMatchObject({
+      org: "acme",
+      slug: "support-agent",
+      guestCookieId: "",
+      // No embedOrigin configured (the unframed hosted page): the field
+      // must stay empty so the server's absence-means-exempt rule applies.
+      embedOrigin: "",
+    });
+  });
+
+  it("passes the configured embedOrigin through to every mint", async () => {
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({
+      ...CONFIG,
+      storage: createMemoryStorage(),
+      embedOrigin: "https://docs.example.com",
+    });
+
+    await auth.getAccessToken();
+    // Expire the cached token, forcing a re-mint — the origin must persist.
+    vi.advanceTimersByTime(900_000);
+    await auth.getAccessToken();
+
+    expect(mintGuestToken).toHaveBeenCalledTimes(2);
+    for (const call of mintGuestToken.mock.calls) {
+      expect(call[0]).toMatchObject({ embedOrigin: "https://docs.example.com" });
+    }
+  });
+
+  it("passes the configured linkToken through to every mint", async () => {
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({
+      ...CONFIG,
+      storage: createMemoryStorage(),
+      linkToken: "tok123",
+    });
+
+    await auth.getAccessToken();
+    // Expire the cached token, forcing a re-mint — the token must persist
+    // so a locked link keeps working across silent re-mints.
+    vi.advanceTimersByTime(900_000);
+    await auth.getAccessToken();
+
+    expect(mintGuestToken).toHaveBeenCalledTimes(2);
+    for (const call of mintGuestToken.mock.calls) {
+      expect(call[0]).toMatchObject({ linkToken: "tok123" });
+    }
+  });
+
+  it("sends an empty linkToken when none is configured (plain link)", async () => {
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    await auth.getAccessToken();
+
+    expect(mintGuestToken.mock.calls[0][0]).toMatchObject({ linkToken: "" });
+  });
+
+  it("rejects with permission-denied when the embed origin is refused", async () => {
+    mintGuestToken.mockRejectedValue(
+      new ConnectError(
+        "This agent can\u2019t be embedded on this site.",
+        Code.PermissionDenied,
+      ),
+    );
+    const auth = createGuestAuth({
+      ...CONFIG,
+      storage: createMemoryStorage(),
+      embedOrigin: "https://evil.example.com",
+    });
+
+    await expect(auth.getAccessToken()).rejects.toMatchObject({
+      code: "permission-denied",
+    });
+  });
+
+  it("persists the server-issued guest id and presents it on re-mint", async () => {
+    const storage = createMemoryStorage();
+    mintGuestToken.mockResolvedValue(mintResponse({ guestCookieId: "cookie-abc" }));
+    const auth = createGuestAuth({ ...CONFIG, storage });
+
+    await auth.getAccessToken();
+    expect(storage.store.get("stigmer:guest-id:acme")).toBe("cookie-abc");
+    expect(auth.guestCookieId).toBe("cookie-abc");
+
+    // Expire the cached token, forcing a second mint.
+    vi.advanceTimersByTime(900_000);
+    await auth.getAccessToken();
+
+    expect(mintGuestToken).toHaveBeenCalledTimes(2);
+    expect(mintGuestToken.mock.calls[1][0]).toMatchObject({
+      guestCookieId: "cookie-abc",
+    });
+  });
+
+  it("restores a persisted guest id from a prior visit", async () => {
+    const storage = createMemoryStorage();
+    storage.setItem("stigmer:guest-id:acme", "cookie-from-last-visit");
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage });
+
+    await auth.getAccessToken();
+
+    expect(mintGuestToken.mock.calls[0][0]).toMatchObject({
+      guestCookieId: "cookie-from-last-visit",
+    });
+  });
+
+  it("returns the cached token while it is fresh", async () => {
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    await auth.getAccessToken();
+    // 13 minutes into a 15-minute token: still beyond the 60s skew.
+    vi.advanceTimersByTime(13 * 60_000);
+    const token = await auth.getAccessToken();
+
+    expect(token).toBe("guest-jwt-1");
+    expect(mintGuestToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-mints when the cached token is within the expiry skew", async () => {
+    mintGuestToken
+      .mockResolvedValueOnce(mintResponse({ accessToken: "guest-jwt-1" }))
+      .mockResolvedValueOnce(mintResponse({ accessToken: "guest-jwt-2" }));
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    await auth.getAccessToken();
+    // 30 seconds of life left — inside the 60s skew window.
+    vi.advanceTimersByTime(900_000 - 30_000);
+    const token = await auth.getAccessToken();
+
+    expect(token).toBe("guest-jwt-2");
+    expect(mintGuestToken).toHaveBeenCalledTimes(2);
+  });
+
+  it("collapses concurrent callers into a single mint", async () => {
+    let release!: (value: ReturnType<typeof mintResponse>) => void;
+    mintGuestToken.mockImplementation(
+      () => new Promise((resolve) => { release = resolve; }),
+    );
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    const first = auth.getAccessToken();
+    const second = auth.getAccessToken();
+    release(mintResponse());
+
+    await expect(first).resolves.toBe("guest-jwt-1");
+    await expect(second).resolves.toBe("guest-jwt-1");
+    expect(mintGuestToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects with a wrapped StigmerError when sharing is revoked", async () => {
+    mintGuestToken.mockRejectedValue(
+      new ConnectError("agent not found", Code.NotFound),
+    );
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    try {
+      await auth.getAccessToken();
+      expect.fail("should have thrown");
+    } catch (e: unknown) {
+      expect(e).toHaveProperty("name", "StigmerError");
+      expect(e).toHaveProperty("code", "not-found");
+    }
+  });
+
+  it("recovers after a failed mint instead of caching the failure", async () => {
+    mintGuestToken
+      .mockRejectedValueOnce(new ConnectError("unavailable", Code.Unavailable))
+      .mockResolvedValueOnce(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage: createMemoryStorage() });
+
+    await expect(auth.getAccessToken()).rejects.toMatchObject({
+      code: "unavailable",
+    });
+    await expect(auth.getAccessToken()).resolves.toBe("guest-jwt-1");
+    expect(mintGuestToken).toHaveBeenCalledTimes(2);
+  });
+
+  it("still mints when storage throws", async () => {
+    const brokenStorage: GuestIdStorage = {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    };
+    mintGuestToken.mockResolvedValue(mintResponse());
+    const auth = createGuestAuth({ ...CONFIG, storage: brokenStorage });
+
+    await expect(auth.getAccessToken()).resolves.toBe("guest-jwt-1");
+    expect(auth.guestCookieId).toBeNull();
+  });
+});

package/src/__tests__/sharing.test.ts

@@ -0,0 +1,159 @@
+// Unit tests for the framework-free agent-sharing helpers: origin
+// validation (mirror of the proto CEL rule) and the hosted-link / embed
+// snippet builders shared by the web console, desktop app, and CLI.
+
+import { describe, expect, it } from "vitest";
+import {
+  LINK_TOKEN_PARAM,
+  MAX_ALLOWED_ORIGINS,
+  appendLinkToken,
+  buildChatUrl,
+  buildEmbedLoaderUrl,
+  buildEmbedSnippet,
+  chatPath,
+  validateOrigin,
+} from "../sharing";
+
+describe("validateOrigin", () => {
+  it("accepts exact web origins", () => {
+    expect(validateOrigin("https://example.com")).toBeNull();
+    expect(validateOrigin("http://example.com")).toBeNull();
+    expect(validateOrigin("https://sub.example.com")).toBeNull();
+    expect(validateOrigin("https://example.com:8443")).toBeNull();
+    expect(validateOrigin("http://localhost:3000")).toBeNull();
+  });
+
+  it("trims surrounding whitespace before validating", () => {
+    expect(validateOrigin("  https://example.com  ")).toBeNull();
+  });
+
+  it("rejects empty input with guidance", () => {
+    expect(validateOrigin("")).toMatch(/Enter an origin/);
+    expect(validateOrigin("   ")).toMatch(/Enter an origin/);
+  });
+
+  it("rejects trailing slashes, paths, queries, and fragments", () => {
+    for (const bad of [
+      "https://example.com/",
+      "https://example.com/path",
+      "https://example.com?q=1",
+      "https://example.com#top",
+    ]) {
+      expect(validateOrigin(bad)).toMatch(/exact web origin/);
+    }
+  });
+
+  it("rejects non-http(s) schemes and bare hosts", () => {
+    expect(validateOrigin("ftp://example.com")).toMatch(/exact web origin/);
+    expect(validateOrigin("example.com")).toMatch(/exact web origin/);
+  });
+
+  it("rejects hostname labels with leading/trailing hyphens", () => {
+    expect(validateOrigin("https://-bad.example.com")).toMatch(/exact web origin/);
+    expect(validateOrigin("https://bad-.example.com")).toMatch(/exact web origin/);
+  });
+
+  it("exposes the proto max_items bound", () => {
+    expect(MAX_ALLOWED_ORIGINS).toBe(32);
+  });
+});
+
+describe("chatPath / buildChatUrl", () => {
+  it("builds the canonical /chat/<org>/<slug> path", () => {
+    expect(chatPath("acme", "support-agent")).toBe("/chat/acme/support-agent");
+  });
+
+  it("builds the absolute hosted chat URL", () => {
+    expect(buildChatUrl("https://app.stigmer.ai", "acme", "support-agent")).toBe(
+      "https://app.stigmer.ai/chat/acme/support-agent",
+    );
+  });
+
+  it("tolerates a trailing slash on the origin", () => {
+    expect(buildChatUrl("https://app.stigmer.ai/", "acme", "support-agent")).toBe(
+      "https://app.stigmer.ai/chat/acme/support-agent",
+    );
+  });
+
+  it("works with localhost origins (local backend)", () => {
+    expect(buildChatUrl("http://localhost:8234", "stigmer", "helper")).toBe(
+      "http://localhost:8234/chat/stigmer/helper",
+    );
+  });
+
+  it("appends ?k= when the share link is locked with a token", () => {
+    expect(chatPath("acme", "support-agent", "tok123")).toBe(
+      "/chat/acme/support-agent?k=tok123",
+    );
+    expect(
+      buildChatUrl("https://app.stigmer.ai", "acme", "support-agent", "tok123"),
+    ).toBe("https://app.stigmer.ai/chat/acme/support-agent?k=tok123");
+  });
+
+  it("url-encodes the token (defense in depth; generated tokens are url-safe)", () => {
+    expect(chatPath("acme", "bot", "a+b/c")).toBe("/chat/acme/bot?k=a%2Bb%2Fc");
+  });
+
+  it("omits ?k= for an empty/undefined token (plain link)", () => {
+    expect(chatPath("acme", "bot", "")).toBe("/chat/acme/bot");
+    expect(chatPath("acme", "bot", undefined)).toBe("/chat/acme/bot");
+  });
+});
+
+describe("appendLinkToken", () => {
+  it("appends the identical ?k= shape chatPath emits", () => {
+    expect(appendLinkToken("https://app.stigmer.ai/chat/acme/bot", "tok123")).toBe(
+      buildChatUrl("https://app.stigmer.ai", "acme", "bot", "tok123"),
+    );
+  });
+
+  it("uses & when the URL already carries a query", () => {
+    expect(appendLinkToken("/chat/acme/bot?theme=dark", "tok123")).toBe(
+      `/chat/acme/bot?theme=dark&${LINK_TOKEN_PARAM}=tok123`,
+    );
+  });
+
+  it("returns the URL unchanged for a null/empty token", () => {
+    expect(appendLinkToken("/chat/acme/bot", null)).toBe("/chat/acme/bot");
+    expect(appendLinkToken("/chat/acme/bot", undefined)).toBe("/chat/acme/bot");
+    expect(appendLinkToken("/chat/acme/bot", "")).toBe("/chat/acme/bot");
+  });
+});
+
+describe("buildEmbedLoaderUrl", () => {
+  it("points at embed.js on the app origin root", () => {
+    expect(buildEmbedLoaderUrl("https://app.stigmer.ai")).toBe("https://app.stigmer.ai/embed.js");
+  });
+
+  it("tolerates a trailing slash on the origin", () => {
+    expect(buildEmbedLoaderUrl("https://app.stigmer.ai/")).toBe("https://app.stigmer.ai/embed.js");
+  });
+});
+
+describe("buildEmbedSnippet", () => {
+  it("emits exactly the two-line loader + element snippet", () => {
+    expect(buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent")).toBe(
+      [
+        `<script src="https://app.stigmer.ai/embed.js" async></script>`,
+        `<stigmer-agent org="acme" agent="support-agent"></stigmer-agent>`,
+      ].join("\n"),
+    );
+  });
+
+  it("adds the token attribute when the share link is locked", () => {
+    expect(
+      buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent", "tok123"),
+    ).toBe(
+      [
+        `<script src="https://app.stigmer.ai/embed.js" async></script>`,
+        `<stigmer-agent org="acme" agent="support-agent" token="tok123"></stigmer-agent>`,
+      ].join("\n"),
+    );
+  });
+
+  it("omits the token attribute for an empty token (plain link)", () => {
+    expect(buildEmbedSnippet("https://app.stigmer.ai", "acme", "bot", "")).toBe(
+      buildEmbedSnippet("https://app.stigmer.ai", "acme", "bot"),
+    );
+  });
+});