@lit-protocol/vincent-app-sdk 1.0.0-1

package/dist/README.md

@@ -0,0 +1,215 @@
+# Vincent SDK
+
+## Installation
+
+```
+npm install @lit-protocol/vincent-app-sdk
+```
+
+## Usage
+
+# Client (Web)
+
+## VincentWebAppClient
+
+The Vincent Web App Client provides methods for managing user authentication, JWT tokens, and consent flows in Vincent applications.
+
+### Methods
+
+#### redirectToConsentPage()
+
+Redirects the user to the Vincent consent page to obtain authorization. Once the user has completed the vincent consent flow
+they will be redirected back to your app with a signed JWT that you can use to authenticate requests against your backend APIs
+
+- When a JWT is expired, you need to use this method to get a new JWT
+
+#### isLoginUri()
+
+Checks if the current window location contains a Vincent login JWT. You can use this method to know that you should update login state with the newly provided JWT
+
+- Returns: Boolean indicating if the URI contains a login JWT
+
+#### decodeVincentLoginJWT(expectedAudience)
+
+Decodes a Vincent login JWT. Performs basic sanity check but does not perform full verify() logic. You will want to run `verify()` from the jwt tools to verify the JWT is fully valid and not expired etc.
+
+- The expected audience is typically your app's domain -- it should be one of your valid redirectUri values from your Vincent app configuration
+
+- Returns: An object containing both the original JWT string and the decoded JWT object
+
+#### removeLoginJWTFromURI()
+
+Removes the login JWT parameter from the current URI. Call this after you have verified and stored the JWT for later usage.
+
+### Basic Usage
+
+```typescript
+import { getVincentWebAppClient, jwt } from '@lit-protocol/vincent-app-sdk';
+
+const { isExpired } = jwt;
+
+const vincentAppClient = getVincentWebAppClient({ appId: MY_APP_ID });
+// ... In your app logic:
+if (vincentAppClient.isLogin()) {
+  // Handle app logic for the user has just logged in
+  const { decoded, jwt } = vincentAppClient.decodeVincentLoginJWT(window.location.origin);
+  // Store `jwt` for later usage; the user is now logged in.
+} else {
+  // Handle app logic for the user is _already logged in_ (check for stored & unexpired JWT)
+
+  const jwt = localStorage.getItem('VINCENT_AUTH_JWT');
+  if (jwt && isExpired(jwt)) {
+    // User must re-log in
+    vincentAppClient.redirectToConsentPage({ redirectUri: window.location.href });
+  }
+
+  if (!jwt) {
+    // Handle app logic for the user is not yet logged in
+    vincentAppClient.redirectToConsentPage({ redirectUri: window.location.href });
+  }
+}
+```
+
+# Backend
+
+In your backend, you will have to verify the JWT to make sure the user has granted you the required permissions to act on their behalf.
+
+## VincentToolClient
+
+The Vincent Tool Client uses an ethers signer for your delegatee account to run Vincent Tools on behalf of your app users.
+
+This client will typically be used by an AI agent or your app backend service, as it requires a signer that conforms to the ethers v5 signer API, and with access to your delegatee account's private key to authenticate with the LIT network when executing the Vincent Tool.
+
+### Configuration
+
+```typescript
+interface VincentToolClientConfig {
+  ethersSigner: ethers.Signer; // An ethers v5 compatible signer
+  vincentToolCid: string; // The CID of the Vincent Tool to execute
+}
+```
+
+### Methods
+
+#### execute(params: VincentToolParams): Promise<ExecuteJsResponse>
+
+Executes a Vincent Tool with the provided parameters.
+
+- `params`: Record<string, unknown> - Parameters to pass to the Vincent Tool
+- Returns: Promise resolving to an ExecuteJsResponse from the LIT network
+
+### Tool execution
+
+```typescript
+import { getVincentToolClient } from '@lit-protocol/vincent-app-sdk';
+// Import the tool you want to execute
+import { bundledVincentTool as erc20BundledTool } from '@lit-protocol/vincent-tool-erc20-approval';
+
+// One of delegatee signers from your app's Vincent Dashboard
+const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY');
+
+// Initialize the Vincent Tool Client
+const toolClient = getVincentToolClient({
+  ethersSigner: delegateeSigner,
+  bundledVincentTool: erc20BundledTool,
+});
+const delegatorPkpEthAddress = '0x09182301238';
+
+const toolParams = {
+  // Fill with the params your tool needs
+};
+
+// Run precheck to see if tool should be executed
+const precheckResult = await client.precheck(toolParams, {
+  delegatorPkpEthAddress,
+});
+
+if (precheckResult.success === true) {
+  // Execute the Vincent Tool
+  const executeResult = await client.execute(toolParams, {
+    delegatorPkpEthAddress,
+  });
+
+  // ...tool has executed, you can check `executeResult` for details
+}
+```
+
+### Usage
+
+### Authentication
+
+A basic Express authentication middleware factory function is provided with the SDK.
+
+- Create an express middleware using `getAuthenticateUserExpressHandler()`
+- Once you have added the middleware to your route, use `authenticatedRequestHandler()` to provide
+  type-safe access to `req.user` in your downstream RequestHandler functions.
+- When defining your authenticated routes, use the `ExpressAuthHelpers` type to type your functions and function arguments.
+
+See getAuthenticateUserExpressHandler() documentation to see the source for the express authentication route handler
+
+```typescript
+import { expressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+const { authenticatedRequestHandler, getAuthenticateUserExpressHandler } = expressAuthHelpers;
+
+import type { ExpressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+
+const { ALLOWED_AUDIENCE } = process.env;
+
+const authenticateUserMiddleware = getAuthenticateUserExpressHandler(ALLOWED_AUDIENCE);
+
+// Define an authenticated route handler
+const getUserProfile = async (req: ExpressAuthHelpers['AuthenticatedRequest'], res: Response) => {
+  // Access authenticated user information
+  const { pkpAddress } = req.user;
+
+  // Fetch and return user data
+  const userData = await userRepository.findByAddress(pkpAddress);
+  res.json(userData);
+};
+
+// Use in Express route with authentication
+app.get('/profile', authenticateUser, authenticatedRequestHandler(getUserProfile));
+```
+
+## JWT Authentication
+
+### Overview
+
+The JWT authentication system in Vincent SDK allows for secure communication between user applications and Vincent Tools. JWTs are used to verify user consent and authorize tool executions.
+
+### Authentication Flow
+
+1. User initiates an action requiring Vincent Tool access
+2. Application redirects to the Vincent consent page using `VincentWebAppClient.redirectToConsentPage()`
+3. User provides consent for the requested tools/policies
+4. User is redirected back to the application with a JWT in the URL
+5. Application validates and stores the JWT using `VincentWebAppClient` methods
+6. JWT is used to authenticate with the app backend
+
+### JWT Structure
+
+Vincent JWTs contain:
+
+- User account identity information (pkpAddress and pkpPublicKey)
+- Expiration timestamp
+- Signature from the Vincent authorization service
+
+### Error Handling
+
+When JWT validation fails, descriptive error messages are thrown to help with troubleshooting.
+
+### Usage Notes
+
+- JWTs have an expiration time after which they are no longer valid
+- When a JWT expires, redirect the user to the consent page to obtain a new one using the `VincentWebAppClient`
+
+## Release
+
+Pre-requisites:
+
+- You will need a valid npm account with access to the `@lit-protocol` organization.
+- Run `pnpm vercel login` at sdk root to get a authentication token for vercel
+- Also you will need to fill the `.env` file with the vercel project and org ids for the [vincent-docs](https://vercel.com/lit-protocol/vincent-docs) project.
+
+Then run `pnpm release` on the repository root. It will prompt you to update the Vincent SDK version and then ask you to confirm the release.
+This process will also generate a `CHANGELOG.md` record with the changes for the release and update typedoc in vercel after publishing the SDK.

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lit-protocol/vincent-app-sdk",
+  "version": "0.0.7",
+  "description": "Vincent SDK for browser and backend",
+  "author": "Lit Protocol",
+  "license": "ISC",
+  "access": "public",
+  "packageManager": "pnpm@10.7.0",
+  "engines": {
+    "node": "^20.11.1",
+    "pnpm": "10.7.0"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "keywords": [
+    "jwt",
+    "authentication",
+    "sdk"
+  ],
+  "scripts": {
+    "type-tests": "./scripts/run-typecheck.sh",
+    "watch:type-tests": "chokidar 'src/**/*' --initial --await-write-finish --delay 100 --silent -c './scripts/run-typecheck.sh'",
+    "typecheck": "./scripts/precommit-check.sh"
+  },
+  "dependencies": {
+    "@lit-protocol/auth-helpers": "^7.0.9",
+    "@lit-protocol/constants": "^7.0.8",
+    "@lit-protocol/lit-node-client": "^7.0.8",
+    "@lit-protocol/vincent-tool-sdk": "workspace:*",
+    "@noble/secp256k1": "^2.2.3",
+    "did-jwt": "^8.0.8",
+    "ethers": "5.8.0",
+    "tslib": "^2.8.1",
+    "zod": "3.25.64"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/**/*",
+    "*.md"
+  ],
+  "devDependencies": {
+    "@lit-protocol/pkp-ethers": "^7.2.0",
+    "@lit-protocol/types": "^7.0.8",
+    "@types/express": "^5.0.1",
+    "chokidar-cli": "^3.0.0",
+    "live-server": "^1.2.2",
+    "typedoc": "0.27.9",
+    "typedoc-material-theme": "1.3.0",
+    "typedoc-plugin-extras": "^4.0.0",
+    "typedoc-plugin-zod": "^1.4.1",
+    "vercel": "^41.6.2"
+  },
+  "type": "commonjs"
+}

package/dist/src/app/app.d.ts

@@ -0,0 +1,9 @@
+import { VincentAppClientConfig, VincentWebAppClient } from './types';
+/** Create a new {@link VincentWebAppClient} instance.
+ *
+ * - `appId` is the numeric app ID displayed for your app on the Vincent Dashboard
+ *
+ * @category Vincent SDK API
+ * */
+export declare const getVincentWebAppClient: (appClientConfig: VincentAppClientConfig) => VincentWebAppClient;
+//# sourceMappingURL=app.d.ts.map

package/dist/src/app/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/app/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAgBjB;;;;;KAKK;AACL,eAAO,MAAM,sBAAsB,GACjC,iBAAiB,sBAAsB,KACtC,mBAmBF,CAAC"}

package/dist/src/app/app.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVincentWebAppClient = void 0;
+const internal_1 = require("./internal");
+const constants_1 = require("./constants");
+const { isLoginUri, composeConsentUrl, removeSearchParam, decodeVincentJWTFromUri } = internal_1.uriHelpers;
+const redirectToConsentPage = ({ appId, redirectUri, consentPageUrl, }) => window.open(composeConsentUrl(appId, redirectUri, consentPageUrl).toString(), '_self');
+/** Create a new {@link VincentWebAppClient} instance.
+ *
+ * - `appId` is the numeric app ID displayed for your app on the Vincent Dashboard
+ *
+ * @category Vincent SDK API
+ * */
+const getVincentWebAppClient = (appClientConfig) => {
+    const { appId } = appClientConfig;
+    return {
+        redirectToConsentPage: (redirectConsentPageConfig) => {
+            const { consentPageUrl, redirectUri } = redirectConsentPageConfig;
+            redirectToConsentPage({ appId, consentPageUrl, redirectUri });
+        },
+        isLogin: () => isLoginUri(window.location.href),
+        decodeVincentLoginJWT: (expectedAudience) => decodeVincentJWTFromUri(window.location.href, expectedAudience),
+        removeLoginJWTFromURI: () => {
+            const urlWithoutJWTSearchParam = removeSearchParam({
+                paramName: constants_1.JWT_URL_KEY,
+                uri: window.location.href,
+            });
+            window.history.replaceState({}, document.title, urlWithoutJWTSearchParam);
+        },
+    };
+};
+exports.getVincentWebAppClient = getVincentWebAppClient;
+//# sourceMappingURL=app.js.map

package/dist/src/app/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/app/app.ts"],"names":[],"mappings":";;;AAKA,yCAAwC;AACxC,2CAA0C;AAE1C,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,GAAG,qBAAU,CAAC;AAEjG,MAAM,qBAAqB,GAAG,CAAC,EAC7B,KAAK,EACL,WAAW,EACX,cAAc,GAKf,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;AAE7F;;;;;KAKK;AACE,MAAM,sBAAsB,GAAG,CACpC,eAAuC,EAClB,EAAE;IACvB,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC;IAElC,OAAO;QACL,qBAAqB,EAAE,CAAC,yBAA6D,EAAE,EAAE;YACvF,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,yBAAyB,CAAC;YAClE,qBAAqB,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/C,qBAAqB,EAAE,CAAC,gBAAwB,EAAE,EAAE,CAClD,uBAAuB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;QACjE,qBAAqB,EAAE,GAAG,EAAE;YAC1B,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;gBACjD,SAAS,EAAE,uBAAW;gBACtB,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;aAC1B,CAAC,CAAC;YACH,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;QAC5E,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AArBW,QAAA,sBAAsB,0BAqBjC"}

package/dist/src/app/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const PRODUCTION_VINCENT_DASHBOARD_URL = "https://dashboard.heyvincent.ai/";
+export declare const JWT_URL_KEY = "jwt";
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/app/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/app/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AACnF,eAAO,MAAM,WAAW,QAAQ,CAAC"}

package/dist/src/app/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JWT_URL_KEY = exports.PRODUCTION_VINCENT_DASHBOARD_URL = void 0;
+exports.PRODUCTION_VINCENT_DASHBOARD_URL = 'https://dashboard.heyvincent.ai/';
+exports.JWT_URL_KEY = 'jwt';
+//# sourceMappingURL=constants.js.map

package/dist/src/app/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/app/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,gCAAgC,GAAG,kCAAkC,CAAC;AACtE,QAAA,WAAW,GAAG,KAAK,CAAC"}

package/dist/src/app/index.d.ts

@@ -0,0 +1,3 @@
+import { getVincentWebAppClient } from './app';
+export { getVincentWebAppClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,OAAO,CAAC;AAE/C,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/src/app/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVincentWebAppClient = void 0;
+const app_1 = require("./app");
+Object.defineProperty(exports, "getVincentWebAppClient", { enumerable: true, get: function () { return app_1.getVincentWebAppClient; } });
+//# sourceMappingURL=index.js.map

package/dist/src/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/app/index.ts"],"names":[],"mappings":";;;AAAA,+BAA+C;AAEtC,uGAFA,4BAAsB,OAEA"}

package/dist/src/app/internal/index.d.ts

@@ -0,0 +1,3 @@
+import * as uriHelpers from './uriHelpers';
+export { uriHelpers };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/app/internal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app/internal/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/src/app/internal/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uriHelpers = void 0;
+const tslib_1 = require("tslib");
+const uriHelpers = tslib_1.__importStar(require("./uriHelpers"));
+exports.uriHelpers = uriHelpers;
+//# sourceMappingURL=index.js.map

package/dist/src/app/internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/internal/index.ts"],"names":[],"mappings":";;;;AAAA,iEAA2C;AAElC,gCAAU"}

package/dist/src/app/internal/uriHelpers.d.ts

@@ -0,0 +1,11 @@
+export declare const decodeVincentJWTFromUri: (uri: string, expectedAudience: string) => {
+    decodedJWT: import("../..").VincentJWT;
+    jwtStr: string;
+} | null;
+export declare const isLoginUri: (uri: string) => boolean;
+export declare function composeConsentUrl(appId: string, redirectUri: string, consentPageUrl?: string): URL;
+export declare const removeSearchParam: ({ paramName, uri, }: {
+    paramName: string;
+    uri: string;
+}) => string;
+//# sourceMappingURL=uriHelpers.d.ts.map

package/dist/src/app/internal/uriHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriHelpers.d.ts","sourceRoot":"","sources":["../../../../src/app/internal/uriHelpers.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,EAAE,kBAAkB,MAAM;;;QAS5E,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,YAKrC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,OAK5F;AAED,eAAO,MAAM,iBAAiB,GAAI,qBAG/B;IACD,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb,KAAG,MAKH,CAAC"}

package/dist/src/app/internal/uriHelpers.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeSearchParam = exports.isLoginUri = exports.decodeVincentJWTFromUri = void 0;
+exports.composeConsentUrl = composeConsentUrl;
+const constants_1 = require("../constants");
+const validate_1 = require("../../jwt/core/validate");
+const decodeVincentJWTFromUri = (uri, expectedAudience) => {
+    const url = new URL(uri);
+    const jwt = url.searchParams.get(constants_1.JWT_URL_KEY);
+    if (!jwt) {
+        return null;
+    }
+    return { decodedJWT: (0, validate_1.verifyJWT)(jwt, expectedAudience), jwtStr: jwt };
+};
+exports.decodeVincentJWTFromUri = decodeVincentJWTFromUri;
+const isLoginUri = (uri) => {
+    const url = new URL(uri);
+    const loginJwt = url.searchParams.get(constants_1.JWT_URL_KEY);
+    return !!loginJwt;
+};
+exports.isLoginUri = isLoginUri;
+function composeConsentUrl(appId, redirectUri, consentPageUrl) {
+    return new URL(`/appId/${appId}/consent?redirectUri=${redirectUri}`, consentPageUrl || constants_1.PRODUCTION_VINCENT_DASHBOARD_URL);
+}
+const removeSearchParam = ({ paramName, uri, }) => {
+    const url = new URL(uri);
+    url.searchParams.delete(paramName);
+    // Update the browser's history without reloading the page
+    return url.toString();
+};
+exports.removeSearchParam = removeSearchParam;
+//# sourceMappingURL=uriHelpers.js.map

package/dist/src/app/internal/uriHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriHelpers.js","sourceRoot":"","sources":["../../../../src/app/internal/uriHelpers.ts"],"names":[],"mappings":";;;AAqBA,8CAKC;AA1BD,4CAA6E;AAC7E,sDAAoD;AAE7C,MAAM,uBAAuB,GAAG,CAAC,GAAW,EAAE,gBAAwB,EAAE,EAAE;IAC/E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,uBAAW,CAAC,CAAC;IAE9C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,IAAA,oBAAS,EAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACvE,CAAC,CAAC;AATW,QAAA,uBAAuB,2BASlC;AAEK,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,EAAE;IACxC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,uBAAW,CAAC,CAAC;IAEnD,OAAO,CAAC,CAAC,QAAQ,CAAC;AACpB,CAAC,CAAC;AALW,QAAA,UAAU,cAKrB;AAEF,SAAgB,iBAAiB,CAAC,KAAa,EAAE,WAAmB,EAAE,cAAuB;IAC3F,OAAO,IAAI,GAAG,CACZ,UAAU,KAAK,wBAAwB,WAAW,EAAE,EACpD,cAAc,IAAI,4CAAgC,CACnD,CAAC;AACJ,CAAC;AAEM,MAAM,iBAAiB,GAAG,CAAC,EAChC,SAAS,EACT,GAAG,GAIJ,EAAU,EAAE;IACX,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,0DAA0D;IAC1D,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC,CAAC;AAXW,QAAA,iBAAiB,qBAW5B"}

package/dist/src/app/types.d.ts

@@ -0,0 +1,119 @@
+import { VincentJWT } from '../jwt/types';
+/**
+ * @inline
+ * @hidden
+ */
+export interface VincentAppClientConfig {
+    appId: string;
+}
+/**
+ * @inline
+ * @hidden
+ */
+export interface RedirectToVincentConsentPageParams {
+    redirectUri: string;
+    /** This only needs to be provided for local development with the entire stack
+     * @hidden
+     * */
+    consentPageUrl?: string;
+}
+/**
+ * The Vincent Web Application Client is used in web apps to handle interactions with the Vincent app portal.
+ *
+ * - Consent page redirection
+ * - Authentication helpers that are browser specific
+ *
+ * @category Vincent Web App
+ */
+export interface VincentWebAppClient {
+    /**
+     * Redirects the user to the Vincent consent page.
+     *
+     * If the user approves your app permissions, they will be redirected back to the `redirectUri`.
+     *
+     * Use {@link VincentWebAppClient.isLogin} to detect if a user has just opened your app via the consent page
+     *
+     * Use {@link VincentWebAppClient.decodeVincentLoginJWT} to decode and verify the {@link VincentJWT} from the page URI, and store it for later usage
+     *
+     * NOTE: You must register the `redirectUri` on your Vincent app for it to be considered a valid redirect target
+     *
+     * @example
+     * ```typescript
+     *   import { getVincentWebAppClient } from '@lit-protocol/vincent-app-sdk';
+     *
+     *   const vincentAppClient = getVincentWebAppClient({ appId: MY_APP_ID });
+     *   // ... In your app logic:
+     *   if(vincentAppClient.isLogin()) {
+     *     // Handle app logic for the user has just logged in
+     *     const { decoded, jwt } = vincentAppClient.decodeVincentLoginJWT(EXPECTED_AUDIENCE);
+     *     // Store `jwt` for later usage; the user is now logged in.
+     *   } else {
+     *     // Handle app logic for the user is already logged in (check for stored & unexpired JWT)
+     *     // ...
+     *
+     *     // Handle app logic for the user is not yet logged in
+     *    vincentAppClient.redirectToConsentPage({ redirectUri: window.location.href });
+     *   }
+     * ```
+     * @function
+     * @inline
+     */
+    redirectToConsentPage: (redirectConfig: RedirectToVincentConsentPageParams) => void;
+    /**
+     * Determines whether the current window location is a login URI associated with Vincent
+  
+     * You can use this to detect if a user is loading your app as a result of approving permissions
+     * on the Vincent consent page -- e.g. they just logged in
+     *
+     * See: {@link VincentWebAppClient.redirectToConsentPage} for example usage
+     *
+     * @function
+     * @inline
+     * @returns `true` if the current window URI is a login URI, otherwise `false`.
+     */
+    isLogin: () => boolean;
+    /**
+     * Extracts a decoded/parsed Vincent JWT (JSON Web Token) from the current window location
+     *
+     * The token is verified as part of this process; if the token is invalid or expired, this method will throw.
+     *
+     * See: {@link VincentWebAppClient.redirectToConsentPage} for example usage
+     *
+     * @param { string } expectedAudience Provide a valid `redirectUri` for your app; this is typically your app's origin
+     * @function
+     * @inline
+     * @returns {decodedJWT: VincentJWT; jwtStr: string | null} `null` if no JWT is found, otherwise both the decoded jwt and the original JWT string is returned
+     * @throws {Error} If there was a JWT in the page URL, but it was invalid / could not be verified
+     */
+    decodeVincentLoginJWT: (expectedAudience: string) => {
+        decodedJWT: VincentJWT;
+        jwtStr: string;
+    } | null;
+    /**
+     * Removes the Vincent login JWT from the current window URI.
+     *
+     * This is useful for cleaning up the URL after decoding and storing the JWT,
+     * ensuring the redirect URL looks clean for the user and no sensitive information
+     * is exposed in the URI.
+     *
+     * @example
+     * ```typescript
+     * import { getVincentWebAppClient } from '@lit-protocol/vincent-app-sdk';
+     *
+     * const vincentAppClient = getVincentWebAppClient({ appId: MY_APP_ID });
+     *
+     * if (vincentAppClient.isLogin()) {
+     *   const { decodedJWT, jwtStr } = vincentAppClient.decodeVincentLoginJWT();
+     *   // Store the JWT and use it for authentication
+     *
+     *   // Now we can remove the JWT from the URL searchParams
+     *   vincentAppClient.removeLoginJWTFromURI();
+     * }
+     * ```
+     *
+     * @function
+     * @inline
+     */
+    removeLoginJWTFromURI: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/app/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/app/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,kCAAkC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB;;SAEK;IACL,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,qBAAqB,EAAE,CAAC,cAAc,EAAE,kCAAkC,KAAK,IAAI,CAAC;IAEpF;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC;IAEvB;;;;;;;;;;;;OAYG;IACH,qBAAqB,EAAE,CACrB,gBAAgB,EAAE,MAAM,KACrB;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAEvD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,qBAAqB,EAAE,MAAM,IAAI,CAAC;CACnC"}

package/dist/src/app/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src/app/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/app/types.ts"],"names":[],"mappings":""}

package/dist/src/express-authentication-middleware/express.d.ts

@@ -0,0 +1,79 @@
+import type { NextFunction, Request, Response } from 'express';
+import { AuthenticatedRequestHandler } from './types';
+/**
+ * Higher-order helper function to enforce authentication on a request handler and assert the type of `Request` that is
+ * passed into your authenticated Express routes.
+ *
+ * This function takes an `AuthenticatedRequestHandler` and returns a new request handler
+ * that verifies that the request has a 'user' property with the correct shape on it before calling the original handler.
+ * If the `req.user` property isn't the correct shape, it sends a `401 Unauthorized` response to the client.
+ *
+ * NOTE: This does not verify signatures or any other content -- use `getAuthenticateUserExpressHandler` to create a
+ * middleware that does those things and ensure that your routes use it.
+ *
+ * See [express.js documentation](https://expressjs.com/en/guide/writing-middleware.html) for details on writing your route handler
+ * @example
+ * ```typescript
+ * import { expressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+ * const { authenticatedRequestHandler, getAuthenticateUserExpressHandler } = expressAuthHelpers;
+ *
+ * import type { ExpressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+ *
+ * // Define an authenticated route handler
+ * const getUserProfile = async (req: ExpressAuthHelpers['AuthenticatedRequest'], res: Response) => {
+ *   // Access authenticated user information
+ *   const { pkpAddress } = req.user;
+ *
+ *   // Fetch and return user data
+ *   const userData = await userRepository.findByAddress(pkpAddress);
+ *   res.json(userData);
+ * };
+ *
+ * // Use in Express route with authentication
+ * app.get('/profile', authenticateUser, authenticatedRequestHandler(getUserProfile));
+ * ```
+ */
+export declare const authenticatedRequestHandler: (handler: AuthenticatedRequestHandler) => (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * Creates an Express middleware function to authenticate a user using a JWT token.
+ *
+ * This middleware checks the `Authorization` header for a Bearer token, verifies the token, and checks its audience.
+ * If the token is valid, it attaches the user information (decoded JWT, raw token, and PKP address) to the request object as `req.user`.
+ * If the token is missing or invalid, it returns a 401 Unauthorized response with an error message.
+ *
+ * NOTE: Wrap your route handler functions with `authenticatedRequestHandler()` to assert the type of `Request` and to
+ * ensure that `req.user` was correctly set before your route handler is run.
+ *
+ * See [express.js documentation](https://expressjs.com/en/guide/writing-middleware.html) for details on writing your route handler
+ *
+ * @example
+ * ```typescript
+ * import { expressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+ * const { authenticatedRequestHandler, getAuthenticateUserExpressHandler } = expressAuthHelpers;
+ *
+ * import type { ExpressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+ *
+ * // In your environment configuration
+ * const ALLOWED_AUDIENCE = 'https://yourapp.example.com';
+ *
+ * // Create the authentication middleware
+ * const authenticateUser = getAuthenticateUserExpressHandler(ALLOWED_AUDIENCE);
+ *
+ * // Define a handler that requires authentication
+ * const getProtectedResource = (req: ExpressAuthHelpers['AuthenticatedRequest'], res: Response) => {
+ *   // The request is now authenticated
+ *   // No need for type casting as the handler is properly typed
+ *   const { pkpAddress } = req.user;
+ *   res.json({ message: `Hello, user with PKP address ${pkpAddress}` });
+ * };
+ *
+ * // Apply to routes that require authentication by using authenticatedRequestHandler
+ * app.get('/protected-resource', authenticateUser, authenticatedRequestHandler(getProtectedResource));
+ * ```
+ *
+ * You can see the source for `getAuthenticateUserExpressHandler()` below; use this as a reference to implement
+ * your own midddleware/authentication for other frameworks! Pull requests are welcome.
+ * {@includeCode ./express.ts#expressHandlerTSDocExample}
+ */
+export declare const getAuthenticateUserExpressHandler: (allowedAudience: string) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=express.d.ts.map

package/dist/src/express-authentication-middleware/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../../src/express-authentication-middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAK/D,OAAO,EAAwB,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAsB5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,2BAA2B,GACrC,SAAS,2BAA2B,MAAM,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,yBAOzF,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,eAAO,MAAM,iCAAiC,GAC3C,iBAAiB,MAAM,MAAY,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,kBAmClF,CAAC"}