@polyguard/sdk 1.4.2 → 1.5.0

package/dist/server.esm.js

@@ -0,0 +1,83 @@
+// src/server.js
+var DEFAULT_ALLOWED_PATHS = [
+  "POST /v2/ticket/",
+  "PUT /link/",
+  "GET /v2/preview/"
+];
+var HOP_BY_HOP = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+function isAllowed(method, pathname, allowedPaths) {
+  const upper = method.toUpperCase();
+  for (const rule of allowedPaths) {
+    const idx = rule.indexOf(" ");
+    if (idx < 0) continue;
+    const ruleMethod = rule.slice(0, idx).toUpperCase();
+    const rulePrefix = rule.slice(idx + 1);
+    if (ruleMethod === upper && pathname.startsWith(rulePrefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+function createProxyHandler(options = {}) {
+  const { apiKey, apiServer = "api.polyguard.ai", allowedPaths = DEFAULT_ALLOWED_PATHS, pathPrefix = "/api/polyguard" } = options;
+  if (!apiKey) {
+    throw new Error("createProxyHandler: apiKey is required");
+  }
+  if (!apiServer) {
+    throw new Error("createProxyHandler: apiServer is required");
+  }
+  return async function polyguardProxy(request) {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+    if (pathPrefix && pathname.startsWith(pathPrefix)) {
+      pathname = pathname.slice(pathPrefix.length) || "/";
+    }
+    if (!isAllowed(request.method, pathname, allowedPaths)) {
+      return new Response("Not Found", { status: 404 });
+    }
+    const targetUrl = `https://${apiServer}${pathname}${url.search}`;
+    const forwardHeaders = new Headers();
+    for (const [name, value] of request.headers) {
+      const lower = name.toLowerCase();
+      if (lower === "x-pg-api-key" || lower === "authorization") continue;
+      if (HOP_BY_HOP.has(lower)) continue;
+      if (lower === "host") continue;
+      forwardHeaders.set(name, value);
+    }
+    forwardHeaders.set("x-pg-api-key", apiKey);
+    const init = {
+      method: request.method,
+      headers: forwardHeaders,
+      redirect: "manual"
+    };
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      init.body = request.body;
+      init.duplex = "half";
+    }
+    const upstream = await fetch(targetUrl, init);
+    const responseHeaders = new Headers();
+    for (const [name, value] of upstream.headers) {
+      const lower = name.toLowerCase();
+      if (HOP_BY_HOP.has(lower)) continue;
+      if (lower === "set-cookie") continue;
+      responseHeaders.set(name, value);
+    }
+    return new Response(upstream.body, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: responseHeaders
+    });
+  };
+}
+export {
+  createProxyHandler
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyguard/sdk",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/sdk.esm.js",
   "module": "dist/sdk.esm.js",
@@ -10,15 +10,21 @@
       "import": "./dist/sdk.esm.js",
       "require": "./dist/sdk.esm.js",
       "default": "./dist/sdk.esm.js"
+    },
+    "./server": {
+      "import": "./dist/server.esm.js",
+      "default": "./dist/server.esm.js"
     }
   },
   "scripts": {
-    "build": "npm run build:esm && npm run build:iife",
+    "build": "npm run build:esm && npm run build:iife && npm run build:server",
     "build:esm": "esbuild src/index.js --bundle --format=esm --outfile=dist/sdk.esm.js",
     "build:iife": "esbuild src/browser.js --bundle --format=iife --global-name=Polyguard --outfile=dist/sdk.js",
+    "build:server": "esbuild src/server.js --bundle --format=esm --platform=neutral --outfile=dist/server.esm.js",
     "prepare": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "regenerate-client": "bash scripts/regenerate-client.sh"
   },
   "keywords": [],
@@ -31,6 +37,7 @@
     "superagent": "^10.3.0"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.6",
     "esbuild": "^0.25.0",
     "jsdom": "^28.0.0",
     "vitest": "^4.0.18"

package/src/PolyguardWebsocketClientImpl.js

@@ -8,15 +8,28 @@ import { handleWebSocketMessage } from './messageHandler.js';
 export class PolyguardWebsocketClientImpl {
   constructor(params = {}) {
     this.apiClient = new PolyguardApi.ApiClient();
-    const { apiKey, baseUrl, appId, apiServer, requiredProofs = ['Full Name'], scanType = 'single', redirectUrl, callbackUrl, cookieName, link_uuid, sidebarUrl } = params;
+    const { apiKey, baseUrl, appId, apiServer, proxyUrl, iKnowThisIsInsecure, requiredProofs = ['Full Name'], scanType = 'single', redirectUrl, callbackUrl, cookieName, link_uuid, sidebarUrl } = params;
     this.sidebarUrl = sidebarUrl;
-    if (baseUrl) {
+
+    if (apiKey && typeof window !== 'undefined' && iKnowThisIsInsecure !== true) {
+      throw new Error(
+        'apiKey is forbidden in browser code; use proxyUrl with a server-side proxy (see @polyguard/sdk/server). ' +
+        'Set iKnowThisIsInsecure: true to bypass.'
+      );
+    }
+
+    if (proxyUrl) {
+      this.apiClient.basePath = proxyUrl.replace(/\/$/, '');
+    } else if (baseUrl) {
       this.apiClient.basePath = baseUrl;
     }
+
     if (apiKey) {
       if (this.apiClient.authentications['bearerAuth']) {
         this.apiClient.authentications['bearerAuth'].apiKey = apiKey;
       }
+      this.apiClient.defaultHeaders = this.apiClient.defaultHeaders || {};
+      this.apiClient.defaultHeaders['x-pg-api-key'] = apiKey;
     }
     // Instantiate all API services
     for (const key in PolyguardApi) {
@@ -29,6 +42,7 @@ export class PolyguardWebsocketClientImpl {
     this.integrationType = 'websocket';
     this.appId = appId;
     this.apiServer = apiServer;
+    this.proxyUrl = proxyUrl;
     this.requiredProofs = requiredProofs;
     this.scanType = scanType;
     this.redirectUrl = redirectUrl;
@@ -120,6 +134,7 @@ export class PolyguardWebsocketClientImpl {
 
         const newTicket = await fetchTicket({
           apiServer: this.apiServer,
+          proxyUrl: this.proxyUrl,
           appId: this.appId,
           link_uuid: this.link_uuid,
           requiredProofs: this.requiredProofs,

package/src/__tests__/PolyguardWebsocketClientImpl.test.js

@@ -162,11 +162,35 @@ describe('PolyguardWebsocketClientImpl', () => {
       expect(client.apiClient.basePath).toBe('https://custom.api');
     });
 
-    it('sets apiKey when provided', () => {
-      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, apiKey: 'my-key' });
+    it('throws when apiKey is provided in browser without iKnowThisIsInsecure flag', () => {
+      expect(() => new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, apiKey: 'my-key' })).toThrow(/apiKey is forbidden in browser code/);
+    });
+
+    it('accepts apiKey in browser with iKnowThisIsInsecure: true', () => {
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, apiKey: 'my-key', iKnowThisIsInsecure: true });
       expect(client.apiClient.authentications.bearerAuth.apiKey).toBe('my-key');
     });
 
+    it('also sets x-pg-api-key default header when apiKey is accepted', () => {
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, apiKey: 'my-key', iKnowThisIsInsecure: true });
+      expect(client.apiClient.defaultHeaders['x-pg-api-key']).toBe('my-key');
+    });
+
+    it('sets basePath from proxyUrl and strips trailing slash', () => {
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, proxyUrl: '/api/polyguard/' });
+      expect(client.apiClient.basePath).toBe('/api/polyguard');
+    });
+
+    it('proxyUrl takes precedence over baseUrl', () => {
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, proxyUrl: '/api/polyguard', baseUrl: 'https://other.api' });
+      expect(client.apiClient.basePath).toBe('/api/polyguard');
+    });
+
+    it('stores proxyUrl on the instance', () => {
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, proxyUrl: '/api/polyguard' });
+      expect(client.proxyUrl).toBe('/api/polyguard');
+    });
+
     it('sets integrationType to websocket', () => {
       const client = new PolyguardWebsocketClientImpl(DEFAULT_PARAMS);
       expect(client.integrationType).toBe('websocket');
@@ -255,6 +279,25 @@ describe('PolyguardWebsocketClientImpl', () => {
       await promise.catch(() => {});
     });
 
+    it('builds ticket URL through proxyUrl when set, bypassing apiServer', async () => {
+      const fetchMock = stubFetch();
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, proxyUrl: '/api/polyguard' });
+      const { promise, ws } = await startVerifyAndGetWs(client);
+      const url = fetchMock.mock.calls[0][0];
+      expect(url).toBe(`/api/polyguard/v2/ticket/${DEFAULT_PARAMS.appId}`);
+      if (ws) ws.simulateMessage({ jwt: 'cleanup' });
+      await promise.catch(() => {});
+    });
+
+    it('still uses apiServer for WebSocket upgrade even when proxyUrl is set', async () => {
+      stubFetch();
+      const client = new PolyguardWebsocketClientImpl({ ...DEFAULT_PARAMS, proxyUrl: '/api/polyguard' });
+      const { promise, ws } = await startVerifyAndGetWs(client);
+      expect(ws.url).toBe(`wss://${DEFAULT_PARAMS.apiServer}/v2/realtime/test-ticket-123`);
+      ws.simulateMessage({ jwt: 'cleanup' });
+      await promise.catch(() => {});
+    });
+
     it('sends POST with requiredProofs and scanType in body', async () => {
       const fetchMock = stubFetch();
       const client = new PolyguardWebsocketClientImpl(DEFAULT_PARAMS);

package/src/__tests__/server.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createProxyHandler } from '../server.js';
+
+function makeRequest(method, url, { headers = {}, body = null } = {}) {
+  const init = { method, headers };
+  if (body !== null) init.body = typeof body === 'string' ? body : JSON.stringify(body);
+  return new Request(url, init);
+}
+
+function stubFetch(responseOpts = {}) {
+  const { status = 200, body = '{"ok":true}', headers = { 'content-type': 'application/json' } } = responseOpts;
+  const mock = vi.fn().mockImplementation(async () => new Response(body, { status, headers }));
+  vi.stubGlobal('fetch', mock);
+  return mock;
+}
+
+describe('createProxyHandler', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('throws when apiKey is missing', () => {
+    expect(() => createProxyHandler({ apiServer: 'api.polyguard.ai' })).toThrow(/apiKey is required/);
+  });
+
+  it('throws when apiServer is falsy', () => {
+    expect(() => createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: '' })).toThrow(/apiServer is required/);
+  });
+
+  it('returns 404 for paths not in the allowlist', async () => {
+    stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('GET', 'http://localhost/api/polyguard/account/1/apps/3/api-keys');
+    const res = await handler(req);
+    expect(res.status).toBe(404);
+  });
+
+  it('returns 404 for an allowlisted prefix used with the wrong HTTP method', async () => {
+    stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('GET', 'http://localhost/api/polyguard/v2/ticket/3');
+    const res = await handler(req);
+    expect(res.status).toBe(404);
+  });
+
+  it('forwards POST /v2/ticket/* with x-pg-api-key injected', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('POST', 'http://localhost/api/polyguard/v2/ticket/3', {
+      headers: { 'content-type': 'application/json' },
+      body: { requiredProofs: ['name'], scanType: 'single' },
+    });
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [forwardedUrl, init] = fetchMock.mock.calls[0];
+    expect(forwardedUrl).toBe('https://api.polyguard.ai/v2/ticket/3');
+    expect(init.method).toBe('POST');
+    const headers = new Headers(init.headers);
+    expect(headers.get('x-pg-api-key')).toBe('pgk_live_x.y');
+  });
+
+  it('strips client-supplied x-pg-api-key before injecting', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_real.secret', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('POST', 'http://localhost/api/polyguard/v2/ticket/3', {
+      headers: { 'x-pg-api-key': 'pgk_live_attacker.smuggled', 'content-type': 'application/json' },
+      body: {},
+    });
+    await handler(req);
+    const init = fetchMock.mock.calls[0][1];
+    const headers = new Headers(init.headers);
+    expect(headers.get('x-pg-api-key')).toBe('pgk_live_real.secret');
+  });
+
+  it('strips client-supplied authorization header', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('POST', 'http://localhost/api/polyguard/v2/ticket/3', {
+      headers: { authorization: 'Bearer pgk_live_attacker.smuggled', 'content-type': 'application/json' },
+      body: {},
+    });
+    await handler(req);
+    const init = fetchMock.mock.calls[0][1];
+    const headers = new Headers(init.headers);
+    expect(headers.get('authorization')).toBeNull();
+  });
+
+  it('preserves query string when forwarding', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('GET', 'http://localhost/api/polyguard/v2/preview/3/link-abc?format=svg');
+    await handler(req);
+    expect(fetchMock.mock.calls[0][0]).toBe('https://api.polyguard.ai/v2/preview/3/link-abc?format=svg');
+  });
+
+  it('forwards PUT /link/* (link creation)', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const req = makeRequest('PUT', 'http://localhost/api/polyguard/link/3', {
+      headers: { 'content-type': 'application/json' },
+      body: { type: 'login' },
+    });
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    expect(fetchMock.mock.calls[0][0]).toBe('https://api.polyguard.ai/link/3');
+  });
+
+  it('honors a custom allowedPaths list', async () => {
+    stubFetch();
+    const handler = createProxyHandler({
+      apiKey: 'pgk_live_x.y',
+      apiServer: 'api.polyguard.ai',
+      allowedPaths: ['POST /v2/ticket/'],
+    });
+    const denied = await handler(makeRequest('PUT', 'http://localhost/api/polyguard/link/3'));
+    expect(denied.status).toBe(404);
+    const allowed = await handler(makeRequest('POST', 'http://localhost/api/polyguard/v2/ticket/3', { body: {} }));
+    expect(allowed.status).toBe(200);
+  });
+
+  it('honors a custom pathPrefix', async () => {
+    const fetchMock = stubFetch();
+    const handler = createProxyHandler({
+      apiKey: 'pgk_live_x.y',
+      apiServer: 'api.polyguard.ai',
+      pathPrefix: '/custom/proxy',
+    });
+    await handler(makeRequest('POST', 'http://localhost/custom/proxy/v2/ticket/3', { body: {} }));
+    expect(fetchMock.mock.calls[0][0]).toBe('https://api.polyguard.ai/v2/ticket/3');
+  });
+
+  it('strips hop-by-hop response headers and set-cookie', async () => {
+    stubFetch({
+      headers: {
+        'content-type': 'application/json',
+        'set-cookie': 'session=abc; path=/',
+        'transfer-encoding': 'chunked',
+        'x-custom': 'visible',
+      },
+    });
+    const handler = createProxyHandler({ apiKey: 'pgk_live_x.y', apiServer: 'api.polyguard.ai' });
+    const res = await handler(makeRequest('POST', 'http://localhost/api/polyguard/v2/ticket/3', { body: {} }));
+    expect(res.headers.get('set-cookie')).toBeNull();
+    expect(res.headers.get('transfer-encoding')).toBeNull();
+    expect(res.headers.get('x-custom')).toBe('visible');
+  });
+});

package/src/server.js

@@ -0,0 +1,91 @@
+const DEFAULT_ALLOWED_PATHS = [
+  'POST /v2/ticket/',
+  'PUT /link/',
+  'GET /v2/preview/',
+];
+
+const HOP_BY_HOP = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+function isAllowed(method, pathname, allowedPaths) {
+  const upper = method.toUpperCase();
+  for (const rule of allowedPaths) {
+    const idx = rule.indexOf(' ');
+    if (idx < 0) continue;
+    const ruleMethod = rule.slice(0, idx).toUpperCase();
+    const rulePrefix = rule.slice(idx + 1);
+    if (ruleMethod === upper && pathname.startsWith(rulePrefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function createProxyHandler(options = {}) {
+  const { apiKey, apiServer = 'api.polyguard.ai', allowedPaths = DEFAULT_ALLOWED_PATHS, pathPrefix = '/api/polyguard' } = options;
+
+  if (!apiKey) {
+    throw new Error('createProxyHandler: apiKey is required');
+  }
+  if (!apiServer) {
+    throw new Error('createProxyHandler: apiServer is required');
+  }
+
+  return async function polyguardProxy(request) {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+    if (pathPrefix && pathname.startsWith(pathPrefix)) {
+      pathname = pathname.slice(pathPrefix.length) || '/';
+    }
+
+    if (!isAllowed(request.method, pathname, allowedPaths)) {
+      return new Response('Not Found', { status: 404 });
+    }
+
+    const targetUrl = `https://${apiServer}${pathname}${url.search}`;
+
+    const forwardHeaders = new Headers();
+    for (const [name, value] of request.headers) {
+      const lower = name.toLowerCase();
+      if (lower === 'x-pg-api-key' || lower === 'authorization') continue;
+      if (HOP_BY_HOP.has(lower)) continue;
+      if (lower === 'host') continue;
+      forwardHeaders.set(name, value);
+    }
+    forwardHeaders.set('x-pg-api-key', apiKey);
+
+    const init = {
+      method: request.method,
+      headers: forwardHeaders,
+      redirect: 'manual',
+    };
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      init.body = request.body;
+      init.duplex = 'half';
+    }
+
+    const upstream = await fetch(targetUrl, init);
+
+    const responseHeaders = new Headers();
+    for (const [name, value] of upstream.headers) {
+      const lower = name.toLowerCase();
+      if (HOP_BY_HOP.has(lower)) continue;
+      if (lower === 'set-cookie') continue;
+      responseHeaders.set(name, value);
+    }
+
+    return new Response(upstream.body, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: responseHeaders,
+    });
+  };
+}

package/src/ticketService.js

@@ -1,7 +1,11 @@
-export async function fetchTicket({ apiServer, appId, link_uuid, requiredProofs, scanType }) {
+export async function fetchTicket({ apiServer, proxyUrl, appId, link_uuid, requiredProofs, scanType }) {
+  const base = proxyUrl
+    ? proxyUrl.replace(/\/$/, '')
+    : `https://${apiServer}`;
+
   const ticketUrl = link_uuid
-    ? `https://${apiServer}/v2/ticket/${appId}/${link_uuid}`
-    : `https://${apiServer}/v2/ticket/${appId}`;
+    ? `${base}/v2/ticket/${appId}/${link_uuid}`
+    : `${base}/v2/ticket/${appId}`;
 
   const ticketRes = await fetch(ticketUrl, {
     method: 'POST',