Architecture

For a non-technical overview, start with How It Works.

The whole product in one picture

System overview

Transcodes is four deployable surfaces plus one shared backend:

Read the diagram left to right:

• Browser path — your app calls the SDK, which redirects the user to Transcodes Auth for login, step-up, or credential management; WebAuthn runs there, and the SDK exchanges the returned sid for a JWT.
• AI path — agents call MCP tools; risky actions redirect a human to Transcodes Auth.
• Transcodes Console — operators configure projects, roles, and the RBAC permission matrix.
• transcodes CLI — stores member tokens locally for MCP/guard and shows a read-only RBAC view (never paste tokens into chat).

Component reference

Path A — SDK in your web app

The SDK is a WebWorker loaded from Transcodes CDN. It renders no auth UI — instead it redirects the user to Transcodes Auth, then exchanges the returned sid for a JWT and manages the token lifecycle.

Redirect helpers (window.transcodes.*):

What the SDK owns: redirect orchestration, automatic token lifecycle (memory → secure storage → re-auth), event bus (AUTH_STATE_CHANGED, TOKEN_REFRESHED, …), AES-256-GCM encrypted in-memory tokens.

What Transcodes Auth owns: all WebAuthn / MFA UI and ceremonies.

Your app owns: business UI, when to call the redirect helpers, server-side JWT verification.

SDK token API (conceptual)

interface TokenAPI {
  getCurrentMember(): Promise<Member | null>;
  getAccessToken(): Promise<string | null>;
  hasToken(): boolean;
  isAuthenticated(): Promise<boolean>;
  signOut(options?: { webhookNotification?: boolean }): Promise<void>;
}

See Events API for event payloads.

Path B — MCP + AI agent

The MCP server is a local Node process your IDE spawns. It authenticates with a Member Access Token (MAT) and exposes admin tools to the agent.

Token storage: {{HOME_DIR}}/.transcodes/config.json via the transcodes CLI .

RBAC & guard: Configure resources, roles, and permission levels (0 deny · 1 allow · 2 step-up) in Console. transcodes-guard PreToolUse hooks call POST /guard/evaluate to classify shell commands and external MCP calls into { resource, action } and enforce the same matrix. Create or edit RBAC only in Console; the CLI dashboard shows the matrix read-only.

Two JWT types

Both are signed with the project’s ES256 key pair. They differ by audience and header:

Security model (summary)

Standards: ECDSA P-256 · ES256 JWT · AES-256-GCM · WebAuthn / FIDO2 · TLS 1.3

Scope

Transcodes provides authentication, authorization (RBAC), step-up MFA, and audit logging. It does not protect against XSS, CSRF, or infrastructure attacks in your app — you must configure CSP, sanitize inputs, and use HTTPS in production.

HTTPS

WebAuthn requires a secure context. Allowed in dev: localhost, 127.0.0.1. Production: valid TLS certificate required.

Token hygiene

• Never put tokens in URLs or agent chat
• Verify JWTs server-side with project JWK
• Use Authorization: Bearer (SDK) or X-Transcodes-Token (MCP) — not cookies for MCP

Browser support

Security checklist

Before production:

• HTTPS with valid certificate
• CSP allows Transcodes CDN and your backend API origin
• Server-side JWT verification (ES256 + JWK)
• Rate limiting on your API
• No tokens in logs or URLs

Security issues: security@transcodes.io

Next steps