@keyringnetwork/keyring-connect-sdk

Keyring Connect SDK

A TypeScript 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

npm install @keyringnetwork/keyring-connect-sdk
yarn add @keyringnetwork/keyring-connect-sdk
pnpm install @keyringnetwork/keyring-connect-sdk

Features

• Check if the extension is installed
• Launch Keyring Connect with custom client configuration
• Redirect the user back to the app where they left off after extension installation
• Monitor extension status and user state
• Full TypeScript support with comprehensive type definitions
• Support for isolated proving mode (verification without credential creation)

Usage

Initialize

import { KeyringConnect } from "@keyringnetwork/keyring-connect-sdk";

Check if the extension is installed

const isInstalled = await KeyringConnect.isKeyringConnectInstalled();

Launch Keyring Connect

const extensionConfig = {
  name: "My App",
  app_url: "https://myapp.com",
  logo_url: "https://myapp.com/logo.png",
  policy_id: 123,
};

// This method handles both launching the extension if installed
// or redirecting to the Chrome Web Store if not installed
try {
  await KeyringConnect.launchExtension(extensionConfig);
} catch (error) {
  console.error("Failed to launch Keyring Connect:", error);
}

Monitor Extension Status

export interface ExtensionState {
  status: "idle" | "mounted" | "proving" | "prove_success" | "error";
  manifest?: any;
  error?: string; // error message, only if status is 'error'
  user?: User;
}

const extensionState = await KeyringConnect.getExtensionState();

Integration Example

import { useEffect, useState } from "react";
import {
  ExtensionSDKConfig,
  KeyringConnect,
} from "@keyringnetwork/keyring-connect-sdk";

function KeyringConnectButton() {
  const [isInstalled, setIsInstalled] = useState<boolean | undefined>(
    undefined
  );

  // Check if extension is installed
  useEffect(() => {
    const checkExtension = async () => {
      const isInstalled = await KeyringConnect.isKeyringConnectInstalled();
      setIsInstalled(isInstalled);
    };
    checkExtension();
  }, []);

  // Configure your app
  const config: ExtensionSDKConfig = {
    app_url: window.location.origin,
    name: "My App",
    logo_url: "https://myapp.com/logo.png",
    policy_id: 7,
  };

  // Launch the extension (handles both installed and not installed cases)
  const launchExtension = () => {
    KeyringConnect.launchExtension(config);
  };

  if (isInstalled === undefined) {
    return <button disabled>Checking extension...</button>;
  }

  return (
    <button onClick={launchExtension}>
      {isInstalled ? "Launch Extension" : "Install Extension"}
    </button>
  );
}

API Reference

Core Types Overview

• ExtensionConfig: Configuration for initializing the Keyring Connect extension
• ExtensionState: Current state and status information of the extension
• User: User's verification and credential status information

Status Types

• ExtensionStatus: Extension states (idle, mounted, proving, prove_error, prove_success, error)
• AttestationStatus: Off-chain verification status (onboarding_required, onboarding_pending, attestation_ready, non_compliant)
• CredentialStatus: On-chain credential status (expired, valid, none)

Extension States

• idle: Extension is installed but not active
• mounted: Extension is launched and ready
• proving: Currently generating proof
• prove_success: Proof generation successful
• error: An error occurred

Requirements

• An on-chain Keyring policy
• Chrome browser (version 88 or higher recommended)
• Keyring Connect browser extension installed
• Active internet connection