@bsv/wallet-toolbox 1.1.0

package/src/sdk/WalletStorage.interfaces.ts

@@ -0,0 +1,416 @@
+import {
+  AbortActionArgs,
+  AbortActionResult,
+  Beef,
+  InternalizeActionArgs,
+  InternalizeActionResult,
+  ListActionsArgs,
+  ListActionsResult,
+  ListCertificatesResult,
+  ListOutputsArgs,
+  ListOutputsResult,
+  RelinquishCertificateArgs,
+  RelinquishOutputArgs,
+  SendWithResult
+} from '@bsv/sdk'
+import { sdk, table } from '../index.client'
+
+/**
+ * This is the `WalletStorage` interface implemented by a class such as `WalletStorageManager`,
+ * which manges an active and set of backup storage providers.
+ *
+ * Access and conrol is not directly managed. Typically each request is made with an associated identityKey
+ * and it is left to the providers: physical access or remote channel authentication.
+ */
+export interface WalletStorage {
+  /**
+   * @returns false
+   */
+  isStorageProvider(): boolean
+
+  isAvailable(): boolean
+  makeAvailable(): Promise<table.Settings>
+  migrate(storageName: string, storageIdentityKey: string): Promise<string>
+  destroy(): Promise<void>
+
+  setServices(v: sdk.WalletServices): void
+  getServices(): sdk.WalletServices
+  getSettings(): table.Settings
+
+  getAuth(): Promise<sdk.AuthId>
+
+  findOrInsertUser(
+    identityKey: string
+  ): Promise<{ user: table.User; isNew: boolean }>
+
+  abortAction(args: AbortActionArgs): Promise<AbortActionResult>
+  createAction(
+    args: sdk.ValidCreateActionArgs
+  ): Promise<sdk.StorageCreateActionResult>
+  processAction(
+    args: sdk.StorageProcessActionArgs
+  ): Promise<sdk.StorageProcessActionResults>
+  internalizeAction(
+    args: InternalizeActionArgs
+  ): Promise<InternalizeActionResult>
+
+  findCertificates(args: sdk.FindCertificatesArgs): Promise<table.Certificate[]>
+  findOutputBaskets(
+    args: sdk.FindOutputBasketsArgs
+  ): Promise<table.OutputBasket[]>
+  findOutputs(args: sdk.FindOutputsArgs): Promise<table.Output[]>
+  findProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<table.ProvenTxReq[]>
+
+  listActions(args: ListActionsArgs): Promise<ListActionsResult>
+  listCertificates(
+    args: sdk.ValidListCertificatesArgs
+  ): Promise<ListCertificatesResult>
+  listOutputs(args: ListOutputsArgs): Promise<ListOutputsResult>
+
+  insertCertificate(certificate: table.CertificateX): Promise<number>
+
+  relinquishCertificate(args: RelinquishCertificateArgs): Promise<number>
+  relinquishOutput(args: RelinquishOutputArgs): Promise<number>
+}
+
+/**
+ * This is the `WalletStorage` interface implemented with authentication checking and
+ * is the actual minimal interface implemented by storage and remoted storage providers.
+ */
+export interface WalletStorageProvider extends WalletStorageSync {
+  /**
+   * @returns true if this object's interface can be extended to the full `StorageProvider` interface
+   */
+  isStorageProvider(): boolean
+  setServices(v: sdk.WalletServices): void
+}
+
+export interface WalletStorageSync extends WalletStorageWriter {
+  findOrInsertSyncStateAuth(
+    auth: sdk.AuthId,
+    storageIdentityKey: string,
+    storageName: string
+  ): Promise<{ syncState: table.SyncState; isNew: boolean }>
+
+  setActive(
+    auth: sdk.AuthId,
+    newActiveStorageIdentityKey: string
+  ): Promise<number>
+
+  getSyncChunk(args: sdk.RequestSyncChunkArgs): Promise<sdk.SyncChunk>
+  processSyncChunk(
+    args: sdk.RequestSyncChunkArgs,
+    chunk: sdk.SyncChunk
+  ): Promise<sdk.ProcessSyncChunkResult>
+}
+
+export interface WalletStorageWriter extends WalletStorageReader {
+  makeAvailable(): Promise<table.Settings>
+  migrate(storageName: string, storageIdentityKey: string): Promise<string>
+  destroy(): Promise<void>
+
+  findOrInsertUser(
+    identityKey: string
+  ): Promise<{ user: table.User; isNew: boolean }>
+
+  abortAction(
+    auth: sdk.AuthId,
+    args: AbortActionArgs
+  ): Promise<AbortActionResult>
+  createAction(
+    auth: sdk.AuthId,
+    args: sdk.ValidCreateActionArgs
+  ): Promise<sdk.StorageCreateActionResult>
+  processAction(
+    auth: sdk.AuthId,
+    args: sdk.StorageProcessActionArgs
+  ): Promise<sdk.StorageProcessActionResults>
+  internalizeAction(
+    auth: sdk.AuthId,
+    args: InternalizeActionArgs
+  ): Promise<InternalizeActionResult>
+
+  insertCertificateAuth(
+    auth: sdk.AuthId,
+    certificate: table.CertificateX
+  ): Promise<number>
+
+  relinquishCertificate(
+    auth: sdk.AuthId,
+    args: RelinquishCertificateArgs
+  ): Promise<number>
+  relinquishOutput(
+    auth: sdk.AuthId,
+    args: RelinquishOutputArgs
+  ): Promise<number>
+}
+
+export interface WalletStorageReader {
+  isAvailable(): boolean
+
+  getServices(): sdk.WalletServices
+  getSettings(): table.Settings
+
+  findCertificatesAuth(
+    auth: sdk.AuthId,
+    args: sdk.FindCertificatesArgs
+  ): Promise<table.Certificate[]>
+  findOutputBasketsAuth(
+    auth: sdk.AuthId,
+    args: sdk.FindOutputBasketsArgs
+  ): Promise<table.OutputBasket[]>
+  findOutputsAuth(
+    auth: sdk.AuthId,
+    args: sdk.FindOutputsArgs
+  ): Promise<table.Output[]>
+  findProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<table.ProvenTxReq[]>
+
+  listActions(
+    auth: sdk.AuthId,
+    vargs: sdk.ValidListActionsArgs
+  ): Promise<ListActionsResult>
+  listCertificates(
+    auth: sdk.AuthId,
+    vargs: sdk.ValidListCertificatesArgs
+  ): Promise<ListCertificatesResult>
+  listOutputs(
+    auth: sdk.AuthId,
+    vargs: sdk.ValidListOutputsArgs
+  ): Promise<ListOutputsResult>
+}
+
+export interface AuthId {
+  identityKey: string
+  userId?: number
+  isActive?: boolean
+}
+
+export interface FindSincePagedArgs {
+  since?: Date
+  paged?: sdk.Paged
+  trx?: sdk.TrxToken
+}
+
+export interface FindForUserSincePagedArgs extends FindSincePagedArgs {
+  userId: number
+}
+
+export interface FindPartialSincePagedArgs<T extends object>
+  extends FindSincePagedArgs {
+  partial: Partial<T>
+}
+
+export interface FindCertificatesArgs extends FindSincePagedArgs {
+  partial: Partial<table.Certificate>
+  certifiers?: string[]
+  types?: string[]
+  includeFields?: boolean
+}
+
+export interface FindOutputBasketsArgs extends FindSincePagedArgs {
+  partial: Partial<table.OutputBasket>
+}
+
+export interface FindOutputsArgs extends FindSincePagedArgs {
+  partial: Partial<table.Output>
+  noScript?: boolean
+  txStatus?: sdk.TransactionStatus[]
+}
+
+export type StorageProvidedBy = 'you' | 'storage' | 'you-and-storage'
+
+export interface StorageCreateTransactionSdkInput {
+  vin: number
+  sourceTxid: string
+  sourceVout: number
+  sourceSatoshis: number
+  sourceLockingScript: string
+  unlockingScriptLength: number
+  providedBy: StorageProvidedBy
+  type: string
+  spendingDescription?: string
+  derivationPrefix?: string
+  derivationSuffix?: string
+  senderIdentityKey?: string
+}
+
+export interface StorageCreateTransactionSdkOutput
+  extends sdk.ValidCreateActionOutput {
+  vout: number
+  providedBy: StorageProvidedBy
+  purpose?: string
+  derivationSuffix?: string
+}
+
+export interface StorageCreateActionResult {
+  inputBeef?: number[]
+  inputs: StorageCreateTransactionSdkInput[]
+  outputs: StorageCreateTransactionSdkOutput[]
+  noSendChangeOutputVouts?: number[]
+  derivationPrefix: string
+  version: number
+  lockTime: number
+  reference: string
+}
+
+export interface StorageProcessActionArgs {
+  isNewTx: boolean
+  isSendWith: boolean
+  isNoSend: boolean
+  isDelayed: boolean
+  reference?: string
+  txid?: string
+  rawTx?: number[]
+  sendWith: string[]
+  log?: string
+}
+
+export interface StorageProcessActionResults {
+  sendWithResults?: SendWithResult[]
+  log?: string
+}
+
+export interface ProvenOrRawTx {
+  proven?: table.ProvenTx
+  rawTx?: number[]
+  inputBEEF?: number[]
+}
+
+export interface PurgeParams {
+  purgeCompleted: boolean
+  purgeFailed: boolean
+  purgeSpent: boolean
+
+  /**
+   * Minimum age in msecs for transient completed transaction data purge.
+   * Default is 14 days.
+   */
+  purgeCompletedAge?: number
+  /**
+   * Minimum age in msecs for failed transaction data purge.
+   * Default is 14 days.
+   */
+  purgeFailedAge?: number
+  /**
+   * Minimum age in msecs for failed transaction data purge.
+   * Default is 14 days.
+   */
+  purgeSpentAge?: number
+}
+
+export interface PurgeResults {
+  count: number
+  log: string
+}
+
+export interface StorageProvenOrReq {
+  proven?: table.ProvenTx
+  req?: table.ProvenTxReq
+}
+
+/**
+ * Specifies the available options for computing transaction fees.
+ */
+export interface StorageFeeModel {
+  /**
+   * Available models. Currently only "sat/kb" is supported.
+   */
+  model: 'sat/kb'
+  /**
+   * When "fee.model" is "sat/kb", this is an integer representing the number of satoshis per kb of block space
+   * the transaction will pay in fees.
+   *
+   * If undefined, the default value is used.
+   */
+  value?: number
+}
+
+export interface StorageGetBeefOptions {
+  /** if 'known', txids known to local storage as valid are included as txidOnly */
+  trustSelf?: 'known'
+  /** list of txids to be included as txidOnly if referenced. Validity is known to caller. */
+  knownTxids?: string[]
+  /** optional. If defined, raw transactions and merkle paths required by txid are merged to this instance and returned. Otherwise a new Beef is constructed and returned. */
+  mergeToBeef?: Beef | number[]
+  /** optional. Default is false. `storage` is used for raw transaction and merkle proof lookup */
+  ignoreStorage?: boolean
+  /** optional. Default is false. `getServices` is used for raw transaction and merkle proof lookup */
+  ignoreServices?: boolean
+  /** optional. Default is false. If true, raw transactions with proofs missing from `storage` and obtained from `getServices` are not inserted to `storage`. */
+  ignoreNewProven?: boolean
+  /** optional. Default is zero. Ignores available merkle paths until recursion detpth equals or exceeds value  */
+  minProofLevel?: number
+}
+
+export interface StorageSyncReaderOptions {
+  chain: sdk.Chain
+}
+
+export interface FindCertificateFieldsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.CertificateField>
+}
+
+export interface FindCommissionsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.Commission>
+}
+export interface FindOutputTagMapsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.OutputTagMap>
+  tagIds?: number[]
+}
+export interface FindOutputTagsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.OutputTag>
+}
+export interface FindProvenTxReqsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.ProvenTxReq>
+  status?: sdk.ProvenTxReqStatus[]
+  txids?: string[]
+}
+export interface FindProvenTxsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.ProvenTx>
+}
+export interface FindSyncStatesArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.SyncState>
+}
+export interface FindTransactionsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.Transaction>
+  status?: sdk.TransactionStatus[]
+  noRawTx?: boolean
+}
+export interface FindTxLabelMapsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.TxLabelMap>
+  labelIds?: number[]
+}
+export interface FindTxLabelsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.TxLabel>
+}
+export interface FindUsersArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.User>
+}
+export interface FindMonitorEventsArgs extends sdk.FindSincePagedArgs {
+  partial: Partial<table.MonitorEvent>
+}
+/**
+ * Place holder for the transaction control object used by actual storage provider implementation.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface TrxToken {}
+
+export interface UpdateProvenTxReqWithNewProvenTxArgs {
+  provenTxReqId: number
+  txid: string
+  attempts: number
+  status: sdk.ProvenTxReqStatus
+  history: string
+  height: number
+  index: number
+  blockHash: string
+  merkleRoot: string
+  merklePath: number[]
+}
+
+export interface UpdateProvenTxReqWithNewProvenTxResult {
+  status: sdk.ProvenTxReqStatus
+  history: string
+  provenTxId: number
+  log?: string
+}

package/src/sdk/__test/CertificateLifeCycle.test.ts

@@ -0,0 +1,194 @@
+import {
+  Certificate as BsvCertificate,
+  CompletedProtoWallet,
+  KeyDeriver,
+  MasterCertificate,
+  PrivateKey,
+  Utils,
+  WalletCertificate
+} from '@bsv/sdk'
+import { sdk } from '../../index.all'
+
+describe('CertificateLifeCycle tests', () => {
+  jest.setTimeout(99999999)
+
+  test('0 encrypt decrypt sign verify', async () => {
+    const subjectWallet = new CompletedProtoWallet(PrivateKey.fromRandom())
+    const { cert, certifier, subject } = makeSampleCert(
+      subjectWallet.keyDeriver.rootKey.toString()
+    )
+
+    const c = new BsvCertificate(
+      cert.type,
+      cert.serialNumber,
+      cert.subject,
+      cert.certifier,
+      cert.revocationOutpoint,
+      cert.fields
+    )
+
+    const certifierWallet = new CompletedProtoWallet(certifier)
+
+    const imc = await MasterCertificate.issueCertificateForSubject(
+      certifierWallet,
+      c.subject,
+      c.fields,
+      c.type,
+      async () => c.revocationOutpoint
+    )
+    const imcSignature = imc.signature
+    await expect(imc.sign(certifierWallet)).rejects.toThrow(
+      'Certificate has already been signed'
+    )
+    expect(imcSignature).toBeTruthy()
+    expect(imcSignature).toBe(imc.signature)
+    const imcVerified = await imc.verify()
+    expect(imcVerified).toBe(true)
+    const dfs = await MasterCertificate.decryptFields(
+      subjectWallet,
+      imc.masterKeyring,
+      imc.fields,
+      (await certifierWallet.getPublicKey({ identityKey: true })).publicKey
+    )
+    for (const fn of Object.keys(cert.fields)) {
+      // decrypted fields should be original un-encrypted fields
+      expect(cert.fields[fn]).toBe(dfs[fn])
+      // issued certificate fields should encrypted, not the original un-encrypted fields
+      expect(cert.fields[fn]).not.toBe(imc.fields[fn])
+    }
+
+    await c.sign(certifierWallet)
+    const verified = await c.verify()
+    expect(verified).toBe(true)
+
+    const co = new sdk.CertOps(certifierWallet, cert)
+
+    expect(co.signature).toBe('')
+    await expect(co.verify()).rejects.toThrow(
+      'Signature DER must start with 0x30'
+    )
+    await co.sign(new CompletedProtoWallet(new KeyDeriver(certifier)))
+    expect(await co.verify()).toBe(true)
+
+    {
+      await co.encryptFields(subject.toPublicKey().toString())
+      await expect(co.verify()).rejects.toThrow('Signature is not valid')
+      co.signature = undefined
+      await co.sign(new CompletedProtoWallet(new KeyDeriver(certifier)))
+      expect(await co.verify()).toBe(true)
+    }
+
+    await co.decryptFields()
+    for (const n of Object.keys(co.fields)) {
+      expect(co.fields[n]).toBe(co._decryptedFields![n])
+    }
+
+    {
+      await co.encryptFields()
+      const crypto2 = new CompletedProtoWallet(
+        new KeyDeriver(PrivateKey.fromHex('2'.repeat(64)))
+      )
+      const co2 = new sdk.CertOps(crypto2, co.toWalletCertificate())
+      // even with the keyring, without the right crypto root key decryption will fail.
+      co2._keyring = co._keyring
+      await expect(co2.decryptFields()).rejects.toThrow('Decryption failed!')
+    }
+  })
+
+  test('1 createKeyringForVerifier', async () => {
+    const { cert, certifier, subject } = makeSampleCert()
+
+    const crypto = new CompletedProtoWallet(subject)
+    const co = new sdk.CertOps(crypto, cert)
+  })
+
+  test('2 complete flow', async () => {
+    // Issuer beging with an un-encrypted (decrypted) raw certificate template:
+    // The public keys of both the certifier (the authority issuing the certificate),
+    // and the subject (who the certificate pertains to) are included in the certificate.
+    const { cert, certifier, subject } = makeSampleCert()
+
+    // Next the certifier must encrypt the field values for privacy and sign the certificate
+    // such that the values it contains can be attributed to the certifier through its public key.
+    // Encryption is done with random symmetric keys and the keys are then encrypted by the certifier
+    // such that each key can also be decrypted by the subject:
+    const certifierWallet = new CompletedProtoWallet(certifier)
+    const co = new sdk.CertOps(certifierWallet, cert)
+
+    await co.encryptAndSignNewCertificate()
+
+    // Grab a copy of the certificate to send to the subject
+    const exportForSubject = co.exportForSubject()
+
+    // The subject imports their copy of the new certificate:
+    const subjectWallet = new CompletedProtoWallet(subject)
+    const cs = await sdk.CertOps.fromCertifier(subjectWallet, exportForSubject)
+
+    // The subject's imported certificate should verify
+    expect(await cs.verify()).toBe(true)
+
+    // Confirm subject can decrypt the certifier's copy of the cert:
+    await co.decryptFields(subject.toPublicKey().toString())
+
+    // Confirm subject can decrypt their own copy of the cert:
+    await cs.decryptFields(cs.certifier, co._keyring)
+
+    // Restore the encrypted field values.
+    cs.fields = cs._encryptedFields!
+
+    // Prepare to send certificate to third party veifier of the 'name' and 'email' fields.
+    // The verifier must be able to confirm the signature on the original certificate's encrypted values.
+    // And then use a keyRing that their public key will work to reveal decrypted values for 'name' and 'email' only.
+    const verifier = PrivateKey.fromRandom()
+    // subject makes a keyring for the verifier
+    const exportForVerifier = await cs.exportForCounterparty(
+      verifier.toPublicKey().toString(),
+      ['name', 'email']
+    )
+
+    // The verifier uses their own wallet to import the certificate, verify it, and decrypt their designated fields.
+    const verifierWallet = new CompletedProtoWallet(verifier)
+    const cv = await sdk.CertOps.fromCounterparty(
+      verifierWallet,
+      exportForVerifier
+    )
+
+    // verifier must check that the certifier's public key generates a matching signature over all the encrypted
+    // certificate field values before using their keyring to decrypt the fields they've been authorized to see.
+    expect(await cv.verify()).toBe(true)
+
+    // The wallet's private key is the verifier's, so the counterparty is the certificate subject (who sent the cert to verifier).
+    // This decrypt is using the keyring provided for verification by the subject.
+    await cv.decryptFields()
+    expect(cv.fields['name']).toBe('Alice')
+    expect(cv.fields['email']).toBe('alice@example.com')
+    expect(cv.fields['organization']).not.toBe('Example Corp')
+  })
+})
+
+function makeSampleCert(subjectRootKeyHex?: string): {
+  cert: WalletCertificate
+  subject: PrivateKey
+  certifier: PrivateKey
+} {
+  const subject = subjectRootKeyHex
+    ? PrivateKey.fromString(subjectRootKeyHex)
+    : PrivateKey.fromRandom()
+  const certifier = PrivateKey.fromRandom()
+  const verifier = PrivateKey.fromRandom()
+  const cert: WalletCertificate = {
+    type: Utils.toBase64(new Array(32).fill(1)),
+    serialNumber: Utils.toBase64(new Array(32).fill(2)),
+    revocationOutpoint:
+      'deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef.1',
+    subject: subject.toPublicKey().toString(),
+    certifier: certifier.toPublicKey().toString(),
+    fields: {
+      name: 'Alice',
+      email: 'alice@example.com',
+      organization: 'Example Corp'
+    },
+    signature: ''
+  }
+  return { cert, subject, certifier }
+}