Skip to content

Cleanup Sessions

Method

REST method is adopted.

HTTP Method

POST: Maintenance operation

Naming Convention

To unify naming of query parameters and nodes and improve readability, snake_case is used for URIs and nodes in JSON during requests.

Request and Response

Headers

Meta information is set in HTTP headers rather than in the response body.

Request Headers

  • X-API-Key: <session_cleanup_api_key>

Response Headers

  • Content-Type: application/json

Cleanup Sessions

URI

/api/v1/auth/cleanup_sessions

Request Body

No request body required.

Response (200 OK)

Response is JSON. 

{
  "message": "Session cleanup completed",
  "cleaned_count": 42
}

Note: This endpoint is intended for use by scheduled services (e.g., AWS EventBridge cron job) to periodically remove expired sessions. It is not intended for direct user access.

Authentication

Authentication is performed using an API key passed via the X-API-Key header. The API key is validated using timing-safe comparison to prevent timing attacks.

Exception Handling

Exception handling status codes are as follows.

Description Status Code Status Name
Missing or invalid API key 401 Unauthorized
Internal server error 500 Internal Server Error

Process Flow

Sequence Diagram

sequenceDiagram
    participant Scheduler as AWS EventBridge
    participant API as Hono Router
    participant Validate as API Key Validation
    participant Service as Auth Service
    participant DB as PostgreSQL Database

    Scheduler->>API: POST /api/v1/auth/cleanup_sessions
    API->>Validate: Extract X-API-Key header

    alt API Key Valid
        Validate->>Validate: timingSafeEqual(apiKey, expectedKey)
        Validate-->>API: API key valid
        API->>Service: cleanupExpiredSessions()
        Service->>DB: Find expired sessions (expires_at < now)
        DB-->>Service: Expired sessions list
        Service->>DB: Soft-delete expired sessions
        DB-->>Service: Deleted count
        Service-->>API: cleanedCount
        API-->>Scheduler: 200 OK { message, cleaned_count }
    else API Key Missing or Invalid
        Validate-->>API: UnauthorizedError
        API-->>Scheduler: 401 Unauthorized
    end

Routes Layer

API routing is performed here. The API key is validated inline within the handler using timing-safe comparison. If valid, delegates to the auth service for cleanup.

Source: src/routes/v1/auth.ts:176

Services Layer

This section describes business logic. It queries the database for sessions past their expiration time and performs soft-deletion.

Source: src/services/auth.ts

Repositories Layer

This section describes access to databases. It handles querying expired sessions and batch soft-deletion.

Source: src/repositories/

Security

  • API key validated using timingSafeEqual to prevent timing attacks
  • If SESSION_CLEANUP_API_KEY is not configured, the endpoint uses a dummy buffer to maintain constant-time comparison
  • Unauthorized access attempts are logged
  • Intended for internal/scheduled invocation only

Configuration

# Required environment variable
SESSION_CLEANUP_API_KEY=<secure-random-key>

AWS EventBridge Schedule Example

Rate: cron(0 0 * * ? *)  # Daily at midnight UTC
Target: API Gateway -> /api/v1/auth/cleanup_sessions
Headers: X-API-Key: ${SESSION_CLEANUP_API_KEY}