Architecture

How Transcodes works under the hood, and where the SDK, Console, and optional MCP tooling fit in

System Overview

The WebWorker runs entirely in the browser: pre-built UI, automatic token management, event-driven state updates, and AES-256-GCM encrypted in-memory tokens

Zero-Knowledge Architecture

For a conceptual overview of DPoP and encryption, see How It Works

Technical details:

• Key Generation: ECDSA P-256 via Web Crypto API
• Private Key: Encrypted on device, never exportable, never transmitted
• Public Key: Registered with Transcodes server on passkey creation
• Auth Flow: Server challenge → client signs with private key → server verifies with public key
• Origin Binding: Credentials bound to RP ID (your domain), blocking cross-origin attacks

Core Components

Token API

interface TokenAPI {
  getCurrentMember(): Promise<Member | null>;   // Member from JWT payload
  getAccessToken(): Promise<string | null>;     // Memory → Secure storage → New issuance
  hasToken(): boolean;                          // Sync in-memory check
  isAuthenticated(): Promise<boolean>;          // Validity check: Memory → Secure storage
  signOut(options?: { webhookNotification?: boolean }): Promise<void>;
}

Event System

See Events API for payload details

Security Model

Standards: ECDSA P-256 · AES-256-GCM · TLS 1.3 · Standard JWT · No attestation data collected

Token Refresh Flow

getAccessToken() lookup order:

1. Return cached token if valid
2. Re-authenticate using stored credentials
3. Request fresh token from Transcodes server
4. Emit TOKEN_REFRESHED event

No refresh token needed—the private key is the permanent credential

Browser Support

Scope of Service

Your Responsibilities

What Your Agent Handles

WebAuthn is a W3C/FIDO standard for passwordless authentication using public-key cryptography. Users authenticate with biometrics, security keys, or device PINs instead of passwords

Simple flow: User registers → Private key stored on device → Public key sent to Transcodes → Login uses cryptographic signatures → Your app receives JWT

Key benefits: No passwords, phishing-resistant (origin-bound), works across devices via sync

HTTPS Requirement

Allowed in development:

• localhost
• 127.0.0.1

Required in production:

• Valid TLS certificate (HTTPS)
• Properly configured SSL/TLS

Token Security

Use the SDK’s Built-in Storage

Let Transcodes handle token storage. The SDK securely manages access tokens and private keys

// Recommended: Let the SDK handle storage automatically
const token = await transcodes.token.getAccessToken();

Secure Token Transmission

// Always use Authorization header
fetch('/api/protected', {
  headers: {
    Authorization: `Bearer ${await transcodes.token.getAccessToken()}`,
  },
});

Never:

• Include tokens in URLs (?token=xxx)
• Log tokens to console in production
• Store tokens in global variables

CSP (Content Security Policy)

CSP prevents XSS by controlling which resources your page can load. Transcodes SDK requires specific domains—without proper CSP, the browser may block our resources

Configure CSP headers:

Content-Security-Policy:
  script-src 'self' https://cdn.transcodes.link;
  connect-src 'self' <YOUR_API_URL>;
  frame-src 'self' <YOUR_API_URL>;

HTML Meta Tag Alternative

<meta
  http-equiv="Content-Security-Policy"
  content="
  default-src 'self';
  script-src 'self' https://cdn.transcodes.link;
  connect-src 'self' <YOUR_API_URL>;
  frame-src 'self' <YOUR_API_URL>;
"
/>

Data Handling & Privacy

Your agent is built with privacy at its core

What We Collect

What We Don’t Collect

• ❌ Private keys (personally identifiable information (PII))
• ❌ Biometric data (never transmitted)
• ❌ Passwords (we don’t use them)
• ❌ Collecting or storing tracking or analytics clinets’ data

Data Encryption

Your Rights

• Access your data
• Delete your account and all associated data
• Export your data in a machine-readable format

Your Responsibilities

1. User Consent: Informing users about authentication data processing
2. Privacy Policy: Disclosing Transcodes usage in your privacy policy
3. Security Practices: Following the security checklist below
4. Data Requests: Handling your users’ data rights requests

Security Checklist

Development

• Test on HTTPS (or localhost)
• Configure CSP headers
• Implement server-side token verification (see JSON Web Key)
• Review error messages (avoid information leakage)

Production

• Enable HTTPS with valid certificate
• Remove all console.log statements containing tokens
• Enable rate limiting on your API
• Configure security headers (HSTS, X-Frame-Options, etc.)
• Set up monitoring and alerting

Ongoing Maintenance

• Keep SDK version up to date
• Subscribe to security advisories
• Conduct periodic security audits
• Review access logs regularly

Next Steps

• Passkey-first Login - Get started in 5 minutes
• API Reference - Full SDK documentation
• JSON Web Key - Server-side JWT verification
• MDN Web Security  · OWASP Top 10 

Security Issues: security@transcodes.io