create-miden-app 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-miden-app",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A Miden Project Scaffold Template",
   "bin": {
     "create-miden-app": "cli.js"

package/template/.claude/commands/review-security.md

@@ -0,0 +1,67 @@
+---
+model: opus
+---
+
+You are a security-focused code reviewer specializing in web3, WASM, and TypeScript/Rust applications.
+
+Review the code at: $ARGUMENTS
+
+This can be a file, directory, or glob pattern. Read the relevant source files and perform a focused security audit across these dimensions, reporting only actual findings (skip any section with no issues):
+
+## 1. Input Validation & Injection
+- Are user-supplied strings (hex IDs, bech32 addresses, amounts) validated before being passed to WASM/Rust?
+- Can malformed input cause panics in Rust that propagate as unhandled exceptions in JS?
+- Are there any paths where unsanitized input reaches sensitive operations (key derivation, transaction building)?
+- Could numeric inputs overflow (e.g., BigInt conversion from plain numbers)?
+
+## 2. Key Material & Secrets
+- Is key material ever logged, serialized to JSON, or exposed in error messages?
+- Are private keys properly zeroed after use or held only in WASM memory?
+- Could keystore callbacks leak secrets through exception messages or stack traces?
+- Is seed material handled securely (not stored in localStorage, not logged)?
+
+## 3. Transaction Safety
+- Can transaction parameters be manipulated to send to unintended recipients?
+- Are there TOCTOU (time-of-check-time-of-use) issues between building and submitting transactions?
+- Could amount values be manipulated through type coercion (string→number precision loss)?
+- Are note IDs validated to prevent consuming the wrong notes?
+
+## 4. WASM Boundary
+- Are there memory safety issues at the JS↔WASM boundary?
+- Could JsValue conversions fail in ways that leave state inconsistent?
+- Are WASM errors properly caught or could they crash the runtime?
+- Is there potential for use-after-free when JS holds references to WASM objects?
+
+## 5. State & Storage
+- Is IndexedDB data integrity protected (could concurrent tabs corrupt state)?
+- Are there race conditions in async operations that could lead to double-spends or stale reads?
+- Could store export/import be used to replay old state maliciously?
+- Are database transactions (Dexie) used appropriately for atomic operations?
+
+## 6. Network & RPC
+- Are RPC responses validated before being trusted?
+- Could a malicious RPC endpoint feed incorrect block data or note metadata?
+- Is TLS enforced for RPC and prover connections?
+- Are there timing side-channels in how responses are processed?
+
+## 7. Supply Chain & Dependencies
+- Are there known vulnerable dependencies?
+- Are lockfile integrity hashes (`package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`) unchanged when WASM-bundled dependencies (e.g. `@miden-sdk/*`) update?
+- Could wasm-bindgen-generated glue code introduce issues?
+
+## Output Format
+
+For each finding, use severity levels:
+- **[CRITICAL]** - Exploitable vulnerability that could cause loss of funds or key compromise
+- **[HIGH]** - Security issue that should be fixed before production use
+- **[MEDIUM]** - Weakness that could be exploited under specific conditions
+- **[LOW]** - Defense-in-depth improvement
+- **[INFO]** - Observation worth noting but not directly exploitable
+
+For each finding include:
+1. File and line number
+2. Description of the vulnerability
+3. Attack scenario (how it could be exploited)
+4. Recommended fix
+
+End with a summary: count of findings by severity, and the top 3 highest-priority items to address.

package/template/.claude/settings.json

@@ -15,13 +15,7 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-affected-tests.sh",
             "timeout": 120,
             "statusMessage": "Running affected tests..."
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
+          },
           {
             "type": "command",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" && npx vitest --run && npx tsc -b --noEmit && npx vite build",

package/template/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:api.github.com)",
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_console_messages",
+      "mcp__playwright__browser_take_screenshot",
+      "WebFetch(domain:registry.npmjs.org)",
+      "mcp__playwright__browser_wait_for",
+      "mcp__playwright__browser_snapshot",
+      "mcp__playwright__browser_evaluate",
+      "WebFetch(domain:rpc.testnet.miden.io)",
+      "WebFetch(domain:testnet.midenscan.com)",
+      "WebFetch(domain:transport.miden.io)",
+      "mcp__playwright__browser_close",
+      "WebFetch(domain:scan-backend-testnet-miden.eu-central-8.gateway.fm)",
+      "WebFetch(domain:transport.devnet.miden.io)",
+      "WebFetch(domain:tx-prover.testnet.miden.io)",
+      "WebFetch(domain:registry.yarnpkg.com)",
+      "mcp__playwright__browser_network_requests"
+    ]
+  }
+}

package/template/.claude/skills/frontend-pitfalls/SKILL.md

@@ -18,7 +18,7 @@ function App() {
 
 // CORRECT — use loadingComponent or check isReady
 <MidenProvider
-  config={{ rpcUrl: "devnet" }}
+  config={{ rpcUrl: "testnet" }}
   loadingComponent={<p>Loading WASM...</p>}
 >
   <App />
@@ -44,8 +44,9 @@ const handleClick = async () => {
 };
 
 // CORRECT — use runExclusive for sequential execution
+const client = useMidenClient();
 const { runExclusive } = useMiden();
-await runExclusive(async (client) => {
+await runExclusive(async () => {
   await client.syncState();
   // now safe to do next operation
 });
@@ -57,22 +58,22 @@ Built-in hooks (useSend, useConsume, etc.) already use runExclusive internally.
 
 WASM SharedArrayBuffer requires these headers. Without them, WASM init silently fails.
 
+The template's source-of-truth pattern is to opt into COOP/COEP via the Vite plugin explicitly:
+
 ```ts
-// REQUIRED in vite.config.ts
-server: {
-  headers: {
-    "Cross-Origin-Opener-Policy": "same-origin",
-    "Cross-Origin-Embedder-Policy": "require-corp",
-  },
-},
-
-// ALSO REQUIRED on production server (nginx, Vercel, Cloudflare)
-// See vite-wasm-setup skill for deployment configs
+// vite.config.ts — template default
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
+});
 ```
 
-**Gotcha**: These headers break third-party iframes, external scripts without CORS, and OAuth popups. Use `credentialless` for COEP if cross-origin resources are needed.
+Do not rely on the plugin's own default — `@miden-sdk/vite-plugin` defaults `crossOriginIsolation` to `false`, and that default has shifted across releases. Pass `true` explicitly on any route that runs Miden client code.
+
+COOP/COEP must also be set on the production server — the plugin only covers the Vite dev server. See `vite-wasm-setup` for per-host configs (Nginx, Vercel, Cloudflare).
 
-**Note**: `midenVitePlugin()` from `@miden-sdk/vite-plugin` handles COOP/COEP automatically via its `crossOriginIsolation` option (defaults to `false` to avoid breaking OAuth popups). Enable it instead of setting headers manually.
+**Gotcha (opt-out path)**: Cross-origin-isolation breaks third-party iframes, external scripts without CORS, and OAuth popups. If a route must host those and cannot use Miden client code, either (a) use `Cross-Origin-Embedder-Policy: credentialless` for weaker isolation that still allows most cross-origin resources, or (b) scope `crossOriginIsolation: false` to that specific route and accept that Miden operations won't work there. Do not disable isolation globally as a convenience.
 
 ## FP4: BigInt Type Mismatch (HIGH)
 
@@ -117,7 +118,7 @@ Default `autoSyncInterval` is 15000ms (15 seconds). Each sync triggers re-render
 
 ```tsx
 // PROBLEM — form resets every 15 seconds because parent re-renders
-<MidenProvider config={{ rpcUrl: "devnet" }}>
+<MidenProvider config={{ rpcUrl: "testnet" }}>
   <SendForm />  {/* re-renders on every sync */}
 </MidenProvider>
 
@@ -125,7 +126,7 @@ Default `autoSyncInterval` is 15000ms (15 seconds). Each sync triggers re-render
 const MemoizedForm = React.memo(SendForm);
 
 // SOLUTION 2 — disable auto-sync for manual control
-<MidenProvider config={{ rpcUrl: "devnet", autoSyncInterval: 0 }}>
+<MidenProvider config={{ rpcUrl: "testnet", autoSyncInterval: 0 }}>
 ```
 
 ## FP7: IndexedDB State Loss (MEDIUM)
@@ -138,40 +139,36 @@ The client persists accounts, keys, and notes in IndexedDB. Browser "Clear site
 
 ## FP8: Vite Configuration Requirements (MEDIUM)
 
-The `@miden-sdk/vite-plugin` package handles all Miden-specific Vite config.
-The minimal setup is:
+The `@miden-sdk/vite-plugin` package handles all Miden-specific Vite config. The template's source-of-truth pattern — which you should copy for any new Miden app — is:
 
 ```ts
 import { midenVitePlugin } from "@miden-sdk/vite-plugin";
 
 export default defineConfig({
-  plugins: [react(), midenVitePlugin()],
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
 });
 ```
 
-`midenVitePlugin()` handles: WASM loading, top-level await, WASM pre-bundling exclusion,
-and optionally COOP/COEP headers (via the `crossOriginIsolation` option, defaults to `false`
-to avoid breaking OAuth popups).
+`midenVitePlugin()` handles WASM loading, top-level await, pre-bundling exclusion, and — when `crossOriginIsolation: true` is passed — emits the COOP `same-origin` + COEP `require-corp` headers the SDK requires for `SharedArrayBuffer`.
 
-| Option | Default | Purpose |
-|--------|---------|---------|
-| `crossOriginIsolation` | `false` | Add COOP/COEP headers for SharedArrayBuffer |
+| Option | Plugin default | Template default | Purpose |
+|--------|----------------|------------------|---------|
+| `crossOriginIsolation` | `false` | **`true`** | Emit COOP/COEP headers for SharedArrayBuffer |
 
-Enable `crossOriginIsolation: true` only if your app doesn't use OAuth or cross-origin iframes.
-For production COOP/COEP, set headers at the server level (see vite-wasm-setup skill).
+Always pass `crossOriginIsolation: true` explicitly. The plugin's `false` default is wrong for a Miden app, and relying on it risks silent WASM-init failures if the default shifts in a future release. The opt-out path (routes that host OAuth popups or cross-origin iframes incompatible with isolation) is discussed in FP3. For production, set the same headers at the server level — see `vite-wasm-setup` for host-specific configs.
 
 ## FP9: React StrictMode Double-Init (LOW)
 
-React 19 StrictMode double-invokes effects in development. MidenProvider handles this via `isInitializedRef`, but direct `WebClient.createClient()` calls will initialize twice.
+React 19 StrictMode double-invokes effects in development. MidenProvider handles this via `isInitializedRef`, but direct `WasmWebClient.createClient()` calls will initialize twice. (The SDK exports `WasmWebClient` as `WebClient` for convenience.)
 
 ```tsx
 // WRONG — manual client creation in useEffect
 useEffect(() => {
-  const client = await WebClient.createClient(url); // called twice in dev
+  const client = await WasmWebClient.createClient(url); // called twice in dev
 }, []);
 
 // CORRECT — always use MidenProvider
-<MidenProvider config={{ rpcUrl: "devnet" }}>
+<MidenProvider config={{ rpcUrl: "testnet" }}>
 ```
 
 ## Quick Reference
@@ -185,5 +182,5 @@ useEffect(() => {
 | FP5 | Bech32 mismatch | HIGH | Match network in rpcUrl and addresses |
 | FP6 | Auto-sync | MEDIUM | Set autoSyncInterval: 0 if UI stability matters |
 | FP7 | IndexedDB loss | MEDIUM | Warn users; use external signers for production |
-| FP8 | Vite config | MEDIUM | Use `midenVitePlugin()` — it handles all Miden Vite config |
+| FP8 | Vite config | MEDIUM | Always pass `midenVitePlugin({ crossOriginIsolation: true })` — don't rely on the plugin default |
 | FP9 | StrictMode | LOW | Use MidenProvider, not manual client creation |

package/template/.claude/skills/frontend-source-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-source-guide
-description: Guide for advanced Miden frontend development using source repo exploration. Covers AI development practices (Plan Mode, verification-driven development, context engineering, sub-agents) and maps the miden-client source repository for discovering advanced patterns. Use when building complex applications beyond basic hook usage, implementing custom signers, working with raw WebClient, or troubleshooting SDK internals.
+description: Guide for advanced Miden frontend development using source repo exploration. Covers AI development practices (Plan Mode, verification-driven development, context engineering, sub-agents) and maps the miden-client source repository for discovering advanced patterns. Use when building complex applications beyond basic hook usage, implementing custom signers, working with WasmWebClient directly, or troubleshooting SDK internals.
 ---
 
 # Advanced Miden Frontend Development: Source-Guided Context Engineering
@@ -13,7 +13,7 @@ For any non-trivial frontend application, start in Plan Mode before writing code
 
 - Explore React SDK source and examples to understand available patterns
 - Design the component hierarchy, data flow, and which hooks to use
-- Identify which built-in hooks cover your needs vs what requires raw WebClient
+- Identify which built-in hooks cover your needs vs what requires direct WasmWebClient access
 - Map out the user flow: account creation, token operations, note handling
 
 Rule of thumb: if the task involves custom transactions, external signers, or patterns not covered by the basic skills, plan first.
@@ -70,7 +70,7 @@ When stuck at any stage: search the React SDK source for a similar working patte
 Clone this repo alongside your project for reference. Claude will explore it when needed for advanced patterns.
 
 ```bash
-# Contains React SDK source, WebClient WASM bindings, and working examples
+# Contains React SDK source, WasmWebClient WASM bindings, and working examples
 git clone --depth 1 https://github.com/0xMiden/miden-client.git ../miden-client
 ```
 
@@ -92,10 +92,10 @@ The primary reference for all frontend development.
 
 The Rust-to-WASM bridge that the React SDK wraps.
 
-- Contains the `WebClient` struct and all methods available via `useMidenClient()`
+- Contains the `WasmWebClient` struct and all methods available via `useMidenClient()`
 - JavaScript bindings in `js/` directory
 
-**Explore when**: A hook doesn't exist for your operation, understanding what WebClient methods are available, debugging WASM-level errors.
+**Explore when**: A hook doesn't exist for your operation, understanding what WasmWebClient methods are available, debugging WASM-level errors.
 
 ### `crates/idxdb-store/` — IndexedDB Persistence
 
@@ -117,14 +117,14 @@ The browser storage layer for accounts, keys, notes, and transaction history.
 | Token display | `src/utils/amounts.ts` | formatAssetAmount, parseAssetAmount |
 | Account ID formatting | `src/utils/accountBech32.ts` | toBech32AccountId |
 | State management | `src/store/MidenStore.ts` | Zustand selectors, cached state |
-| Direct WebClient usage | `src/context/MidenProvider.tsx` | useMidenClient(), runExclusive |
+| Direct WasmWebClient usage | `src/context/MidenProvider.tsx` | useMidenClient(), runExclusive |
 | Multi-step workflow | `src/hooks/useWaitForCommit.ts`, `useWaitForNotes.ts` | Polling, timeout patterns |
 
 ---
 
 ## Common Advanced Patterns
 
-### Custom Hooks Wrapping WebClient
+### Custom Hooks Wrapping WasmWebClient
 For operations not covered by built-in hooks, create custom hooks that use useMidenClient() and runExclusive:
 ```tsx
 function useBlockHeader(blockNumber: number) {
@@ -146,16 +146,16 @@ function useBlockHeader(blockNumber: number) {
 ### Multi-Step Workflows
 Compose hooks for complex flows (mint → wait for commit → sync → consume):
 ```tsx
-const { mutate: mint } = useMint();
-const { mutate: waitForCommit } = useWaitForCommit();
-const { mutate: waitForNotes } = useWaitForNotes();
-const { mutate: consume } = useConsume();
+const { mint } = useMint();
+const { waitForCommit } = useWaitForCommit();
+const { waitForConsumableNotes } = useWaitForNotes();
+const { consume } = useConsume();
 
 const mintAndConsume = async () => {
   const { transactionId } = await mint({ targetAccountId, faucetId, amount });
-  await waitForCommit({ transactionId });
-  await waitForNotes({ accountId: targetAccountId });
-  await consume({ accountId: targetAccountId, noteIds: [...] });
+  await waitForCommit(transactionId);
+  await waitForConsumableNotes({ accountId: targetAccountId });
+  await consume({ accountId: targetAccountId, notes: [...] });
 };
 ```
 

package/template/.claude/skills/miden-concepts/SKILL.md

@@ -40,7 +40,7 @@ Accounts are composed from **components** — reusable Rust modules annotated wi
 ### Notes
 Notes are **UTXO-like messages** for asynchronous inter-account communication. A note contains:
 - **Script** — Logic that executes when the note is consumed
-- **Inputs** — Data passed to the script (Vec<Felt>)
+- **Storage** — Data accessible to the script during execution (`NoteStorage`, Vec<Felt>)
 - **Assets** — Fungible/non-fungible tokens attached to the note
 - **Metadata** — Sender, tag, note type (public/private)
 
@@ -84,7 +84,9 @@ A transaction is a **single-account state transition** with 4 phases:
 | `BasicWallet` | Standard wallet: `receive_asset()`, `move_asset_to_note()` |
 | `BasicFungibleFaucet` | Mint/burn fungible tokens |
 | `NoAuth` | No authentication (for testing) |
-| `AuthFalcon512Rpo` | Production signature authentication |
+| `AuthSingleSig` | Production signature authentication — unified auth component covering both Falcon-512 and ECDSA-K256 key types |
+
+**v14 note**: `AuthSingleSig` unifies what were previously per-scheme auth components (one for Falcon-512, one for ECDSA-K256) into a single component that dispatches on the key type ([miden-client#1798](https://github.com/0xMiden/miden-client/pull/1798)). In the same release the underlying Falcon-512 signature scheme adopted Poseidon2 as its hash function, and is now named `Falcon512Poseidon2`. If you see the older per-scheme component names or the old signature-scheme name in examples or docs, the source predates 0.14 and needs updating.
 
 ## Development Model