TokenPass

TokenPass is a personal identity server that enables Bitcoin-backed authentication. Run your own OAuth provider with cryptographic signing, encryption, and BAP (Bitcoin Attestation Protocol) identity management.

Overview

TokenPass consists of two components:

Component	Description	Port
TokenPass Server	REST API for wallet management, signing, encryption	21000
TokenPass Desktop	Electron app with system tray, auto-start	-

Installation

TokenPass Server

# Clone and install
git clone https://github.com/b-open-io/tokenpass-server
cd tokenpass-server
bun install

# Start the server
bun dev

Server runs at http://localhost:21000 with API prefix /api/.

TokenPass Desktop

Download from GitHub Releases:

Platform	File
macOS (Apple Silicon)	TokenPass-X.X.X-arm64.dmg
macOS (Intel)	TokenPass-X.X.X-x64.dmg
Windows	TokenPass-X.X.X-setup.exe
Linux	TokenPass-X.X.X.AppImage

The desktop app wraps the server with a system tray icon and auto-start capability.

Authentication Flow

TokenPass uses a two-step authentication model:

1. Wallet Setup (one-time): Create wallet with POST /api/register
2. Unlock Wallet: Call POST /api/login with password
3. Get Access Token: Call POST /api/auth with host and scopes
4. Make API Calls: Use token in Authorization header

// 1. Register (first time only)
await fetch('http://localhost:21000/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    password: 'secure-password',
    displayName: 'Alice'
  })
});

// 2. Login (unlocks wallet)
await fetch('http://localhost:21000/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ password: 'secure-password' })
});

// 3. Get access token for a host
const { accessToken } = await fetch('http://localhost:21000/api/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    password: 'secure-password',
    host: 'example.com',
    expire: '1h',
    scopes: 'sign,encrypt'
  })
}).then(r => r.json());

// 4. Sign a message
const signature = await fetch('http://localhost:21000/api/sign', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': accessToken  // No "Bearer" prefix
  },
  body: JSON.stringify({ message: 'Hello World' })
}).then(r => r.json());

API Endpoints

Wallet Management

Endpoint	Method	Auth	Description
/api/register	POST	-	Create new wallet
/api/login	POST	-	Unlock wallet
/api/logout	POST	-	Lock wallet
/api/status	GET	-	Check wallet status
/api/export	POST	Password	Export seed/mnemonic

Access Tokens

Endpoint	Method	Auth	Description
/api/auth	POST	Password	Generate access token

Token Expiry Options: once (10s), 1h, 1d, 1w, 1m, forever

Scopes: sign, encrypt, decrypt, read_profile, write_profile, read_state, write_state, fund, transfer

Cryptographic Operations

Endpoint	Method	Auth	Description
/api/sign	POST	Token	Sign message (BSM format)
/api/encrypt	POST	Token	Encrypt with ECIES

Identity Management

Endpoint	Method	Auth	Description
/api/profile	GET	-	Get BAP profile
/api/profile	POST	-	Update BAP profile

Configuration

Environment Variables

# CORS whitelist (comma-separated)
TOKENPASS_ORIGIN_WHITELIST=https://app1.com,https://app2.com

Data Storage

All data stored in ~/.tokenpass/:

File	Description
seed.db	Encrypted master seed (AES-256-CBC)
keys.db	Derived Bitcoin keys per host
state.db	Access tokens and per-host state

React Integration

The @sigma-auth/better-auth-plugin provides a full React client with automatic TokenPass detection:

import { createAuthClient } from "better-auth/client";
import { sigmaClient } from "@sigma-auth/better-auth-plugin/client";

export const authClient = createAuthClient({
  baseURL: "https://auth.sigmaidentity.com",
  plugins: [
    sigmaClient({
      preferLocal: true,  // Auto-detect local TokenPass
      localServerUrl: "http://localhost:21000",
      onServerDetected: (url, isLocal) => {
        console.log(`Using ${isLocal ? 'local' : 'cloud'} signer: ${url}`);
      }
    })
  ],
});

// Sign requests (uses TokenPass if available)
const authToken = await authClient.sigma.sign("/api/endpoint", { data: "value" });

// Encrypt/decrypt with Type42 key derivation
const encrypted = await authClient.sigma.encrypt("secret", friendBapId);
const decrypted = await authClient.sigma.decrypt(encrypted, friendBapId);

The client automatically:

• Probes for local TokenPass server on localhost:21000
• Falls back to cloud iframe signer if unavailable
• Handles OAuth flow with PKCE
• Manages identity state and token storage

Related Skills

• setup-nextjs: Full Next.js integration guide with OAuth flow
• bitcoin-auth-diagnostics: Troubleshoot auth token issues
• bsv-skills:message-signing: BSM signature verification
• bsv-skills:key-derivation: Type42/BIP32 key derivation

Additional Resources

Reference Files

For detailed API documentation and examples:

• references/api-reference.md - Complete REST API documentation
• references/integration-examples.md - Code examples for common integrations

Documentation

• Server README: https://github.com/b-open-io/tokenpass-server
• Desktop Releases: https://github.com/b-open-io/tokenpass-desktop/releases
• Web Documentation: https://tokenpass.app/docs