@bsv/sdk 1.1.5 → 1.1.7

package/src/totp/__tests/totp.test.ts

@@ -0,0 +1,80 @@
+import { toArray } from "../../../dist/cjs/src/primitives/utils.js";
+import { TOTP } from "../../../dist/cjs/src/totp/totp.js";
+
+const secret = toArray("48656c6c6f21deadbeef", 'hex');
+const period = 30; //sec
+const periodMS = 30 * 1000; //ms
+const options = {
+  digits: 6,
+  period,
+  algorithm: "SHA-1",
+};
+
+describe("totp generation and validation", () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.resetAllMocks());
+
+  test.each([
+    {
+      time: 0,
+      expected: "282760",
+      description: "should generate token at Unix epoch start",
+    },
+    {
+      time: 1465324707000,
+      expected: "341128",
+      description: "should generate token for a specific timestamp in 2016",
+    },
+    {
+      time: 1665644340000 + 1,
+      expected: "886842",
+      description: "should generate correct token at the start of the cycle",
+    },
+    {
+      time: 1665644340000 - 1,
+      expected: "134996",
+      description: "should generate correct token at the end of the cycle",
+    },
+    {
+      time: 1365324707000,
+      expected: "089029",
+      description: "should generate token with a leading zero",
+    },
+  ])("$description", async ({ time, expected }) => {
+    jest.setSystemTime(time);
+
+    //check if expected passcode is generated
+    const passcode = TOTP.generate(secret, options);
+    expect(passcode).toEqual(expected);
+
+    expect(TOTP.validate(secret, "000000", options)).toEqual(false); //this passcode should not be valid for any of above test cases
+
+    //should not be valid for only a part of passcode
+    expect(TOTP.validate(secret, passcode.slice(1), options)).toEqual(false);
+
+    expect(TOTP.validate(secret, passcode, options)).toEqual(true);
+
+    const checkAdjacentWindow = (
+      timeOfGeneration: number,
+      expected: boolean
+    ) => {
+      jest.setSystemTime(timeOfGeneration);
+      const adjacentTimewindowPasscode = TOTP.generate(secret, options);
+
+      jest.setSystemTime(time);
+      expect(
+        TOTP.validate(secret, adjacentTimewindowPasscode, options)
+      ).toEqual(expected);
+    };
+
+    //because the 'skew' is '1' by default, the passcode for the next window also should be valid
+    checkAdjacentWindow(time + periodMS, true);
+    checkAdjacentWindow(time - periodMS, true);
+
+    //for 'skew': 1, other passcodes for further timewindows should not be valid
+    for (let i = 2; i < 10; i++) {
+      checkAdjacentWindow(time + i * periodMS, false);
+      checkAdjacentWindow(time - i * periodMS, false);
+    }
+  });
+});

package/src/totp/index.ts

@@ -0,0 +1 @@
+export * from './totp.js'

package/src/totp/totp.ts

@@ -0,0 +1,142 @@
+import { SHA1HMAC, SHA256HMAC, SHA512HMAC } from '../primitives/Hash.js'
+import BigNumber from '../primitives/BigNumber.js'
+
+export type TOTPAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-512'
+
+/**
+ * Options for TOTP generation.
+ * @param {number} [digits=6] - The number of digits in the OTP.
+ * @param {TOTPAlgorithm} [algorithm="SHA-1"] - Algorithm used for hashing.
+ * @param {number} [period=30] - The time period for OTP validity in seconds.
+ * @param {number} [timestamp=Date.now()] - The current timestamp.
+ */
+export interface TOTPOptions {
+  digits?: number
+  algorithm?: TOTPAlgorithm
+  period?: number
+  timestamp?: number
+}
+
+/**
+ * Options for TOTP validation.
+ * @param {number} [skew=1] - The number of time periods to check before and after the current time period.
+ */
+export type TOTPValidateOptions = TOTPOptions & {
+  skew?: number
+}
+
+export class TOTP {
+  /**
+   * Generates a Time-based One-Time Password (TOTP).
+   * @param {number[]} secret - The secret key for TOTP.
+   * @param {TOTPOptions} options - Optional parameters for TOTP.
+   * @returns {string} The generated TOTP.
+   */
+  static generate (secret: number[], options?: TOTPOptions): string {
+    const _options = this.withDefaultOptions(options)
+
+    const counter = this.getCounter(_options.timestamp, _options.period)
+    const otp = generateHOTP(secret, counter, _options)
+    return otp
+  }
+
+  /**
+   * Validates a Time-based One-Time Password (TOTP).
+   * @param {number[]} secret - The secret key for TOTP.
+   * @param {string} passcode - The passcode to validate.
+   * @param {TOTPValidateOptions} options - Optional parameters for TOTP validation.
+   * @returns {boolean} A boolean indicating whether the passcode is valid.
+   */
+  static validate (
+    secret: number[],
+    passcode: string,
+    options?: TOTPValidateOptions
+  ): boolean {
+    const _options = this.withDefaultValidateOptions(options)
+    passcode = passcode.trim()
+    if (passcode.length != _options.digits) {
+      return false
+    }
+
+    const counter = this.getCounter(_options.timestamp, _options.period)
+
+    const counters = [counter]
+    for (let i = 1; i <= _options.skew; i++) {
+      counters.push(counter + i)
+      counters.push(counter - i)
+    }
+
+    for (const c of counters) {
+      if (passcode === generateHOTP(secret, c, _options)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  private static getCounter (timestamp: number, period: number): number {
+    const epochSeconds = Math.floor(timestamp / 1000)
+    const counter = Math.floor(epochSeconds / period)
+    return counter
+  }
+
+  private static withDefaultOptions (
+    options?: TOTPOptions
+  ): Required<TOTPOptions> {
+    return {
+      digits: 2,
+      algorithm: 'SHA-1',
+      period: 30,
+      timestamp: Date.now(),
+      ...options
+    }
+  }
+
+  private static withDefaultValidateOptions (
+    options?: TOTPValidateOptions
+  ): Required<TOTPValidateOptions> {
+    return { skew: 1, ...this.withDefaultOptions(options) }
+  }
+}
+
+function generateHOTP (
+  secret: number[],
+  counter: number,
+  options: Required<TOTPOptions>
+): string {
+  const timePad = new BigNumber(counter).toArray('be', 8)
+  console.log({ timePad })
+  const hmac = calcHMAC(secret, timePad, options.algorithm)
+
+  const signature = hmac.digest()
+  const signatureHex = hmac.digestHex()
+
+  // RFC 4226 https://datatracker.ietf.org/doc/html/rfc4226#section-5.4
+  const offset = signature[signature.length - 1] & 0x0f // offset is the last byte in the hmac
+  const fourBytesRange = signature.slice(offset, offset + 4) // starting from offset, get 4 bytes
+  const mask = 0x7fffffff // 32-bit number with a leading 0 followed by 31 ones [0111 (...) 1111]
+  const masked = new BigNumber(fourBytesRange).toNumber() & mask
+
+  console.log({ signatureHex, signature, offset, fourBytesRange, mask, masked })
+
+  const otp = masked.toString().slice(-options.digits)
+  return otp
+}
+
+function calcHMAC (
+  secret: number[],
+  timePad: number[],
+  algorithm: TOTPAlgorithm
+) {
+  switch (algorithm) {
+    case 'SHA-1':
+      return new SHA1HMAC(secret).update(timePad)
+    case 'SHA-256':
+      return new SHA256HMAC(secret).update(timePad)
+    case 'SHA-512':
+      return new SHA512HMAC(secret).update(timePad)
+    default:
+      throw new Error('unsupported HMAC algorithm')
+  }
+}

package/src/transaction/MerklePath.ts

@@ -3,10 +3,10 @@ import { hash256 } from '../primitives/Hash.js'
 import ChainTracker from './ChainTracker.js'
 
 export interface MerklePathLeaf {
-    offset: number
-    hash?: string
-    txid?: boolean
-    duplicate?: boolean
+  offset: number
+  hash?: string
+  txid?: boolean
+  duplicate?: boolean
 }
 
 /**
@@ -218,13 +218,13 @@ export default class MerklePath {
 
   /**
    * Find leaf with `offset` at `height` or compute from level below, recursively.
-   * 
+   *
    * Does not add computed leaves to path.
-   * 
+   *
    * @param height
-   * @param offset 
+   * @param offset
    */
-  findOrComputeLeaf(height: number, offset: number) : MerklePathLeaf | undefined {
+  findOrComputeLeaf (height: number, offset: number): MerklePathLeaf | undefined {
     const hash = (m: string): string => toHex((
       hash256(toArray(m, 'hex').reverse())
     ).reverse())
@@ -245,10 +245,7 @@ export default class MerklePath {
     if (!leaf1) return undefined
 
     let workinghash: string
-    if (leaf1.duplicate)
-      workinghash = hash(leaf0.hash + leaf0.hash)
-    else
-      workinghash = hash(leaf1.hash + leaf0.hash)
+    if (leaf1.duplicate) { workinghash = hash(leaf0.hash + leaf0.hash) } else { workinghash = hash(leaf1.hash + leaf0.hash) }
     leaf = {
       offset,
       hash: workinghash
@@ -312,21 +309,19 @@ export default class MerklePath {
    * Assumes that at least all required nodes are present.
    * Leaves all levels sorted by increasing offset.
    */
-  trim() {
+  trim () {
     const pushIfNew = (v: number, a: number[]) => {
-      if (a.length === 0 || a.slice(-1)[0] !== v)
-        a.push(v)
+      if (a.length === 0 || a.slice(-1)[0] !== v) { a.push(v) }
     }
 
     const dropOffsetsFromLevel = (dropOffsets: number[], level: number) => {
       for (let i = dropOffsets.length; i >= 0; i--) {
         const l = this.path[level].findIndex(n => n.offset === dropOffsets[i])
-        if (l >= 0)
-          this.path[level].splice(l, 1)
+        if (l >= 0) { this.path[level].splice(l, 1) }
       }
     }
 
-    const nextComputedOffsets = (cos: number[]) : number[] => {
+    const nextComputedOffsets = (cos: number[]): number[] => {
       const ncos: number[] = []
       for (const o of cos) {
         pushIfNew(o >> 1, ncos)
@@ -334,25 +329,25 @@ export default class MerklePath {
       return ncos
     }
 
-    let computedOffsets: number[] = []; // in next level
+    let computedOffsets: number[] = [] // in next level
     let dropOffsets: number[] = []
     for (let h = 0; h < this.path.length; h++) {
       // Sort each level by increasing offset order
       this.path[h].sort((a, b) => a.offset - b.offset)
     }
     for (let l = 0; l < this.path[0].length; l++) {
-        const n = this.path[0][l]
-        if (n.txid) {
-            // level 0 must enable computing level 1 for txid nodes
-            pushIfNew(n.offset >> 1, computedOffsets)
-        } else {
-            const isOdd = n.offset % 2 === 1
-            const peer = this.path[0][l + (isOdd ? -1 : 1)]
-            if (!peer.txid) {
-                // drop non-txid level 0 nodes without a txid peer
-                pushIfNew(peer.offset, dropOffsets)
-            }
+      const n = this.path[0][l]
+      if (n.txid) {
+        // level 0 must enable computing level 1 for txid nodes
+        pushIfNew(n.offset >> 1, computedOffsets)
+      } else {
+        const isOdd = n.offset % 2 === 1
+        const peer = this.path[0][l + (isOdd ? -1 : 1)]
+        if (!peer.txid) {
+          // drop non-txid level 0 nodes without a txid peer
+          pushIfNew(peer.offset, dropOffsets)
         }
+      }
     }
     dropOffsetsFromLevel(dropOffsets, 0)
     for (let h = 1; h < this.path.length; h++) {
@@ -361,5 +356,4 @@ export default class MerklePath {
       dropOffsetsFromLevel(dropOffsets, h)
     }
   }
-
 }

package/src/transaction/Transaction.ts

@@ -62,7 +62,7 @@ export default class Transaction {
    * @param beef A binary representation of a transaction in BEEF format.
    * @returns An anchored transaction, linked to its associated inputs populated with merkle paths.
    */
-  static fromBEEF(beef: number[]): Transaction {
+  static fromBEEF (beef: number[]): Transaction {
     const reader = new Reader(beef)
     // Read the version
     const version = reader.readUInt32LE()
@@ -122,13 +122,12 @@ export default class Transaction {
     return transactions[lastTXID].tx
   }
 
-
   /**
    * Creates a new transaction, linked to its inputs and their associated merkle paths, from a EF (BRC-30) structure.
    * @param ef A binary representation of a transaction in EF format.
    * @returns An extended transaction, linked to its associated inputs by locking script and satoshis amounts only.
    */
-  static fromEF(ef: number[]): Transaction {
+  static fromEF (ef: number[]): Transaction {
     const br = new Reader(ef)
     const version = br.readUInt32LE()
     if (toHex(br.read(6)) !== '0000000000ef') throw new Error('Invalid EF marker')
@@ -190,7 +189,7 @@ export default class Transaction {
    *   outputs: { vout: number, offset: number, length: number }[]
    * }
    */
-  static parseScriptOffsets(bin: number[]): {
+  static parseScriptOffsets (bin: number[]): {
     inputs: Array<{ vin: number, offset: number, length: number }>
     outputs: Array<{ vout: number, offset: number, length: number }>
   } {
@@ -216,7 +215,7 @@ export default class Transaction {
     return { inputs, outputs }
   }
 
-  private static fromReader(br: Reader): Transaction {
+  private static fromReader (br: Reader): Transaction {
     const version = br.readUInt32LE()
     const inputsLength = br.readVarIntNum()
     const inputs: TransactionInput[] = []
@@ -257,7 +256,7 @@ export default class Transaction {
    * @param {number[]} bin - The binary array representation of the transaction.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromBinary(bin: number[]): Transaction {
+  static fromBinary (bin: number[]): Transaction {
     const br = new Reader(bin)
     return Transaction.fromReader(br)
   }
@@ -269,7 +268,7 @@ export default class Transaction {
    * @param {string} hex - The hexadecimal string representation of the transaction.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHex(hex: string): Transaction {
+  static fromHex (hex: string): Transaction {
     return Transaction.fromBinary(toArray(hex, 'hex'))
   }
 
@@ -280,7 +279,7 @@ export default class Transaction {
    * @param {string} hex - The hexadecimal string representation of the transaction EF.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHexEF(hex: string): Transaction {
+  static fromHexEF (hex: string): Transaction {
     return Transaction.fromEF(toArray(hex, 'hex'))
   }
 
@@ -291,11 +290,11 @@ export default class Transaction {
    * @param {string} hex - The hexadecimal string representation of the transaction BEEF.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHexBEEF(hex: string): Transaction {
+  static fromHexBEEF (hex: string): Transaction {
     return Transaction.fromBEEF(toArray(hex, 'hex'))
   }
 
-  constructor(
+  constructor (
     version: number = 1,
     inputs: TransactionInput[] = [],
     outputs: TransactionOutput[] = [],
@@ -317,7 +316,7 @@ export default class Transaction {
    * @param {TransactionInput} input - The TransactionInput object to add to the transaction.
    * @throws {Error} - If the input does not have a sourceTXID or sourceTransaction defined.
    */
-  addInput(input: TransactionInput): void {
+  addInput (input: TransactionInput): void {
     if (
       typeof input.sourceTXID === 'undefined' &&
       typeof input.sourceTransaction === 'undefined'
@@ -337,7 +336,7 @@ export default class Transaction {
    *
    * @param {TransactionOutput} output - The TransactionOutput object to add to the transaction.
    */
-  addOutput(output: TransactionOutput): void {
+  addOutput (output: TransactionOutput): void {
     this.cachedHash = undefined
     this.outputs.push(output)
   }
@@ -347,7 +346,7 @@ export default class Transaction {
    *
    * @param {Record<string, any>} metadata - The metadata object to merge into the existing metadata.
    */
-  updateMetadata(metadata: Record<string, any>): void {
+  updateMetadata (metadata: Record<string, any>): void {
     this.metadata = {
       ...this.metadata,
       ...metadata
@@ -365,7 +364,7 @@ export default class Transaction {
    *
    * TODO: Benford's law change distribution.
    */
-  async fee(modelOrFee?: FeeModel | number, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
+  async fee (modelOrFee?: FeeModel | number, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
     this.cachedHash = undefined
     if (typeof modelOrFee === 'undefined') {
       modelOrFee = new SatoshisPerKilobyte(10)
@@ -426,7 +425,7 @@ export default class Transaction {
    *
    * @returns The current transaction fee
    */
-  getFee(): number {
+  getFee (): number {
     let totalIn = 0
     for (const input of this.inputs) {
       if (typeof input.sourceTransaction !== 'object') {
@@ -444,7 +443,7 @@ export default class Transaction {
   /**
    * Signs a transaction, hydrating all its unlocking scripts based on the provided script templates where they are available.
    */
-  async sign(): Promise<void> {
+  async sign (): Promise<void> {
     this.cachedHash = undefined
     for (const out of this.outputs) {
       if (typeof out.satoshis === 'undefined') {
@@ -475,7 +474,7 @@ export default class Transaction {
    * @param broadcaster The Broadcaster instance wwhere the transaction will be sent
    * @returns A BroadcastResponse or BroadcastFailure from the Broadcaster
    */
-  async broadcast(broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> {
+  async broadcast (broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> {
     return await broadcaster.broadcast(this)
   }
 
@@ -484,7 +483,7 @@ export default class Transaction {
    *
    * @returns {number[]} - The binary array representation of the transaction.
    */
-  toBinary(): number[] {
+  toBinary (): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(this.version)
     writer.writeVarIntNum(this.inputs.length)
@@ -516,7 +515,7 @@ export default class Transaction {
    *
    * @returns {number[]} - The BRC-30 EF representation of the transaction.
    */
-  toEF(): number[] {
+  toEF (): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(this.version)
     writer.write([0, 0, 0, 0, 0, 0xef])
@@ -556,7 +555,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction EF.
    */
-  toHexEF(): string {
+  toHexEF (): string {
     return toHex(this.toEF())
   }
 
@@ -565,7 +564,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction.
    */
-  toHex(): string {
+  toHex (): string {
     return toHex(this.toBinary())
   }
 
@@ -574,7 +573,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction BEEF.
    */
-  toHexBEEF(): string {
+  toHexBEEF (): string {
     return toHex(this.toBEEF())
   }
 
@@ -584,7 +583,7 @@ export default class Transaction {
    * @param {'hex' | undefined} enc - The encoding to use for the hash. If 'hex', returns a hexadecimal string; otherwise returns a binary array.
    * @returns {string | number[]} - The hash of the transaction in the specified format.
    */
-  hash(enc?: 'hex'): number[] | string {
+  hash (enc?: 'hex'): number[] | string {
     let hash
     if (this.cachedHash) {
       hash = this.cachedHash
@@ -604,21 +603,21 @@ export default class Transaction {
    *
    * @returns {number[]} - The ID of the transaction in the binary array format.
    */
-  id(): number[]
+  id (): number[]
   /**
    * Calculates the transaction's ID in hexadecimal format.
    *
    * @param {'hex'} enc - The encoding to use for the ID. If 'hex', returns a hexadecimal string.
    * @returns {string} - The ID of the transaction in the hex format.
    */
-  id(enc: 'hex'): string
+  id (enc: 'hex'): string
   /**
    * Calculates the transaction's ID.
    *
    * @param {'hex' | undefined} enc - The encoding to use for the ID. If 'hex', returns a hexadecimal string; otherwise returns a binary array.
    * @returns {string | number[]} - The ID of the transaction in the specified format.
    */
-  id(enc?: 'hex'): number[] | string {
+  id (enc?: 'hex'): number[] | string {
     const id = [...this.hash() as number[]]
     id.reverse()
     if (enc === 'hex') {
@@ -633,8 +632,10 @@ export default class Transaction {
    * @param chainTracker - An instance of ChainTracker, a Bitcoin block header tracker. If the value is set to 'scripts only', headers will not be verified. If not provided then the default chain tracker will be used.
    *
    * @returns Whether the transaction is valid according to the rules of SPV.
+   *
+   * @example tx.verify(new WhatsOnChain(), new SatoshisPerKilobyte(1))
    */
-  async verify(chainTracker: ChainTracker | 'scripts only' = defaultChainTracker()): Promise<boolean> {
+  async verify (chainTracker: ChainTracker | 'scripts only' = defaultChainTracker(), feeModel?: FeeModel): Promise<boolean> {
     // If the transaction has a valid merkle path, verification is complete.
     if (typeof this.merklePath === 'object' && chainTracker !== 'scripts only') {
       const proofValid = await this.merklePath.verify(
@@ -647,6 +648,14 @@ export default class Transaction {
       }
     }
 
+    if (typeof feeModel !== 'undefined') {
+      const cpTx = Transaction.fromHexEF(this.toHexEF())
+      delete cpTx.outputs[0].satoshis
+      cpTx.outputs[0].change = true
+      await cpTx.fee(feeModel)
+      if (this.getFee() < cpTx.getFee()) throw new Error(`Verification failed because the transaction ${this.id('hex')} has an insufficient fee and has not been mined.`)
+    }
+
     // Verify each input transaction and evaluate the spend events.
     // Also, keep a total of the input amounts for later.
     let inputTotal = 0
@@ -660,7 +669,7 @@ export default class Transaction {
       }
       const sourceOutput = input.sourceTransaction.outputs[input.sourceOutputIndex]
       inputTotal += sourceOutput.satoshis
-      const inputVerified = await input.sourceTransaction.verify(chainTracker)
+      const inputVerified = await input.sourceTransaction.verify(chainTracker, feeModel)
       if (!inputVerified) {
         return false
       }
@@ -702,7 +711,7 @@ export default class Transaction {
    *
    * @returns The serialized BEEF structure
    */
-  toBEEF(): number[] {
+  toBEEF (): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(4022206465)
     const BUMPs: MerklePath[] = []