@ducat-unit/wallet-snap 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducat-unit/wallet-snap",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Ducat Bitcoin account and signing Snap for MetaMask.",
   "keywords": [
     "ducat",
@@ -29,16 +29,7 @@
     "images/",
     "snap.manifest.json",
     "README.md",
-    "LICENSE",
-    "PRIVACY.md",
-    "SECURITY.md",
-    "SUPPORT.md",
-    "RELEASE_CHECKLIST.md",
-    "LISTING.md",
-    "DEMO_SCRIPT.md",
-    "AUDIT_SCOPE.md",
-    "SNAPPER_REVIEW.md",
-    "DEPENDENCY_AUDIT.md"
+    "LICENSE"
   ],
   "scripts": {
     "build": "mm-snap build",
@@ -50,15 +41,13 @@
     "verify": "npm run type-check && npm test && npm run build && npm run manifest",
     "lint": "npm run type-check && npm test",
     "audit:prod": "npm audit --omit=dev",
-    "fixture:capture": "node scripts/capture-submission-fixture.mjs",
     "harness:accounts": "node scripts/snap-simulation-harness.mjs accounts",
     "harness:smoke-signing": "node scripts/snap-simulation-harness.mjs smoke-signing",
-    "verify:harness": "npm run harness:accounts && npm run harness:smoke-signing",
-    "snapper": "npx --yes @sayfer_io/snapper --path . --output snapper-report.json",
-    "verify:metadata": "node scripts/verify-release-metadata.js",
-    "verify:release-manifest": "node scripts/verify-release-manifest.js",
-    "verify:fixtures": "DUCAT_REQUIRE_SUBMISSION_FIXTURES=1 jest --runTestsByPath src/__tests__/submission-fixtures.test.ts --runInBand",
-    "verify:submission-ready": "node scripts/verify-submission-ready.js",
+    "harness:session": "node scripts/snap-simulation-harness.mjs session",
+    "harness:bitvm3-reclaim": "node scripts/snap-simulation-harness.mjs bitvm3-reclaim",
+    "harness:bitvm3-reclaim-reject": "node scripts/snap-simulation-harness.mjs bitvm3-reclaim-reject",
+    "verify:bitvm3": "npm run harness:bitvm3-reclaim && npm run harness:bitvm3-reclaim-reject",
+    "verify:harness": "npm run harness:accounts && npm run harness:smoke-signing && npm run verify:bitvm3",
     "verify:release": "bash scripts/verify-release.sh",
     "pack:dry-run": "npm pack --dry-run",
     "prepublishOnly": "npm run verify:release"

package/snap.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Ducat Bitcoin accounts, Ducat-aware confirmations, and PSBT/message signing for MetaMask.",
   "proposedName": "Ducat",
   "repository": {
@@ -7,7 +7,7 @@
     "url": "git+https://github.com/DUCAT-UNIT/ducat-snap.git"
   },
   "source": {
-    "shasum": "RE0s+LP6Soq0Xn0R8P+DA2ChhPOB2pasPp9BsJng5/Y=",
+    "shasum": "Kj7mZpspXKh+MdQJXSYSzeoyr3zkbkNOrHY4b0J0mNE=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

package/AUDIT_SCOPE.md

@@ -1,46 +0,0 @@
-# Ducat Snap Audit Scope
-
-This file defines the minimum security review scope before MetaMask allowlisting for `@ducat-unit/wallet-snap@0.1.5`.
-
-## In Scope
-
-- `snap.manifest.json` permissions and allowed origins.
-- BIP32 entropy use for `m/84'/0'`, `m/86'/0'`, `m/84'/1'`, and `m/86'/1'`.
-- Local BIP32 child derivation in `src/bip32.ts`.
-- Account derivation in `src/accounts.ts`.
-- BIP322-style message signing in `src/message.ts`.
-- PSBT parsing, validation, summarization, and signing in `src/psbt.ts`.
-- Taproot script-path commitment verification in `src/psbt.ts`.
-- Ducat vault sequence and OP_RETURN return-data decoding in `src/psbt.ts`.
-- Transfer construction, signing, and broadcast in `src/transfer.ts`.
-- RPC routing and origin authorization in `src/rpc.ts`.
-- User confirmation content in `src/confirmations.ts`.
-- State storage in `src/state.ts`.
-- Home page network fetches in `src/home.ts`.
-- Build artifacts produced by `npm run verify:release`.
-
-## Required Findings To Rule Out
-
-- Any path that exports, logs, stores, or returns private keys or raw entropy.
-- Any signing path that signs an input not explicitly listed in `signInputs`.
-- Any signing path that signs inputs for addresses not derived by the Snap.
-- Any irreversible operation that can proceed without a MetaMask confirmation.
-- Any mainnet request that uses a testnet key path, testnet address, or testnet broadcast endpoint, and any testnet request that uses a mainnet key path, mainnet address, or mainnet broadcast endpoint.
-- Any unauthorized origin able to invoke Snap RPC methods.
-- Any malformed PSBT, wrong-network PSBT, unknown address, or unknown input index that is accepted.
-- Any package dependency that violates MetaMask Snap SES constraints or creates avoidable key-management risk.
-- Any Taproot script-path behavior that signs a Ducat vault input without proving the tapleaf is a Ducat cosign leaf, commits to the prevout output key, contains the derived vault pubkey in the client slot, and uses distinct client and guard pubkeys.
-
-## Audit Evidence
-
-The final audit package should include:
-
-- Public source repository URL.
-- Audited commit hash.
-- Fixed commit hash, if fixes are required.
-- `npm pack --dry-run` output.
-- `npm audit --omit=dev` output.
-- `npm run verify:release` output.
-- Snapper/security scan output.
-- Final `snap.manifest.json` shasum.
-- Demo video URL following `DEMO_SCRIPT.md`.

package/DEMO_SCRIPT.md

@@ -1,35 +0,0 @@
-# Ducat Snap Demo Script
-
-Use this script for the MetaMask allowlist/directory submission video. Record against the audited build and the same package version submitted to npm.
-
-## Setup
-
-1. Build and serve the Snap with `npm run verify` and `npm run serve`.
-2. Configure the Ducat frontend with `NEXT_PUBLIC_DUCAT_SNAP_ID` pointing at the local Snap during pre-submission testing, or `npm:@ducat-unit/wallet-snap` for the npm build.
-3. Use the audited network being demonstrated. For mainnet demos, use small controlled amounts and the audited production validator/frontend configuration.
-4. Fund the Snap-derived sats account with BTC for the selected network.
-
-## Recording Steps
-
-1. Open the Ducat frontend and choose MetaMask from the wallet list.
-2. Show the MetaMask Snap install request and permissions.
-3. Approve the Snap installation.
-4. Connect and show the derived `sats`, `runes`, and `vault` addresses in the Ducat app.
-5. Open MetaMask Snap home and show account addresses, BTC balance, UNIT balance, vault status, recent actions, clickable HTTPS app links, and copyable local routes.
-6. Execute or stage a create-vault flow and show the compact Ducat PSBT confirmation summary, inputs, outputs, fees, warnings, and app metadata.
-7. Execute or stage deposit BTC and show the confirmation summary.
-8. Execute or stage borrow UNIT and show the confirmation summary.
-9. Execute or stage repay UNIT and show the confirmation summary.
-10. Execute or stage withdraw BTC and show the confirmation summary.
-11. Execute or stage UNIT swap and show the confirmation summary.
-12. Execute or stage liquidation/repossess and show the batch confirmation.
-13. Sign an authentication message and show the message confirmation.
-14. Disable and re-enable the Snap, then reconnect from the Ducat frontend.
-
-## Evidence To Capture
-
-- Every irreversible signing action shows a MetaMask confirmation.
-- Confirmations include origin, network, signed input indexes, output summary, and fee when calculable.
-- Private keys are never exported or shown.
-- Mainnet, signet, and mutinynet all use the expected network-specific addresses, validator endpoints, and broadcast endpoints.
-- Xverse and UniSat remain available in the wallet list.

package/DEPENDENCY_AUDIT.md

@@ -1,36 +0,0 @@
-# Dependency Audit Notes
-
-Last local production audit:
-
-```bash
-npm run audit:prod
-```
-
-Result: 0 production vulnerabilities.
-
-Last local full audit:
-
-```bash
-npm audit
-```
-
-Result: 31 development-toolchain vulnerabilities, all low or moderate.
-
-## Current Assessment
-
-The published Snap package contains the production bundle and release metadata. `npm audit --omit=dev` is clean for production dependencies.
-
-Direct `dependencies` and `devDependencies` in `package.json` are pinned to exact versions. Transitive dependency versions are locked by `package-lock.json`.
-
-The full audit findings are in development tooling paths, primarily transitive dependencies of MetaMask Snap build/test tooling. `npm audit fix --package-lock-only` did not resolve them. npm reports that the remaining forced path would install older breaking versions of MetaMask Snap packages, so it was not applied locally.
-
-## Release Requirement
-
-Before public submission, re-run:
-
-```bash
-npm audit
-npm run audit:prod
-```
-
-Then review whether newer compatible MetaMask Snap SDK/CLI releases are available, or document auditor approval for the remaining dev-toolchain findings if production dependencies remain clean.

package/LISTING.md

@@ -1,44 +0,0 @@
-# Ducat Snap Listing
-
-## Short Description
-
-Ducat Bitcoin accounts and Ducat-aware transaction signing in MetaMask.
-
-## Long Description
-
-Ducat is a MetaMask Snap for using Ducat with Bitcoin mainnet, signet, and mutinynet accounts derived inside MetaMask. The Snap derives deterministic Bitcoin accounts from the user's MetaMask Secret Recovery Phrase, keeps private keys inside MetaMask, and signs only explicit PSBT inputs requested by the Ducat web app.
-
-The Ducat web app remains the action surface for create, deposit, borrow, repay, withdraw, swap, liquidation, and repossess flows. The Snap provides account discovery, BIP322-style message signing, PSBT signing, batch PSBT signing, a simple transfer path, Ducat-aware MetaMask confirmations, pending/completed/failed action notifications, recent action history, and a Snap home page with copyable account addresses, BTC/UNIT balance, vault summary lookups, recent activity, and Ducat app routes.
-
-Mainnet is enabled in this audit candidate and must be covered by the third-party review before production distribution.
-
-## Permissions Rationale
-
-- `endowment:rpc`: Allows only approved Ducat frontend origins to invoke the Snap.
-- `snap_getBip32Entropy`: Derives Bitcoin account keys for `m/84'/0'`, `m/86'/0'`, `m/84'/1'`, and `m/86'/1'`.
-- `snap_dialog`: Shows mandatory confirmations before message signing, PSBT signing, batch signing, or transfers.
-- `snap_manageState`: Stores recent Ducat action metadata for Snap home.
-- `snap_notify`: Shows informational MetaMask notifications for pending approvals, completed actions, and failed non-rejection actions.
-- `endowment:page-home`: Shows Ducat account status and Ducat app routes in MetaMask.
-- `endowment:network-access`: Fetches public balance, vault, fee, UTXO, and broadcast data.
-- `endowment:lifecycle-hooks`: Shows the install notice.
-
-## Screenshot Checklist
-
-- Install approval screen for the Ducat Snap.
-- Ducat app wallet modal showing MetaMask as a connector.
-- Connected Ducat account addresses.
-- PSBT confirmation for create or deposit showing an action title, origin, network, compact summary rows, signed input details, output details, fees, warnings, and Ducat app metadata.
-- Batch confirmation for liquidation or repossess showing all-or-nothing signing, per-transaction rows, total fee, and warnings.
-- Message signing confirmation showing origin, network, signing account, BIP322 signature type, message fingerprint, message length, and copyable message body.
-- Transfer confirmation showing amount, fee, the `You pay` amount, change, sender, recipient, selected UTXOs, and broadcast endpoint.
-- Snap home showing structured cards for accounts, BTC balance, UNIT balance, vault status, recent actions, clickable HTTPS app links, and copyable local development routes.
-
-## Listing Asset Checklist
-
-- Square icon: `images/icon.svg`.
-- Screenshots captured from the audited build.
-- Demo video following `DEMO_SCRIPT.md`.
-- Privacy policy from `PRIVACY.md` or approved legal URL.
-- Support and escalation contact from `SUPPORT.md`.
-- Security disclosure process from `SECURITY.md`.

package/PRIVACY.md

@@ -1,13 +0,0 @@
-# Privacy Policy
-
-Last updated: 2026-06-12
-
-The Ducat Snap derives Bitcoin accounts locally inside MetaMask using the user's MetaMask Secret Recovery Phrase. Private keys never leave MetaMask.
-
-The Snap stores only recent Ducat action metadata needed for the Snap home page, such as action type, action title, status, network, origin, timestamp, approximate amount, summary text, and transaction IDs. The Snap also remembers the last connected Ducat app origin and network so Snap Home can show the correct testnet and Ducat app routes.
-
-The Snap may query public Bitcoin indexer APIs and Ducat validator APIs to display balances, display vault status, estimate fees, fetch UTXOs, and broadcast transactions. Those services may receive public Bitcoin addresses, transaction identifiers, requested network, and normal request metadata such as IP address and user agent.
-
-The Snap does not collect analytics, sell user data, or expose private keys. The Snap does not store seed phrases, private keys, or signed transaction secrets in Snap state.
-
-Users can remove locally stored recent-action metadata by invoking the confirmed `ducat_clearRecentActions` RPC method from an approved Ducat frontend origin, or by removing the Snap from MetaMask.

package/RELEASE_CHECKLIST.md

@@ -1,55 +0,0 @@
-# Ducat Snap Release Checklist
-
-## Completed For `0.1.5`
-
-- [x] Public repository contains the audit-candidate source tag.
-- [x] Audit candidate tag exists after the final handoff commit: `audit-candidate-0.1.5-20260615-audit-confirmation-hardening`.
-- [ ] `.github/workflows/verify.yml` succeeds on the current audit candidate.
-- [x] `npm run verify:release` succeeds locally.
-- [x] `npm run pack:dry-run` output reviewed.
-- [x] `npm run audit:prod` output reviewed.
-- [x] Dependency audit reviewed.
-- [x] Snapper/security scan reviewed.
-- [x] Console logs, unused permissions, accidental placeholders, and dead RPC methods removed or documented as external gates.
-- [x] Legacy Taproot script-path compatibility behavior removed and replaced with committed tapleaf verification.
-- [x] Deterministic MetaMask simulation harness covers account derivation and owned P2WPKH PSBT signing.
-- [x] Mainnet derivation, network parsing, endpoint selection, and release metadata added to the audit candidate.
-- [x] `@ducat-unit/wallet-snap@0.1.5` release metadata prepared for audit handoff.
-- [ ] Frontend PR #675 default Snap version range updated to `^0.1.5`.
-
-## Required Before MetaMask Submission
-
-- [ ] Third-party audit completed because the Snap uses `snap_getBip32Entropy`.
-- [ ] Audit fixes merged and tagged, if the audit requires fixes.
-- [ ] `submission/metamask-directory.json` pending external fields are replaced.
-- [ ] `submission/ALLOWLIST_SUBMISSION.md` pending external fields are replaced.
-- [ ] Real create/deposit/borrow/repay/withdraw/swap/liquidation/repossess PSBT fixtures captured in `submission/fixtures/`.
-- [ ] Final mainnet/signet/mutinynet E2E evidence captured in `submission/e2e/evidence.json`.
-- [ ] Final screenshots captured in `submission/screenshots/`.
-- [ ] Demo video recorded with `DEMO_SCRIPT.md`.
-- [ ] Production support, escalation, and response-time details finalized.
-- [ ] `npm run verify:submission-ready` succeeds after external evidence is complete.
-
-## Listing Assets
-
-- [x] Icon: `images/icon.svg`.
-- [x] Short description from `LISTING.md`.
-- [x] Long description from `LISTING.md`.
-- [x] Privacy policy source: `PRIVACY.md`.
-- [x] Security disclosure source: `SECURITY.md`.
-- [x] Support source: `SUPPORT.md`.
-- [ ] Final PNG screenshots captured from the audited build.
-- [ ] Demo video recorded from the audited build.
-- [ ] Support and escalation contact copied into the submission form.
-
-## Submission
-
-- [ ] Submit MetaMask allowlist/directory request with the audited commit, fixed commit if any, audit report, npm URL, public repository URL, demo video, support details, and listing assets.
-- [ ] MetaMask allowlist approval received.
-
-## Production Cutover
-
-- [ ] Frontend production config uses `NEXT_PUBLIC_DUCAT_SNAP_ID=npm:@ducat-unit/wallet-snap`.
-- [ ] Frontend production config uses the approved release range in `NEXT_PUBLIC_DUCAT_SNAP_VERSION`.
-- [ ] Existing Xverse and UniSat regression flows pass.
-- [ ] Mainnet/signet/mutinynet install, connect, create, deposit, borrow, repay, withdraw, swap, liquidation, and repossess E2E scenarios pass.

package/SECURITY.md

@@ -1,12 +0,0 @@
-# Security
-
-Report security issues privately to the Ducat maintainers before public disclosure.
-
-Release requirements:
-
-- Third-party audit for key-management usage of `snap_getBip32Entropy`.
-- MetaMask allowlist/directory review before production distribution.
-- Production dependency audit and Snapper/security scan for every release candidate.
-- Mainnet key derivation, signing, and broadcast support must be covered by the third-party audit before production distribution.
-
-`@ducat-unit/wallet-snap@0.1.5` supports mainnet, signet, and mutinynet. It signs only explicit PSBT input indexes that match Snap-derived addresses and requires MetaMask confirmation before message, PSBT, batch, or transfer signing.

package/SNAPPER_REVIEW.md

@@ -1,36 +0,0 @@
-# Snapper Review
-
-Last local command:
-
-```bash
-npx --yes @sayfer_io/snapper --path . --output snapper-report.json
-```
-
-Local result: 221 findings across the `ESLinting`, `ExcessiveComments`, and `HardcodedSecrets` categories.
-
-The three `HardcodedSecrets` findings are the Ducat guardian x-only **public** key (`ef8e6d84…ca2e`) hardcoded per network in `src/networks.ts`. It is a public key that is intended to be embedded so the Snap can pin the vault cosigner identity; it is not a secret. The remaining findings are style/comment-density scanner policy, not signing, key-export, origin-authorization, confirmation-bypass, or network-scope findings.
-
-## Addressed Findings
-
-The first local scan reported 105 findings. The implementation now fixes the non-style/high-signal findings from that run:
-
-- Removed an unused `Buffer` import.
-- Replaced empty catch handling with explicit behavior.
-- Removed duplicate taproot key update catch logic by validating `tapInternalKey` before signing.
-- Removed an unused function parameter.
-- Removed an unused type import introduced during the confirmation cleanup.
-- Replaced `||` fallback logic with `??` where empty strings should remain meaningful.
-- Removed the content-type false positive from the hardcoded-secret detector.
-
-## Remaining Finding Summary
-
-- 178 missing JSDoc comments.
-- External API response fields using snake_case, such as Esplora and Ducat validator fields (`funded_txo_sum`, `spent_txo_sum`, `chain_stats`, `mempool_stats`, `asset_balance`, `unit_balance`, and vault summary fields).
-- One object literal key using `vault_pubkey`, matching the Ducat validator API.
-- One `hmac(sha512, ...)` style warning in local BIP32 derivation.
-
-## Review Notes
-
-The remaining findings should be reviewed by the external Snap auditor, but they are not currently treated as local release blockers because they are style or scanner-policy findings rather than signing, key-export, origin-authorization, confirmation-bypass, or network-scope findings.
-
-The generated `snapper-report.json` is intentionally ignored and not included in the npm package because it contains machine-local absolute paths. Keep it with release evidence for the audited commit rather than committing it to the public source repository.

package/SUPPORT.md

@@ -1,9 +0,0 @@
-# Support
-
-Use the Ducat Snap repository issue tracker for development support and bug reports:
-
-https://github.com/DUCAT-UNIT/ducat-snap/issues
-
-Security issues should not be filed as public issues. Follow `SECURITY.md` for private disclosure.
-
-Before MetaMask directory submission, copy the final public support URL, private escalation contact, and response-time expectation into `submission/ALLOWLIST_SUBMISSION.md`.