@bsv/auth

This source candidate declares SDK peer ^2.1.6 || ^3.0.0. SDK3 remains a coordinated proposal; see the qualification and migration limits before adopting it.

@bsv/auth provides framework-neutral, expiry-bound, single-use wallet authentication proofs. It separates proof creation and verification from HTTP, Express, and database choices.

Install

Install the SDK peer dependency with the package:

npm install @bsv/auth @bsv/sdk

Public API

• AuthProofClient and createAuthProof create an action-bound proof with a wallet.
• AuthProofServer and verifyAuthProof verify the signature, identity, action, expiry, and nonce.
• checkAuthSigData, createAuthSigData, and serializeAuthSigData expose the lower-level proof data contract.

import { AuthProofClient, AuthProofServer } from '@bsv/auth'

const options = { protocol: [2, 'example auth'] as [2, string] }
const client = new AuthProofClient(options)
const server = new AuthProofServer(options)

Client and server must use the same protocol. Production verification must inject an atomic consumeNonce implementation. A process-local map is suitable only for one process; replicated or restarting services need a shared store with uniqueness and expiry.

The verifier counterparty participates in key derivation at every valid security level. The level controls wallet consent (0 silent, 1 per app, 2 per counterparty), so choose it deliberately and prefer level 2 when each verifier needs separate user approval. Proof data, signature bytes, and wallet verdicts must be plain own data rather than inherited or accessor-backed authority, and are snapshotted before asynchronous wallet work. Structured request bodies reject non-finite numbers and negative zero because their JSON encodings are ambiguous.

The package publishes strict ESM and CommonJS entry points and supports Node.js 22 or newer. See the package README for a complete client/server example and store guidance.

License

Open BSV License Version 6. See the package license.