Wallet Authentication Backend (WAB)

A TypeScript/Express server that provides presentation-key and Shamir-share recovery workflows for BSV wallet applications, using Twilio verification in production and an explicitly development-only console OTP method.

What it does

WAB enables Twilio phone verification and coordinates key/share storage through SQLite (development) or MySQL (production). A Persona example exists in source but is not registered as a supported method. The DevConsole method is available only when explicitly enabled in a development or test runtime and cannot be activated in production or staging.

Clients authenticate by phone number, recover original presentation keys, optionally receive one-time BSV payments, and can verify a same-or-new phone number to rotate the presentation key. Operators can pin a legacy ambiguous UMP account to one verified outpoint and restore recorded phone associations.

When to deploy this

• BSV wallet applications needing multi-factor user authentication
• Key recovery using 2-of-3 threshold system (presentation key + password + recovery key)
• Development/testing with OTP-based console auth
• Production deployments with Twilio SMS verification
• Faucet distribution for new users (with SERVER_PRIVATE_KEY and STORAGE_URL)

Dependencies

HTTP endpoints

WebSocket endpoints

None.

Configuration (env vars)

See Public Service Edge Security for endpoint rate limits, errors, CORS/CSP behavior, and the threat model.

Run locally

# Install dependencies
npm install

# Development with auto-restart
npm run dev

# Database migrations
npm run migrate

# Run tests with coverage
npm test

# Build TypeScript
npm run build

# Run production server
npm start

Uses SQLite by default (./dev.sqlite3); MySQL configured via DB_* env vars.

Deploy to production

# Build Docker image
docker build -t wab-server:latest .

# Run with MySQL backend
docker run -d \
  -e NODE_ENV=production \
  -e DB_CLIENT=mysql2 \
  -e DB_HOST=mysql \
  -e DB_USER=root \
  -e DB_PASS=password \
  -e DB_NAME=wab \
  -e TWILIO_ACCOUNT_SID=<sid> \
  -e TWILIO_AUTH_TOKEN=<token> \
  -e TWILIO_VERIFY_SERVICE_SID=<service-id> \
  -e SERVER_PRIVATE_KEY=<hex-key> \
  -e STORAGE_URL=<overlay-url> \
  -p 3000:3000 \
  wab-server:latest

# Or with GCP Cloud SQL
docker run -d \
  -e DB_CLIENT=mysql2 \
  -e DB_CONNECTION_NAME=project:region:instance \
  -e DB_USER=root \
  -e DB_PASS=password \
  -e DB_NAME=wab \
  ... (other env vars)

# Or via docker-compose with MySQL
docker compose up -d

Migrations

Run Knex migrations for schema initialization:

npm run migrate

Creates the core users, auth-method, payment, share, deletion, and abuse-control tables. The UMP support migration adds nullable users.umpTokenOutpoint plus phone_change_sessions and phone_change_history. Back up the database before rollout. Do not remove the history table after users begin changing numbers.

Health checks

GET /healthz is the liveness endpoint and GET /info is the readiness and configuration endpoint. Monitor:

• Database connectivity (run npm run migrate to verify)
• Auth method configuration (Twilio credentials, etc.)
• POST /auth/start endpoint responds with 200/4xx

Spec conformance

• BRC-100 – Optional integration with @bsv/wallet-toolbox for faucet R-puzzle transactions
• 2-of-3 Recovery – Presentation key is factor #1 (password #2, recovery key #3) in XOR-based derivation system

Integration with ts-stack

• Clients implement AuthMethod subclasses for custom verification flows
• Wallet Toolbox integration for faucet BSV payments and key derivation
• WalletAuthenticationManager uses WAB for presentation key authentication
• UMP (User Management Protocol) token system coordinates with presentation keys
• A WAB UMP pin is an ambiguity-only fallback and must match a wallet-verified lookup candidate
• Phone changes verify possession by OTP, stage current/pending keys across the UMP publish boundary, and clear a stale pin at finalization while recording reversible association history
• See how-it-works.md for detailed 2-of-3 cryptographic recovery explanation
• See UMP account support for the operator workflow

Common pitfalls

• User identification by config, not presentation key: Auth method's buildConfigFromPayload() extracts unique identifier (e.g., phone number); two devices with same phone return same user's key
• Twilio setup critical: TWILIO_VERIFY_SERVICE_SID must be VAxxxx (Verify) or VExxxx (Verify Email); wrong SID causes all auth attempts to fail
• SQLite for dev only: In-memory tables reset on restart; switch to MySQL for production
• Faucet requires funds: SERVER_PRIVATE_KEY wallet must have UTXOs; transactions fail if insufficient balance
• Dev console is ephemeral: its OTP store resets on restart and is intentionally unavailable in production/staging
• Public CORS is intentional for wallet apps on unknown domains; use WAB_CORS_MODE=allowlist only when the deployment has a closed caller set
• Migration timing: Must run before server startup; Knex handles schema versioning automatically
• Support token: /admin/* returns 404 when WAB_ADMIN_TOKEN is absent; a non-empty token shorter than 32 characters fails startup
• Phone takeover: proving possession of a number can transfer its WAB association; support must preserve and audit the returned changeId so a fraudulent transfer can be restored

Source

• GitHub
• npm package