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.

SHARE_ENCRYPTION_KEY is a long-lived data-encryption key, not an ordinary restart secret. Keep it stable and backed up separately from the database. Losing or replacing it makes existing recovery shares unreadable; rotation requires an explicit, authenticated re-encryption procedure rather than merely changing the environment variable.

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> \
  -e SHARE_ENCRYPTION_KEY=<64-hex-characters> \
  -p 8080:8080 \
  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.

The 2026-09-18-001-faucet-payment-reservations migration adds one durable payment reservation per current user. It deliberately stops if pre-existing duplicate non-null payments.userId rows exist; reconcile those financial records rather than deleting one automatically. A ready payment may be returned again to the same current account so a lost HTTP response does not destroy the only R-puzzle secret. A concurrent or ambiguous first payout remains in creating state and returns 503 until an operator reconciles that reservation; the server never starts a second irreversible payout for it. An orphaned auth identity whose preserved receivedFaucet flag has no payment on its newly linked user remains ineligible for another payout. Unlink and account-deletion flows detach rather than delete authentication rows and payment evidence so this anti-abuse history survives account removal.

User-facing deletion responses disclose that account/share data is removed while detached authentication identity and faucet-payment evidence is retained solely to enforce the one-time faucet policy. Operators must document and disclose the privacy and legal basis and retention period for that limited evidence, restrict access to abuse-prevention purposes, and archive or delete it only when doing so cannot reset a faucet claim.

The 2026-09-21-001-faucet-claim-backfill migration marks every auth method linked to a user with any persisted payment row. Only ready is deliverable; every other status is a fail-closed pending claim. The migration stops on any payment whose userId is already null: old data cannot prove which now-orphaned identity rows shared that payment, and the absence of such a row can mean an old unlink operation deleted it. Before retrying, an operator must back up the database, correlate each orphaned payment from payment evidence, audit logs, and backups, mark every formerly linked auth identity receivedFaucet=true, and either restore the payment's correct user association or archive its evidence under the incident record before removing the uncorrelatable active row. If the identities cannot be reconstructed, conservatively mark every plausible orphaned identity before archiving the payment. Never clear a faucet marker or discard the only payment evidence merely to make the migration pass.

The faucet-claim migration requires a maintenance-window deployment and is not safe as a mixed-version rolling upgrade. Remove the service from traffic, drain and stop every old WAB replica, verify that no old writer remains, and take a restorable backup before starting one new replica to apply the migration. Keep traffic blocked until every replica uses the new image. Never run the old image against the migrated database because its link/unlink paths can erase monotonic claim evidence and reopen faucet reclaim. Roll forward, or restore the old image and pre-migration database together while the service remains stopped.

Faucet recovery must cover both the database and the external wallet action. Retain point-in-time database logs and protected wallet/audit evidence through the latest faucet payment. After restoring a snapshot, keep the faucet endpoint out of service until every later wallet action is correlated to its payment row and authentication identities and the payment and receivedFaucet markers are reconstructed. Where an identity association cannot be proved, conservatively mark every plausible identity before re-enabling faucet traffic. A claim missing from an older snapshot never authorizes another payout.

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 the canonical VA Verify Service SID. Partial or malformed Twilio configuration fails startup; with all three Twilio values absent the method is disabled and omitted from /info. WAB accepts only the service's exact 4–10 digit OTP and treats all non-approved provider states as the same authentication failure.
• 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