explorer-monorepo/docs/specs/security/auth-spec.md

Authentication & Authorization Specification

Overview

Authentication and authorization system for user access and API access.

User Authentication Flows

Authentication Methods

1. Email/Password:

• Registration with email
• Password hashing (bcrypt/argon2)
• Email verification

2. OAuth:

• Google, GitHub, etc.
• OAuth 2.0 flow
• Token-based authentication

3. Wallet Authentication:

• Signature-based authentication
• Prove ownership of address

Session Management

Storage: HTTP-only cookies or JWT tokens Expiration: Configurable (default: 24 hours) Refresh: Refresh tokens for extended sessions

API Key Management

Key Generation

Format: Secure random tokens Storage: Hashed (not plaintext) Metadata: Name, tier, permissions, expiration

Key Usage

Authentication: Via X-API-Key header Rate Limiting: Based on key tier Revocation: Support key revocation

RBAC (Role-Based Access Control)

Roles

Public: Unauthenticated users User: Authenticated users Pro: Paid tier users Admin: Platform administrators Compliance: Compliance officers

Permissions

Read: View data Write: Create/update data Admin: Full access Compliance: Compliance-specific access

OAuth Integration

OAuth Providers

• Google
• GitHub
• Others as needed

OAuth Flow

1. User initiates OAuth login
2. Redirect to provider
3. User authorizes
4. Callback with code
5. Exchange code for tokens
6. Create/login user account
7. Establish session

Session Management

Session Storage

Options:

• Server-side sessions (Redis)
• JWT tokens (stateless)

Recommendation: Server-side sessions for better security

Session Security

• Secure cookies (HTTPS only)
• HttpOnly flag
• SameSite attribute
• CSRF protection

References

• Security Architecture: See security-architecture.md