Architecture

Deep dive into Transcodes’ technical architecture and security model.

System Overview

Transcodes WebWorker handles all authentication complexity in the browser:

What the WebWorker provides:

• Pre-built components with one function call
• Automatic token management
• Event-driven auth state updates
• In-memory accessible access token with AES-256-GCM encryption
• Secure web storage for storing private credentials

Core Components

TokenManager

Handles access token lifecycle:

interface TokenManager {
  getCurrentUser(): Promise<User | null>; // Get user from JWT payload
  getAccessToken(): Promise<string | null>; // Auto-refreshes if expired
  hasToken(): boolean; // Sync check
  hasPrivateKey(): Promise<boolean>; // Check Private Key in storage for generating access token
  validateToken(): boolean; // Validate without refresh
  isAuthenticated(): Promise<boolean>; // Full validation
  signOut(): Promise<void>; // Clear all credentials
}

EventEmitter

Reactive event system for auth state changes:

See API Reference for event payload details.

Zero-Knowledge Architecture

Transcodes implements a zero-knowledge security model where your private key never leaves your device:

Key principles:

• Private Key Isolation: Generated and stored exclusively in encrypted browser storage
• Cryptographic Proof: Authentication uses digital signatures, not shared secrets
• No Server Secrets: Transcodes servers only store public keys
• Origin Binding: Keys are bound to your domain, preventing phishing

Security Model

Data Storage

Security Standards

• Encryption: Industry-standard cryptographic algorithms
• Authentication: Challenge-response protocol with digital signatures
• Privacy: No attestation data collected
• Token Format: Standard JWT (JSON Web Token)

DPOP (Proof of Possession) Private Key

Traditional OAuth stores secrets on servers. Transcodes keeps credentials in the browser:

1. Unphishable: Key is bound to only user physical device
2. Confidentiality: No one can see user’s private key
3. User control: User can control his/her own private credential data in browser by himself/herself

Token Refresh Flow

Access tokens are automatically refreshed using secure credentials stored in the browser. When you call getAccessToken(), the SDK:

1. Returns cached token if still valid
2. Otherwise, authenticates using stored credentials
3. Requests a fresh token from Transcodes server
4. Emits TOKEN_REFRESHED event

No refresh token needed—the private key serves as traditional refresh token

Browser Support

Next Steps

• Quick Start - Get started in 5 minutes
• API Reference - Full SDK documentation
• Integration Guides - Framework-specific guides