agentsclimarketplace

Chipi passkey troubleshooting

Skill chipi-pay/skills/skills/chipi-passkey-troubleshooting

Debug passkey and PIN authentication issues in Chipi integrations. Diagnose encryption version mismatches, PRF failures, migration errors, multi-device problems, and decryption failures. Use when user says "passkey not working", "decryption failed", "wrong key", "migration failed", "biometric error", or "PRF not supported".From its SKILL.md

Install
npx -y skills add chipi-pay/skills --skill chipi-passkey-troubleshooting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

6.4 KB, as published. Nobody here has run it

Debug Passkey & PIN Authentication

Systematic debugging guide for passkey and PIN authentication issues in Chipi wallets.

When in Doubt, Ask

Before debugging, ask the user for:

  • Error message — exact text
  • Auth method — PIN or passkey?
  • How was the wallet created? — MCP components, SDK hooks, or custom?
  • Browser/device — Chrome, Safari, mobile? (matters for PRF)
  • Did it ever work? — new setup vs regression?

Step 1: Identify the Problem

Authentication error
├─ Decryption failed? → Step 2
│  ("wrong key", empty result, corrupted data)
├─ PRF not working? → Step 3
│  ("NotAllowedError", null PRF output, biometric cancelled)
├─ Migration failed? → Step 4
│  (PIN → passkey migration errors)
├─ Multi-device issue? → Step 5
│  (works on one device, fails on another)
├─ Encryption version mismatch? → Step 6
│  (MCP vs SDK incompatibility)
└─ PIN issues? → Step 7
   (wrong PIN, change PIN, lost PIN)

Step 2: Decryption Failed

ErrorCauseFix
"Decryption failed - wrong key or corrupted data"Encryption key doesn't match what was used to encryptCheck encryption version (Step 6). Verify correct auth method.
Empty string after decryptKey derived differently than at creation timePRF salt or derivation method mismatch. See Step 6.
"Cannot read property 'toString' of undefined"crypto-es version mismatchCheck crypto-es version: MCP uses v3.1.2, SDK uses v2.1.0.

Quick diagnostic:

// Check which auth method the wallet uses
const metadata = user.unsafeMetadata as PasskeyMetadata;
const authMethod = metadata?.passkeys?.authMethod; // "prf" | "pin" | undefined
const encryptionVersion = metadata?.passkeys?.encryptionVersion; // "sdk-v1" | "mcp-v1" | undefined
console.log({ authMethod, encryptionVersion });

Step 3: PRF Not Working

ErrorCauseFix
"NotAllowedError"User cancelled biometric promptPrompt again. Check if device has biometric enrolled.
PRF output is nullBrowser doesn't support PRF extensionCheck browser: Chrome 116+, Edge 116+, Safari 17.4+. Firefox not supported.
prf.enabled === falseCredential was created without PRFRe-register passkey with PRF enabled.
Works in Chrome, fails in SafariSafari PRF support is newer (17.4+)Check Safari version. Fall back to PIN on unsupported browsers.

Quick diagnostic:

import { isPRFSupported } from "@/lib/prf-encryption";
const supported = await isPRFSupported();
console.log("PRF supported:", supported);

Step 4: Migration Failed (PIN → Passkey)

ErrorStageFix
"Decryption failed" during PIN verifyStep 1 (verify PIN)Wrong PIN entered. Retry.
"NotAllowedError" during registrationStep 2 (register passkey)User cancelled biometric. Old PIN still works.
"PRF not enabled on credential"Step 3 (authenticate)Passkey was created without PRF. Delete and re-register.
"Failed to update user"Step 4 (re-encrypt)Clerk API error. Old PIN still works. Retry.

Migration is safe: If any step fails, the old PIN continues to work. No data is lost.

Step 5: Multi-Device Issues

ProblemCauseFix
Works on iPhone, fails on laptopDifferent passkey credentials per deviceRegister a new passkey on the laptop via Passkey Manager.
"Credential not found" on new devicePasskey is device-bound (not synced)Register a new passkey on the new device.
"Counter mismatch"Cloned credential detectedSecurity measure. Re-register passkey.

How multi-device works: Each device has its own passkey credential. All use the same PRF salt, so they derive the same encryption key. The encrypted private key in Clerk metadata is shared across devices.

Step 6: Encryption Version Mismatch

This is the most common issue when mixing MCP components and SDK.

Two encryption versions exist:

VersionPRF SaltKey DerivationUsed By
mcp-v1chipi-wallet-encryption-v1 (UTF-8 bytes)SHA256(base64(prfOutput))MCP components (legacy)
sdk-v1chipi-wallet-encryption-key-v1 (base64url)arrayBufferToHex(prfOutput)SDK @chipi-stack/chipi-passkey

A wallet encrypted with mcp-v1 CANNOT be decrypted with sdk-v1, and vice versa.

Diagnostic:

const metadata = user.unsafeMetadata as PasskeyMetadata;
const version = metadata?.passkeys?.encryptionVersion;
// "sdk-v1" → SDK encryption
// "mcp-v1" → MCP encryption
// undefined → legacy wallet, try both

Fix for legacy wallets (no encryptionVersion in metadata):

  • MCP's updated tryDecryptWithVersions() tries both methods automatically
  • After successful decryption, stamps the correct version in metadata
  • Going forward, all new wallets use sdk-v1

Fix for mixed implementations:

  • If using MCP components: update to latest MCP (PR #65+) which aligns with SDK
  • If using SDK directly: no changes needed
  • If using both: ensure MCP is updated, then legacy wallets auto-migrate on next sign

Step 7: PIN Issues

ProblemFix
Forgot PINNo recovery if wallet is PIN-only. Consider migrating to passkey first next time.
Change PINDecrypt with old PIN, re-encrypt with new PIN via useUpdateWalletEncryption.
PIN works on MCP but not SDKShouldn't happen — PIN encryption is the same. Check if PIN has leading zeros (they matter).

Metadata Reference

interface PasskeyMetadata {
  chipiWallet?: {
    publicKey: string;
    encryptedPrivateKey: string;
    txHash?: string;
  };
  passkeys?: {
    enabled: boolean;
    credentials: PassKey[];
    authMethod?: "prf" | "pin";
    prfEnabled?: boolean;
    encryptionVersion?: "mcp-v1" | "sdk-v1"; // Added in MCP PR #65
    lastAuthAt?: number;
  };
}

Check metadata at: Clerk Dashboard → Users → select user → Unsafe Metadata.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.