Architecture

⚡ 10 min read

How Transcodes works under the hood — so your AI secretary can handle admin authentication, operations, and management safely on your behalf

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

Event	When Fired
`AUTH_STATE_CHANGED`	Login, logout, or initial auth check
`TOKEN_REFRESHED`	Access token automatically renewed
`TOKEN_EXPIRED`	Token expired before refresh
`ERROR`	Authentication error occurred

See Events API for payload details

Security Model

Location	Data	Encryption
In-Memory	Access tokens	AES-256-GCM
Device Storage	Private keys, credentials	Platform encryption
Transcodes Server	Public keys, metadata	AES-256 at rest

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

Token Refresh Flow

getAccessToken() lookup order:

Return cached token if valid
Re-authenticate using stored credentials
Request fresh token from Transcodes server
Emit TOKEN_REFRESHED event

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

Browser Support

Browser	Minimum Version
Chrome	67+
Safari	14+
Firefox	60+
Edge	79+

WebAuthn requires HTTPS in production. localhost works for development

Scope of Service

Transcodes is your AI secretary for admin authentication, operations, and management — not a full security platform.

We provide:

✅ WebAuthn-based passwordless authentication
✅ Secure credential storage and verification
✅ JWT token issuance

We do NOT provide:

❌ Protection against client-side attacks (XSS, CSRF, etc.)
❌ Application-level security
❌ Infrastructure security

Your Responsibilities

Client-side security is YOUR responsibility. Transcodes is NOT liable for attacks from compromised client code, vulnerabilities in your application, or improper implementation. You must implement CSP, sanitize inputs, and follow web security best practices

What Your Secretary 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

MDN Web Authentication API

We Do	We Don’t Do
Issue JWT after passkey verification	Authorization (you manage roles)
Store public keys and credential IDs	Client security (XSS, CSRF, etc.)
Handle FIDO2/WebAuthn protocol	Your data encryption or infrastructure

HTTPS Requirement

WebAuthn requires a secure context (HTTPS). The SDK will not function over plain HTTP

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();

Never manually store tokens in cookies or custom storage. The SDK’s storage is designed for security

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 secretary is built with privacy at its core

What We Collect

Data Type	Purpose	Retention
Email Address	Account identification	Account lifetime
Public Key	Authentication verification	Account lifetime
Credential ID	Passkey identification	Account lifetime

Data Minimization: We only collect data essential for authentication. No tracking, no profiling, no data selling

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

Layer	Standard
In Transit	TLS 1.3, PFS, HSTS
At Rest	AES-256, keys managed separately
On Your Device	Secure browser storage, Secure Enclave/TPM on supported devices

Your Rights

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

Your Responsibilities

User Consent: Informing users about authentication data processing
Privacy Policy: Disclosing Transcodes usage in your privacy policy
Security Practices: Following the security checklist below
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