Authentication Flow

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• apps/cli/CLAUDE.md
• apps/server/workers/README.md
• apps/server/workers/src/tests/auth.spec.ts
• apps/web/react/CLAUDE.md
• apps/admin/api/CLAUDE.md

The Authentication Flow in the Magic-Agent ecosystem is a cryptographic, zero-knowledge system designed to securely link disparate clients (CLI, Mobile, Web) without the use of traditional passwords. It primarily utilizes Ed25519 public key signatures and challenge-response mechanisms to establish trust and facilitate end-to-end encrypted (E2EE) communication.

The flow ensures that the server acts merely as a "zero-knowledge" relay, facilitating the exchange of encrypted messages while having no access to the plaintext content or the private keys of the users.

Sources: CLAUDE.md, apps/server/workers/README.md

Core Authentication Architecture

The system relies on cryptographic identity established through keypairs generated by the clients. The primary authentication method involves a challenge-response handshake where the server or a peer client provides a challenge that must be signed by the private key corresponding to a registered public key.

Key Components

Component	Responsibility
CLI (Daemon)	Generates Ed25519 keypairs and displays QR codes for pairing. Initiates terminal auth requests.
Mobile App	Scans QR codes, approves connection requests, and performs challenge-response to obtain session tokens.
Server (Workers/Docker)	Facilitates the challenge-response handshake, manages ephemeral auth requests, and issues JWT or session tokens.
Admin API	Handles specific administrative authentication using Better-Auth with D1 adapter for the dashboard.

Sources: CLAUDE.md, apps/server/workers/README.md, apps/admin/api/CLAUDE.md

High-Level Flow Diagram

The following diagram illustrates the lifecycle of a connection from initial terminal request to authenticated session.

Terminal and Mobile Pairing Flow

The pairing process is the mechanism by which a mobile device authorizes a CLI instance (or vice versa) to access the user's encrypted sessions.

Terminal Authentication Sequence

1. Request Initiation: The CLI generates a public key and sends a request to /v1/auth/request. This creates a pending authentication state in the database.
2. QR Generation: The CLI displays a QR code containing its public key and the server URL.
3. Mobile Approval: The Mobile App scans the QR code. It then sends an approval response to /v1/auth/response which includes an encrypted payload signed by the mobile device's private key.
4. Token Exchange: Once the server verifies the mobile's approval, the CLI (polling /v1/auth/request/status) receives the authenticated token.

API Endpoints and Security

Authentication Endpoints

The server exposes several endpoints to manage the authentication lifecycle:

Endpoint	Method	Description	Security Requirements
/v1/auth	POST	Direct authentication using { publicKey, challenge, signature }.	None (Handshake)
/v1/auth/request	POST	Initiates a pairing request for terminal/account.	None
/v1/auth/request/status	GET	Polls for the status of a pending request using publicKey.	None
/v1/auth/response	POST	Approves a pending pairing request.	Valid Session Token
/api/auth/*	*	Admin dashboard auth managed by Better-Auth.	CSRF + Rate Limiting

Sources: apps/server/workers/README.md, apps/admin/api/CLAUDE.md, apps/server/workers/src/tests/auth.spec.ts

Security Measures

• Signature Verification: The server uses privacy-kit and Ed25519 to verify that auth responses are signed by the claimed owner of the public key.
• CSRF Protection: For the Admin API, state-changing requests require an X-CSRF-Token header matching a double-submit cookie pattern.
• Rate Limiting: Specifically applied to the Admin API to prevent brute force. Sign-in attempts are limited to 5 per minute.
• Audit Logging: The Admin system maintains audit logs for role changes and user management, retained for 90 days.

Sources: apps/admin/api/CLAUDE.md, apps/server/workers/src/tests/auth.spec.ts

Admin Authentication (Better-Auth)

The happy-admin-api utilizes Better-Auth for user management within the admin dashboard. This flow is separate from the E2EE pairing flow used by the CLI and Mobile apps.

Admin Identity Logic

• Database: Uses D1 (SQLite) with tables users, sessions, accounts, and verifications.
• Role-Based Access: Access to metrics and admin routes requires a user to have role = 'admin' in the database.
• Registration: Public registration is disabled; admin users are created via the Better-Auth admin API or direct D1 execution by existing admins.

Sources: apps/admin/api/CLAUDE.md

Technical Implementation Details

The implementation leverages TweetNaCl for cryptographic primitives and Zod for schema validation of auth payloads.

// Example: Authentication Data Structure
// Derived from apps/server/workers/src/__tests__/auth.spec.ts
{
    publicKey: "base64_encoded_32_byte_key",
    challenge: "base64_encoded_challenge",
    signature: "base64_encoded_64_byte_ed25519_signature"
}

Protocol Helpers

To ensure consistency across the monorepo, the @magic-agent/protocol and @happy/lint-rules packages enforce the use of specific helpers for accessing session and machine IDs during the authenticated flow.

Sources: CLAUDE.md:325-330, apps/admin/api/CLAUDE.md:120-130

Conclusion

The Authentication Flow in Magic-Agent provides a secure, decentralized method for device pairing and session access. By combining Ed25519 signatures with a server-mediated challenge-response system, it achieves a zero-knowledge architecture where sensitive user data remains encrypted end-to-end, while admin functions remain strictly controlled through standard role-based access and rate-limited API endpoints.