✅
Email Verified Successfully!
Your email address has been verified.
```
---
### User Registration
#### POST /api/register
Completes user registration after email verification.
**Request Body:**
```json
{
"email": "user@example.com",
"name": "John Doe",
"public_key": "04a1b2c3d4e5f6..."
}
```
**Response:**
```json
{
"success": true,
"message": "Registration completed successfully",
"user_id": "uuid-user-id"
}
```
**Error Response:**
```json
{
"success": false,
"message": "Email not verified",
"user_id": null
}
```
**Status Codes:**
- `200 OK`: Registration successful
- `400 Bad Request`: Email not verified or invalid data
- `500 Internal Server Error`: Server error
**Validation:**
- Email must be verified before registration
- Public key must be valid hex format
- Name cannot be empty
---
### OAuth 2.0 Authentication
#### POST /oauth/token
OAuth 2.0 token endpoint for cryptographic authentication.
**Request Body:**
```json
{
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": "signed-jwt-token",
"public_key": "04a1b2c3d4e5f6...",
"challenge": "server-challenge",
"scope": "openid profile"
}
```
**Response:**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
```
**Error Response:**
```json
{
"error": "invalid_client",
"error_description": "User not found"
}
```
**Status Codes:**
- `200 OK`: Authentication successful
- `401 Unauthorized`: Invalid credentials or signature
- `400 Bad Request`: Malformed request
**OAuth 2.0 Error Codes:**
- `invalid_client`: Public key not found
- `invalid_grant`: Invalid signature or challenge
- `unsupported_grant_type`: Grant type not supported
- `server_error`: Internal server error
#### GET /oauth/userinfo
OpenID Connect UserInfo endpoint. Returns user profile information.
**Headers:**
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
**Response:**
```json
{
"sub": "user-id",
"email": "user@example.com",
"name": "John Doe",
"public_key": "04a1b2c3d4e5f6...",
"created_at": "1640995200"
}
```
**Error Response:**
```json
{
"error": "invalid_token",
"error_description": "Missing Authorization header"
}
```
**Status Codes:**
- `200 OK`: User info returned successfully
- `401 Unauthorized`: Invalid or missing token
---
## Data Models
### User Model
```rust
struct User {
id: String, // UUID v4
email: String, // Verified email address
public_key: String, // Hex-encoded public key
name: String, // Display name
created_at: String, // Unix timestamp
}
```
### JWT Claims
```rust
struct Claims {
sub: String, // Subject (public key)
iss: String, // Issuer ("self-sovereign-identity")
aud: String, // Audience ("identity-server")
exp: usize, // Expiration time (Unix timestamp)
iat: usize, // Issued at time (Unix timestamp)
scope: String, // Granted scopes
}
```
### Verification Status
```rust
struct VerificationStatus {
email: String, // Email address
verified: bool, // Verification state
verification_token: String, // UUID token
}
```
## Authentication Flow
### 1. Challenge-Response Authentication
```mermaid
sequenceDiagram
participant C as Client
participant S as Server
C->>S: POST /oauth/token (with signature)
S->>S: Verify signature against public key
S->>S: Generate JWT token
S->>C: Return access_token
C->>S: GET /oauth/userinfo (with Bearer token)
S->>S: Validate JWT token
S->>C: Return user profile
```
### 2. JWT Token Validation
1. Extract Bearer token from Authorization header
2. Decode JWT using server secret
3. Validate issuer, audience, and expiration
4. Extract public key from subject claim
5. Look up user by public key
6. Return user information
## Error Handling
### Standard HTTP Status Codes
- `200 OK`: Request successful
- `400 Bad Request`: Invalid request format or data
- `401 Unauthorized`: Authentication required or failed
- `404 Not Found`: Resource not found
- `500 Internal Server Error`: Server error
### OAuth 2.0 Error Format
All OAuth errors follow RFC 6749 format:
```json
{
"error": "error_code",
"error_description": "Human readable description",
"error_uri": "https://docs.example.com/oauth/errors"
}
```
### Common Error Scenarios
1. **Email Not Verified**
```json
{
"success": false,
"message": "Email not verified"
}
```
2. **Invalid Token**
```json
{
"error": "invalid_token",
"error_description": "Invalid or expired token"
}
```
3. **User Not Found**
```json
{
"error": "invalid_client",
"error_description": "User not found"
}
```
## Rate Limiting
Currently not implemented but recommended for production:
- **Email Verification**: 5 requests per email per hour
- **Authentication**: 10 attempts per public key per minute
- **Registration**: 3 registrations per IP per hour
## Security Headers
The server should include security headers in production:
```
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'
```
## Monitoring and Logging
### Log Levels
- **INFO**: Normal operations (requests, registrations)
- **WARN**: Invalid tokens, failed verifications
- **ERROR**: Server errors, database failures
### Metrics to Track
- Request count by endpoint
- Authentication success/failure rates
- Registration completion rates
- Email verification rates
- Response times
- Error rates
### Health Check Details
The `/health` endpoint can be extended for detailed health information:
```json
{
"status": "healthy",
"service": "self-server",
"version": "1.0.0",
"uptime": 3600,
"checks": {
"database": "healthy",
"email_service": "healthy",
"jwt_signing": "healthy"
}
}
```
## Production Considerations
### Database Integration
Replace in-memory storage with persistent database:
```rust
// Example with SQLx
async fn store_user(pool: &PgPool, user: &User) -> Result<(), sqlx::Error> {
sqlx::query!(
"INSERT INTO users (id, email, public_key, name, created_at) VALUES ($1, $2, $3, $4, $5)",
user.id, user.email, user.public_key, user.name, user.created_at
)
.execute(pool)
.await?;
Ok(())
}
```
### SMTP Integration
Replace console logging with actual email sending:
```rust
use lettre::{SmtpTransport, Transport, Message};
async fn send_verification_email(email: &str, verification_url: &str) -> Result<(), Box