bsv-wallet 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f3c7d9f919b64229f0c2c9c99a05fbd58850803af74861157f884ade90f7af6
-  data.tar.gz: c655fbf296f6a4a3ed554681b8ab673c8dd3d108d37e6832cbf48814b3ed2169
+  metadata.gz: e7f0eba4cf58a9a63db79d2b731700f5d2d3ae04b82416ccc0288a1c5659a365
+  data.tar.gz: 2453264034fbbe664ced66bd853e8e5b4a52eb668e87a6eb01fd71e5b589d61b
 SHA512:
-  metadata.gz: 87e2b8653d787445a281fb78393e380857799852908487cbef82af26a3e1e04f16df5f67ce295ed4162742527d7ebc5d1380b4670f8a949b78d4c44524e6ab66
-  data.tar.gz: 9d288d1787f7448278eb95de1e96e41384e0c06141c755812549b9bc693c0269b8361cf31982f6b38472be3418ef575e7f373bde11d3ef0892743041c14dab10
+  metadata.gz: '092fa8e32a2ac7b7b4429c0fe715858ba16bba9869530cb97c4dfab0ff5730b2b2ff018da87a60cea5c5beaf7e527945c1158127e27806825db8ba29e895e2ed'
+  data.tar.gz: 68c27f04fa860ce116c7ddaa1a76a25b4ccfc56ab4b8b3af454dbbf5b2f452c719b884df92497b01ff6b74dbcb4eced994fbe519a51443bf7200a87cdaed65df

data/CHANGELOG-wallet.md

@@ -0,0 +1,267 @@
+# Changelog — bsv-wallet
+
+All notable changes to the `bsv-wallet` gem are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.4.0 — 2026-04-10
+
+### Added
+
+- **Protocol-ID normalisation** (F8.7): `Validators.validate_protocol_id!` now
+  strips and downcases the name before applying rules, so `' MyProtocol '` and
+  `'myprotocol'` are treated identically and cannot silently fork to different
+  key-derivation paths.
+- **Permission-rule constants** (F8.8): Reserved prefix/suffix strings are now
+  named constants on `BSV::Wallet::Validators` (`RESERVED_PROTOCOL_PREFIXES`,
+  `RESERVED_PROTOCOL_SUFFIX`, `RESERVED_BASKET_PREFIXES`, `RESERVED_BASKET_SUFFIX`,
+  `RESERVED_BASKET_NAME`), making them discoverable and documentable.
+- **BEEF verification in `internalize_action`** (F8.14): The BEEF bundle is now
+  verified via `Beef#verify` before any outputs are stored. If the bundle is
+  structurally invalid, a `WalletError` is raised rather than storing unverified
+  data. When the chain provider supports `valid_root_for_height?`, full SPV
+  verification is performed.
+- **Depth cap and cycle detection in `wire_source_tx_ancestors`** (F8.18):
+  Recursion is now bounded by `WalletClient::ANCESTOR_DEPTH_CAP` (64 levels)
+  and a visited-txid `Set`, preventing stack overflow on deep or cyclic
+  transaction ancestry chains.
+
+### Changed
+
+- **`ProtoWallet#create_signature` default counterparty** (P305.1): The default
+  value for `counterparty` has changed from `'self'` to `'anyone'`, matching the
+  behaviour of `ts-sdk`'s `ProtoWallet.createSignature`. Callers that rely on
+  the `'self'` derivation path when omitting `counterparty:` must now pass
+  `counterparty: 'self'` explicitly.
+
+### Migration notes
+
+**P305.1 — `create_signature` counterparty default change (breaking)**
+
+Previously, calling `wallet.create_signature({ protocol_id: ..., key_id: ...,
+data: ... })` without a `counterparty:` key would derive using `'self'`. It now
+derives using `'anyone'`. This changes the resulting private key and therefore
+the signature. If your application omits `counterparty:`, add
+`counterparty: 'self'` to preserve the old behaviour.
+
+**F8.14 — BEEF verification now mandatory in `internalize_action`**
+
+Calls to `internalize_action` that previously succeeded with a malformed or
+unverifiable BEEF will now raise `BSV::Wallet::WalletError`. In practice this
+only affects callers passing synthetic or hand-crafted BEEF bytes; legitimate
+BEEF produced by `create_action` or broadcast round-trips will continue to work.
+
+### Added
+
+- **Shared conformance suite** for `StorageAdapter`
+  implementations at `spec/support/shared_examples_for_storage_adapter.rb`.
+  `MemoryStore` and `FileStore` now both drive their behavioural
+  tests through `it_behaves_like 'a storage adapter'`, and the
+  extraction backfilled previously-missing coverage (certificate
+  `:attributes` filter, `count_certificates`, proof and transaction
+  round-trip, pagination ordering).
+
+## 0.3.4 — 2026-04-08
+
+Paired security patch release. Three P0 findings from the
+[2026-04-08 cross-SDK compliance review](.architecture/reviews/20260408-cross-sdk-compliance-review.md)
+plus follow-up hardening from the PR review pass. Must be installed
+together — the `bsv-wallet` gemspec now pins its `bsv-sdk` dependency
+to `>= 0.8.2, < 1.0` to enforce the paired upgrade and prevent a stale
+pair where one gem has its fixes and the other doesn't.
+
+Two GitHub Security Advisories accompany this release (draft until
+CVE IDs return from MITRE):
+
+
+### Security
+
+- **`acquire_certificate` now verifies certifier signatures** before
+  persisting (BRC-52). Both the `'direct'` and `'issuance'` acquisition
+  paths previously wrote user-supplied `signature:` values to storage
+  without any verification — a caller could forge a certificate that
+  `list_certificates` / `prove_certificate` would later treat as
+  authentic. This was a credential forgery primitive masquerading as
+  an API finding. The new `BSV::Wallet::CertificateSignature` module
+  builds the canonical BRC-52 preimage (matching the TS reference
+  `Certificate#toBinary(false)` byte-for-byte) and delegates to
+  `ProtoWallet#verify_signature`. Invalid certificates raise
+  `BSV::Wallet::CertificateSignature::InvalidError` and are not
+  persisted. Closes F8.15 (and the verification aspect of F8.16).
+
+
+
+### Changed
+
+- **`bsv-wallet.gemspec` bsv-sdk dependency pinned** to
+  `>= 0.8.2, < 1.0`. The previous `~> 0.4` constraint was stale (wallet
+  hasn't been tested against bsv-sdk 0.4.x in months) and would have
+  let a user install `bsv-wallet 0.3.4` against an old `bsv-sdk` that
+  was missing F1.3 and F5.13. Technically breaking — any consumer
+  pinned to `bsv-sdk < 0.8.2` must upgrade — but un-breaking in
+  practice: it forces users to the known-good pair rather than a
+  silently-broken combination.
+
+### Internal
+
+- `lib/bsv/wallet_interface/**/*` added to the
+  `Metrics/ModuleLength` exclusion list (was previously only excluded
+  from `Metrics/ClassLength`). The new `CertificateSignature` module
+  triggered the discrepancy.
+- Review-feedback hardening bundled into the same PR to
+  keep the security-patch window small: case-insensitive ARC failure
+  matching, `Base64.strict_decode64` on BRC-52 preimage fields,
+  `EncodingError` rescue in `CertificateSignature.verify!`, rejection
+  of mixed string / symbol duplicate field names, malformed 2xx
+  rejection in ARC, and even-length guard on hex signatures.
+
+### Migration notes
+
+- **Existing `bsv-wallet` users** pinned to `bsv-sdk ~> 0.4` will need
+  to relax their constraint or upgrade. Anything installed before
+  `bsv-wallet 0.3.4` is vulnerable to the F8.15 certificate forgery
+  primitive.
+- **Callers passing negative integers to `VarInt.encode`** (unlikely —
+  the docstring already disallowed it) will now get an `ArgumentError`
+  instead of silent corruption. Fix: pass non-negative values.
+- **Callers relying on ARC broadcaster silently succeeding for INVALID
+  / MALFORMED / MINED_IN_STALE_BLOCK / ORPHAN responses** will now see
+  `BroadcastError` raised. Fix: handle the error — the previous
+  behaviour was objectively wrong and any downstream logic that
+  tolerated it was silently corrupt.
+- **Callers of `acquire_certificate` with a fake or untrusted
+  `signature:` field** will now see
+  `BSV::Wallet::CertificateSignature::InvalidError`. Fix: ensure the
+  certificate has been properly signed by the declared certifier.
+
+### Test suite
+
+- 3112 examples, 0 failures (up from 3080 on 0.8.1)
+- 16 new regression tests for F1.3, F5.13, and F8.15
+- 16 further regression tests for the review-feedback hardening
+- Ruby 2.7 — 3.4 matrix green
+- CodeQL clean; RuboCop clean across 266 files
+
+## 0.3.3 — 2026-04-06
+
+### Fixed
+
+- `finalize_action` now stores the spending transaction so subsequent
+  `internalize_action` / proof resolution flows can find it. Previously the
+  wallet remembered the inputs and outputs but not the finalised tx itself.
+
+## 0.3.2 — 2026-04-06
+
+### Fixed
+
+- `internalize_action` now stores **all** transactions from the
+  incoming BEEF, not just the proven ones. Unproven ancestors are needed for
+  later BEEF reconstruction in `create_action` → `to_beef`.
+
+## 0.3.1 — 2026-04-06
+
+### Fixed
+
+- `internalize_action` now stores the subject transaction hex (not
+  just its proof and outputs), so the wallet can rebuild BEEF for spends of
+  the inbound outputs without re-fetching the tx.
+
+## 0.3.0 — 2026-04-06
+
+### Added
+
+- **Pluggable proof store** for merkle proof persistence. The wallet
+  is now a lightweight SPV node: `internalize_action` extracts and stores
+  merkle proofs from incoming BEEF; `create_action` reattaches them to
+  produce valid BEEF with BUMPs for ARC broadcast.
+  - `ProofStore` interface with `store_proof` / `resolve_proof`.
+  - `LocalProofStore` default implementation using `StorageAdapter`.
+  - `WalletClient` accepts injectable `proof_store:` parameter.
+  - Transaction caching (`store_transaction` / `find_transaction`) for
+    ancestry reconstruction.
+- `StorageAdapter` gains `store_proof`, `find_proof`,
+  `store_transaction`, `find_transaction` methods, implemented in both
+  `MemoryStore` and `FileStore`.
+
+### Fixed
+
+- `wire_source_from_storage` resolves merkle proofs via proof store
+  so `to_beef` produces valid BEEF that ARC accepts. Previously, BEEF
+  contained source transactions without proofs, causing ARC 463/468
+  rejections.
+
+## 0.2.2 — 2026-04-06
+
+### Fixed
+
+- `to_beef` now includes source transactions in the BEEF output, not
+  just the subject transaction. Without ancestors, ARC could not validate the
+  spend graph.
+
+## 0.2.1 — 2026-04-06
+
+### Added
+
+- `WalletClient#create_action` now accepts `UnlockingScriptTemplate`
+  objects (e.g. `P2PKH`) as input unlocking scripts, enabling template-based
+  signing without BEEF.
+- `wire_source_from_storage` fallback populates `source_satoshis`
+  and `source_locking_script` from wallet storage when BEEF is absent or
+  incomplete, enabling BIP-143 sighash computation for wallet-tracked
+  outputs.
+- `finalize_action` resolves template inputs via `sign_all` before
+  serialisation.
+- `MemoryStore#filter_outputs` supports outpoint filtering for
+  efficient single-output lookups.
+
+The sdk gem was re-released alongside this wallet change with no
+behavioural changes of its own.
+
+## 0.2.0 — 2026-04-01
+
+### Added
+
+#### Primitives
+
+
+#### Transaction
+
+
+#### Wallet
+
+- **FileStore** — JSON file-backed persistent storage, now the
+  default for `WalletClient`. Data survives process restarts. `MemoryStore`
+  becomes explicit opt-in for tests.
+- **File permissions** — directory created with 0700, files with
+  0600. Warns via Logger on startup if permissions are too open.
+
+## 0.1.2 — 2026-03-30
+
+### Added
+
+#### Script
+
+
+#### Transaction
+
+
+#### Wallet
+
+- **BRC-31 Auth/Peer** — mutual authentication with nonce-based
+  challenges, ECDSA signatures, and session management.
+- **BRC-100 wire protocol** — binary ABI serialisation for all 28
+  BRC-100 methods (call codes 1-28, VarInt encoding).
+- **Certificate issuance** — `acquire_certificate` with
+  `'issuance'` protocol (POST to certifier URL).
+
+### Fixed
+
+- Subject and certifier pinned in certificate issuance response
+  (not overridable by remote certifier).
+- Wire reader negative `privileged_reason` length crash.
+
+This was the first formal `bsv-wallet` gem release tag. Wallet code that
+landed in master before this date (notably the BRC-100 identity certificate
+methods and the BRC-100 blockchain-data / authentication methods committed
+during the sdk-0.3.1 window) is part of this gem's initial released state.

data/lib/bsv/wallet_interface/proto_wallet.rb

@@ -141,7 +141,7 @@ module BSV
       # @param originator [String, nil] FQDN of the originating application
       # @return [Hash] { signature: Array<Integer> } DER-encoded signature as byte array
       def create_signature(args, originator: nil)
-        counterparty = args[:counterparty] || 'self'
+        counterparty = args[:counterparty] || 'anyone'
         priv_key = @key_deriver.derive_private_key(args[:protocol_id], args[:key_id], counterparty)
 
         hash = if args[:hash_to_directly_sign]

data/lib/bsv/wallet_interface/validators.rb

@@ -3,6 +3,23 @@
 module BSV
   module Wallet
     module Validators
+      # Reserved protocol name prefixes (BRC-44 and BRC-98).
+      # Names beginning with any of these strings are disallowed.
+      RESERVED_PROTOCOL_PREFIXES = ['admin', 'p '].freeze
+
+      # Suffix that is disallowed on protocol names.
+      RESERVED_PROTOCOL_SUFFIX = ' protocol'
+
+      # Reserved basket name prefixes.
+      # Basket names beginning with any of these strings are disallowed.
+      RESERVED_BASKET_PREFIXES = ['admin', 'p '].freeze
+
+      # Suffix that is disallowed on basket names.
+      RESERVED_BASKET_SUFFIX = ' basket'
+
+      # Basket name that is globally reserved and cannot be used.
+      RESERVED_BASKET_NAME = 'default'
+
       module_function
 
       # BRC-100 protocol ID rules:
@@ -14,6 +31,10 @@ module BSV
       # - must not end with ' protocol'
       # - must not start with 'admin' (BRC-44)
       # - must not start with 'p ' (BRC-98 reserved)
+      #
+      # The name is normalised (stripped and downcased) before validation so
+      # that ' MyProtocol ' and 'myprotocol' are treated identically and do not
+      # silently fork to different key-derivation paths (F8.7).
       def validate_protocol_id!(protocol_id)
         unless protocol_id.is_a?(Array) && protocol_id.length == 2
           raise InvalidParameterError.new('protocol_id',
@@ -24,13 +45,19 @@ module BSV
         raise InvalidParameterError.new('protocol_id security level', '0, 1, or 2') unless [0, 1, 2].include?(level)
         raise InvalidParameterError.new('protocol_id name', 'a String') unless name.is_a?(String)
 
+        name = name.strip.downcase
+
         max_length = name.start_with?('specific linkage revelation') ? 430 : 400
         raise InvalidParameterError.new('protocol_id name', "between 5 and #{max_length} characters") if name.length < 5 || name.length > max_length
         raise InvalidParameterError.new('protocol_id name', 'lowercase letters, numbers, and spaces only') unless name.match?(/\A[a-z0-9 ]+\z/)
         raise InvalidParameterError.new('protocol_id name', 'free of consecutive spaces') if name.include?('  ')
-        raise InvalidParameterError.new('protocol_id name', 'not ending with " protocol"') if name.end_with?(' protocol')
-        raise InvalidParameterError.new('protocol_id name', 'not starting with "admin"') if name.start_with?('admin')
-        raise InvalidParameterError.new('protocol_id name', 'not starting with "p "') if name.start_with?('p ')
+        if name.end_with?(RESERVED_PROTOCOL_SUFFIX)
+          raise InvalidParameterError.new('protocol_id name', "not ending with \"#{RESERVED_PROTOCOL_SUFFIX}\"")
+        end
+
+        RESERVED_PROTOCOL_PREFIXES.each do |prefix|
+          raise InvalidParameterError.new('protocol_id name', "not starting with \"#{prefix}\"") if name.start_with?(prefix)
+        end
       end
 
       # Key ID: 1-800 bytes
@@ -67,10 +94,12 @@ module BSV
         raise InvalidParameterError.new('basket', 'between 5 and 300 characters') if basket.length < 5 || basket.length > 300
         raise InvalidParameterError.new('basket', 'lowercase letters, numbers, and spaces only') unless basket.match?(/\A[a-z0-9 ]+\z/)
         raise InvalidParameterError.new('basket', 'free of consecutive spaces') if basket.include?('  ')
-        raise InvalidParameterError.new('basket', 'not ending with " basket"') if basket.end_with?(' basket')
-        raise InvalidParameterError.new('basket', 'not starting with "admin"') if basket.start_with?('admin')
-        raise InvalidParameterError.new('basket', 'not equal to "default"') if basket == 'default'
-        raise InvalidParameterError.new('basket', 'not starting with "p "') if basket.start_with?('p ')
+        raise InvalidParameterError.new('basket', "not ending with \"#{RESERVED_BASKET_SUFFIX}\"") if basket.end_with?(RESERVED_BASKET_SUFFIX)
+
+        RESERVED_BASKET_PREFIXES.each do |prefix|
+          raise InvalidParameterError.new('basket', "not starting with \"#{prefix}\"") if basket.start_with?(prefix)
+        end
+        raise InvalidParameterError.new('basket', "not equal to \"#{RESERVED_BASKET_NAME}\"") if basket == RESERVED_BASKET_NAME
       end
 
       # Label: 1-300 characters

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.3.4'
+    VERSION = '0.4.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -4,6 +4,7 @@ require 'securerandom'
 require 'base64'
 require 'net/http'
 require 'json'
+require 'set'
 require 'uri'
 
 module BSV
@@ -180,6 +181,13 @@ module BSV
         validate_internalize_action!(args)
         beef_binary = args[:tx].pack('C*')
         beef = BSV::Transaction::Beef.from_binary(beef_binary)
+
+        # F8.14: verify the BEEF bundle before trusting its contents.
+        # Pass the chain provider if it supports SPV root verification;
+        # otherwise fall back to structural validation via valid?.
+        chain_tracker = @chain_provider.respond_to?(:valid_root_for_height?) ? @chain_provider : nil
+        raise WalletError, 'BEEF verification failed: the bundle is structurally invalid' unless beef.verify(chain_tracker)
+
         tx = extract_subject_transaction(beef)
 
         store_proofs_from_beef(beef)
@@ -400,6 +408,10 @@ module BSV
         { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
       end
 
+      # Maximum ancestor depth to traverse when wiring source transactions.
+      # Guards against stack overflow on pathologically deep or cyclic chains.
+      ANCESTOR_DEPTH_CAP = 64
+
       private
 
       # --- Validation ---
@@ -542,18 +554,28 @@ module BSV
         input.source_transaction = source_tx
       end
 
-      def wire_source_tx_ancestors(tx)
+      def wire_source_tx_ancestors(tx, visited: nil, depth: 0)
+        return if depth >= ANCESTOR_DEPTH_CAP
+
+        visited ||= Set.new
+        tx_txid = tx.txid_hex
+        return if visited.include?(tx_txid)
+
+        visited.add(tx_txid)
+
         tx.inputs.each do |inp|
           next if inp.source_transaction
 
           ancestor_txid_hex = inp.prev_tx_id.reverse.unpack1('H*')
+          next if visited.include?(ancestor_txid_hex)
+
           tx_hex = @storage.find_transaction(ancestor_txid_hex)
           next unless tx_hex
 
           ancestor_tx = BSV::Transaction::Transaction.from_hex(tx_hex)
           proof = @proof_store.resolve_proof(ancestor_txid_hex)
           ancestor_tx.merkle_path = proof if proof
-          wire_source_tx_ancestors(ancestor_tx) unless ancestor_tx.merkle_path
+          wire_source_tx_ancestors(ancestor_tx, visited: visited, depth: depth + 1) unless ancestor_tx.merkle_path
           inp.source_transaction = ancestor_tx
         end
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-08 00:00:00.000000000 Z
+date: 2026-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -29,7 +29,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.8.2
+        version: 0.9.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.8.2
+        version: 0.9.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -49,6 +49,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG-wallet.md
 - LICENSE
 - lib/bsv-wallet.rb
 - lib/bsv/wallet_interface.rb
@@ -81,7 +82,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sgbett/bsv-ruby-sdk
   source_code_uri: https://github.com/sgbett/bsv-ruby-sdk
-  changelog_uri: https://github.com/sgbett/bsv-ruby-sdk/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/sgbett/bsv-ruby-sdk/blob/master/CHANGELOG-wallet.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: