feat(auth): add DB-backed login, token management, and idempotent auth migration

docs/api-examples.md

@@ -259,11 +259,105 @@ Response 204:
 
 ### 5.1 GET /strategy-sets
 
-## 6. Users
+## 6. Auth
+
+### 6.1 POST /auth/login
+
+Request:
+
+```bash
+curl -X POST "http://localhost:8000/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "bootstrap123"
+  }'
+```
+
+Response 200:
+
+```json
+{
+  "access_token": "plain-token-value",
+  "token_type": "bearer",
+  "expires_at": "2026-04-03T12:00:00Z",
+  "permission": "admin",
+  "user": {
+    "id": "user-1",
+    "username": "admin",
+    "email": "admin@example.com",
+    "permission": "admin",
+    "is_active": true,
+    "created_at": "2026-04-03T00:00:00Z",
+    "updated_at": "2026-04-03T00:00:00Z",
+    "last_login_at": "2026-04-03T00:00:00Z"
+  }
+}
+```
+
+### 6.2 POST /auth/tokens
+
+Request:
+
+```bash
+curl -X POST "http://localhost:8000/auth/tokens" \
+  -H "Authorization: Bearer <SESSION_OR_DB_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "mobile-app",
+    "permission": "read",
+    "expires_in_days": 30
+  }'
+```
+
+Response 201:
+
+```json
+{
+  "token": "plain-client-token",
+  "token_type": "bearer",
+  "auth_token": {
+    "id": "token-1",
+    "user_id": "user-1",
+    "name": "mobile-app",
+    "token_prefix": "abcd1234",
+    "permission": "read",
+    "token_type": "client",
+    "expires_at": "2026-05-03T00:00:00Z",
+    "last_used_at": null,
+    "revoked_at": null,
+    "created_at": "2026-04-03T00:00:00Z"
+  }
+}
+```
+
+### 6.3 GET /auth/tokens
+
+Request:
+
+```bash
+curl -X GET "http://localhost:8000/auth/tokens" \
+  -H "Authorization: Bearer <SESSION_OR_DB_TOKEN>"
+```
+
+### 6.4 DELETE /auth/tokens/{token_id}
+
+Request:
+
+```bash
+curl -X DELETE "http://localhost:8000/auth/tokens/token-1" \
+  -H "Authorization: Bearer <SESSION_OR_DB_TOKEN>"
+```
+
+Response 204:
+
+- No content.
+
+## 7. Users
 
 All user management endpoints require an admin token.
 
-### 6.1 GET /users
+### 7.1 GET /users
 
 Request:
 
@@ -286,7 +380,7 @@ Response 200:
 ]
 ```
 
-### 6.2 GET /users/{user_id}
+### 7.2 GET /users/{user_id}
 
 Request:
 
@@ -307,7 +401,7 @@ Response 200:
 }
 ```
 
-### 6.3 POST /users
+### 7.3 POST /users
 
 Request:
 
@@ -317,7 +411,10 @@ curl -X POST "http://localhost:8000/users" \
   -H "Content-Type: application/json" \
   -d '{
     "username": "alice",
-    "email": "alice@example.com"
+    "email": "alice@example.com",
+    "password": "password123",
+    "permission": "read",
+    "is_active": true
   }'
 ```
 
@@ -328,12 +425,15 @@ Response 201:
   "id": "user-1",
   "username": "alice",
   "email": "alice@example.com",
+  "permission": "read",
+  "is_active": true,
   "created_at": "2026-04-03T00:00:00Z",
-  "updated_at": "2026-04-03T00:00:00Z"
+  "updated_at": "2026-04-03T00:00:00Z",
+  "last_login_at": null
 }
 ```
 
-### 6.4 PATCH /users/{user_id}
+### 7.4 PATCH /users/{user_id}
 
 Request:
 
@@ -353,12 +453,15 @@ Response 200:
   "id": "user-1",
   "username": "alice-updated",
   "email": "alice@example.com",
+  "permission": "read",
+  "is_active": true,
   "created_at": "2026-04-03T00:00:00Z",
-  "updated_at": "2026-04-03T00:10:00Z"
+  "updated_at": "2026-04-03T00:10:00Z",
+  "last_login_at": null
 }
 ```
 
-### 6.5 DELETE /users/{user_id}
+### 7.5 DELETE /users/{user_id}
 
 Request: