@keyringnetwork/keyring-connect-sdk NPM

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)