tana-identity

QR code authentication service for the Tana blockchain.

overview

tana-identity enables passwordless authentication where users scan QR codes with their mobile app instead of entering credentials. the mobile app holds Ed25519 private keys and signs challenges. desktop browsers never see private keys.

how it works

when a web application needs to authenticate a user, it creates a session with tana-identity and displays the QR code. the user scans it with their mobile app, which extracts the challenge and signs it with their private key. the identity service verifies the signature and issues a session token.

authentication flow

web app                  mobile app               identity service
   |                         |                          |
   |----create session------------------------------>|
   |<---QR data + session ID-------------------------|
   |                         |                          |
   |---display QR-->         |                          |
   |---listen SSE----------------------------------->|
   |                         |                          |
   |                    scan QR                         |
   |                         |------sign challenge----->|
   |                         |<-----session token-------|
   |<---SSE: approved + token--------------------------|

session lifecycle

1. waiting - session created, QR displayed
2. scanned - mobile app acknowledged QR
3. approved - signature verified, token issued
4. rejected - user denied or timeout
5. expired - five-minute QR expiration

architecture

built with TypeScript and Hono. uses server-sent events (SSE) to push real-time status updates to web clients. session data is stored in PostgreSQL with automatic cleanup of expired sessions.

security model

• private keys never leave the mobile device
• each session has a unique cryptographic challenge
• signed messages include timestamps to prevent replay attacks
• session tokens expire after 24 hours
• QR codes expire after five minutes

api

• POST /auth/session/create - create authentication session
• GET /auth/session/:id/events - SSE stream for status updates
• POST /auth/session/:id/scan - mark session as scanned
• POST /auth/session/:id/approve - approve with signature
• GET /auth/session/verify - verify session token

integration

tana-identity integrates with tana-mobile for the signing workflow and with web applications through the session token. applications verify tokens by calling the identity service before trusting authenticated requests.