@bsv/sdk 1.3.36 → 1.4.1

package/src/identity/README.md

@@ -0,0 +1,93 @@
+# IdentityClient
+
+**Resolve who others are and let the world know who you are.**
+
+## Overview
+
+`IdentityClient` provides a straightforward interface for resolving and revealing identity certificates. It allows applications to verify user identities through certificates issued by trusted certifiers, reveal identity attributes publicly on the blockchain, and resolving identities associated with given attributes or identity keys.
+
+## Features
+
+- **Selective Attribute Revelation**: Create identity tokens which publicly reveal selective identity attributes and are tracked by overlay services.
+- **Identity Resolution**: Easily resolve identity certificates based on identity keys or specific attributes.
+- **Displayable Identities**: Parse identity certificates into user-friendly, displayable identities.
+
+## Installation
+
+```bash
+npm install @bsv/sdk
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { IdentityClient } from '@bsv/sdk'
+
+const identityClient = new IdentityClient()
+```
+
+### Publicly Reveal Attributes
+
+```typescript
+const broadcastResult = await identityClient.publiclyRevealAttributes(certificate, ['name', 'email'])
+```
+
+### Resolve Identity by Key
+
+```typescript
+const identities = await identityClient.resolveByIdentityKey({
+  identityKey: '<identity-key-here>'
+})
+```
+
+### Resolve Identity by Attributes
+
+```typescript
+const identities = await identityClient.resolveByAttributes({
+  attributes: { email: 'user@example.com' }
+})
+```
+
+## React Example
+
+```ts
+import React, { useEffect, useState } from 'react'
+import { IdentityClient } from '@bsv/sdk'
+
+const identityClient = new IdentityClient()
+
+function IdentityDisplay({ identityKey }) {
+  const [identities, setIdentities] = useState([])
+
+  useEffect(() => {
+    async function fetchIdentities() {
+      const results = await identityClient.resolveByIdentityKey({ identityKey })
+      setIdentities(results)
+    }
+
+    fetchIdentities()
+  }, [identityKey])
+
+  return (
+    <div>
+      {identities.map((identity, index) => (
+        <div key={index} style={{ border: '1px solid #ccc', padding: '10px', marginBottom: '10px', borderRadius: '5px' }}>
+          <img src={identity.avatarURL} alt="Avatar" style={{ width: '50px', height: '50px', borderRadius: '25px' }} />
+          <h3>{identity.name}</h3>
+          <p>{identity.badgeLabel}</p>
+          <a href={identity.badgeClickURL}>Learn More</a>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export default IdentityDisplay
+```
+
+## License
+
+Open BSV License
+

package/src/identity/__tests/IdentityClient.test.ts

@@ -0,0 +1,278 @@
+import { WalletCertificate, WalletInterface } from '../../wallet/index'
+import { IdentityClient } from '../IdentityClient'
+import { Certificate } from '../../auth/certificates/index.js'
+import { KNOWN_IDENTITY_TYPES, defaultIdentity } from '../types/index.js'
+
+// ----- Mocks for external dependencies -----
+jest.mock('../../script', () => {
+  return {
+    PushDrop: jest.fn().mockImplementation(() => ({
+      lock: jest.fn().mockResolvedValue({
+        toHex: () => 'lockingScriptHex'
+      }),
+      unlock: jest.fn()
+    }))
+  }
+})
+
+jest.mock('../../overlay-tools/index.js', () => {
+  return {
+    TopicBroadcaster: jest.fn().mockImplementation(() => ({
+      broadcast: jest.fn().mockResolvedValue('broadcastResult')
+    }))
+  }
+})
+
+jest.mock('../../transaction/index.js', () => {
+  return {
+    Transaction: {
+      fromAtomicBEEF: jest.fn().mockImplementation((tx) => ({
+        toHexBEEF: () => 'transactionHex'
+      })),
+      fromBEEF: jest.fn()
+    }
+  }
+})
+
+// ----- Begin Test Suite -----
+describe('IdentityClient', () => {
+  let walletMock: Partial<WalletInterface>
+  let identityClient: IdentityClient
+
+  beforeEach(() => {
+    // Create a fake wallet implementing the methods used by IdentityClient.
+    walletMock = {
+      proveCertificate: jest.fn().mockResolvedValue({ keyringForVerifier: 'fakeKeyring' }),
+      createAction: jest.fn().mockResolvedValue({
+        tx: [1, 2, 3],
+        signableTransaction: { tx: [1, 2, 3], reference: 'ref' }
+      }),
+      listCertificates: jest.fn().mockResolvedValue({ certificates: [] }),
+      acquireCertificate: jest.fn().mockResolvedValue({
+        fields: { name: 'Alice' },
+        verify: jest.fn().mockResolvedValue(true)
+      }),
+      signAction: jest.fn().mockResolvedValue({ tx: [4, 5, 6] }),
+      getNetwork: jest.fn().mockResolvedValue({ network: 'testnet' }),
+      discoverByIdentityKey: jest.fn(),
+      discoverByAttributes: jest.fn()
+    }
+
+    identityClient = new IdentityClient(walletMock as WalletInterface)
+
+    // Clear any previous calls/spies.
+    jest.clearAllMocks()
+  })
+
+  describe('publiclyRevealAttributes', () => {
+    it('should throw an error if certificate has no fields', async () => {
+      const certificate = {
+        fields: {},
+        verify: jest.fn().mockResolvedValue(true)
+      } as any as WalletCertificate
+      const fieldsToReveal = ['name']
+      await expect(
+        identityClient.publiclyRevealAttributes(certificate, fieldsToReveal)
+      ).rejects.toThrow('Certificate has no fields to reveal!')
+    })
+
+    it('should throw an error if fieldsToReveal is empty', async () => {
+      const certificate = {
+        fields: { name: 'Alice' },
+        verify: jest.fn().mockResolvedValue(true)
+      } as any as WalletCertificate
+      const fieldsToReveal: string[] = []
+      await expect(
+        identityClient.publiclyRevealAttributes(certificate, fieldsToReveal)
+      ).rejects.toThrow('You must reveal at least one field!')
+    })
+
+    it('should throw an error if certificate verification fails', async () => {
+      const certificate = {
+        fields: { name: 'Alice' },
+        verify: jest.fn().mockRejectedValue(new Error('Verification error')),
+        type: 'dummyType',
+        serialNumber: 'dummySerial',
+        subject: 'dummySubject',
+        certifier: 'dummyCertifier',
+        revocationOutpoint: 'dummyRevocation',
+        signature: 'dummySignature'
+      } as any as WalletCertificate
+      const fieldsToReveal = ['name']
+      await expect(
+        identityClient.publiclyRevealAttributes(certificate, fieldsToReveal)
+      ).rejects.toThrow('Certificate verification failed!')
+    })
+
+    it('should publicly reveal attributes successfully', async () => {
+      // Prepare a dummy certificate with all required properties.
+      const certificate = {
+        fields: { name: 'Alice' },
+        verify: jest.fn().mockResolvedValue(true), // this property is not used since the Certificate is re-instantiated
+        type: 'xCert',
+        serialNumber: '12345',
+        subject: 'abcdef1234567890',
+        certifier: 'CertifierX',
+        revocationOutpoint: 'outpoint1',
+        signature: 'signature1'
+      } as any as WalletCertificate
+
+      // Ensure that Certificate.verify (called on the re-instantiated Certificate)
+      // resolves successfully.
+      jest.spyOn(Certificate.prototype, 'verify').mockResolvedValue(false)
+
+      const fieldsToReveal = ['name']
+      const result = await identityClient.publiclyRevealAttributes(certificate, fieldsToReveal)
+      expect(result).toEqual('broadcastResult')
+
+      // Validate that proveCertificate was called with the proper arguments.
+      expect(walletMock.proveCertificate).toHaveBeenCalledWith({
+        certificate,
+        fieldsToReveal,
+        verifier: expect.any(String)
+      })
+
+      // Validate that createAction was called.
+      expect(walletMock.createAction).toHaveBeenCalled()
+    })
+  })
+
+  describe('resolveByIdentityKey', () => {
+    it('should return parsed identities from discovered certificates', async () => {
+      const dummyCertificate = {
+        type: KNOWN_IDENTITY_TYPES.xCert,
+        subject: 'abcdef1234567890',
+        decryptedFields: {
+          userName: 'Alice',
+          profilePhoto: 'alicePhotoUrl'
+        },
+        certifierInfo: {
+          name: 'CertifierX',
+          iconUrl: 'certifierIconUrl'
+        }
+      }
+      // Mock discoverByIdentityKey to return a certificate list.
+      walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates: [dummyCertificate] })
+
+      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'dummyKey' })
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalledWith({ identityKey: 'dummyKey' }, undefined)
+      expect(identities).toHaveLength(1)
+      expect(identities[0]).toEqual({
+        name: 'Alice',
+        avatarURL: 'alicePhotoUrl',
+        abbreviatedKey: 'abcdef1234...',
+        identityKey: 'abcdef1234567890',
+        badgeLabel: 'X account certified by CertifierX',
+        badgeIconURL: 'certifierIconUrl',
+        badgeClickURL: 'https://socialcert.net'
+      })
+    })
+  })
+
+  it('should throw if createAction returns no tx', async () => {
+    const certificate = {
+      fields: { name: 'Alice' },
+      verify: jest.fn().mockResolvedValue(true),
+      type: 'xCert',
+      serialNumber: '12345',
+      subject: 'abcdef1234567890',
+      certifier: 'CertifierX',
+      revocationOutpoint: 'outpoint1',
+      signature: 'signature1'
+    } as any as WalletCertificate
+
+    jest.spyOn(Certificate.prototype, 'verify').mockResolvedValue(false)
+
+    // Simulate createAction returning an object with tx = undefined
+    walletMock.createAction = jest.fn().mockResolvedValue({
+      tx: undefined,
+      signableTransaction: { tx: undefined, reference: 'ref' }
+    })
+
+    const fieldsToReveal = ['name']
+
+    await expect(
+      identityClient.publiclyRevealAttributes(certificate, fieldsToReveal)
+    ).rejects.toThrow('Public reveal failed: failed to create action!')
+  })
+
+  describe('resolveByAttributes', () => {
+    it('should return parsed identities from discovered certificates', async () => {
+      const dummyCertificate = {
+        type: KNOWN_IDENTITY_TYPES.emailCert,
+        subject: 'emailSubject1234',
+        decryptedFields: {
+          email: 'alice@example.com',
+          profilePhoto: 'ignored' // not used for email type
+        },
+        certifierInfo: {
+          name: 'EmailCertifier',
+          iconUrl: 'emailIconUrl'
+        }
+      }
+      // Mock discoverByAttributes to return a certificate list.
+      walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [dummyCertificate] })
+
+      const identities = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } })
+      expect(walletMock.discoverByAttributes).toHaveBeenCalledWith({ attributes: { email: 'alice@example.com' } }, undefined)
+      expect(identities).toHaveLength(1)
+      expect(identities[0]).toEqual({
+        name: 'alice@example.com',
+        avatarURL: 'XUTZxep7BBghAJbSBwTjNfmcsDdRFs5EaGEgkESGSgjJVYgMEizu',
+        abbreviatedKey: 'emailSubje...',
+        identityKey: 'emailSubject1234',
+        badgeLabel: 'Email certified by EmailCertifier',
+        badgeIconURL: 'emailIconUrl',
+        badgeClickURL: 'https://socialcert.net'
+      })
+    })
+  })
+
+  describe('parseIdentity', () => {
+    it('should correctly parse an xCert identity', () => {
+      const dummyCertificate = {
+        type: KNOWN_IDENTITY_TYPES.xCert,
+        subject: 'abcdef1234567890',
+        decryptedFields: {
+          userName: 'Alice',
+          profilePhoto: 'alicePhotoUrl'
+        },
+        certifierInfo: {
+          name: 'CertifierX',
+          iconUrl: 'certifierIconUrl'
+        }
+      }
+      const identity = IdentityClient.parseIdentity(dummyCertificate as unknown as any)
+      expect(identity).toEqual({
+        name: 'Alice',
+        avatarURL: 'alicePhotoUrl',
+        abbreviatedKey: 'abcdef1234...',
+        identityKey: 'abcdef1234567890',
+        badgeLabel: 'X account certified by CertifierX',
+        badgeIconURL: 'certifierIconUrl',
+        badgeClickURL: 'https://socialcert.net'
+      })
+    })
+
+    it('should return default identity for unknown type', () => {
+      const dummyCertificate = {
+        type: 'unknownType',
+        subject: '',
+        decryptedFields: {
+          profilePhoto: 'defaultPhoto'
+        },
+        certifierInfo: {}
+      }
+      const identity = IdentityClient.parseIdentity(dummyCertificate as any)
+      expect(identity).toEqual({
+        name: defaultIdentity.name,
+        avatarURL: 'defaultPhoto',
+        abbreviatedKey: '',
+        identityKey: '',
+        badgeLabel: defaultIdentity.badgeLabel,
+        badgeIconURL: defaultIdentity.badgeIconURL,
+        badgeClickURL: defaultIdentity.badgeClickURL
+      })
+    })
+  })
+})

package/src/identity/index.ts

@@ -0,0 +1,2 @@
+export * from './IdentityClient.js'
+export * from './types/index.js'

package/src/identity/types/index.ts

@@ -0,0 +1,46 @@
+import { WalletProtocol } from "../../wallet/index.js"
+
+export const defaultIdentity: DisplayableIdentity = {
+  name: 'Unknown Identity',
+  avatarURL: 'XUUB8bbn9fEthk15Ge3zTQXypUShfC94vFjp65v7u5CQ8qkpxzst',
+  identityKey: '',
+  abbreviatedKey: '',
+  badgeIconURL: 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG',
+  badgeLabel: 'Not verified by anyone you trust.',
+  badgeClickURL: 'https://projectbabbage.com/docs/unknown-identity'
+}
+
+export interface IdentityClientOptions {
+  protocolID: WalletProtocol
+  keyID: string
+  tokenAmount: number
+  outputIndex: number
+}
+export const DEFAULT_IDENTITY_CLIENT_OPTIONS: IdentityClientOptions = {
+  protocolID: [1, 'identity'],
+  keyID: '1',
+  tokenAmount: 1,
+  outputIndex: 0
+}
+
+export interface DisplayableIdentity {
+  name: string
+  avatarURL: string
+  abbreviatedKey: string
+  identityKey: string
+  badgeIconURL: string
+  badgeLabel: string
+  badgeClickURL: string
+}
+
+export const KNOWN_IDENTITY_TYPES = {
+  identiCert: 'z40BOInXkI8m7f/wBrv4MJ09bZfzZbTj2fJqCtONqCY=',
+  discordCert: '2TgqRC35B1zehGmB21xveZNc7i5iqHc0uxMb+1NMPW4=',
+  phoneCert: 'mffUklUzxbHr65xLohn0hRL0Tq2GjW1GYF/OPfzqJ6A=',
+  xCert: 'vdDWvftf1H+5+ZprUw123kjHlywH+v20aPQTuXgMpNc=',
+  registrant: 'YoPsbfR6YQczjzPdHCoGC7nJsOdPQR50+SYqcWpJ0y0=',
+  emailCert: 'exOl3KM0dIJ04EW5pZgbZmPag6MdJXd3/a1enmUU/BA=',
+  anyone: 'mfkOMfLDQmrr3SBxBQ5WeE+6Hy3VJRFq6w4A5Ljtlis=',
+  self: 'Hkge6X5JRxt1cWXtHLCrSTg6dCVTxjQJJ48iOYd7n3g=',
+  coolCert: 'AGfk/WrT1eBDXpz3mcw386Zww2HmqcIn3uY6x4Af1eo='
+}

package/src/overlay-tools/LookupResolver.ts

@@ -227,8 +227,8 @@ export default class LookupResolver {
             continue
           }
         }
-      } catch (error) {
-        console.error('Error processing response outputs:', error)
+      } catch (_) {
+        // Error processing output, proceed.
       }
     }
     return {

package/src/primitives/utils.ts

@@ -359,7 +359,7 @@ export const fromBase58Check = (
   str: string,
   enc?: 'hex',
   prefixLength: number = 1
-): any => {
+): { data: number[] | string, prefix: number[] | string } => {
   const bin = fromBase58(str)
   let prefix: string | number[] = bin.slice(0, prefixLength)
   let data: string | number[] = bin.slice(prefixLength, -4)