101 lines
1.9 KiB
Markdown
101 lines
1.9 KiB
Markdown
# 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`
|
|
|