@agnostack/verifyd 2.4.1-alpha.1 → 2.5.0-alpha.2

package/README.md

@@ -1,95 +1,106 @@
 # @agnostack/verifyd
+
 ![Test](https://github.com/agnostack/verifyd/actions/workflows/test.yml/badge.svg)
+
+Cryptographic verification and encryption library for agnoStack platform integrations. Provides ECDH key exchange, HMAC verification, AES-GCM encryption/decryption, and related utilities.
+
 ## Installation
 
 ```bash
 yarn add @agnostack/verifyd
-# npm install @agnostack/verifyd
+# or
+npm install @agnostack/verifyd
 ```
 
-## Quickstart - TODO
+## Export Paths
 
-TODO!!!!!!! This readme needs to be updated to show how to use verifyd!
+| Path | Format | Use Case |
+|------|--------|----------|
+| `@agnostack/verifyd` | CJS | Default — works everywhere (Node.js, bundlers) |
+| `@agnostack/verifyd/esm` | ESM | Tree-shakeable — for modern bundlers (Vite, esbuild, Webpack 5+) |
+| `@agnostack/verifyd/react` | CJS | React hooks (`useVerification`) |
+| `@agnostack/verifyd/react/esm` | ESM | Tree-shakeable React hooks |
+| `@agnostack/verifyd/external` | UMD | Script tag / CDN usage |
 
-Inside of `next.config.js`, add the following:
-```js
-const { withShopify } = require('@agnostack/verifyd')
+### Tree-Shaking (ESM)
 
-const manifestTemplate = require('./manifestTemplate.json')
+The `/esm` subpaths enable bundlers to eliminate unused code. For example, importing only `{ WebCrypto }` from `@agnostack/verifyd/esm` produces a ~62% smaller bundle compared to the CJS export (unused utilities like `display.js` are fully eliminated).
 
-const nextConfig = withShopify({
-  zendesk: { manifestTemplate },
-})
+```js
+// CJS (no tree-shaking)
+import { WebCrypto } from '@agnostack/verifyd'
 
+// ESM (tree-shakeable)
+import { WebCrypto } from '@agnostack/verifyd/esm'
 ```
 
-Also, create an api route (`pages/api/apps.js`) containing the following:
-```js
-import getConfig from 'next/config'
-import { withShopify } from '@agnostack/verifyd'
+## Web Crypto Resolution
 
-const { serverRuntimeConfig } = getConfig() ?? {}
+`WebCrypto` uses a layered resolution strategy to find a Web Crypto API implementation:
 
-export default withShopify(serverRuntimeConfig)
-```
+1. **Constructor-injected** — if you pass `{ crypto }` to `new WebCrypto({ crypto })`, that's used directly
+2. **`globalThis.crypto.subtle`** — native Web Crypto, available in all modern browsers and Node.js 18+
+3. **`isomorphic-webcrypto`** polyfill — fallback for older Node.js environments (see below)
+4. **Node.js `crypto` module** — last resort fallback
+
+Each stage exits early on success — later fallbacks are only reached if all earlier checks fail.
+
+### `isomorphic-webcrypto` (Optional Peer Dependency)
+
+`isomorphic-webcrypto` is an **optional** peer dependency. Most consumers do not need to install it:
+
+- **Browser**: `globalThis.crypto.subtle` is always available natively — the polyfill is never reached
+- **Node.js 18+**: `globalThis.crypto.subtle` is available natively — the polyfill is never reached
+- **Node.js <15**: `globalThis.crypto` is not available — install the polyfill if you are not passing `crypto` to the `WebCrypto` constructor:
 
+  ```bash
+  yarn add isomorphic-webcrypto
+  # or
+  npm install isomorphic-webcrypto
+  ```
 
-## Alternate Option #1
+> **Note**: `isomorphic-webcrypto` transitively pulls in `expo` and `react-native` as optional dependencies, which is why it is not included as a direct dependency of this package.
+
+## Usage
+
+### WebCrypto — Encryption / Decryption
 
-Inside of `next.config.js`, add the following:
 ```js
-const { withPlugins } = require('@agnostack/next-plugins')
-const { withShopify } = require('@agnostack/verifyd')
-
-const manifest = require('./manifest.json')
-
-const nextPlugins = [{
-  [withShopify]: {
-    manifestTemplate: manifest,
-    /* NOTE: add optionale below
-    apiRoute: '/api/my-custom-api-json-route', // (defaults to /api/apps)
-    interactive: true, // (defaults to false)
-    data: {
-      plan: 'silver',
-      app_id: 123,
-      installation_id: 12434234,
-      my_token: 'myValue',
-      parameters: {
-        someToken: 'fksjdhfb231435',
-        someSecret: 123,
-      },
-    },
-    routes: {
-      background: '/background'
-      user_sidebar: '/noTicket',
-      organization_sidebar: '/noTicket',
-      ticket_sidebar: '/ticket',
-      new_ticket_sidebar: '/ticket',
-    },
-    */
-  },
-}]
-
-const nextConfig = withPlugins({
-  /* NOTE: standard nextConfig goes in here
-  reactStrictMode: true,
-  experimental: {
-    esmExternals: false,
-  },
-  */
-}, [nextPlugins])
+import { WebCrypto } from '@agnostack/verifyd'
+
+// Option 1: Let WebCrypto resolve crypto automatically
+const webCrypto = new WebCrypto()
+
+// Option 2: Pass native crypto explicitly (recommended for known environments)
+const webCrypto = new WebCrypto({ crypto: globalThis.crypto })
+
+// Encrypt
+const encrypted = await webCrypto.encryptMessage('secret data', cryptoKey)
 
+// Decrypt
+const decrypted = await webCrypto.decryptMessage(encrypted, cryptoKey)
 ```
 
-Also, create an api route (`pages/api/apps.js`) containing the following:
+### Verification Helpers (Server-Side)
+
 ```js
-import getConfig from 'next/config'
-import { withShopify } from '@agnostack/verifyd'
+import { getVerificationHelpers } from '@agnostack/verifyd'
+
+const {
+  generateStorableKeyPairs,
+  prepareVerificationRequest,
+  processVerificationResponse,
+} = getVerificationHelpers()
+```
 
-const { publicRuntimeConfig } = getConfig() ?? {}
+### React Hook
+
+```js
+import { useVerification } from '@agnostack/verifyd/react'
 
-export default withShopify(publicRuntimeConfig)
+const { verify, isVerified, error } = useVerification(options)
 ```
 
+---
 
 _Contact [Adam Grohs](https://agnostack.com/founding-team/adam-grohs) @ [agnoStack](https://agnostack.com/) for any questions._

package/dist/esm/lib/index.js

@@ -0,0 +1,3 @@
+export * from '../shared';
+export * from './utils';
+export * from './verification';

package/dist/esm/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/lib/utils/index.js

@@ -0,0 +1 @@
+export * from './rawbody';

package/dist/esm/lib/utils/rawbody.js

@@ -0,0 +1,35 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { lowercase } from '../../shared/display';
+const getChunkedRawBody = (req) => __awaiter(void 0, void 0, void 0, function* () {
+    if (req === null || req === void 0 ? void 0 : req.rawBody) {
+        return req.rawBody;
+    }
+    // TODO: move to req.text() after next 13.5: https://github.com/vercel/next.js/discussions/13405
+    try {
+        const _getRawBody = (yield import('raw-body')).default;
+        if (!req.method || (lowercase(req.method) === 'get')) {
+            return undefined;
+        }
+        return _getRawBody(req).then((_rawBody) => _rawBody === null || _rawBody === void 0 ? void 0 : _rawBody.toString());
+    }
+    catch (error) {
+        console.error(`Failed to import 'raw-body', please ensure the dependency is installed`);
+        throw error;
+    }
+});
+// TODO: explore returning mutated request object adding on req.rawBody??
+export const ensureRawBody = (req) => __awaiter(void 0, void 0, void 0, function* () {
+    return (getChunkedRawBody(req)
+        .catch((error) => {
+        console.error(`Error getting raw body for '${req === null || req === void 0 ? void 0 : req.url}'`, error);
+        throw error;
+    }));
+});

package/dist/esm/lib/verification.js

@@ -0,0 +1,94 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { objectToSortedString, ensureString, safeParse, isTrue, } from '../shared/display';
+import { normalizeURIParts, getRequestMethod, VERIFYD_HEADERS, } from '../shared/request';
+import { VerificationError } from '../shared/errors';
+import { WebCrypto } from '../shared/WebCrypto';
+import { ensureRawBody } from './utils';
+export const generateStorableKeyPairs = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* ({ crypto: _crypto, util: _util } = {}) {
+    const webCrypto = new WebCrypto({ crypto: _crypto, util: _util });
+    const sharedKeyPair = yield webCrypto.generateKeyPair();
+    return webCrypto.getStorableKeyPair({
+        publicKey: sharedKeyPair.publicKey,
+        privateKey: sharedKeyPair.privateKey,
+    });
+});
+export const getVerificationHelpers = ({ keyPairs, util: _util, crypto: _crypto, DISABLE_RECRYPTION, } = { keyPairs: {} }) => {
+    const webCrypto = new WebCrypto({ crypto: _crypto, util: _util });
+    return (req, params) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        const { [VERIFYD_HEADERS.PUBLIC_KEY]: _apiKey, [VERIFYD_HEADERS.PUBLIC_KEY.toLowerCase()]: apiKey = _apiKey, [VERIFYD_HEADERS.EPHEMERAL_KEY]: _ephemeralPublicKey, [VERIFYD_HEADERS.EPHEMERAL_KEY.toLowerCase()]: ephemeralPublicKey = _ephemeralPublicKey, [VERIFYD_HEADERS.AUTHORIZATION_TIMESTAMP]: _customAuthTimestamp, [VERIFYD_HEADERS.AUTHORIZATION_TIMESTAMP.toLowerCase()]: customAuthTimestamp = _customAuthTimestamp, [VERIFYD_HEADERS.AUTHORIZATION]: _customAuth, [VERIFYD_HEADERS.AUTHORIZATION.toLowerCase()]: customAuth = _customAuth, } = (_a = req.headers) !== null && _a !== void 0 ? _a : {};
+        const { uri: _uri, disableRecryption: _disableRecryption } = params !== null && params !== void 0 ? params : {};
+        const uri = _uri !== null && _uri !== void 0 ? _uri : req.url;
+        const disableRecryption = isTrue(DISABLE_RECRYPTION) || isTrue(_disableRecryption);
+        let isVerifiable = false;
+        try {
+            const [authProtocol, authSignature] = ensureString(customAuth).split(' ');
+            isVerifiable = isTrue(apiKey &&
+                ephemeralPublicKey &&
+                customAuthTimestamp &&
+                authSignature &&
+                (authProtocol === 'HMAC-SHA256') &&
+                (keyPairs === null || keyPairs === void 0 ? void 0 : keyPairs.shared));
+            let verificationKeys;
+            const rawBody = yield ensureRawBody(req);
+            // NOTE: requestBody should be wind up decrypted when isVerifiable (unless disableRecryption, then will pass through)
+            let requestBody = safeParse(rawBody);
+            // TEMP!!! remove isVerifiable check once web widget moved to react
+            if (isVerifiable) {
+                if (!apiKey ||
+                    !ephemeralPublicKey ||
+                    !customAuthTimestamp ||
+                    !authSignature ||
+                    (authProtocol !== 'HMAC-SHA256') ||
+                    !(keyPairs === null || keyPairs === void 0 ? void 0 : keyPairs.shared) ||
+                    (apiKey !== keyPairs.shared.publicKey)) {
+                    throw new VerificationError('Invalid or missing authorization', { code: 401 });
+                }
+                verificationKeys = yield webCrypto.getVerificationKeys({
+                    publicKey: ephemeralPublicKey,
+                    privateKey: keyPairs.shared.privateKey,
+                });
+                if (!verificationKeys) {
+                    throw new VerificationError('Invalid or missing verification', { code: 412 });
+                }
+                const verificationPayload = objectToSortedString(Object.assign({ method: getRequestMethod(rawBody, req.method), timestamp: customAuthTimestamp, body: requestBody }, normalizeURIParts(uri)));
+                const isValid = yield webCrypto.verifyHMAC(verificationPayload, verificationKeys.derivedHMACKey, authSignature);
+                if (!isValid) {
+                    throw new VerificationError('Invalid or missing verification', { code: 403 });
+                }
+                if (!disableRecryption && requestBody) {
+                    try {
+                        const decryptedMessage = yield webCrypto.decryptMessage(requestBody, verificationKeys.derivedSecretKey);
+                        requestBody = safeParse(decryptedMessage);
+                    }
+                    catch (_b) {
+                        throw new VerificationError('Error decrypting request', { code: 400 });
+                    }
+                }
+            }
+            const processResponse = (response) => __awaiter(void 0, void 0, void 0, function* () {
+                if (disableRecryption || !response || !isVerifiable || !(verificationKeys === null || verificationKeys === void 0 ? void 0 : verificationKeys.derivedSecretKey)) {
+                    return response;
+                }
+                return webCrypto.encryptMessage(JSON.stringify(response), verificationKeys.derivedSecretKey);
+            });
+            return { rawBody, requestBody, processResponse };
+        }
+        catch (error) {
+            console.error(`Error handling request verification for '${uri}'`, {
+                error,
+                isVerifiable,
+                disableRecryption,
+            });
+            throw error;
+        }
+    });
+};

package/dist/esm/react/hooks/index.js

@@ -0,0 +1 @@
+export * from './useVerification';

package/dist/esm/react/hooks/useVerification.js

@@ -0,0 +1,47 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { useState } from 'react';
+import { getVerificationKeysData, prepareVerificationRequest, processVerificationResponse, } from '../../shared/verification';
+export const useVerification = (_a = {}) => {
+    var { publicKey, disableRecryption } = _a, params = __rest(_a, ["publicKey", "disableRecryption"]);
+    const [keysData, setKeysData] = useState();
+    const ensureKeysData = () => __awaiter(void 0, void 0, void 0, function* () {
+        const _keysData = keysData !== null && keysData !== void 0 ? keysData : (yield getVerificationKeysData(publicKey, params));
+        if (_keysData && !keysData) {
+            setKeysData(_keysData);
+        }
+        return _keysData;
+    });
+    const prepareVerification = (requestPath, requestOptions) => __awaiter(void 0, void 0, void 0, function* () {
+        const _keysData = yield ensureKeysData();
+        const _prepareVerification = prepareVerificationRequest({ disableRecryption, keysData: _keysData });
+        return _prepareVerification(requestPath, requestOptions);
+    });
+    const processResponse = (encryptedResponse, derivedSecretKey) => __awaiter(void 0, void 0, void 0, function* () {
+        const _keysData = yield ensureKeysData();
+        const _processResponse = processVerificationResponse({ disableRecryption, keysData: _keysData });
+        return _processResponse(encryptedResponse, derivedSecretKey);
+    });
+    return {
+        prepareVerification,
+        processResponse,
+    };
+};

package/dist/esm/react/index.js

@@ -0,0 +1,2 @@
+export * from '../shared/request'; // HMMMM: why cant we export WebCrypto class??
+export * from './hooks';