@cardanotech/walletproof provides a non-custodial Cardano wallet-control proof protocol. It creates short-lived, audience-bound challenges, signs their exact UTF-8 payload through a CIP-30 browser wallet, validates CIP-19 reward addresses, and verifies CIP-8 COSE signatures on the server.

The v1 profile proves control of one key-backed reward address at one moment. It does not establish personhood, authenticate an account by itself, recover an account, provide MFA, or grant an entitlement.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @cardanotech/walletproof

Protocol profile

Wallet Proof v1 accepts only canonical, key-backed CIP-19 reward addresses:

stake addresses on mainnet;
stake_test addresses on test networks;
exactly 29 bytes with header type 14;
the exact address used for CIP-30 signData.

Payment addresses, script-backed reward addresses, malformed addresses, and network mismatches fail closed. CIP-30 distinguishes mainnet from testnet but does not distinguish preview from pre-production.

The server stores the exact challenge message and verifies that payload. It does not reconstruct a message from completion-time browser input. Challenge claims are single-use: the repository atomically moves a matching pending challenge to verifying, and an invalid completion burns it. Claims carry an expiring, attempt-specific token so an abandoned verification can be reclaimed without a stale attempt terminalizing the newer claim.

Tenant, subject, and credential identifiers are keyed HMAC-SHA-256 values. The service requires a stable deployment binding secret of at least 32 random bytes. Subject and credential identifiers are tenant-scoped, so the default receipt does not provide a cross-tenant correlation key.

The server verifier applies a strict CIP-30 profile before cryptographic verification:

protected alg is EdDSA (-8) and protected address equals the submitted raw reward address;
unprotected hashed is present and false;
embedded payloads equal the exact challenge message; detached payloads are verified against that message;
the COSE key is OKP/Ed25519 with a 32-byte public key and no private-key material;
optional key identifiers are byte strings present on both structures and equal;
duplicate or conflicting header labels, malformed lengths, and non-minimal protected-map encodings fail closed.

Unknown well-formed extension headers remain permitted. The protected map must use the minimal definite-length encoding accepted by the underlying Cardano Foundation verifier; this explicit v1 compatibility constraint avoids silently verifying different bytes than the wallet signed.

Browser usage

The consuming application obtains a CIP-30 API from the wallet extension and passes it to WalletProofBrowserClient. Wallet discovery and user consent remain the host application's responsibility.

import { WalletProofBrowserClient } from '@cardanotech/walletproof/browser';
import type { IWalletProofChallenge } from '@cardanotech/walletproof';

const challenge: IWalletProofChallenge = await response.json();
const walletApi = await window.cardano.eternl.enable();

const browserClient = new WalletProofBrowserClient();
const submission = await browserClient.createSubmission(walletApi, challenge);

await fetch('/wallet-proof/complete', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(submission),
});

The challenge contains both authoritative structured messageData and its canonical message. Before any wallet access, createSubmission() validates the envelope against messageData, re-encodes and compares the exact message, and rejects expiry or an origin mismatch. The expected origin defaults to the executing browser's location.origin; non-browser tests must pass expectedOrigin explicitly. It then checks the wallet network, selects from a bounded reward-address set, encodes the challenge message as UTF-8 hexadecimal, calls signData, and returns the canonical address with bounded COSE signature and key values.

Server usage

The server must derive the trusted context from authenticated application state. Never accept tenant, subject, issuer, audience, origin, or purpose authority from the browser.

import {
  InMemoryWalletProofRepository,
  WalletProofService,
} from '@cardanotech/walletproof/server';
import type {
  IWalletProofSubmission,
  IWalletProofTrustedContext,
} from '@cardanotech/walletproof';

const repository = new InMemoryWalletProofRepository();
declare const bindingSecret: Uint8Array; // Stable 32+ random bytes from a secret boundary.
const walletProofService = new WalletProofService({
  repository,
  bindingSecret,
});

const trustedContext: IWalletProofTrustedContext = {
  tenantId: 'tenant_01J...',
  subjectId: 'subject_01J...',
  issuer: 'https://cardano.example',
  audience: 'my-application',
  origin: 'https://app.example',
  purpose: 'link-wallet',
};

const challenge = await walletProofService.createChallenge(
  trustedContext,
  'testnet',
);

const submission: IWalletProofSubmission = await receiveBrowserSubmission();
const receipt = await walletProofService.completeChallenge(
  trustedContext,
  submission,
);

// During application/service shutdown, after admission of new work has stopped:
walletProofService.dispose();

InMemoryWalletProofRepository is explicitly for tests and local development. It is not durable and must not be used by a hosted or production service. It has a configurable hard record bound (10,000 by default), evicts retained terminal records under capacity pressure, and exposes clear() for explicit disposal. Production integration requires an IWalletProofRepository implementation with durable, tenant-scoped atomic claim, claim-lease, and token-guarded terminal transitions, such as SmartData on MongoDB. Verification has a configurable deadline (10 seconds by default, one minute maximum) and supplies an AbortSignal to custom verifiers.

dispose() is idempotent, rejects new operations, and zeroes the service-owned binding-secret copy. Operations already in flight finish using isolated copies that are zeroed in finally. The repository and verifier remain caller-owned and are not stopped or disposed by the service.

Receipt privacy

The default receipt contains a domain-separated credential identifier, bindings to the trusted tenant and subject, protocol context, timestamps, and verifier profile. It intentionally excludes the raw reward address, COSE key, signature, and challenge message. With the same binding secret, tenant, network, and reward address, credentialId is stable so a tenant can recognize an existing link. It is not stable across tenants or binding-secret rotation.

Production boundary

This package is a protocol and library foundation, not a production gateway. A hosted integration must additionally provide authenticated start and completion methods, authorization, tenant policy, rate limits, durable persistence, audit, retention, and operational controls. Mainnet enablement should remain a separate policy decision. The binding secret belongs in an injected managed-secret boundary; rotation requires an explicit identifier-migration plan.

The broader component and service design is documented in the cardano.tech target-architecture.md.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@cardanotech/walletproof