First-builder audit: starter runs, but the real-wallet path still dead-ends before a tangible BSV result

[ty-everett]

I ran the use.bsv.tools first-run path as a new BSV/BRC-100/Metanet developer on a real macOS machine, starting from a clean clone.

What I ran:

git clone https://github.com/p2ppsr/use.bsv.tools.git
cd use.bsv.tools/starter
npm install
npm test
npm run preflight
npm run dev
node ./bin/wallet-preflight.mjs --strict

What worked:

• npm install completed cleanly with no vulnerabilities.
• npm test passed.
• npm run dev served the starter at http://127.0.0.1:7171.
• The three no-spend UI flows complete:
  • Paid API returns an HTTP 402 challenge and mock receipt.
  • Private Memory encrypts locally, stores ciphertext, lists it, and decrypts locally.
  • Creation Proof hashes metadata, signs it with WebCrypto, and verifies the signature.
• Browser console had no errors in the starter UI.

Where the real-world first-builder path still breaks:

1. Real wallet readiness can dead-end even when a wallet is installed.

   On this machine, Metanet Client.app was already listening on both expected ports, 127.0.0.1:3321 and 127.0.0.1:2121. The preflight correctly detected the listeners, but every status call timed out:

   • getVersion: timeout
   • isAuthenticated: timeout
   • getNetwork: timeout
   • real wallet loop: skipped because status checks failed
   • identity key: skipped because status checks failed

   curl also connected to http://localhost:3321/getVersion and then received no response, so this was not just the starter UI. node ./bin/wallet-preflight.mjs --strict exited 1, which is correct for a production gate, but the new developer is left with no concrete recovery path.

   Missing: exact instructions for what to do inside Metanet Client or BSV Desktop when ports are open but wallet API calls hang. The site needs screenshots or very explicit steps for origin approval, auth state, local API state, port ownership, app restart, and choosing one wallet when multiple wallet apps are installed.

2. The visible app result is still raw JSON, not a product-shaped success state.

   The starter proves mechanics, but every success state is JSON.stringify(...) output. That is useful for maintainers but not a satisfying first BSV result. A new developer should finish with a visible receipt/proof/record they can point to, not a debug dump.

   Suggested improvement: render each path as a real mini-product state:

   • Paid API: show price, payment challenge, paid receipt, and where a real AuthFetch/payment middleware swap occurs.
   • Private Memory: show stored record metadata, encrypted-vs-decrypted comparison, and whether the record is actually wallet-owned or only no-spend demo data.
   • Creation Proof: show a shareable proof card with signer, timestamp, artifact hash, verification status, and the next hook for UHRP storage or paid unlock.

3. The no-spend flows can be mistaken for production primitives.

   The README is honest that this is no-spend mock mode, but the app still needs stronger boundaries in the UI and in the generated prompts:

   • Private Memory uses a static browser AES-GCM key derived from use-bsv-tools-starter-no-spend-key. That is fine for a demo, but it is not wallet-owned user data.
   • Creation Proof uses a throwaway browser P-256 key, not a BRC-100 wallet identity or a durable creator identity.
   • Paid API pays by retrying with x-bsv-mock-payment: paid, not through AuthFetch or actual payment middleware.

   Missing: a hard “mock vs real” diff table for each flow with exact APIs/packages to swap in and acceptance checks for the real version.

4. Preflight is too slow and too raw for the first-run UI.

   On this run:

   • npm test took roughly 56 seconds.
   • CLI preflight took roughly 31 seconds.
   • UI preflight stayed on “Checking local wallet ports and real BRC-100 crypto loop...” for more than 35 seconds, then eventually rendered a raw JSON object.

   Suggested improvement: probe endpoints in parallel, show per-endpoint progress as rows, cap slow wallet probes more aggressively, and turn the final result into a diagnosis with next actions instead of dumping the full JSON by default.

5. The site needs a real ecosystem bridge after the starter.

   The current path gives a good first local slice, but it does not yet connect the dots for a developer who wants to build a non-toy Metanet app. The next page should be an explicit upgrade ladder:

   • BRC-100 wallet readiness and permissions
   • real wallet-backed signing/encryption
   • AuthFetch or payment middleware for low-value payments
   • UHRP/NanoStore upload and retrieval for content-addressed storage
   • Overlay topic manager + lookup service for shared/queryable state
   • CARS/LARS or another deployment path
   • app catalog / marketplace publication path

   Each rung should include: package name, known-good repo/example, one command, expected output, failure modes, and how to verify from another machine.

6. Docs need to stay accessible from terminal/agents.

   Several linked Project Babbage docs pages render as “You need to enable JavaScript” in basic fetch/search contexts. An aspiring developer using an AI agent or terminal-first workflow needs canonical markdown/raw docs, or the site should link directly to source-backed docs pages where possible. Otherwise the instruction “do not invent API methods” is hard to follow during real agent-assisted development.

7. Small starter packaging issue.

   starter/package.json contains duplicate dependencies keys. npm tolerates it, but starters should avoid anything that makes a new developer wonder whether the example is carefully maintained.

What I think would make this site the right website:

• Keep the current starter. It is a useful first step.
• Make the first run end in a tangible artifact, not only diagnostics: a paid receipt, wallet-backed private record, or signed proof page.
• Make real-wallet failure recovery first-class. “Port open but API timeout” should have a concrete checklist.
• Add a production upgrade ladder from starter -> wallet-backed -> UHRP -> overlay -> deploy/publish.
• Keep every tutorial tied to a pass/fail command and a visible result a new developer can verify.
• Make the mock/real boundary impossible to miss.

The important framing: this should not merely feel like a toy. A first-builder path should answer, “What did I actually build, who controls it, where is it stored, what did it cost, can another machine verify it, and what exact step makes it production-real?”

[ty-everett]

Wallet-side remediation has been merged in p2ppsr/metanet-client-desktop#26: https://github.com/p2ppsr/metanet-client-desktop/pull/26

Merged commit: b628019fde14900d9d52929f8cf922a52ca4452e

Correction to the earlier framing: WALLET_PERMISSION_REQUIRED is not the normal product success path, and builders should not have to handle it during ordinary wallet-backed app flow. The expected contract is:

• permission already exists -> the operation succeeds;
• permission is missing -> Metanet Client opens a permission prompt and the original app request waits;
• user grants -> that original request succeeds;
• user denies -> that original request fails at the denial point.

Root causes confirmed under local Tauri dev:

• Pre-login Metanet Client only answered the first /getVersion request, then detached, so later real app calls could be accepted by Rust and never answered.
• Authenticated bridge errors were inconsistent and unstructured.
• The installed toolbox getPublicKey path dropped explicit seekPermission=false, which is still worth fixing as a diagnostic/edge case, but it is not the core builder flow.
• The previous prompt-stress gate did not prove the actual allow/deny contract.
• The blanket 60s wallet-method timeout conflicted with legitimate permission prompts, because a real user decision should resolve the request rather than an arbitrary timer.

Merged remediation:

• keeps the pre-login bridge responsive;
• adds Rust-side not-ready responses instead of accepting requests into a missing frontend listener;
• removes the blanket wallet-method timeout;
• keeps structured errors for actual bad requests;
• adds the seekPermission=false compatibility patch only as an explicit no-prompt diagnostic/edge path;
• adds a local prompt QA gate that exercises real Grant and Deny decisions.

Validation run before merge:

• npm test
• npm run build
• npm run lint
• cargo check
• npm run qa:bridge
• npm run qa:bridge:prompt
• node --check scripts/wallet-bridge-qa.mjs

What npm run qa:bridge:prompt proves on a real authenticated Tauri wallet after removing the timeout:

• A fresh getPublicKey with seekPermission=true opens a real Metanet Client prompt; clicking Grant resolves the original HTTP request with HTTP 200 and publicKey.
• A second fresh getPublicKey with seekPermission=true opens a real prompt; clicking Deny resolves the original HTTP request with HTTP 400 and Permission denied..
• /isAuthenticated remains responsive after both decisions.

So the acceptance target for Issue #2 is not "throw a permission required error faster" and not "eventually timeout." The target is reliable prompt-mediated wallet behavior for real apps, with explicit diagnostics only for nonstandard no-prompt calls.

[ty-everett]

Current status after the Metanet Client Desktop fix landed:

• With fixed Metanet Client running locally, node ./bin/wallet-preflight.mjs --strict now passes against both http://localhost:3321 and https://localhost:2121 on this machine.
• The strict preflight verified: getVersion, isAuthenticated, getNetwork, derived public key, wallet encrypt/decrypt, wallet createSignature/verifySignature, and identity-key readiness.
• That proves the underlying BRC-100 wallet loop can work with the corrected wallet bridge.

But the starter is still not a real-tools-only entrypoint:

• /api/paid-summary still uses x-bsv-mock-payment: paid and returns mock-bsv-receipt-*.
• Private Memory still uses a static browser WebCrypto AES-GCM key, not wallet-owned encryption for the visible app flow.
• Creation Proof still uses a throwaway browser P-256 key, not wallet createSignature/verifySignature.
• The preflight wallet loop still uses seekPermission=false, so it is a diagnostic/no-prompt path and not the correct first-run prompt-mediated app path.

So Issue #2 is not done. The next use.bsv.tools remediation should remove mock/no-spend as the main entrypoint and make the starter's visible user actions use real BRC-100 wallet calls. For payment specifically, we should not fake it: either wire a real AuthFetch/payment-middleware flow with a configured receiving wallet/service, or remove/disable that path until the real service is available.