セッションクリーンアップ

メソッド

REST メソッドを採用しています。

HTTP メソッド

POST: メンテナンス操作

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時の URI と JSON 内のノードには snake_case を使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTP ヘッダーに設定されます。

リクエストヘッダー

X-API-Key: <session_cleanup_api_key>

レスポンスヘッダー

Content-Type: application/json

セッションクリーンアップ

URI

/api/v1/auth/cleanup_sessions

リクエストボディ

リクエストボディは不要です。

レスポンス（200 OK）

レスポンスは JSON です。

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

注: 本エンドポイントは、期限切れセッションを定期的に削除するスケジュール済みサービス（例: AWS EventBridge の cron）向けです。一般ユーザーが直接呼び出すものではありません。

認証要件

X-API-Key ヘッダーで API キーを渡して認証します。API キーはタイミング攻撃を防ぐため、タイミングセーフな比較で検証されます。

例外処理

例外時のステータスコードは次のとおりです。

説明	ステータスコード	ステータス名
API キーが欠落または無効	401	Unauthorized
サーバ内部エラー	500	Internal Server Error

処理フロー

シーケンス図

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 層

ルーティングはここで行います。ハンドラ内で API キーをタイミングセーフな比較で検証し、有効なら認証サービスにクリーンアップを委譲します。

ソース: src/routes/v1/auth.ts:176

Services 層

ビジネスロジックの説明です。有効期限を過ぎたセッションをデータベースから検索し、ソフト削除します。

ソース: src/services/auth.ts

Repositories 層

データベースへのアクセスです。期限切れセッションの検索と一括ソフト削除を扱います。

ソース: src/repositories/

セキュリティ

API キーは timingSafeEqual で検証し、タイミング攻撃を防ぎます
SESSION_CLEANUP_API_KEY が未設定の場合は、一定時間比較のためダミーバッファを使用します
不正なアクセス試行はログに記録されます
内部／スケジュール呼び出し専用を想定しています

設定

# 必須の環境変数
SESSION_CLEANUP_API_KEY=<secure-random-key>

AWS EventBridge スケジュール例

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