@bsv/wallet-toolbox 1.7.13 → 1.7.15

package/mobile/node_modules/@bsv/sdk/src/identity/IdentityClient.ts

@@ -0,0 +1,497 @@
+import { DEFAULT_IDENTITY_CLIENT_OPTIONS, defaultIdentity, DisplayableIdentity, KNOWN_IDENTITY_TYPES } from './types/index.js'
+import {
+  Base64String,
+  CertificateFieldNameUnder50Bytes,
+  DiscoverByAttributesArgs,
+  DiscoverByIdentityKeyArgs,
+  IdentityCertificate,
+  OriginatorDomainNameStringUnder250Bytes,
+  PubKeyHex,
+  WalletCertificate,
+  WalletClient,
+  WalletInterface
+} from '../wallet/index.js'
+import { BroadcastFailure, BroadcastResponse, Transaction } from '../transaction/index.js'
+import Certificate from '../auth/certificates/Certificate.js'
+import { PushDrop } from '../script/index.js'
+import { PrivateKey, Utils } from '../primitives/index.js'
+import { LookupResolver, SHIPBroadcaster, TopicBroadcaster, withDoubleSpendRetry } from '../overlay-tools/index.js'
+import { ContactsManager, Contact } from './ContactsManager.js'
+
+/**
+ * IdentityClient lets you discover who others are, and let the world know who you are.
+ */
+export class IdentityClient {
+  private readonly wallet: WalletInterface
+  private readonly contactsManager: ContactsManager
+  constructor (
+    wallet?: WalletInterface,
+    private readonly options = DEFAULT_IDENTITY_CLIENT_OPTIONS,
+    private readonly originator?: OriginatorDomainNameStringUnder250Bytes
+  ) {
+    this.originator = originator
+    this.wallet = wallet ?? new WalletClient()
+    this.contactsManager = new ContactsManager(this.wallet, this.originator)
+  }
+
+  /**
+   * Publicly reveals selected fields from a given certificate by creating a publicly verifiable certificate.
+   * The publicly revealed certificate is included in a blockchain transaction and broadcast to a federated overlay node.
+   *
+   * @param {Certificate} certificate - The master certificate to selectively reveal.
+   * @param {CertificateFieldNameUnder50Bytes[]} fieldsToReveal - An array of certificate field names to reveal. Only these fields will be included in the public certificate.
+   *
+   * @returns {Promise<object>} A promise that resolves with the broadcast result from the overlay network.
+   * @throws {Error} Throws an error if the certificate is invalid, the fields cannot be revealed, or if the broadcast fails.
+   */
+  async publiclyRevealAttributes (
+    certificate: WalletCertificate,
+    fieldsToReveal: CertificateFieldNameUnder50Bytes[]
+  ): Promise<BroadcastResponse | BroadcastFailure> {
+    if (Object.keys(certificate.fields).length === 0) {
+      throw new Error(
+        'Public reveal failed: Certificate has no fields to reveal!'
+      )
+    }
+    if (fieldsToReveal.length === 0) {
+      throw new Error(
+        'Public reveal failed: You must reveal at least one field!'
+      )
+    }
+    try {
+      const masterCert = new Certificate(
+        certificate.type,
+        certificate.serialNumber,
+        certificate.subject,
+        certificate.certifier,
+        certificate.revocationOutpoint,
+        certificate.fields,
+        certificate.signature
+      )
+      await masterCert.verify()
+    } catch (error) {
+      throw new Error('Public reveal failed: Certificate verification failed!')
+    }
+
+    // Given we already have a master certificate from a certifier,
+    // create an anyone verifiable certificate with selectively revealed fields
+    const { keyringForVerifier } = await this.wallet.proveCertificate(
+      {
+        certificate,
+        fieldsToReveal,
+        verifier: new PrivateKey(1).toPublicKey().toString()
+      },
+      this.originator
+    )
+
+    // Build the lockingScript with pushdrop.create() and the transaction with createAction()
+    const lockingScript = await new PushDrop(this.wallet, this.originator).lock(
+      [
+        Utils.toArray(
+          JSON.stringify({ ...certificate, keyring: keyringForVerifier })
+        )
+      ],
+      this.options.protocolID,
+      this.options.keyID,
+      'anyone',
+      true,
+      true
+    )
+    // TODO: Consider verification and if this is necessary
+    // counterpartyCanVerifyMyOwnership: true
+
+    const { tx } = await this.wallet.createAction(
+      {
+        description: 'Create a new Identity Token',
+        outputs: [
+          {
+            satoshis: this.options.tokenAmount,
+            lockingScript: lockingScript.toHex(),
+            outputDescription: 'Identity Token'
+          }
+        ],
+        options: {
+          randomizeOutputs: false
+        }
+      },
+      this.originator
+    )
+
+    if (tx !== undefined) {
+      // Submit the transaction to an overlay
+      const broadcaster = new TopicBroadcaster(['tm_identity'], {
+        networkPreset: (await this.wallet.getNetwork({})).network
+      })
+      return await broadcaster.broadcast(Transaction.fromAtomicBEEF(tx))
+    }
+    throw new Error('Public reveal failed: failed to create action!')
+  }
+
+  /**
+   * Resolves displayable identity certificates, issued to a given identity key by a trusted certifier.
+   *
+   * @param {DiscoverByIdentityKeyArgs} args - Arguments for requesting the discovery based on the identity key.
+   * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
+   * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
+   */
+  async resolveByIdentityKey (
+    args: DiscoverByIdentityKeyArgs,
+    overrideWithContacts = true
+  ): Promise<DisplayableIdentity[]> {
+    if (overrideWithContacts) {
+      // Override results with personal contacts if available
+      const contacts = await this.contactsManager.getContacts(args.identityKey)
+      if (contacts.length > 0) {
+        return contacts
+      }
+    }
+
+    const { certificates } = await this.wallet.discoverByIdentityKey(
+      args,
+      this.originator
+    )
+    return certificates.map((cert) => {
+      return IdentityClient.parseIdentity(cert)
+    })
+  }
+
+  /**
+   * Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
+   *
+   * @param {DiscoverByAttributesArgs} args - Attributes and optional parameters used to discover certificates.
+   * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
+   * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
+   */
+  async resolveByAttributes (
+    args: DiscoverByAttributesArgs,
+    overrideWithContacts = true
+  ): Promise<DisplayableIdentity[]> {
+    // Run both queries in parallel for better performance
+    const [contacts, certificatesResult] = await Promise.all([
+      overrideWithContacts
+        ? this.contactsManager.getContacts()
+        : Promise.resolve([]),
+      this.wallet.discoverByAttributes(args, this.originator)
+    ])
+
+    // Fast lookup by identityKey
+    const contactByKey = new Map<PubKeyHex, Contact>(
+      contacts.map((contact) => [contact.identityKey, contact] as const)
+    )
+
+    // Guard if certificates might be absent
+    const certs = certificatesResult?.certificates ?? []
+
+    // Parse certificates and substitute with contacts where available
+    return certs.map(
+      (cert) =>
+        contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
+    )
+  }
+
+  /**
+   * Remove public certificate revelation from overlay services by spending the identity token
+   * @param serialNumber - Unique serial number of the certificate to revoke revelation
+   */
+  async revokeCertificateRevelation (
+    serialNumber: Base64String
+  ): Promise<void> {
+    // 1. Find existing UTXO
+    const lookupResolver = new LookupResolver({
+      networkPreset: (await this.wallet.getNetwork({})).network
+    })
+    const result = await lookupResolver.query({
+      service: 'ls_identity',
+      query: {
+        serialNumber
+      }
+    })
+
+    if (result.type !== 'output-list') { throw new Error('Failed to get lookup result') }
+
+    const topicBroadcaster = new SHIPBroadcaster(['tm_identity'], {
+      networkPreset: (await this.wallet.getNetwork({})).network,
+      requireAcknowledgmentFromAllHostsForTopics: [],
+      requireAcknowledgmentFromAnyHostForTopics: [],
+      requireAcknowledgmentFromSpecificHostsForTopics: { tm_identity: [] }
+    })
+
+    await withDoubleSpendRetry(async () => {
+      const tx = Transaction.fromBEEF(result.outputs[0].beef)
+      const outpoint = `${tx.id('hex')}.${this.options.outputIndex}`
+      const lockingScript = tx.outputs[this.options.outputIndex].lockingScript
+
+      if (lockingScript === undefined || outpoint === undefined) {
+        throw new Error('Failed to get locking script for revelation output!')
+      }
+
+      // 2. Parse results
+      const { signableTransaction } = await this.wallet.createAction(
+        {
+          description: 'Spend certificate revelation token',
+          inputBEEF: result.outputs[0].beef,
+          inputs: [
+            {
+              inputDescription: 'Revelation token',
+              outpoint,
+              unlockingScriptLength: 74
+            }
+          ],
+          options: {
+            randomizeOutputs: false,
+            acceptDelayedBroadcast: false,
+            noSend: true
+          }
+        },
+        this.originator
+      )
+
+      if (signableTransaction === undefined) {
+        throw new Error('Failed to create signable transaction')
+      }
+
+      const partialTx = Transaction.fromBEEF(signableTransaction.tx)
+
+      const unlocker = new PushDrop(this.wallet, this.originator).unlock(
+        this.options.protocolID,
+        this.options.keyID,
+        'anyone'
+      )
+
+      const unlockingScript = await unlocker.sign(
+        partialTx,
+        this.options.outputIndex
+      )
+
+      const { tx: signedTx } = await this.wallet.signAction(
+        {
+          reference: signableTransaction.reference,
+          spends: {
+            [this.options.outputIndex]: {
+              unlockingScript: unlockingScript.toHex()
+            }
+          },
+          options: {
+            acceptDelayedBroadcast: false,
+            noSend: true
+          }
+        },
+        this.originator
+      )
+
+      if (signedTx === undefined) {
+        throw new Error('Failed to sign transaction')
+      }
+
+      await topicBroadcaster.broadcast(Transaction.fromAtomicBEEF(signedTx))
+    }, topicBroadcaster)
+  }
+
+  /**
+   * Load all records from the contacts basket
+   * @param identityKey Optional specific identity key to fetch
+   * @param forceRefresh Whether to force a check for new contact data
+   * @param limit Optional limit on number of contacts to fetch
+   * @returns A promise that resolves with an array of contacts
+   */
+  public async getContacts (
+    identityKey?: PubKeyHex,
+    forceRefresh = false,
+    limit = 1000
+  ): Promise<Contact[]> {
+    return await this.contactsManager.getContacts(
+      identityKey,
+      forceRefresh,
+      limit
+    )
+  }
+
+  /**
+   * Save or update a Metanet contact
+   * @param contact The displayable identity information for the contact
+   * @param metadata Optional metadata to store with the contact (ex. notes, aliases, etc)
+   */
+  public async saveContact (
+    contact: DisplayableIdentity,
+    metadata?: Record<string, any>
+  ): Promise<void> {
+    return await this.contactsManager.saveContact(contact, metadata)
+  }
+
+  /**
+   * Remove a contact from the contacts basket
+   * @param identityKey The identity key of the contact to remove
+   */
+  public async removeContact (identityKey: PubKeyHex): Promise<void> {
+    return await this.contactsManager.removeContact(identityKey)
+  }
+
+  /**
+   * Parse out identity and certifier attributes to display from an IdentityCertificate
+   * @param identityToParse - The Identity Certificate to parse
+   * @returns - IdentityToDisplay
+   */
+  static parseIdentity (
+    identityToParse: IdentityCertificate
+  ): DisplayableIdentity {
+    const { type, decryptedFields, certifierInfo } = identityToParse
+    let name, avatarURL, badgeLabel, badgeIconURL, badgeClickURL
+
+    // Parse out the name to display based on the specific certificate type which has clearly defined fields.
+    switch (type) {
+      case KNOWN_IDENTITY_TYPES.xCert:
+        name = decryptedFields.userName
+        avatarURL = decryptedFields.profilePhoto
+        badgeLabel = `X account certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        break
+      case KNOWN_IDENTITY_TYPES.discordCert:
+        name = decryptedFields.userName
+        avatarURL = decryptedFields.profilePhoto
+        badgeLabel = `Discord account certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        break
+      case KNOWN_IDENTITY_TYPES.emailCert:
+        name = decryptedFields.email
+        avatarURL = 'XUTZxep7BBghAJbSBwTjNfmcsDdRFs5EaGEgkESGSgjJVYgMEizu'
+        badgeLabel = `Email certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        break
+      case KNOWN_IDENTITY_TYPES.phoneCert:
+        name = decryptedFields.phoneNumber
+        avatarURL = 'XUTLxtX3ELNUwRhLwL7kWNGbdnFM8WG2eSLv84J7654oH8HaJWrU'
+        badgeLabel = `Phone certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://socialcert.net' // TODO Make a specific page for this.
+        break
+      case KNOWN_IDENTITY_TYPES.identiCert:
+        name = `${decryptedFields.firstName} ${decryptedFields.lastName}`
+        avatarURL = decryptedFields.profilePhoto
+        badgeLabel = `Government ID certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://identicert.me' // TODO Make a specific page for this.
+        break
+      case KNOWN_IDENTITY_TYPES.registrant:
+        name = decryptedFields.name
+        avatarURL = decryptedFields.icon
+        badgeLabel = `Entity certified by ${certifierInfo.name}`
+        badgeIconURL = certifierInfo.iconUrl
+        badgeClickURL = 'https://projectbabbage.com/docs/registrant' // TODO: Make this doc page exist
+        break
+      case KNOWN_IDENTITY_TYPES.coolCert:
+        name = decryptedFields.cool === 'true' ? 'Cool Person!' : 'Not cool!'
+        break
+      case KNOWN_IDENTITY_TYPES.anyone:
+        name = 'Anyone'
+        avatarURL = 'XUT4bpQ6cpBaXi1oMzZsXfpkWGbtp2JTUYAoN7PzhStFJ6wLfoeR'
+        badgeLabel =
+          'Represents the ability for anyone to access this information.'
+        badgeIconURL = 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG'
+        badgeClickURL = 'https://projectbabbage.com/docs/anyone-identity' // TODO: Make this doc page exist
+        break
+      case KNOWN_IDENTITY_TYPES.self:
+        name = 'You'
+        avatarURL = 'XUT9jHGk2qace148jeCX5rDsMftkSGYKmigLwU2PLLBc7Hm63VYR'
+        badgeLabel = 'Represents your ability to access this information.'
+        badgeIconURL = 'XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG'
+        badgeClickURL = 'https://projectbabbage.com/docs/self-identity' // TODO: Make this doc page exist
+        break
+      default: {
+        const parsed = IdentityClient.tryToParseGenericIdentity(
+          type,
+          decryptedFields,
+          certifierInfo
+        )
+        name = parsed.name
+        avatarURL = parsed.avatarURL
+        badgeLabel = parsed.badgeLabel
+        badgeIconURL = parsed.badgeIconURL
+        badgeClickURL = parsed.badgeClickURL
+        break
+      }
+    }
+
+    return {
+      name,
+      avatarURL,
+      abbreviatedKey:
+        identityToParse.subject.length > 0
+          ? `${identityToParse.subject.substring(0, 10)}...`
+          : '',
+      identityKey: identityToParse.subject,
+      badgeIconURL,
+      badgeLabel,
+      badgeClickURL
+    }
+  }
+
+  /**
+   * Helper to check if a value is a non-empty string
+   */
+  private static hasValue (value: any): value is string {
+    return value !== undefined && value !== null && value !== ''
+  }
+
+  /**
+   * Try to parse identity information from unknown certificate types
+   * by checking common field names
+   */
+  private static tryToParseGenericIdentity (
+    type: string,
+    decryptedFields: Record<string, any>,
+    certifierInfo: any
+  ): {
+      name: string
+      avatarURL: string
+      badgeLabel: string
+      badgeIconURL: string
+      badgeClickURL: string
+    } {
+    // Try to construct a name from common field patterns
+    const firstName = decryptedFields.firstName
+    const lastName = decryptedFields.lastName
+    const fullName =
+      IdentityClient.hasValue(firstName) && IdentityClient.hasValue(lastName)
+        ? `${firstName} ${lastName}`
+        : IdentityClient.hasValue(firstName)
+          ? firstName
+          : IdentityClient.hasValue(lastName)
+            ? lastName
+            : undefined
+
+    const name = IdentityClient.hasValue(decryptedFields.name)
+      ? decryptedFields.name
+      : IdentityClient.hasValue(decryptedFields.userName)
+        ? decryptedFields.userName
+        : (fullName ??
+          (IdentityClient.hasValue(decryptedFields.email)
+            ? decryptedFields.email
+            : defaultIdentity.name))
+
+    // Try to find an avatar/photo from common field names
+    const avatarURL = IdentityClient.hasValue(decryptedFields.profilePhoto)
+      ? decryptedFields.profilePhoto
+      : IdentityClient.hasValue(decryptedFields.avatar)
+        ? decryptedFields.avatar
+        : IdentityClient.hasValue(decryptedFields.icon)
+          ? decryptedFields.icon
+          : IdentityClient.hasValue(decryptedFields.photo)
+            ? decryptedFields.photo
+            : defaultIdentity.avatarURL
+
+    // Generate badge information
+    const badgeLabel = IdentityClient.hasValue(certifierInfo?.name)
+      ? `${type} certified by ${String(certifierInfo.name)}`
+      : defaultIdentity.badgeLabel
+
+    const badgeIconURL = IdentityClient.hasValue(certifierInfo?.iconUrl)
+      ? certifierInfo.iconUrl
+      : defaultIdentity.badgeIconURL
+    const badgeClickURL = defaultIdentity.badgeClickURL
+
+    return { name, avatarURL, badgeLabel, badgeIconURL, badgeClickURL }
+  }
+}

package/mobile/node_modules/@bsv/sdk/src/identity/README.md

@@ -0,0 +1,92 @@
+# 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