phygital-token-mcp 0.1.1

package/dist/lib/sdk-surface.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { pathExists, resolveRustVerifyAssetPath, resolveVerifyAssetTsPath, resolveVerifyTsPath, } from "./paths.js";
+export const SDK_SURFACE = {
+    mint: [
+        "buildCreateMintInstructions",
+        "buildMintTokenInstructions",
+        "parseSecp256r1Pubkey",
+        "parseCredentialId",
+        "validateMetadataFields",
+    ],
+    transfer: [
+        "beginTransfer",
+        "authenticatePasskeyForTransfer",
+        "completeTransfer",
+    ],
+    verifyAssetComposable: [
+        "beginVerifyAsset",
+        "authenticatePasskeyForVerifyAsset",
+        "buildVerifyAssetArgs",
+        "completeVerifyAsset",
+    ],
+    verification: [
+        "verifyDynamicUrl",
+        "verifyDynamicUrlWithoutCounterCheck",
+        "verifyWithChallengeResponse",
+        "verifyWithChallengeResponseOverNfc",
+    ],
+    onChainComposition: {
+        patternA_inspect: {
+            client: ["beginVerifyAsset", "completeVerifyAsset"],
+            transaction: ["secp256r1_verify", "verify_asset", "your_program_ix"],
+            program: "inspect instructions sysvar for verify_asset message",
+        },
+        patternB_cpi: {
+            client: ["beginVerifyAsset", "buildVerifyAssetArgs"],
+            transaction: ["secp256r1_verify", "your_program_ix"],
+            program: "CPI verify_asset via VerifyAssetCpiBuilder",
+        },
+    },
+    assetLookup: [
+        "findAssetPda",
+        "fetchAssetFromCredentialId",
+        "fetchAllAssetsFromOwner",
+        "fetchAssetDisplayInfo",
+        "resolveMedia",
+    ],
+    gating: [
+        "Gating",
+        "GatingTraitValue",
+        "formatGatingPredicate",
+        "summarizeGatingEvaluationFailure",
+        "summarizeGatingFailure",
+        "summarizeGatingTierFailure",
+        "evaluateAssetGating",
+    ],
+    gatingTypes: [
+        "EvaluateAssetGatingOptions",
+        "GatingFilter",
+        "GatingAssetPredicate",
+        "GatingTier",
+        "GatingEvaluationResult",
+        "GatingFilterResult",
+        "GatingTierEvaluationResult",
+        "GatingTiersEvaluationResult",
+    ],
+    generated: [
+        "getCreateMintInstructionAsync",
+        "getMintTokenInstructionAsync",
+        "getExecuteTransferInstructionAsync",
+        "getVerifyAssetInstruction",
+        "getSetLockStateInstruction",
+        "fetchAsset",
+        "findProgramAuthorityPda",
+        "PHYGITAL_TOKEN_PROGRAM_ADDRESS",
+    ],
+    rustClient: {
+        crate: "phygital-token-client",
+        path: "clients/rust/phygital-token",
+        features: ["anchor", "fetch"],
+        cpi: ["VerifyAssetCpi", "VerifyAssetCpiBuilder", "VerifyAssetInstructionArgs"],
+        types: ["Asset", "Secp256r1VerifyArgs", "AssetType"],
+    },
+};
+export async function readSourceExcerpt(which, maxLines = 120) {
+    const paths = {
+        "verify.ts": resolveVerifyTsPath(),
+        "verifyAsset.ts": resolveVerifyAssetTsPath(),
+        "rust_verify_asset.rs": resolveRustVerifyAssetPath(),
+    };
+    const filePath = paths[which];
+    if (!(await pathExists(filePath))) {
+        throw new Error(`Source file not found: ${filePath}. Set PHYGITAL_TOKEN_REPO_ROOT to a cloned phygital-token repo to use read_sdk_source.`);
+    }
+    const content = await readFile(filePath, "utf8");
+    const lines = content.split("\n").slice(0, maxLines);
+    return {
+        path: filePath,
+        excerpt: lines.join("\n") + (content.split("\n").length > maxLines ? "\n// ..." : ""),
+    };
+}
+//# sourceMappingURL=sdk-surface.js.map

package/dist/lib/sdk-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-surface.js","sourceRoot":"","sources":["../../src/lib/sdk-surface.ts"],"names":[],"mappings":"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"}

package/dist/lib/verification.d.ts

@@ -0,0 +1,43 @@
+export type VerificationUseCase = "product_page_lookup" | "deep_link_from_prior_scan" | "offline_identification" | "login_ui_only" | "onchain_standalone_verify" | "onchain_inspect_verify_asset" | "onchain_cpi_verify_asset" | "transfer_ownership" | "wallet_holdings_gate" | "native_mobile_app";
+export type OnChainCompositionPattern = "inspect" | "cpi" | "standalone";
+export type VerificationRecommendation = {
+    method: string;
+    sdkExports: string[];
+    requiresTap: boolean;
+    onChain: boolean;
+    onChainPattern?: OnChainCompositionPattern;
+    rationale: string;
+    docIds: string[];
+    cautions?: string[];
+};
+export declare const ON_CHAIN_PATTERNS: {
+    readonly inspect: {
+        readonly id: "inspect";
+        readonly name: "Pattern A — client posts verify_asset, program inspects";
+        readonly clientTransaction: readonly ["secp256r1_verify", "verify_asset", "your_program_ix"];
+        readonly clientSdk: readonly ["beginVerifyAsset", "completeVerifyAsset", "getVerifyAssetInstruction"];
+        readonly programRust: "Scan instructions sysvar for preceding verify_asset; check message bytes";
+        readonly reference: "programs/phygital-spend";
+    };
+    readonly cpi: {
+        readonly id: "cpi";
+        readonly name: "Pattern B — client posts secp256r1_verify, program CPIs verify_asset";
+        readonly clientTransaction: readonly ["secp256r1_verify", "your_program_ix"];
+        readonly clientSdk: readonly ["beginVerifyAsset", "buildVerifyAssetArgs"];
+        readonly programRust: "VerifyAssetCpiBuilder from phygital-token-client";
+        readonly reference: "clients/rust/phygital-token";
+    };
+    readonly standalone: {
+        readonly id: "standalone";
+        readonly name: "Standalone on-chain verify_asset (no custom program)";
+        readonly clientTransaction: readonly ["secp256r1_verify", "verify_asset"];
+        readonly clientSdk: readonly ["beginVerifyAsset", "completeVerifyAsset"];
+        readonly programRust: "N/A";
+    };
+};
+export declare function recommendVerification(useCase: VerificationUseCase): VerificationRecommendation;
+export declare function listVerificationUseCases(): Array<{
+    id: VerificationUseCase;
+    summary: string;
+}>;
+export declare const VERIFICATION_DECISION_TREE: string;

package/dist/lib/verification.js

@@ -0,0 +1,166 @@
+export const ON_CHAIN_PATTERNS = {
+    inspect: {
+        id: "inspect",
+        name: "Pattern A — client posts verify_asset, program inspects",
+        clientTransaction: ["secp256r1_verify", "verify_asset", "your_program_ix"],
+        clientSdk: ["beginVerifyAsset", "completeVerifyAsset", "getVerifyAssetInstruction"],
+        programRust: "Scan instructions sysvar for preceding verify_asset; check message bytes",
+        reference: "programs/phygital-spend",
+    },
+    cpi: {
+        id: "cpi",
+        name: "Pattern B — client posts secp256r1_verify, program CPIs verify_asset",
+        clientTransaction: ["secp256r1_verify", "your_program_ix"],
+        clientSdk: ["beginVerifyAsset", "buildVerifyAssetArgs"],
+        programRust: "VerifyAssetCpiBuilder from phygital-token-client",
+        reference: "clients/rust/phygital-token",
+    },
+    standalone: {
+        id: "standalone",
+        name: "Standalone on-chain verify_asset (no custom program)",
+        clientTransaction: ["secp256r1_verify", "verify_asset"],
+        clientSdk: ["beginVerifyAsset", "completeVerifyAsset"],
+        programRust: "N/A",
+    },
+};
+const RECOMMENDATIONS = {
+    product_page_lookup: {
+        method: "identification — verifyDynamicUrl",
+        sdkExports: ["verifyDynamicUrl"],
+        requiresTap: false,
+        onChain: false,
+        rationale: "User already scanned; signed URL params identify the asset without a second tap.",
+        docIds: ["verification:methods", "verification:overview"],
+    },
+    deep_link_from_prior_scan: {
+        method: "identification — verifyDynamicUrl",
+        sdkExports: ["verifyDynamicUrl"],
+        requiresTap: false,
+        onChain: false,
+        rationale: "Signed deep-link params from an earlier tap.",
+        docIds: ["verification:methods"],
+    },
+    offline_identification: {
+        method: "identification — verifyDynamicUrlWithoutCounterCheck",
+        sdkExports: ["verifyDynamicUrlWithoutCounterCheck"],
+        requiresTap: false,
+        onChain: false,
+        rationale: "Local signature check only. Not for authorization.",
+        docIds: ["verification:methods"],
+        cautions: ["Copied links can be replayed."],
+    },
+    login_ui_only: {
+        method: "authentication off-chain — verifyWithChallengeResponse",
+        sdkExports: ["verifyWithChallengeResponse", "verifyWithChallengeResponseOverNfc"],
+        requiresTap: true,
+        onChain: false,
+        rationale: "Live NFC tap verified in the client. Optional message binds the WebAuthn challenge (UTF-8). No on-chain transaction.",
+        docIds: ["verification:methods", "verification:overview"],
+    },
+    onchain_standalone_verify: {
+        method: "on-chain verify_asset only",
+        sdkExports: ["beginVerifyAsset", "authenticatePasskeyForVerifyAsset", "completeVerifyAsset"],
+        requiresTap: true,
+        onChain: true,
+        onChainPattern: "standalone",
+        rationale: "Record passkey proof on-chain without a custom program.",
+        docIds: ["verification:verify-asset-composable"],
+    },
+    onchain_inspect_verify_asset: {
+        method: "Pattern A — client posts verify_asset, your program inspects message",
+        sdkExports: [
+            "beginVerifyAsset",
+            "authenticatePasskeyForVerifyAsset",
+            "completeVerifyAsset",
+            "getVerifyAssetInstruction",
+        ],
+        requiresTap: true,
+        onChain: true,
+        onChainPattern: "inspect",
+        rationale: "Client includes verify_asset in the tx. Your program scans instructions sysvar for that verify_asset and validates message bytes.",
+        docIds: [
+            "verification:verify-asset-composable",
+            "building-on-phygital:overview",
+            "building-on-phygital:rust-cpi",
+        ],
+    },
+    onchain_cpi_verify_asset: {
+        method: "Pattern B — buildVerifyAssetArgs, your program CPIs verify_asset",
+        sdkExports: [
+            "beginVerifyAsset",
+            "authenticatePasskeyForVerifyAsset",
+            "buildVerifyAssetArgs",
+        ],
+        requiresTap: true,
+        onChain: true,
+        onChainPattern: "cpi",
+        rationale: "Client includes secp256r1_verify + your ix only. Your program CPIs verify_asset using args from buildVerifyAssetArgs.",
+        docIds: [
+            "verification:verify-asset-composable",
+            "building-on-phygital:rust-cpi",
+            "building-on-phygital:overview",
+        ],
+    },
+    transfer_ownership: {
+        method: "transfer — beginTransfer / completeTransfer",
+        sdkExports: ["beginTransfer", "authenticatePasskeyForTransfer", "completeTransfer"],
+        requiresTap: true,
+        onChain: true,
+        rationale: "Token claim uses execute_transfer, not verify_asset.",
+        docIds: ["verification:overview"],
+        cautions: ["Do not use verifyDynamicUrl for transfers."],
+    },
+    wallet_holdings_gate: {
+        method: "gating — evaluateAssetGating",
+        sdkExports: ["evaluateAssetGating", "Gating", "GatingTraitValue"],
+        requiresTap: false,
+        onChain: false,
+        rationale: "Wallet holdings via DAS. No passkey tap.",
+        docIds: ["gating:overview"],
+    },
+    native_mobile_app: {
+        method: "authentication off-chain — verifyWithChallengeResponseOverNfc",
+        sdkExports: ["verifyWithChallengeResponseOverNfc"],
+        requiresTap: true,
+        onChain: false,
+        rationale: "Native NFC transceive. Off-chain only; use beginVerifyAsset for on-chain proof.",
+        docIds: ["verification:methods"],
+    },
+};
+export function recommendVerification(useCase) {
+    return RECOMMENDATIONS[useCase];
+}
+export function listVerificationUseCases() {
+    return [
+        { id: "product_page_lookup", summary: "Product page from prior scan URL" },
+        { id: "deep_link_from_prior_scan", summary: "App opens from signed deep link" },
+        { id: "offline_identification", summary: "Identify asset offline (weak replay)" },
+        { id: "login_ui_only", summary: "Off-chain tap-to-login (no chain tx)" },
+        { id: "onchain_standalone_verify", summary: "On-chain verify_asset only" },
+        {
+            id: "onchain_inspect_verify_asset",
+            summary: "Pattern A: client posts verify_asset, your program inspects message",
+        },
+        {
+            id: "onchain_cpi_verify_asset",
+            summary: "Pattern B: buildVerifyAssetArgs, your program CPIs verify_asset",
+        },
+        { id: "transfer_ownership", summary: "Claim/transfer token to new owner" },
+        { id: "wallet_holdings_gate", summary: "Gate by wallet NFTs/tokens" },
+        { id: "native_mobile_app", summary: "Native app off-chain authentication" },
+    ];
+}
+export const VERIFICATION_DECISION_TREE = `
+Identification vs Authentication
+├── Need holder present NOW?
+│   NO → verifyDynamicUrl / verifyDynamicUrlWithoutCounterCheck
+│   YES → Need on-chain proof?
+│         NO → verifyWithChallengeResponse (web) / OverNfc (native) — off-chain only
+│         YES → beginVerifyAsset composable flow:
+│               Pattern A: [secp256r1_verify, verify_asset, your_ix] — program inspects sysvar
+│               Pattern B: [secp256r1_verify, your_ix] — program CPIs verify_asset
+└── Transfer ownership? → beginTransfer → completeTransfer
+
+verifyWithChallengeResponse never submits verify_asset. On-chain proof always uses beginVerifyAsset.
+`.trim();
+//# sourceMappingURL=verification.js.map

package/dist/lib/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../src/lib/verification.ts"],"names":[],"mappings":"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"}

package/docs/building-on-phygital/overview.md

@@ -0,0 +1,46 @@
+# Building on phygital assets
+
+Third-party developers can:
+
+- **Gate off-chain** by wallet holdings → `evaluateAssetGating`
+- **Require live passkey presence on-chain** → composable `verify_asset` (two patterns below)
+
+## Two on-chain composition patterns
+
+Both start with the same client flow: `beginVerifyAsset` → NFC tap → `buildVerifyAssetArgs`.
+
+### Pattern A — Client posts `verify_asset`, your program inspects
+
+| Layer | Responsibility |
+|-------|----------------|
+| **Client** | `[secp256r1_verify, verify_asset, your_ix]` via `completeVerifyAsset` |
+| **Your program** | Read instructions sysvar; find preceding `verify_asset`; verify `message` bytes |
+
+Best when your program is a consumer of an already-executed proof. Reference: `phygital-spend`.
+
+### Pattern B — Client posts `secp256r1_verify`, your program CPIs `verify_asset`
+
+| Layer | Responsibility |
+|-------|----------------|
+| **Client** | `[secp256r1_verify, your_ix]` — pass `Secp256r1VerifyArgs` + `message` in your ix data |
+| **Your program** | CPI `verify_asset` via `VerifyAssetCpiBuilder` (`phygital-token-client`) |
+
+Best when your program orchestrates verification as part of its own instruction.
+
+## Off-chain authentication (no `verify_asset`)
+
+`verifyWithChallengeResponse` proves presence in the client only. It does **not** write to chain. Use for UI login when no program needs to inspect `verify_asset`.
+
+## Message design checklist
+
+- [ ] Define domain-separated `message` bytes (prefix + action fields)
+- [ ] Same bytes in `beginVerifyAsset({ message })` and your program's check
+- [ ] Never reuse messages across authorization scopes
+
+## Crates
+
+**TypeScript:** `phygital-token-sdk` — `buildVerifyAssetArgs`, `completeVerifyAsset`, `getVerifyAssetInstruction`
+
+**Rust:** `phygital-token-client` at `clients/rust/phygital-token` — `VerifyAssetCpiBuilder`, `Secp256r1VerifyArgs`
+
+See [rust-cpi.md](./rust-cpi.md).

package/docs/building-on-phygital/rust-cpi.md

@@ -0,0 +1,55 @@
+# Rust: building on `verify_asset`
+
+Crate: `phygital-token-client` (`phygital_token_client`).
+
+## Pattern A — Inspect prior `verify_asset` (phygital-spend)
+
+Client sends `secp256r1_verify` + `verify_asset` + your instruction. Your program does **not** CPI.
+
+1. Load `instructions_sysvar`
+2. Scan instructions **before** your program's index
+3. Find `phygital_token::verify_asset` for the expected `asset`
+4. Decode instruction data; verify `message` matches your canonical payload
+
+```rust
+// Pseudocode — see phygital-spend require_matching_verify_asset
+require!(decoded_message == expected_message, MyError::InvalidProof);
+require!(verify_asset_asset == expected_asset, MyError::WrongAsset);
+```
+
+## Pattern B — CPI `verify_asset` from your program
+
+Client sends `secp256r1_verify` + your instruction (no client-side `verify_asset`). Your program CPIs:
+
+```rust
+use phygital_token_client::generated::instructions::VerifyAssetCpiBuilder;
+use phygital_token_client::generated::types::Secp256r1VerifyArgs;
+
+VerifyAssetCpiBuilder::new(phygital_token_program)
+    .asset(asset_account)
+    .slot_hashes(slot_hashes_sysvar)
+    .instructions_sysvar(instructions_sysvar)
+    .secp256r1_verify_args(secp256r1_verify_args)
+    .message(message_bytes)
+    .invoke()?;
+```
+
+The client obtains `secp256r1_verify_args` from TypeScript `buildVerifyAssetArgs` and passes them in your instruction data.
+
+`secp256r1_verify` must appear earlier in the transaction (client includes it before your ix).
+
+## `Secp256r1VerifyArgs`
+
+```rust
+pub struct Secp256r1VerifyArgs {
+    pub signed_message_index: u8,
+    pub slot_number: u64,
+    pub client_data_json: Vec<u8>,
+}
+```
+
+Mirrors `buildVerifyAssetArgs` output in TypeScript.
+
+## Testing
+
+`programs/phygital-token/tests/verify_asset_flow.rs`

package/docs/glossary.md

@@ -0,0 +1,43 @@
+# Phygital Token — Domain Glossary
+
+Shared vocabulary for on-chain accounts, instructions, tests, and the TypeScript client.
+
+## Hierarchy
+
+```
+Collection (group_mint)
+  └── Design mint (mint)          ← created by `create_mint`
+        └── Asset (asset PDA)     ← created by `mint_token`, 1:1 with passkey
+              └── SPL token unit  ← held in program_authority custody until claim
+```
+
+## Terms
+
+| Term | On-chain / IDL name | Description |
+|------|---------------------|-------------|
+| **Collection** | `group_mint` | Token-2022 TokenGroup parent mint. Groups related designs. |
+| **Design** | `mint` (in `create_mint`) | Shared SFT template — one metadata set, many physical instances. |
+| **Asset** | `asset` account | Per-physical-item record keyed by secp256r1 passkey pubkey. |
+| **Owner** | `asset.owner` | Current custodian after a successful `execute_transfer` claim. |
+| **Custody** | `program_authority` | PDA that holds unclaimed tokens and acts as permanent delegate. |
+
+## Instruction map
+
+| Instruction | What it does |
+|-------------|--------------|
+| `create_mint` | Creates a **design** mint (member of a collection `group_mint`). |
+| `mint_token` | Mints one SPL token into custody and initializes an **asset** PDA. |
+| `execute_transfer` | Passkey-authorized claim/transfer from current owner to recipient. |
+| `set_lock_state` | Owner toggles transfer lock on a configurable asset. |
+| `create_domain_config` / `update_domain_config` | WebAuthn RP ID and origin allowlist. |
+
+## Client naming
+
+| Rust / IDL | TypeScript (hand-written) |
+|------------|---------------------------|
+| `group_mint` | `groupMint` / `collectionMint` (display) |
+| `create_mint` | `buildCreateMintInstructions` |
+| `mint_token` | `buildMintTokenInstructions` |
+| `asset` PDA | `findAssetPda`, `AssetDisplayInfo` |
+
+Test helpers mirror on-chain instruction names (`create_mint`, `mint_token`, etc.).

package/docs/sdk/surface-area.md

@@ -0,0 +1,77 @@
+# SDK surface area
+
+TypeScript package: `phygital-token-sdk` (`clients/js/phygital-token`).
+
+## Mint
+
+| Export | Purpose |
+|--------|---------|
+| `buildCreateMintInstructions` | Create design mint in a collection |
+| `buildMintTokenInstructions` | Mint token + initialize asset PDA |
+| `parseSecp256r1Pubkey` | Parse base64url compressed P-256 key |
+| `parseCredentialId` | Parse base64url credential id |
+| `validateMetadataFields` | Name/symbol/uri length checks |
+
+## Transfer
+
+| Export | Purpose |
+|--------|---------|
+| `beginTransfer` | Slot-bound transfer challenge |
+| `authenticatePasskeyForTransfer` | WebAuthn NFC tap |
+| `completeTransfer` | `secp256r1_verify` + `execute_transfer` |
+
+## Verify asset (composable)
+
+| Export | Purpose |
+|--------|---------|
+| `beginVerifyAsset` | Slot-bound verify challenge for custom `message` |
+| `authenticatePasskeyForVerifyAsset` | WebAuthn NFC tap |
+| `buildVerifyAssetArgs` | Build secp256r1 + resolve asset after tap |
+| `completeVerifyAsset` | Full instruction pair |
+
+## Verification (client helpers — off-chain only)
+
+| Export | Purpose |
+|--------|---------|
+| `verifyDynamicUrl` | Identification via signed URL (server) |
+| `verifyDynamicUrlWithoutCounterCheck` | Identification offline |
+| `verifyWithChallengeResponse` | Off-chain authentication (browser); does not submit `verify_asset` |
+| `verifyWithChallengeResponseOverNfc` | Off-chain authentication (native NFC) |
+
+On-chain proof always uses `beginVerifyAsset` / `buildVerifyAssetArgs` / `completeVerifyAsset`.
+
+## Asset lookup & metadata
+
+| Export | Purpose |
+|--------|---------|
+| `findAssetPda` | Derive asset PDA from secp256r1 pubkey |
+| `fetchAssetFromCredentialId` | Resolve asset + pubkey from credential |
+| `fetchAllAssetsFromOwner` | List assets by wallet owner |
+| `fetchAssetDisplayInfo` | Rich display metadata |
+| `resolveMedia` | Resolve media URLs from token metadata |
+
+## Gating
+
+| Export | Purpose |
+|--------|---------|
+| `evaluateAssetGating` | Full tier evaluation for asset owner wallet |
+| `evaluateGatingTiers` / `evaluateGatingFilter` | Lower-level evaluators |
+| `Gating` / `GatingTraitValue` | Filter builders |
+| `summarizeGatingEvaluationFailure` | Human-readable failure reasons |
+
+## Generated (Codama)
+
+Re-exported from `./generated/index.js`:
+
+- Instructions: `getCreateMintInstructionAsync`, `getMintTokenInstructionAsync`, `getExecuteTransferInstructionAsync`, `getVerifyAssetInstruction`, `getSetLockStateInstruction`, ...
+- Accounts: `fetchAsset`, `Asset`, ...
+- Types: `AssetType`, `Secp256r1VerifyArgs`, `CredentialId`, ...
+- PDAs: `findProgramAuthorityPda`, ...
+
+## Rust client
+
+Crate: `phygital-token-client` at `clients/rust/phygital-token`.
+
+On-chain: instruction builders, CPI helpers, account layouts, errors.
+
+Off-chain (`fetch` feature): RPC account fetching helpers.

package/docs/verification/methods.md

@@ -0,0 +1,58 @@
+# Verification methods (`verify.ts`)
+
+All exports from `clients/js/phygital-token/src/utils/verify.ts`.
+
+## Identification (no second tap)
+
+### `verifyDynamicUrl(params, callback?)`
+
+**Use when:** User already tapped once; you have signed URL query params (`pk`, `s`, `c`, `n`).
+
+### `verifyDynamicUrlWithoutCounterCheck(params)`
+
+**Use when:** Offline device, no verification server. Copied links can be replayed.
+
+## Authentication — off-chain only (live tap)
+
+### `verifyWithChallengeResponse({ rpc, message?, fetchPublicKeyFromCredentialIdCallback? })`
+
+**Use when:** Browser web app; prove holder is present **without** an on-chain transaction.
+
+Optional `message` sets the WebAuthn challenge (UTF-8 encoded). When omitted, a random 32-byte challenge is used. This lets you bind the tap to app-specific context (e.g. session id, action label) without going on-chain.
+
+```ts
+// Random challenge
+await verifyWithChallengeResponse({ rpc });
+
+// Bound challenge (still off-chain)
+await verifyWithChallengeResponse({
+  rpc,
+  message: `login:${sessionId}`,
+});
+```
+
+Returns `{ publicKey, isVerified }`. Does **not** submit `verify_asset`.
+
+For on-chain proof with a bound message, use `beginVerifyAsset({ message: Uint8Array })` instead.
+
+### `verifyWithChallengeResponseOverNfc({ rpc, message?, transceive, ... })`
+
+Same as above for React Native / native NFC apps. Optional `message` binds the challenge the same way.
+
+## Off-chain auth vs on-chain composable
+
+| Need | Use |
+|------|-----|
+| UI login, bound or random challenge, no tx | `verifyWithChallengeResponse({ message? })` |
+| On-chain proof — Pattern A | `completeVerifyAsset` + your ix |
+| On-chain proof — Pattern B | `buildVerifyAssetArgs` + your ix |
+| Transfer ownership | `beginTransfer` → `completeTransfer` |
+
+## Message: off-chain vs on-chain
+
+| Context | `message` type | Effect |
+|---------|----------------|--------|
+| `verifyWithChallengeResponse` | optional `string` | WebAuthn challenge bytes (UTF-8) |
+| `beginVerifyAsset` | `Uint8Array` | Hashed into slot-bound on-chain challenge |
+
+An off-chain `message` in `verifyWithChallengeResponse` does **not** produce an on-chain `verify_asset` record. Use the composable flow when your program must inspect or CPI `verify_asset`.