phygital-token-mcp 0.1.1

package/docs/verification/overview.md

@@ -0,0 +1,70 @@
+# Verification overview
+
+Phygital assets support two fundamentally different checks. Pick the wrong one and you either annoy users with unnecessary taps or accept replayable proofs.
+
+## The two questions
+
+| Kind | Question | User taps again? |
+|------|----------|------------------|
+| **Identification** | Which asset is this? | No |
+| **Authentication** | Is the holder here right now? | Yes |
+
+Think of identification like reading a signed badge from a prior scan. Think of authentication like requiring a live tap before a high-value action.
+
+## Decision tree
+
+```
+Do you need the holder physically present right now?
+├─ NO → Identification
+│   ├─ Online, replay protection → verifyDynamicUrl
+│   └─ Offline / no backend → verifyDynamicUrlWithoutCounterCheck (weaker)
+└─ YES → Authentication
+    ├─ Off-chain only (UI login, no chain) → verifyWithChallengeResponse / OverNfc
+    ├─ On-chain proof for your program → beginVerifyAsset composable flow (see below)
+    └─ Transfer ownership → beginTransfer → completeTransfer (NOT verify_asset)
+```
+
+## Off-chain vs on-chain authentication
+
+`verifyWithChallengeResponse` and `verifyWithChallengeResponseOverNfc` are **off-chain only**. They prompt an NFC tap and verify the WebAuthn signature in the client. They do **not** submit a transaction.
+
+For on-chain proof that a passkey holder signed a specific message at a specific slot, use the composable `beginVerifyAsset` flow.
+
+## Two ways to compose on-chain with your program
+
+Both patterns start the same on the client: `beginVerifyAsset` → tap → `buildVerifyAssetArgs` (or `completeVerifyAsset`).
+
+| Pattern | Client transaction | Your on-chain program |
+|---------|-------------------|----------------------|
+| **A — Inspect** | `[secp256r1_verify, verify_asset, your_ix]` | Scans instructions sysvar for a preceding `verify_asset`; checks `message` bytes |
+| **B — CPI** | `[secp256r1_verify, your_ix]` | CPIs `phygital_token::verify_asset` using args from `buildVerifyAssetArgs` |
+
+### Pattern A — Client posts `verify_asset`, program inspects
+
+The client includes the full `verify_asset` instruction (via `completeVerifyAsset` or `getVerifyAssetInstruction`). Your program runs **after** it and reads the instructions sysvar to confirm a matching `verify_asset` ran with the expected `message`.
+
+Reference: `phygital-spend` — `require_matching_verify_asset`.
+
+### Pattern B — Client posts `secp256r1_verify`, program CPIs `verify_asset`
+
+The client uses `buildVerifyAssetArgs` to get `secp256r1Verify` and the verify args, but does **not** include `verify_asset` in the transaction. Your program receives those args (via instruction data) and CPIs `verify_asset` via `VerifyAssetCpiBuilder` from `phygital-token-client`.
+
+`secp256r1_verify` must still appear **before** your program's instruction in the transaction.
+
+## Message binding
+
+- **Transfer** challenge binds the asset PDA (recipient chosen later at wallet confirm).
+- **Verify asset** challenge binds arbitrary `message` bytes. Hash on-chain: `SHA256(message)`.
+- **Dynamic URL** binds `counter || nonce` (uint32 BE + 8 random bytes).
+
+Embed domain-specific bytes in `message` so a proof for one action cannot authorize another.
+
+## Slot freshness
+
+`verify_asset` records `asset.last_transfer_slot`. Each verification must use a **strictly greater** slot. Complete the flow promptly after `beginVerifyAsset` (~512 slots).
+
+## Next docs
+
+- [Verification methods](./methods.md) — every `verify.ts` export
+- [Composable verify_asset](./verify-asset-composable.md) — `buildVerifyAssetArgs` and both patterns
+- [Building on phygital](../building-on-phygital/overview.md)

package/docs/verification/verify-asset-composable.md

@@ -0,0 +1,97 @@
+# Composable `verify_asset` (TypeScript)
+
+On-chain passkey authentication for custom programs. **Not** the same as `verifyWithChallengeResponse` (which is off-chain only).
+
+## Session flow
+
+```
+beginVerifyAsset({ rpc, message })
+        ↓
+authenticatePasskeyForVerifyAsset(session)   // WebAuthn NFC tap
+        ↓
+buildVerifyAssetArgs(session, response)      // or completeVerifyAsset(...)
+        ↓
+assemble transaction (Pattern A or B below)
+```
+
+## Functions
+
+### `beginVerifyAsset({ rpc, message: Uint8Array })`
+
+Slot-bound challenge: `SHA256("verify_asset" || SHA256(message) || slotHash)`.
+
+### `buildVerifyAssetArgs(session, response)`
+
+Returns `secp256r1Verify`, `signedMessageIndex`, `clientDataJson`, `asset`, `assetPda`.
+
+### `completeVerifyAsset(session, response)`
+
+Returns `[secp256r1Verify, verifyAssetInstruction]`.
+
+## Pattern A — Client posts `verify_asset`, program inspects
+
+**Client transaction order:**
+
+```
+secp256r1_verify → verify_asset → your_program_ix
+```
+
+```ts
+const session = await beginVerifyAsset({ rpc, message });
+const response = await authenticatePasskeyForVerifyAsset(session);
+
+const [secp256r1Verify, verifyAssetIx] = await completeVerifyAsset(
+  session,
+  response,
+);
+
+const myIx = buildMyProgramInstruction(/* binds same message bytes */);
+
+await sendTransaction([secp256r1Verify, verifyAssetIx, myIx], { feePayer });
+```
+
+**Your Rust program:** Scan `instructions_sysvar` for the `verify_asset` instruction that ran earlier in this transaction. Decode and verify `message` matches your canonical payload. Reference: `phygital-spend`.
+
+## Pattern B — Client posts `secp256r1_verify`, program CPIs `verify_asset`
+
+**Client transaction order:**
+
+```
+secp256r1_verify → your_program_ix
+```
+
+```ts
+const session = await beginVerifyAsset({ rpc, message });
+const response = await authenticatePasskeyForVerifyAsset(session);
+
+const { secp256r1Verify, signedMessageIndex, clientDataJson, assetPda } =
+  await buildVerifyAssetArgs(session, response);
+
+// Pass verify args to your program via instruction data
+const myIx = buildMyProgramInstruction({
+  asset: assetPda,
+  secp256r1VerifyArgs: {
+    signedMessageIndex,
+    slotNumber: session.slotNumber,
+    clientDataJson,
+  },
+  message: session.message,
+});
+
+await sendTransaction([secp256r1Verify, myIx], { feePayer });
+```
+
+**Your Rust program:** CPI `verify_asset` using `VerifyAssetCpiBuilder` from `phygital-token-client`. The `secp256r1_verify` instruction must appear earlier in the same transaction (verified via instructions sysvar inside `verify_asset`).
+
+## `verify_asset` instruction layout
+
+Accounts: `asset` (writable), `slot_hashes`, `instructions_sysvar`.
+
+Args: `{ secp256r1VerifyArgs: { signedMessageIndex, slotNumber, clientDataJson }, message }`.
+
+## On-chain effects
+
+- Verifies WebAuthn signature against slot-bound challenge
+- Sets `asset.last_transfer_slot = slotNumber`
+- Emits `VerifyAssetEvent`
+- Does not change token owner or balance

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "phygital-token-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for the phygital-token Solana program, TypeScript SDK, and Rust client",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jychab/phygital-nfts.git",
+    "directory": "mcp/phygital-token"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "solana",
+    "phygital",
+    "webauthn",
+    "nft"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "phygital-token-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "cursor-mcp.example.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@noble/hashes": "^2.0.1",
+    "@solana/kit": "^6.4.0",
+    "phygital-token-sdk": "^0.6.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/add-shebang.mjs",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/index.js"
+  }
+}