@sylergydigital/issue-pin-sdk 0.6.1 → 0.6.3

package/README.md

@@ -15,10 +15,16 @@ npm install @sylergydigital/issue-pin-sdk
 Ensure these are installed in your app:
 
 ```bash
-npm install react react-dom @supabase/supabase-js html2canvas lucide-react
+npm install react react-dom @supabase/supabase-js html2canvas-pro lucide-react
 ```
 
-The public GitHub repo at `sylergydigital/issue-pin-sdk` is a read-only mirror. Source changes should be made in the private source repo and will sync across automatically.
+The public GitHub repo at `https://github.com/sylergydigital/issue-pin-sdk` is a read-only mirror of the publishable SDK package.
+
+The package is published publicly on npm, so no `.npmrc` or GitHub Packages token setup is required for installation.
+
+npm package page: `https://www.npmjs.com/package/@sylergydigital/issue-pin-sdk`
+
+Source changes should still be made in the private source repo and will sync across automatically.
 
 `react-router-dom` is **not** required. The SDK tracks `window.location` for thread fetching and `?highlight_thread=` without router context.
 
@@ -290,14 +296,15 @@ import { supabase } from "./lib/supabase";
 <IssuePin apiKey="ew_live_..." supabaseClient={supabase} enabled={feedbackOn} />
 ```
 
-No backend code, edge functions, or sync secrets needed. The SDK handles everything transparently.
+No backend code or sync secrets are needed in the host app. On the first successful federation call, Issue Pin verifies the external Supabase JWT against its issuer JWKS and bootstraps the workspace trust mapping automatically.
 
 ### How auto-federation works
 
 When a user is detected via `supabaseClient`:
 1. The SDK calls the `sdk-federate` endpoint with the API key + user identity
-2. The endpoint validates the API key, resolves the workspace, and upserts the user as a `client_federated` workspace member with `commenter` role
-3. An identity source (`sdk:<workspace-slug>`) is auto-created if it doesn't exist
+2. The endpoint validates the API key, resolves the workspace, verifies the external Supabase JWT against the issuer JWKS, and derives the external project ref from the token issuer
+3. If the workspace has no active Supabase issuer mapping yet, Issue Pin auto-creates the matching `identity_sources` and `workspace_identity_sources` records for that issuer
+4. The endpoint upserts the user as a `client_federated` workspace member with `commenter` role
 
 ```mermaid
 sequenceDiagram
@@ -311,6 +318,8 @@ sequenceDiagram
     SDK->>EF: POST { apiKey, externalId, email, displayName }
     EF->>DB: SHA-256(apiKey) → resolve_api_key()
     DB-->>EF: workspace_id
+    EF->>DB: verify JWT via issuer JWKS
+    EF->>DB: bootstrap issuer mapping if missing
     EF->>DB: Upsert user_identities
     EF->>DB: Upsert workspace_members (commenter role)
     DB-->>EF: OK
@@ -319,6 +328,8 @@ sequenceDiagram
     Note over SDK: Result cached — runs once per session
 ```
 
+The first verified Supabase issuer becomes the workspace's default SDK federation issuer. If you later need to trust a different or additional issuer, add it explicitly in the Federation UI.
+
 ### Other auth providers (manual)
 
 For non-Supabase auth systems, pass identity props directly:
@@ -345,6 +356,54 @@ For bulk provisioning or non-Supabase apps, use the `federate-user` edge functio
 
 The API key is a **publishable key** — safe to include in client-side code. It only grants scoped access to create threads and comments for the associated workspace, enforced server-side via Row Level Security.
 
+## Content Security Policy (CSP)
+
+If your app sets a Content Security Policy header, add these directives so the IssuePin SDK can connect to Supabase, render screenshot previews, and apply inline styles:
+
+```
+connect-src https://*.supabase.co wss://*.supabase.co;
+img-src data: blob:;
+style-src 'unsafe-inline';
+```
+
+Merge these with your existing CSP directives — for example, if you already have `connect-src 'self'`, change it to `connect-src 'self' https://*.supabase.co wss://*.supabase.co;`.
+
+> **Narrower alternative:** Replace `*.supabase.co` with your project's specific URL (e.g. `https://abcdef.supabase.co`) for a tighter policy.
+
+### Why each directive is needed
+
+| Directive | Sources | Reason |
+|-----------|---------|--------|
+| `connect-src` | `https://*.supabase.co` | REST API calls to read/write threads and comments |
+| `connect-src` | `wss://*.supabase.co` | WebSocket connections for real-time thread updates |
+| `img-src` | `data:` `blob:` | Screenshot preview thumbnails rendered as data URIs and blob URLs |
+| `style-src` | `'unsafe-inline'` | html2canvas-pro injects inline styles during screenshot capture |
+
+### Programmatic access
+
+The SDK exports a typed constant for use in server-side middleware or build-time CSP generation:
+
+```typescript
+import { CSP_REQUIREMENTS } from "@sylergydigital/issue-pin-sdk";
+
+// CSP_REQUIREMENTS = {
+//   "connect-src": ["https://*.supabase.co", "wss://*.supabase.co"],
+//   "img-src": ["data:", "blob:"],
+//   "style-src": ["'unsafe-inline'"],
+// }
+```
+
+### Runtime detection
+
+When a CSP policy blocks an SDK operation, the browser console shows a warning like:
+
+```
+[IssuePin] CSP violation: connect-src blocked "https://abc.supabase.co/rest/v1/threads".
+Add to your Content-Security-Policy: connect-src https://*.supabase.co wss://*.supabase.co
+```
+
+These warnings appear automatically — no `debug` flag needed.
+
 ## AI Agent Prompt
 
 Paste this into **Claude Code**, **Cursor**, or **Codex** to integrate the SDK automatically:
@@ -353,11 +412,7 @@ Paste this into **Claude Code**, **Cursor**, or **Codex** to integrate the SDK a
 Add the Issue Pin feedback SDK to this React app.
 
 Install: npm install @sylergydigital/issue-pin-sdk
-Peer deps: npm install @supabase/supabase-js html2canvas lucide-react
-
-.npmrc setup (required for GitHub Packages):
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-@sylergydigital:registry=https://npm.pkg.github.com
+Peer deps: npm install react react-dom @supabase/supabase-js html2canvas-pro lucide-react
 
 Integration:
 1. Import { IssuePin } from "@sylergydigital/issue-pin-sdk"

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CSP_REQUIREMENTS: () => CSP_REQUIREMENTS,
   ElementWhisperer: () => IssuePin,
   FeedbackButton: () => FeedbackButton,
   FeedbackOverlay: () => FeedbackOverlay,
@@ -40,6 +41,7 @@ __export(index_exports, {
   SdkCommentPopover: () => SdkCommentPopover,
   ThreadPins: () => ThreadPins,
   Z: () => Z,
+  normalizeUserId: () => normalizeUserId,
   useFeedback: () => useFeedback,
   useFeedbackSafe: () => useFeedbackSafe,
   useIssuePinAnchor: () => useIssuePinAnchor
@@ -52,7 +54,7 @@ var import_react11 = require("react");
 // src/FeedbackProvider.tsx
 var import_react2 = require("react");
 var import_supabase_js = require("@supabase/supabase-js");
-var import_html2canvas = __toESM(require("html2canvas"), 1);
+var import_html2canvas_pro = __toESM(require("html2canvas-pro"), 1);
 
 // src/useDocumentPathname.ts
 var import_react = require("react");
@@ -125,6 +127,51 @@ var T = {
   ring: "#6366f1"
 };
 
+// src/uuid.ts
+var import_uuid = require("uuid");
+var NAMESPACE = "8920e263-ef53-4df0-8108-968cd5d8939e";
+var UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normalizeUserId(userId) {
+  if (UUID_SHAPE.test(userId)) return userId;
+  return (0, import_uuid.v5)(userId, NAMESPACE);
+}
+
+// src/csp.ts
+var CSP_REQUIREMENTS = {
+  "connect-src": ["https://*.supabase.co", "wss://*.supabase.co"],
+  "img-src": ["data:", "blob:"],
+  "style-src": ["'unsafe-inline'"]
+};
+var warnedDirectives = /* @__PURE__ */ new Set();
+function isIssuePinViolation(event) {
+  const blocked = event.blockedURI;
+  const directive = event.violatedDirective;
+  if (directive.startsWith("connect-src") && blocked.includes("supabase.co")) return true;
+  if (directive.startsWith("img-src") && (blocked === "data" || blocked === "blob")) return true;
+  if (directive.startsWith("style-src") && (blocked === "inline" || blocked === "'unsafe-inline'")) return true;
+  return false;
+}
+function handleViolation(event) {
+  if (!isIssuePinViolation(event)) return;
+  const directive = event.violatedDirective.split(" ")[0];
+  if (warnedDirectives.has(directive)) return;
+  warnedDirectives.add(directive);
+  const sources = CSP_REQUIREMENTS[directive];
+  const fix = sources ? sources.join(" ") : event.blockedURI;
+  console.warn(
+    `[IssuePin] CSP violation: ${directive} blocked "${event.blockedURI}". Add to your Content-Security-Policy: ${directive} ${fix}`
+  );
+}
+function subscribeCspDetection() {
+  if (typeof document === "undefined") return () => {
+  };
+  const handler = (e) => handleViolation(e);
+  document.addEventListener("securitypolicyviolation", handler);
+  return () => {
+    document.removeEventListener("securitypolicyviolation", handler);
+  };
+}
+
 // src/FeedbackProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var FeedbackContext = (0, import_react2.createContext)(null);
@@ -176,11 +223,11 @@ function setThreadsSchemaMode(workspaceId, mode) {
   threadsSchemaModeByWorkspace.set(workspaceId, mode);
 }
 function resolveIssuePinActorUserId(opts) {
-  if (opts.explicitUserId) return opts.explicitUserId;
+  if (opts.explicitUserId) return normalizeUserId(opts.explicitUserId);
   if (opts.hasApiKey && !opts.skipFederation && opts.autoIdentityUserId) {
     return opts.federatedLocalUserId;
   }
-  return opts.autoIdentityUserId;
+  return opts.autoIdentityUserId ? normalizeUserId(opts.autoIdentityUserId) : opts.autoIdentityUserId;
 }
 function resolveIssuePinActorReady(opts) {
   if (!opts.authReady) return false;
@@ -417,6 +464,10 @@ function FeedbackProvider({
     hasApiKey: !!config.apiKey,
     skipFederation: config.skipFederation
   });
+  const rawUserId = config.userId ?? autoIdentity.userId;
+  if (config.debug && rawUserId && effectiveUserId && rawUserId !== effectiveUserId) {
+    console.log(`[EW SDK] User ID normalized: "${rawUserId}" -> "${effectiveUserId}"`);
+  }
   const actorReady = resolveIssuePinActorReady({
     authReady,
     explicitUserId: config.userId,
@@ -501,12 +552,13 @@ function FeedbackProviderInner({
     console.log(`[EW SDK] ${message}`, extra);
   }, [debug]);
   (0, import_react2.useEffect)(() => {
+    if (!authReady) return;
     if (!userDisplayName && !userEmail) {
       console.warn(
         '[IssuePin] No user identity provided \u2014 comments will appear as "Unknown". Pass supabaseClient={supabase} for automatic identity, or user={{ email, displayName }} for manual attribution. See https://github.com/sylergydigital/issue-pin/blob/main/sdk/README.md#user-identity-avoiding-unknown-comments'
       );
     }
-  }, []);
+  }, [authReady, userDisplayName, userEmail]);
   const client = (0, import_react2.useMemo)(() => {
     try {
       return (0, import_supabase_js.createClient)(supabaseUrl, supabaseAnonKey, {
@@ -613,6 +665,10 @@ function FeedbackProviderInner({
       debugLog("FeedbackProvider unmounted", { workspaceId, path: pathname });
     };
   }, [debugLog, workspaceId, pathname]);
+  (0, import_react2.useEffect)(() => {
+    const unsubscribe = subscribeCspDetection();
+    return unsubscribe;
+  }, []);
   (0, import_react2.useEffect)(() => {
     debugLog("mode / feedbackActive", { mode, feedbackActive });
   }, [debugLog, mode, feedbackActive]);
@@ -680,7 +736,7 @@ function FeedbackProviderInner({
     if (!client) return;
     try {
       await new Promise((resolve) => setTimeout(resolve, 300));
-      const canvas = await (0, import_html2canvas.default)(document.body, {
+      const canvas = await (0, import_html2canvas_pro.default)(document.body, {
         useCORS: true,
         allowTaint: true,
         logging: false,
@@ -712,7 +768,7 @@ function FeedbackProviderInner({
     setMenuOpen(false);
     setScreenshotCapturing(true);
     try {
-      const canvas = await (0, import_html2canvas.default)(document.body, {
+      const canvas = await (0, import_html2canvas_pro.default)(document.body, {
         useCORS: true,
         scale: window.devicePixelRatio,
         logging: false,
@@ -2483,6 +2539,7 @@ function PinsSlot() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CSP_REQUIREMENTS,
   ElementWhisperer,
   FeedbackButton,
   FeedbackOverlay,
@@ -2493,6 +2550,7 @@ function PinsSlot() {
   SdkCommentPopover,
   ThreadPins,
   Z,
+  normalizeUserId,
   useFeedback,
   useFeedbackSafe,
   useIssuePinAnchor