@bsv/wallet-toolbox 1.1.23 → 1.1.25

package/src/utility/identityUtils.ts

@@ -0,0 +1,170 @@
+import {
+  LookupAnswer,
+  Transaction,
+  PushDrop,
+  VerifiableCertificate,
+  Utils,
+  ProtoWallet,
+  LookupResolver,
+  DiscoverCertificatesResult,
+  IdentityCertificate,
+  IdentityCertifier,
+  Base64String
+} from '@bsv/sdk'
+import { Certifier, TrustSettings } from '../WalletSettingsManager'
+
+const OUTPUT_INDEX = 0
+
+// Our extended certificate includes certifierInfo.
+export interface ExtendedVerifiableCertificate extends IdentityCertificate {
+  certifierInfo: IdentityCertifier
+  publiclyRevealedKeyring: Record<string, Base64String>
+}
+
+// --- Helper Types for Grouping ---
+
+interface IdentityGroup {
+  totalTrust: number
+  members: ExtendedVerifiableCertificate[]
+}
+
+/**
+ * Transforms an array of VerifiableCertificate instances according to the trust settings.
+ * Only certificates whose grouped total trust meets the threshold are returned,
+ * and each certificate is augmented with a certifierInfo property.
+ *
+ * @param trustSettings - the user's trust settings including trustLevel and trusted certifiers.
+ * @param certificates - an array of VerifiableCertificate objects.
+ * @returns a DiscoverCertificatesResult with totalCertificates and ordered certificates.
+ */
+export const transformVerifiableCertificatesWithTrust = (
+  trustSettings: TrustSettings,
+  certificates: VerifiableCertificate[]
+): DiscoverCertificatesResult => {
+  // Group certificates by subject while accumulating trust.
+  const identityGroups: Record<string, IdentityGroup> = {}
+  // Cache certifier lookups.
+  const certifierCache: Record<string, Certifier> = {}
+
+  certificates.forEach(cert => {
+    const { subject, certifier } = cert
+    if (!subject || !certifier) return
+
+    // Lookup and cache certifier details from trustSettings.
+    if (!certifierCache[certifier]) {
+      const found = trustSettings.trustedCertifiers.find(
+        x => x.identityKey === certifier
+      )
+      if (!found) return // Skip this certificate if its certifier is not trusted.
+      certifierCache[certifier] = found
+    }
+
+    // Create the IdentityCertifier object that we want to attach.
+    const certifierInfo: IdentityCertifier = {
+      name: certifierCache[certifier].name,
+      iconUrl: certifierCache[certifier].iconUrl || '',
+      description: certifierCache[certifier].description,
+      trust: certifierCache[certifier].trust
+    }
+
+    // Create an extended certificate that includes certifierInfo.
+    // Note: We use object spread to copy over all properties from the original certificate.
+    const extendedCert: IdentityCertificate = {
+      ...cert,
+      signature: cert.signature!, // We know it exists at this point
+      decryptedFields: cert.decryptedFields as Record<string, string>,
+      publiclyRevealedKeyring: cert.keyring,
+      certifierInfo
+    }
+
+    // Group certificates by subject.
+    if (!identityGroups[subject]) {
+      identityGroups[subject] = { totalTrust: 0, members: [] }
+    }
+    identityGroups[subject].totalTrust += certifierInfo.trust
+    identityGroups[subject].members.push(extendedCert)
+  })
+
+  // Filter out groups that do not meet the trust threshold and flatten the results.
+  const finalResults: ExtendedVerifiableCertificate[] = []
+  Object.values(identityGroups).forEach(group => {
+    if (group.totalTrust >= trustSettings.trustLevel) {
+      finalResults.push(...group.members)
+    }
+  })
+
+  // Sort the certificates by their certifier trust in descending order.
+  finalResults.sort((a, b) => b.certifierInfo.trust - a.certifierInfo.trust)
+
+  return {
+    totalCertificates: finalResults.length,
+    certificates: finalResults
+  }
+}
+
+/**
+ * Performs an identity overlay service lookup query and returns the parsed results
+ *
+ * @param query
+ * @returns
+ */
+export const queryOverlay = async (
+  query: unknown,
+  resolver: LookupResolver
+): Promise<VerifiableCertificate[]> => {
+  const results = await resolver.query({
+    service: 'ls_identity',
+    query
+  })
+
+  return await parseResults(results)
+}
+
+/**
+ * Internal func: Parse the returned UTXOs Decrypt and verify the certificates and signatures Return the set of identity keys, certificates and decrypted certificate fields
+ *
+ * @param {Output[]} outputs
+ * @returns {Promise<VerifiableCertificate[]>}
+ */
+export const parseResults = async (
+  lookupResult: LookupAnswer
+): Promise<VerifiableCertificate[]> => {
+  if (lookupResult.type === 'output-list') {
+    const parsedResults: VerifiableCertificate[] = []
+
+    for (const output of lookupResult.outputs) {
+      try {
+        const tx = Transaction.fromAtomicBEEF(output.beef)
+        // Decode the Identity token fields from the Bitcoin outputScript
+        const decodedOutput = PushDrop.decode(
+          tx.outputs[OUTPUT_INDEX].lockingScript
+        )
+
+        // Parse out the certificate and relevant data
+        const certificate: VerifiableCertificate = JSON.parse(
+          Utils.toUTF8(decodedOutput.fields[0])
+        ) // TEST
+        const verifiableCert = new VerifiableCertificate(
+          certificate.type,
+          certificate.serialNumber,
+          certificate.subject,
+          certificate.revocationOutpoint,
+          certificate.certifier,
+          certificate.fields,
+          certificate.keyring,
+          certificate.signature
+        )
+        const decryptedFields = await verifiableCert.decryptFields(
+          new ProtoWallet('anyone')
+        )
+        verifiableCert.decryptedFields = decryptedFields
+        parsedResults.push(verifiableCert)
+      } catch (error) {
+        console.error(error)
+        // do nothing
+      }
+    }
+    return parsedResults
+  }
+  return []
+}

package/src/wab-client/WABClient.ts

@@ -0,0 +1,103 @@
+/**
+ * WABClient
+ *
+ * Provides high-level methods to:
+ *  - Retrieve server info (supported auth methods, faucet info)
+ *  - Generate a random presentation key
+ *  - Start/Complete authentication with a chosen AuthMethodInteractor
+ *  - Link/unlink methods
+ *  - Request faucet
+ *  - Delete user
+ */
+import fetch from 'node-fetch'
+import { AuthMethodInteractor } from './auth-method-interactors/AuthMethodInteractor'
+import crypto from 'crypto'
+
+export class WABClient {
+  constructor(private serverUrl: string) {}
+
+  /**
+   * Return the WAB server info
+   */
+  public async getInfo() {
+    const res = await fetch(`${this.serverUrl}/info`)
+    return res.json()
+  }
+
+  /**
+   * Generate a random 256-bit presentation key as a hex string (client side).
+   */
+  public generateRandomPresentationKey(): string {
+    return crypto.randomBytes(32).toString('hex')
+  }
+
+  /**
+   * Start an Auth Method flow
+   */
+  public async startAuthMethod(
+    authMethod: AuthMethodInteractor,
+    presentationKey: string,
+    payload: any
+  ) {
+    return authMethod.startAuth(this.serverUrl, presentationKey, payload)
+  }
+
+  /**
+   * Complete an Auth Method flow
+   */
+  public async completeAuthMethod(
+    authMethod: AuthMethodInteractor,
+    presentationKey: string,
+    payload: any
+  ) {
+    return authMethod.completeAuth(this.serverUrl, presentationKey, payload)
+  }
+
+  /**
+   * List user-linked methods
+   */
+  public async listLinkedMethods(presentationKey: string) {
+    const res = await fetch(`${this.serverUrl}/user/linkedMethods`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ presentationKey })
+    })
+    return res.json()
+  }
+
+  /**
+   * Unlink a given Auth Method by ID
+   */
+  public async unlinkMethod(presentationKey: string, authMethodId: number) {
+    const res = await fetch(`${this.serverUrl}/user/unlinkMethod`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ presentationKey, authMethodId })
+    })
+    return res.json()
+  }
+
+  /**
+   * Request faucet
+   */
+  public async requestFaucet(presentationKey: string) {
+    const res = await fetch(`${this.serverUrl}/faucet/request`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ presentationKey })
+    })
+    return res.json()
+  }
+
+  /**
+   * Delete user
+   */
+  public async deleteUser(presentationKey: string) {
+    const res = await fetch(`${this.serverUrl}/user/delete`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ presentationKey })
+    })
+    return res.json()
+  }
+}

package/src/wab-client/__tests/WABClient.test.ts

@@ -0,0 +1,58 @@
+import { WABClient } from '../WABClient'
+import { TwilioPhoneInteractor } from '../auth-method-interactors/TwilioPhoneInteractor'
+
+// This test suite requires the WAB server to be running on localhost:3000 or you can
+// spin up a test environment or mock server. For demonstration, we'll keep it simple.
+
+describe('WABClient', () => {
+  let client: WABClient
+  const serverUrl = 'http://localhost:3000' // Adjust if your server is different
+  const testPresentationKey = 'clientTestKey' + Date.now()
+
+  beforeAll(() => {
+    client = new WABClient(serverUrl)
+  })
+
+  it('should get server info', async () => {
+    const info = await client.getInfo()
+    expect(info.supportedAuthMethods).toContain('TwilioPhone')
+  })
+
+  it('should do Twilio phone flow', async () => {
+    const twilio = new TwilioPhoneInteractor()
+
+    const startRes = await client.startAuthMethod(twilio, testPresentationKey, {
+      phoneNumber: '+12223334444'
+    })
+    expect(startRes.success).toBe(true)
+
+    const completeRes = await client.completeAuthMethod(
+      twilio,
+      testPresentationKey,
+      {
+        otp: '123456',
+        phoneNumber: '+12223334444'
+      }
+    )
+    expect(completeRes.success).toBe(true)
+    expect(completeRes.presentationKey).toBe(testPresentationKey)
+  })
+
+  it('should request faucet', async () => {
+    const faucetRes = await client.requestFaucet(testPresentationKey)
+    expect(faucetRes.success).toBe(true)
+    expect(faucetRes.paymentData).toBeDefined()
+    expect(faucetRes.paymentData.amount).toBe(1000)
+  })
+
+  it('should list linked methods', async () => {
+    const linked = await client.listLinkedMethods(testPresentationKey)
+    expect(linked.authMethods).toHaveLength(1)
+    expect(linked.authMethods[0].methodType).toBe('TwilioPhone')
+  })
+
+  it('can delete user', async () => {
+    const del = await client.deleteUser(testPresentationKey)
+    expect(del.success).toBe(true)
+  })
+})

package/src/wab-client/auth-method-interactors/AuthMethodInteractor.ts

@@ -0,0 +1,47 @@
+/**
+ * AuthMethodInteractor
+ *
+ * A base interface/class for client-side logic to interact with a server
+ * for a specific Auth Method's flow (start, complete).
+ */
+
+export interface AuthPayload {
+  [key: string]: any
+}
+
+export interface StartAuthResponse {
+  success: boolean
+  message?: string
+  data?: any
+}
+
+export interface CompleteAuthResponse {
+  success: boolean
+  message?: string
+  presentationKey?: string
+}
+
+/**
+ * Abstract client-side interactor for an Auth Method
+ */
+export abstract class AuthMethodInteractor {
+  public abstract methodType: string
+
+  /**
+   * Start the flow (e.g. request an OTP or create a session).
+   */
+  public abstract startAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<StartAuthResponse>
+
+  /**
+   * Complete the flow (e.g. confirm OTP).
+   */
+  public abstract completeAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<CompleteAuthResponse>
+}

package/src/wab-client/auth-method-interactors/PersonaIDInteractor.ts

@@ -0,0 +1,45 @@
+import {
+  AuthMethodInteractor,
+  AuthPayload,
+  StartAuthResponse,
+  CompleteAuthResponse
+} from './AuthMethodInteractor'
+import fetch from 'node-fetch'
+
+export class PersonaIDInteractor extends AuthMethodInteractor {
+  public methodType = 'PersonaID'
+
+  public async startAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<StartAuthResponse> {
+    const res = await fetch(`${serverUrl}/auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType: this.methodType,
+        presentationKey,
+        payload
+      })
+    })
+    return res.json()
+  }
+
+  public async completeAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<CompleteAuthResponse> {
+    const res = await fetch(`${serverUrl}/auth/complete`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType: this.methodType,
+        presentationKey,
+        payload
+      })
+    })
+    return res.json()
+  }
+}

package/src/wab-client/auth-method-interactors/TwilioPhoneInteractor.ts

@@ -0,0 +1,82 @@
+import {
+  AuthMethodInteractor,
+  AuthPayload,
+  StartAuthResponse,
+  CompleteAuthResponse
+} from './AuthMethodInteractor'
+import fetch from 'node-fetch'
+
+/**
+ * TwilioPhoneInteractor
+ *
+ * A client-side class that knows how to call the WAB server for Twilio-based phone verification.
+ */
+export class TwilioPhoneInteractor extends AuthMethodInteractor {
+  public methodType = 'TwilioPhone'
+
+  /**
+   * Start the Twilio phone verification on the server.
+   * - The server will send an SMS code to the user’s phone, using Twilio Verify.
+   * @param serverUrl         - The base URL of the WAB server (e.g. http://localhost:3000)
+   * @param presentationKey   - The 256-bit key the client is attempting to authenticate with
+   * @param payload           - { phoneNumber: string } (the phone number to verify)
+   * @returns                 - { success, message, data }
+   */
+  public async startAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<StartAuthResponse> {
+    const res = await fetch(`${serverUrl}/auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType: this.methodType,
+        presentationKey,
+        payload
+      })
+    })
+
+    if (!res.ok) {
+      return {
+        success: false,
+        message: `HTTP error ${res.status}`
+      }
+    }
+
+    return res.json()
+  }
+
+  /**
+   * Complete the Twilio phone verification on the server.
+   * - The server will verify the code with Twilio Verify’s verificationChecks endpoint.
+   * @param serverUrl         - The base URL of the WAB server
+   * @param presentationKey   - The 256-bit key
+   * @param payload           - { phoneNumber: string, otp: string } (the code that was received via SMS)
+   * @returns                 - { success, message, presentationKey }
+   */
+  public async completeAuth(
+    serverUrl: string,
+    presentationKey: string,
+    payload: AuthPayload
+  ): Promise<CompleteAuthResponse> {
+    const res = await fetch(`${serverUrl}/auth/complete`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType: this.methodType,
+        presentationKey,
+        payload
+      })
+    })
+
+    if (!res.ok) {
+      return {
+        success: false,
+        message: `HTTP error ${res.status}`
+      }
+    }
+
+    return res.json()
+  }
+}

package/out/test/wallet/action/abortAction.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"abortAction.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/action/abortAction.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/action/createAction.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createAction.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/action/createAction.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/action/createActionToGenerateBeefs.man.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createActionToGenerateBeefs.man.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/action/createActionToGenerateBeefs.man.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/action/internalizeAction.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"internalizeAction.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/action/internalizeAction.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/action/relinquishOutput.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"relinquishOutput.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/action/relinquishOutput.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/construct/Wallet.constructor.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Wallet.constructor.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/construct/Wallet.constructor.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/list/listActions.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listActions.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/list/listActions.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/list/listActions2.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listActions2.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/list/listActions2.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/list/listCertificates.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listCertificates.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/list/listCertificates.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/list/listOutputs.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listOutputs.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/list/listOutputs.test.ts"],"names":[],"mappings":""}

package/out/test/wallet/sync/Wallet.sync.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Wallet.sync.test.d.ts","sourceRoot":"","sources":["../../../../test/wallet/sync/Wallet.sync.test.ts"],"names":[],"mappings":""}