Integrate TAPSIGNER

TAPSIGNER uses the public Coinkite Tap Protocol: ISO 7816/APDU communication over NFC with CBOR request and response maps. A safe integration must verify the factory certificate, verify the supplied chain code, keep CVCs transient, capture encrypted backups without requesting the printed AES key, preserve derivation metadata, and show the complete transaction before signing.

Use the protocol specification and reference implementation as the source of truth. This page is a review checklist, not a substitute for the current command definitions and test vectors.

Protocol surface

The card exposes shared commands for status, certificate verification, setup, reading, derivation, and signing, plus TAPSIGNER-specific commands for changing the CVC, retrieving XPUB data, and creating an encrypted backup. APDU bodies use CBOR mappings.

The NFC Data Exchange Format tap URL is dynamic and signed, but a wallet integration should communicate through the full protocol rather than treating the browser verification result as a certificate check.

Required setup sequence

The official developer hints define this order:

1. verify that the card is genuine and uninitialized;
2. run the key-picking/setup command with a fresh 32-byte chain code;
3. set the required hardened derivation path if it differs from m/84h/0h/0h;
4. capture an encrypted backup;
5. collect a new PIN from the user;
6. change the PIN.

Do not reorder backup and PIN change: the card rejects a CVC change until at least one backup has been made.

Verify the factory certificate

Validate the card's signature chain back to the Coinkite factory root before trusting any returned key or identity data. Fail closed on invalid certificates and present an actionable error rather than continuing with a warning hidden in logs.

Plan for the protocol's variable certificate-chain length even if current production cards commonly use the documented root and batch structure. Use the reference implementation to cross-check test fixtures.

Verify chain-code use

Generate a cryptographically random 32-byte chain code for setup. After key creation, request the master XPUB and verify that its chain code matches the value supplied. Do not merely trust a success response.

Store the required public origin data: master fingerprint, hardened path, XPUB, network, and wallet descriptor or policy. Do not store the CVC as part of the key record.

Handle derivation correctly

The default hardened path is m/84h/0h/0h. The derive command accepts only hardened components, remembers the selected path, and supports up to eight levels. Individual signatures can add zero, one, or two non-hardened subpath components, conventionally change/receive and address index.

Set the hardened account path once, then sign using the relative non-hardened subpath. Validate every component and network. Preserve the current path with backups and wallet exports.

Treat the CVC as transient input

Prompt only when an authenticated operation requires it. Associate the prompt with the observed card identity, keep the CVC in memory for the minimum operation window, and discard it afterward. Never persist it in logs, analytics, crash reports, keychains, or wallet databases.

CVC values are numeric and between 6 and 32 digits after change. Handle authentication failures and the auth_delay/wait flow without encouraging repeated guessing. Never request the printed AES backup key as though it were the CVC.

Implement backup without learning the AES key

Call the authenticated backup command and store the returned encrypted bytes exactly. The card encrypts a text payload containing the master XPRV and current path with AES-128-CTR, zero IV, and the fixed 128-bit key printed on the card.

Your normal backup UI should not ask the user to enter that printed key. Explain that recovery requires a separately stored copy. Export the descriptor or complete wallet configuration alongside the encrypted key backup, but do not mislabel public configuration as sufficient private-key recovery.

There is no restore command. Recovery tooling decrypts and uses the XPRV outside the original card. Make that change in security state explicit.

Build a truthful signing confirmation

Before requesting a tap, show:

• destination address and amount for every external output;
• fee and fee rate;
• selected inputs where relevant;
• detected change outputs;
• network and wallet name;
• policy and remaining cosigners for multisig;
• the exact human-readable message for message signing.

Do not imply that TAPSIGNER confirmed those details. The card has no display and signs the supplied digest. Give users a chance to cancel before NFC/PIN authorization and inspect the finalized transaction before broadcast.

Security checklist

• [ ] Verify the factory certificate on every newly observed card.
• [ ] Reject the wrong product, network, or unexpected initialized state.
• [ ] Generate and verify a fresh setup chain code.
• [ ] Preserve fingerprint, XPUB, path, and descriptor.
• [ ] Capture backup before CVC change.
• [ ] Never prompt for the printed AES key during normal backup.
• [ ] Never persist CVC values.
• [ ] Handle authentication delay and nonce changes correctly.
• [ ] Set hardened path once; use relative non-hardened signing subpaths.
• [ ] Show the complete transaction and disclose the screenless boundary.
• [ ] Test single-sig, multisig, loss, recovery, wrong-card, wrong-network, and corrupted-backup cases.
• [ ] Link users to current support and protocol documentation.

Test and compatibility strategy

Use the reference Python implementation to create cross-implementation fixtures. Test malformed CBOR types, stale nonces, wrong CVC, rate limiting, certificate failures, path boundaries, signing retries, backup counters, corrupted encrypted files, and cards already initialized by another wallet.

Keep integration claims versioned and public. A listing should specify application version, platform, supported wallet policies, required NFC hardware, and last verified date. Report protocol or documentation defects through the official repository rather than inventing silent compatibility workarounds.

Start with the rendered protocol documentation and GitHub repository. Product copy should link users to backup and recovery, screenless signing, and the current wallet matrix.