Wallet interoperability: bounded sync and portable recovery (#544)

.github/workflows/codeql.yml

@@ -32,10 +32,9 @@ jobs:
         language:
           - actions
           - javascript-typescript
-          # The only Python files are deterministic OpenAPI output under
-          # conformance/generated/**. The CodeQL config excludes that owned
-          # generated boundary, while codegen CI verifies its specs, locked
-          # generator, and output.
+          # Scan the independently authored BRC-118 conformance oracle.
+          # Generated OpenAPI clients remain excluded by the owned registry.
+          - python
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 

.github/workflows/conformance.yml

@@ -31,6 +31,8 @@ jobs:
           cache: pnpm
       - name: Install deps
         run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Verify independent BRC-118 wire and signature vectors
+        run: python3 conformance/runner/scripts/brc118-vectors.py
       - name: Build TS runner dependencies
         run: >-
           pnpm -r

.github/workflows/mutation-tests.yml

@@ -101,9 +101,11 @@ jobs:
   mutation-tests:
     name: Mutation / ${{ matrix.target }} / ${{ matrix.partition }}
     needs: prepare
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.wallet_native && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}
     # Preserve the acknowledged wallet/overlays90-minute target union.
-    timeout-minutes: ${{ contains(fromJSON('["revenue-lineage-package","revenue-lineage-graph","sdk-revenue-listing-funding","output-lookup-session-records","output-lookup-session-payloads","wallet-recovery-codec","wallet-recovery-installation","wallet-recovery-store","wallet-funding-store","wallet-recovery-transitions","wallet-recovery-controller","root-eviction-storage","root-eviction-journal","root-eviction-records","wallet-retained-snapshot","wallet-snapshot-sync","wallet-snapshot-sync-destination","wallet-snapshot-sync-rows","wallet-snapshot-archive","wallet-snapshot-remote-http"]'), matrix.target) && 90 || 45 }}
+    # Complete snapshot source-guard service qualification took 58m35s locally,
+    # before hosted checkout/install. Preserve the 45-minute default elsewhere.
+    timeout-minutes: ${{ contains(fromJSON('["revenue-lineage-package","revenue-lineage-graph","sdk-revenue-listing-funding","output-lookup-session-records","output-lookup-session-payloads","wallet-recovery-codec","wallet-recovery-installation","wallet-recovery-store","wallet-funding-store","wallet-recovery-transitions","wallet-recovery-controller","root-eviction-storage","root-eviction-journal","root-eviction-records","wallet-retained-snapshot","wallet-snapshot-journal","wallet-snapshot-sync","wallet-snapshot-sync-destination","wallet-snapshot-sync-rows","wallet-snapshot-archive","wallet-snapshot-remote-http","wallet-snapshot-remote-reader","wallet-snapshot-remote-service"]'), matrix.target) && 90 || 45 }}
     permissions:
       contents: read
     strategy:
@@ -130,6 +132,25 @@ jobs:
       - name: Restore build outputs
         run: tar --extract --gzip --file .ci-artifacts/build-outputs.tar.gz
 
+      - name: Deliver the pinned native browser for selected wallet component tests
+        if: matrix.wallet_native
+        run: node scripts/provision-wallet-native-browser.mjs --target "${{ matrix.target }}"
+
+      - name: Provision the qualified native wallet test executable
+        if: matrix.wallet_native
+        run: bash scripts/provision-wallet-native-tests.sh
+
+      - name: Preserve native component delivery evidence
+        if: always() && matrix.wallet_native
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: mutation-native-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.target }}-${{ matrix.partition }}
+          path: |
+            ${{ runner.temp }}/ts-wallet-native-tests.*/component-delivery.json
+            ${{ runner.temp }}/ts-wallet-native-tests.*/brc38-qualification-*/component-delivery-failure.json
+          if-no-files-found: ignore
+          retention-days: 7
+
       - name: Enforce the governed mutation-quality ratchet
         env:
           MUTATION_VERBOSE: '0'

.sonarcloud.properties

@@ -10,7 +10,7 @@ sonar.exclusions=packages/verifast/src/wasm/bdk-core.*,conformance/generated/**,
 # into self-contained Docker/package build contexts and checked byte-for-byte
 # in CI. Analyze the code for issues, but do not report intentional generated
 # copies as source duplication.
-sonar.cpd.exclusions=**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,**/*.man.test.ts,**/__test__/**,**/__tests__/**,**/test/**,**/tests/**,**/*.vectors.ts,**/eslint.config.js,infra/wab/src/security/rateLimitPolicy.ts,infra/uhrp-server-basic/src/security/rateLimitPolicy.ts,infra/uhrp-server-cloud-bucket/src/security/rateLimitPolicy.ts,infra/message-box-server/src/security/rateLimitPolicy.ts,infra/uhrp-server-basic/src/security/edgePolicy.ts,infra/uhrp-server-cloud-bucket/src/security/edgePolicy.ts,infra/message-box-server/src/security/edgePolicy.ts,infra/chaintracks-server/src/security/edgePolicy.ts,packages/overlays/overlay-express/src/security/edgePolicy.ts,packages/wallet/wallet-toolbox/src/storage/remoting/edgePolicy.ts,infra/uhrp-server-cloud-bucket/src/resourceLimits.ts,infra/uhrp-server-cloud-bucket/src/utils/network.ts,infra/wallet-infra/src/KnexPaymentReplayStore.ts,infra/uhrp-server-basic/src/chirp/core/**,infra/uhrp-server-cloud-bucket/src/chirp/core/**,infra/uhrp-server-basic/src/chirp/openapi.ts,infra/uhrp-server-cloud-bucket/src/chirp/openapi.ts,infra/uhrp-server-cloud-bucket/src/chirp/contracts.ts,infra/uhrp-server-cloud-bucket/src/chirp/commitIndex.ts,infra/uhrp-server-cloud-bucket/src/chirp/routes.ts,infra/uhrp-server-cloud-bucket/src/chirp/bodyMiddleware.ts,infra/chaintracks-server/src/telemetry.ts,infra/wab/src/telemetry.ts,infra/uhrp-server-basic/src/telemetry.ts,infra/uhrp-server-cloud-bucket/src/telemetry.ts,infra/wallet-infra/src/telemetry.ts,infra/message-box-server/src/telemetry.ts
+sonar.cpd.exclusions=**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,**/*.man.test.ts,**/__test__/**,**/__tests__/**,**/test/**,**/tests/**,**/*.vectors.ts,**/eslint.config.js,infra/wab/src/security/rateLimitPolicy.ts,infra/uhrp-server-basic/src/security/rateLimitPolicy.ts,infra/uhrp-server-cloud-bucket/src/security/rateLimitPolicy.ts,infra/message-box-server/src/security/rateLimitPolicy.ts,infra/uhrp-server-basic/src/security/edgePolicy.ts,infra/uhrp-server-cloud-bucket/src/security/edgePolicy.ts,infra/message-box-server/src/security/edgePolicy.ts,infra/chaintracks-server/src/security/edgePolicy.ts,packages/overlays/overlay-express/src/security/edgePolicy.ts,packages/wallet/wallet-toolbox/src/storage/remoting/edgePolicy.ts,infra/uhrp-server-cloud-bucket/src/resourceLimits.ts,infra/uhrp-server-cloud-bucket/src/utils/network.ts,infra/wallet-infra/src/KnexPaymentReplayStore.ts,infra/uhrp-server-basic/src/chirp/core/**,infra/uhrp-server-cloud-bucket/src/chirp/core/**,infra/uhrp-server-basic/src/chirp/openapi.ts,infra/uhrp-server-cloud-bucket/src/chirp/openapi.ts,infra/uhrp-server-cloud-bucket/src/chirp/contracts.ts,infra/uhrp-server-cloud-bucket/src/chirp/commitIndex.ts,infra/uhrp-server-cloud-bucket/src/chirp/routes.ts,infra/uhrp-server-cloud-bucket/src/chirp/bodyMiddleware.ts,infra/chaintracks-server/src/telemetry.ts,infra/wab/src/telemetry.ts,infra/uhrp-server-basic/src/telemetry.ts,infra/uhrp-server-cloud-bucket/src/telemetry.ts,infra/wallet-infra/src/telemetry.ts,infra/message-box-server/src/telemetry.ts,infra/uhrp-server-cloud-bucket/dev/bin/nodemon.js,infra/uhrp-server-cloud-bucket/dev/check-watch.cjs,infra/wab/dev/bin/nodemon.js,infra/wab/dev/check-watch.cjs
 # Narrow compatibility exceptions are registered with owner, evidence, review
 # dates, and objective removal conditions in repository-health/exceptions.json.
 sonar.issue.ignore.multicriteria=werrProtocolNames,curveSingletonAlias,curveSingletonReturn,scriptOpcodeDispatch

conformance/META.json

@@ -20,10 +20,20 @@
       "sdk.keys.publickey",
       "sdk.crypto.signature"
     ],
-    "BRC-74": ["sdk.transactions.merklepath", "broadcast.merklepath"],
-    "BRC-77": ["sdk.compat.bsm"],
-    "BRC-31": ["messaging.brc31.authrite-signature"],
-    "BRC-29": ["wallet.brc29.payment-derivation", "payments.brc29-payment-protocol"],
+    "BRC-74": [
+      "sdk.transactions.merklepath",
+      "broadcast.merklepath"
+    ],
+    "BRC-77": [
+      "sdk.compat.bsm"
+    ],
+    "BRC-31": [
+      "messaging.brc31.authrite-signature"
+    ],
+    "BRC-29": [
+      "wallet.brc29.payment-derivation",
+      "payments.brc29-payment-protocol"
+    ],
     "BRC-100": [
       "wallet.brc100.getpublickey",
       "wallet.brc100.createhmac",
@@ -55,25 +65,65 @@
       "wallet.brc100.getversion",
       "wallet.storage.adapterconformance"
     ],
-    "BRC-121": ["payments.brc121"],
-    "BRC-26": ["storage.uhrp-http"],
-    "BRC-167": ["storage.chirp-v1"],
-    "BRC-62": ["overlay.submit"],
-    "BRC-22": ["overlay.lookup", "overlay.topicmanagement"],
-    "BRC-20": ["broadcast.arcsubmit", "broadcast.merklepath"],
-    "BRC-21": ["sync.gasprotocol"],
-    "BRC-40": ["sync.brc40"],
-    "BRC-14": ["sdk.scripts.evaluation"],
-    "merkle-service": ["broadcast.merkle-service"],
-    "message-box": ["messaging.messagebox-http"],
-    "chaintracks-v2": ["sync.chaintracks-v2-http"],
-    "BRC-141": ["transport.air-gap-optical"],
-    "BRC-103": ["auth.brc31-handshake", "messaging.authsocket"],
-    "BRC-104": ["auth.brc31-handshake"]
+    "BRC-121": [
+      "payments.brc121"
+    ],
+    "BRC-26": [
+      "storage.uhrp-http"
+    ],
+    "BRC-167": [
+      "storage.chirp-v1"
+    ],
+    "BRC-62": [
+      "overlay.submit"
+    ],
+    "BRC-22": [
+      "overlay.lookup",
+      "overlay.topicmanagement"
+    ],
+    "BRC-20": [
+      "broadcast.arcsubmit",
+      "broadcast.merklepath"
+    ],
+    "BRC-21": [
+      "sync.gasprotocol"
+    ],
+    "BRC-40": [
+      "sync.brc40"
+    ],
+    "BRC-14": [
+      "sdk.scripts.evaluation"
+    ],
+    "merkle-service": [
+      "broadcast.merkle-service"
+    ],
+    "message-box": [
+      "messaging.messagebox-http"
+    ],
+    "chaintracks-v2": [
+      "sync.chaintracks-v2-http"
+    ],
+    "BRC-141": [
+      "transport.air-gap-optical"
+    ],
+    "BRC-103": [
+      "auth.brc31-handshake",
+      "messaging.authsocket"
+    ],
+    "BRC-104": [
+      "auth.brc31-handshake",
+      "payments.brc118"
+    ],
+    "BRC-118": [
+      "payments.brc118"
+    ],
+    "BRC-105": [
+      "payments.brc118"
+    ]
   },
   "stats": {
-    "total_files": 77,
-    "total_vectors": 6706,
+    "total_files": 78,
+    "total_vectors": 6712,
     "last_updated": "2026-10-07"
   },
   "regression_index": {

conformance/PARITY_MATRIX.json

@@ -4,18 +4,18 @@
   "source": "ts-stack conformance corpus",
   "description": "Machine-readable parity status for cross-language SDK implementations (Go, Rust, Python). Use this to track and drive conformance.",
   "summary": {
-    "total_files": 77,
-    "total_vectors": 6706,
-    "fully_required_files": 58,
+    "total_files": 78,
+    "total_vectors": 6712,
+    "fully_required_files": 59,
     "files_with_intended": 17,
     "files_with_mixed_status": 15,
     "vectors_by_status": {
-      "required": 6502,
+      "required": 6508,
       "intended": 204,
       "skipped": 7
     },
     "by_reason_category": {
-      "fully_supported": 1283,
+      "fully_supported": 1289,
       "governed_vector_skip": 50,
       "historical_regression": 36,
       "partial_ts_behavioral_difference": 5122,
@@ -145,6 +145,18 @@
       "reason_category": "fully_supported",
       "categories": []
     },
+    {
+      "path": "payments/brc118.json",
+      "id": "payments.brc118",
+      "total_vectors": 6,
+      "file_level_parity": "required",
+      "effective_status": "required",
+      "required_count": 6,
+      "intended_count": 0,
+      "skipped_count": 0,
+      "reason_category": "fully_supported",
+      "categories": []
+    },
     {
       "path": "payments/brc121.json",
       "id": "payments.brc121",

conformance/runner/scripts/brc118-vectors.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Independent stdlib RFC 7578 reader, wire writer, and BRC-104 preimage oracle.
+
+Run without arguments to verify the checked-in corpus. --write regenerates it.
+This is an independent fixture oracle, not a claimed external wallet integration.
+"""
+import base64
+import json
+import struct
+import sys
+from email import policy
+from email.parser import BytesParser
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[3]
+DESTINATION = ROOT / 'conformance/vectors/payments/brc118.json'
+REVISION = '2b959b13f1f73040d13cc4eb14edbfc376f8010b'
+BOUNDARY = '----BsvPayment00112233445566778899aabbccddeeff'
+PAYMENT = '{"derivationPrefix":"AA==","derivationSuffix":"AQ==","transaction":"AQID"}'
+
+
+def varint(number):
+    if number < 0:
+        return b'\xff' + struct.pack('<Q', (1 << 64) + number)
+    if number < 253:
+        return bytes([number])
+    if number <= 65535:
+        return b'\xfd' + struct.pack('<H', number)
+    if number <= 4294967295:
+        return b'\xfe' + struct.pack('<I', number)
+    return b'\xff' + struct.pack('<Q', number)
+
+
+def field(value):
+    value = value.encode('utf-8') if isinstance(value, str) else value
+    return varint(len(value) if value else -1) + value
+
+
+def vector(name, payload, media_type=None, quoted=False):
+    prefix = ('--' + BOUNDARY + '\r\nContent-Disposition: form-data; name="x-bsv-payment"'
+              '\r\nContent-Type: application/json\r\n\r\n').encode('ascii')
+    wire = prefix + PAYMENT.encode('utf-8')
+    if payload is not None:
+        wire += ('\r\n--' + BOUNDARY + '\r\nContent-Disposition: form-data; name="body"'
+                 '\r\nContent-Type: ' + media_type + '\r\n\r\n').encode('ascii') + payload
+    wire += ('\r\n--' + BOUNDARY + '--\r\n').encode('ascii')
+    content_type = 'multipart/form-data; boundary=' + ('"' + BOUNDARY + '"' if quoted else BOUNDARY)
+    # Python's standard MIME parser is independent of both TS writer and parser.
+    message = BytesParser(policy=policy.default).parsebytes(
+        ('MIME-Version: 1.0\r\nContent-Type: ' + content_type + '\r\n\r\n').encode('ascii') + wire)
+    parts = list(message.iter_parts())
+    assert not message.defects and len(parts) == (1 if payload is None else 2)
+    assert parts[0].get_param('name', header='content-disposition') == 'x-bsv-payment'
+    assert parts[0].get_payload(decode=True) == PAYMENT.encode('utf-8')
+    if payload is not None:
+        assert parts[1].get_param('name', header='content-disposition') == 'body'
+        # Nested multipart payloads are deliberately opaque to BRC-118.
+        if not media_type.startswith('multipart/'):
+            assert parts[1].get_payload(decode=True) == payload
+    headers = {'authorization': 'Bearer conformance-fixture', 'content-type': content_type, 'x-bsv-example': 'fixture'}
+    nonce = bytes(range(32))
+    preimage = nonce + field('POST') + field('/paid') + field('?q=%E9%9B%AA&order=1') + varint(len(headers))
+    for key, value in sorted(headers.items()):
+        preimage += field(key) + field(value)
+    preimage += field(wire)
+    return {
+        'id': 'payments.brc118.' + name,
+        'description': 'Exact multipart bytes and authenticated preimage: ' + name,
+        'input': {'payment_json': PAYMENT, 'boundary': BOUNDARY, 'quoted_boundary': quoted,
+                  'payload_base64': None if payload is None else base64.b64encode(payload).decode(),
+                  'payload_content_type': media_type, 'method': 'POST', 'path': '/paid',
+                  'query': '?q=%E9%9B%AA&order=1', 'request_id_hex': nonce.hex(), 'headers': headers},
+        'expected': {'body_base64': base64.b64encode(wire).decode(), 'content_type': content_type,
+                     'request_preimage_hex': preimage.hex()},
+        'tags': ['brc-118', 'exact-bytes', 'independent-python-oracle']
+    }
+
+
+corpus = {
+    '$schema': '../../schema/vector.schema.json', 'id': 'payments.brc118',
+    'name': 'BRC-118 Multipart Transport and BRC-104 Request Preimages', 'version': '1.0.0',
+    'brc': ['BRC-104', 'BRC-105', 'BRC-118'], 'reference_impl': '@bsv/sdk; independent Python stdlib oracle',
+    'parity_class': 'required',
+    'notes': 'Reviewed BRCs commit ' + REVISION + '; peer-to-peer/0104.md, payments/0105.md, payments/0118.md. Payment fields are synthetic transport bytes, not a spendable transaction. Non-multipart released signature preimages remain unchanged.',
+    'vectors': [vector('json-whitespace-utf8', '{ "snow": "雪" }\n'.encode(), 'application/json; charset=utf-8'),
+                vector('binary-nul', bytes([0, 128, 255, 13, 10, 0]), 'application/octet-stream'),
+                vector('empty', b'', 'text/plain'), vector('absent', None),
+                vector('nested-multipart', b'--inner\r\nContent-Disposition: form-data; name="field"\r\n\r\nvalue\r\n--inner--\r\n', 'multipart/form-data; boundary=inner'),
+                vector('quoted-boundary', b'quoted', 'text/plain', True)]
+}
+
+if '--write' in sys.argv:
+    DESTINATION.write_text(json.dumps(corpus, indent=2, ensure_ascii=False) + '\n')
+else:
+    assert json.loads(DESTINATION.read_text()) == corpus, 'BRC-118 corpus differs from independent oracle'
+print(f'Verified {len(corpus["vectors"])} independent BRC-118 wire/preimage vectors at BRCs {REVISION}')

conformance/runner/ts/dispatchers/payments.ts

@@ -18,6 +18,46 @@
  */
 
 import { expect } from '@jest/globals'
+import { AuthFetch, type WalletInterface } from '@bsv/sdk'
+import { buildMultipartPayment } from '@bsv/sdk/auth/utils/paymentTransport'
+import { toHex, Writer } from '@bsv/sdk/primitives/utils'
+
+async function dispatchBRC118(
+  input: Record<string, unknown>,
+  expected: Record<string, unknown>
+): Promise<void> {
+  const payload =
+    input.payload_base64 === null
+      ? undefined
+      : {
+          bytes: new Uint8Array(Buffer.from(input.payload_base64 as string, 'base64')),
+          contentType: input.payload_content_type as string
+        }
+  const encoded = buildMultipartPayment(
+    input.payment_json as string,
+    payload,
+    1024 * 1024,
+    input.boundary as string
+  )
+  expect(Buffer.from(encoded.body).toString('base64')).toBe(expected.body_base64)
+  const client = new AuthFetch({} as WalletInterface) as unknown as {
+    serializeRequest(
+      method: string,
+      headers: Record<string, string>,
+      body: Uint8Array,
+      url: URL,
+      nonce: number[]
+    ): Promise<Writer>
+  }
+  const writer = await client.serializeRequest(
+    input.method as string,
+    input.headers as Record<string, string>,
+    encoded.body,
+    new URL(`https://fixture.invalid${input.path as string}${input.query as string}`),
+    Array.from(Buffer.from(input.request_id_hex as string, 'hex'))
+  )
+  expect(toHex(writer.toArray())).toBe(expected.request_preimage_hex)
+}
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -336,14 +376,16 @@ function dispatchBRC121(input: Record<string, unknown>, expected: Record<string,
 
 // ── Main entry point ──────────────────────────────────────────────────────────
 
-export const categories: ReadonlyArray<string> = ['brc29-payment-protocol', 'brc121']
+export const categories: ReadonlyArray<string> = ['brc29-payment-protocol', 'brc121', 'brc118']
 
 export function dispatch(
   category: string,
   input: Record<string, unknown>,
   expected: Record<string, unknown>
 ): void | Promise<void> {
   switch (category) {
+    case 'brc118':
+      return dispatchBRC118(input, expected)
     case 'brc29-payment-protocol':
       return dispatchBRC29PaymentProtocol(input, expected)
     case 'brc121':