@keyringnetwork/keyring-connect-sdk 1.0.0 → 1.0.2

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-import { ExtensionConfig, ExtensionState } from './types';
+import { ExtensionSDKConfig, ExtensionState } from './types';
 /**
  * Class for interacting with the Keyring Connect browser extension
  */
@@ -7,7 +7,7 @@ export declare class KeyringConnect {
      * Launch the Keyring Connect Extension with the provided configuration
      * @note This will throw an error if the extension is not installed
      */
-    static launchExtension(data: ExtensionConfig): Promise<void>;
+    static launchExtension(data: ExtensionSDKConfig): Promise<void>;
     /**
      * Check if Keyring Connect Extension is installed and ready to use
      */
@@ -16,4 +16,7 @@ export declare class KeyringConnect {
      * Get the current state of the Keyring Connect Extension to allow for UI updates
      */
     static getExtensionState(): Promise<ExtensionState>;
+    private static validateClientConfig;
+    private static validateProofConfig;
+    private static convertToLaunchConfig;
 }

package/dist/main.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringConnect = void 0;
+const jwt_decode_1 = require("jwt-decode");
 const types_1 = require("./types");
 /**
  * Class for interacting with the Keyring Connect browser extension
@@ -21,12 +22,28 @@ class KeyringConnect {
      */
     static launchExtension(data) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const keyringConnectAvailable = yield this.isKeyringConnectInstalled();
             if (!keyringConnectAvailable) {
                 throw new Error('Keyring Connect is not installed');
             }
+            this.validateClientConfig(data);
+            this.validateProofConfig(data);
+            let launchConfig = this.convertToLaunchConfig(data);
+            if ((_a = data.krn_config) === null || _a === void 0 ? void 0 : _a.auth0_id_token) {
+                try {
+                    const decodedJwt = (0, jwt_decode_1.jwtDecode)(data.krn_config.auth0_id_token);
+                    if (!decodedJwt) {
+                        throw new Error('Failed to decode auth token');
+                    }
+                    launchConfig.auth_user = Object.assign(Object.assign({}, decodedJwt), { id_token: data.krn_config.auth0_id_token });
+                }
+                catch (error) {
+                    throw new Error('Invalid auth token provided');
+                }
+            }
             console.log('launching keyring connect');
-            window.postMessage({ type: types_1.EVENT_ACTIONS.LAUNCH_KEYRING_CONNECT, data }, '*');
+            window.postMessage({ type: types_1.EVENT_ACTIONS.LAUNCH_KEYRING_CONNECT, data: launchConfig }, '*');
         });
     }
     /**
@@ -61,5 +78,51 @@ class KeyringConnect {
             });
         });
     }
+    static validateClientConfig(config) {
+        if (!config.name) {
+            throw new Error('Name is required');
+        }
+        if (!config.app_url) {
+            throw new Error('App URL is required');
+        }
+        if (!config.logo_url) {
+            throw new Error('Logo URL is required');
+        }
+        if (!config.policy_id) {
+            throw new Error('Policy ID is required');
+        }
+    }
+    static validateProofConfig(config) {
+        var _a;
+        if ((_a = config.proof_config) === null || _a === void 0 ? void 0 : _a.datasource) {
+            if (config.proof_config.datasource.proof_sources.length === 0) {
+                throw new Error('At least one proof source is required');
+            }
+            if (!config.proof_config.datasource.proof_sources.some((source) => source.claims.length > 0)) {
+                throw new Error('At least one claim is required per proof source');
+            }
+        }
+    }
+    static convertToLaunchConfig(config) {
+        var _a;
+        const launchConfig = {
+            client: {
+                client_name: config.name,
+                client_app_url: config.app_url,
+                client_logo_url: config.logo_url,
+                client_policy_id: config.policy_id,
+                client_entity_id: (_a = config.krn_config) === null || _a === void 0 ? void 0 : _a.entity_id,
+            },
+            krn_config: config.krn_config
+                ? {
+                    onboarding_api_url: config.krn_config.onboarding_api_url,
+                    datastore_api_url: config.krn_config.datastore_api_url,
+                    analytics_api_url: config.krn_config.analytics_api_url,
+                }
+                : undefined,
+            proof_config: config.proof_config,
+        };
+        return launchConfig;
+    }
 }
 exports.KeyringConnect = KeyringConnect;

package/dist/types.d.ts

@@ -3,58 +3,66 @@ export declare enum EVENT_ACTIONS {
     GET_STATUS = "GET_STATUS",
     KEYRING_CONNECT_STATUS = "KEYRING_CONNECT_STATUS"
 }
-export type ExtensionConfig = {
+export type ExtensionSDKConfig = {
+    /**
+     * The name of the client.
+     */
+    name: string;
+    /**
+     * The URL of the client app which the chrome extension will communicate with.
+     */
+    app_url: string;
+    /**
+     * The URL of the client logo.
+     */
+    logo_url: string;
+    /**
+     * The policy ID of the client.
+     */
+    policy_id: number;
+    /**
+     * Additional configuration to customize the extension's verification process.
+     * @note should be used with caution as strict validation is applied to the proof config.
+     */
+    proof_config?: {
+        datasource: DataSource;
+        entity_type?: string;
+    };
+    /**
+     * Keyring Network configuration for the extension.
+     * @note this is meant to be used for internal testing and development purposes.
+     */
+    krn_config?: {
+        onboarding_api_url?: string;
+        datastore_api_url?: string;
+        analytics_api_url?: string;
+        auth0_id_token?: string;
+        entity_id?: string;
+    };
+};
+export type ExtensionLaunchConfig = {
     client: {
-        /**
-         * The name of the client.
-         */
         client_name: string;
-        /**
-         * The URL of the client app which the chrome extension will communicate with.
-         */
         client_app_url: string;
-        /**
-         * The URL of the client logo.
-         */
         client_logo_url: string;
-        /**
-         * The policy ID of the client.
-         */
         client_policy_id: number;
-        /**
-         * The entity ID of the client.
-         */
         client_entity_id?: string;
     };
     proof_config?: {
-        /**
-         * The data source to be used for the proof.
-         */
         datasource: DataSource;
-        /**
-         * The entity type to be used for the proof.
-         */
-        entity_type: string;
+        entity_type?: string;
     };
     krn_config?: {
-        /**
-         * The URL of the onboarding API.
-         */
         onboarding_api_url?: string;
-        /**
-         * The URL of the datastore API.
-         */
         datastore_api_url?: string;
-        /**
-         * The URL of the analytics API.
-         */
         analytics_api_url?: string;
     };
+    auth_user?: any;
 };
 export type ExtensionStatus = 'idle' | 'mounted' | 'proving' | 'prove_success' | 'error';
 export type AttestationStatus = 'onboarding_required' | 'onboarding_pending' | 'attestation_ready' | 'non_compliant';
 export type CredentialStatus = 'expired' | 'valid' | 'none';
-export type UserState = {
+export type User = {
     /**
      * Off-chain attestation status.
      */
@@ -80,7 +88,7 @@ export interface ExtensionState {
     status: ExtensionStatus;
     manifest?: any;
     error?: string;
-    user?: UserState;
+    user?: User;
 }
 export interface DataSource {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyringnetwork/keyring-connect-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "An SDK for interacting with Keyring Connect browser extension",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,5 +17,8 @@
   "devDependencies": {
     "ts-node": "^10.9.2",
     "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "jwt-decode": "^4.0.0"
   }
 }

package/readme.md

@@ -2,7 +2,6 @@
 
 A TypeScript/JavaScript SDK for integrating with the Keyring Connect browser extension. This SDK enables seamless interaction with the Keyring Connect extension for user verification and attestation.
 
-
 ## Installation
 
 ```bash
@@ -27,16 +26,20 @@ import { KeyringConnect } from '@keyringnetwork/keyring-connect-sdk';
 
 ```typescript
 const extensionConfig = {
-  client: {
-    client_name: 'My App',
-    client_app_url: 'https://myapp.com',
-    client_logo_url: 'https://myapp.com/logo.png',
-    client_policy_id: 123,
-    client_entity_id: '123',
-  },
+  name: 'My App',
+  app_url: 'https://myapp.com',
+  logo_url: 'https://myapp.com/logo.png',
+  policy_id: 123,
 };
+
 try {
-  await KeyringConnect.launchExtension(extensionConfig);
+  const isInstalled = await KeyringConnect.isKeyringConnectInstalled();
+
+  if (isInstalled) {
+    await KeyringConnect.launchExtension(extensionConfig);
+  } else {
+    // show UI to install extension
+  }
 } catch (error) {
   console.error('Failed to launch Keyring Connect:', error);
 }
@@ -45,14 +48,14 @@ try {
 ### Monitor Extension Status
 
 ```typescript
-export interface ExtensionStatusData {
-  status: ExtensionStatus;
+export interface ExtensionState {
+  status: 'idle' | 'mounted' | 'proving' | 'prove_success' | 'error';
   manifest?: any;
-  error?: string;
-  user?: UserState;
+  error?: string; // error message, only if status is 'error'
+  user?: User;
 }
 
-const status = await KeyringConnect.getExtensionState();
+const extensionState = await KeyringConnect.getExtensionState();
 ```
 
 ## API Reference
@@ -61,47 +64,18 @@ const status = await KeyringConnect.getExtensionState();
 
 > Full type definitions can be found in our [types.ts](https://github.com/Keyring-Network/keyring-connect/blob/master/keyring-connect-sdk/src/types.ts)
 
-
-#### ExtensionConfig
-
-```typescript
-type ExtensionConfig = {
-  client: {
-    client_name: string; // Name of your application
-    client_app_url: string; // Your application's URL
-    client_logo_url: string; // Your application's logo URL
-    client_policy_id: number; // Your Keyring policy ID
-    client_entity_id?: string; // Your user's entity ID
-  };
-  proof_config?: {
-    datasource: DataSource; // Configuration for the proof source
-    entity_type: string; // Type of entity to verify
-  };
-  krn_config?: {
-    onboarding_api_url?: string; // URL of the onboarding API
-    datastore_api_url?: string; // URL of the datastore API
-    analytics_api_url?: string; // URL of the analytics API
-  };
-};
-```
-
 #### Core Types Overview
+
 - `ExtensionConfig`: Configuration for initializing the Keyring Connect extension
 - `ExtensionState`: Current state and status information of the extension
-- `UserState`: User's verification and credential status information
+- `User`: User's verification and credential status information
 
 #### Status Types
+
 - `ExtensionStatus`: Extension states (`idle`, `mounted`, `proving`, `prove_success`, `error`)
 - `AttestationStatus`: Off-chain verification status (`onboarding_required`, `onboarding_pending`, `attestation_ready`, `non_compliant`)
 - `CredentialStatus`: On-chain credential status (`expired`, `valid`, `none`)
 
-#### Proof Configuration Types
-- `DataSource`: The website that owns the data the Prover is trying to prove, defined by a name and login URL, containing a list of Proof Sources
-- `ProofSource`: Defines how to generate a single Proof on a given Data Source, containing an Endpoint and a list of Claims
-- `Endpoint`: A URL on the Data Source's server that provides access to the data that will need to be disclosed in the Proof
-- `DisclosableField`: A field in the Endpoint's response that the Prover must disclose to the Verifier, defined by a JSON path
-- `Claim`: Links Proofs to Keyring rules, containing a label and rule ID for evaluation of its status
-
 ## Extension States
 
 - **idle**: Extension is installed but not active
@@ -116,17 +90,3 @@ type ExtensionConfig = {
 - Chrome browser (version 88 or higher recommended)
 - Keyring Connect browser extension installed
 - Active internet connection
-
-## Error Handling
-
-The SDK throws errors in the following cases:
-- Network errors
-- Proof generation failures
-- On-chain credential update failures
-
-```typescript
-  const state = await KeyringConnect.getExtensionState();
-  if (state.status === 'error') {
-    console.error('An error occurred:', state.error);
-  }
-```