From 1e853e9f75fc128382436004d63928baa434bf49 Mon Sep 17 00:00:00 2001
From: lyn <lyn@mt.hangman-lab.top>
Date: Tue, 14 Apr 2026 12:54:17 +0000
Subject: [PATCH] Add API key rotation mechanism and client-side key fetch
 documentation

---
 PROJECT_PLAN.md | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md
index 3b29bd2..fba7f66 100644
--- a/PROJECT_PLAN.md
+++ b/PROJECT_PLAN.md
@@ -34,11 +34,35 @@ A lightweight Go service that:
 - **Source DB**: Gitea MySQL (read-only, same docker network)
 - **HTTP**: Standard library `net/http`
 - **Deployment**: Docker + Docker Compose on vps.git
+- **API Key**: Rotates every 10 minutes, stored in Docker volume at `/data/api-key`
+
+## Authentication
+
+All `/list` and `/webhook/gitea` endpoints require `Authorization: Bearer <api-key>` header.
+
+### API Key Rotation
+
+- API key is generated every **10 minutes** by the c-api service itself
+- Stored in the Docker volume at `/data/api-key`
+- Clients must fetch the latest key before each request
+
+### Client-side key fetch
+
+Before calling any c-api endpoint, fetch the current key:
+
+```bash
+API_KEY=$(ssh root@vps.git "cat /path/to/api-key")
+curl -H "Authorization: Bearer $API_KEY" "https://git.hangman-lab.top/c-api/list?username=xxx"
+```
+
+> **Note**: Script-side clients (e.g. `list-projs`) should perform this key fetch as part of their request flow. The key changes every 10 minutes so it must be re-fetched each time.
 
 ## API
 
 ### `GET /list?username={username}`
 
+> **Requires**: `Authorization: Bearer <api-key>` header
+
 Returns all repositories visible to the given Gitea user.
 
 **Response** (JSON):
@@ -61,7 +85,7 @@ Returns all repositories visible to the given Gitea user.
 
 ### `POST /webhook/gitea`
 
-Receives Gitea webhook events (requires `X-Gitea-Event` header).
+Receives Gitea webhook events (create/delete only).
 
 Supported events:
 - `repository.create` — insert new repo into cache
@@ -94,8 +118,9 @@ Environment variables:
 | `DB_USER`     | `root`  | MySQL username               |
 | `DB_PASS`     | —       | MySQL password               |
 | `DB_NAME`     | `giteadb` | MySQL database name        |
-| `SQLITE_PATH` | `cache.db` | SQLite file path          |
-| `WEBHOOK_SECRET` | —    | Gitea webhook secret token   |
+| `SQLITE_PATH` | `/data/cache.db` | SQLite file path              |
+| `API_KEY_FILE` | `/data/api-key` | Path for rotating api-key       |
+| `WEBHOOK_SECRET` | —      | Gitea webhook secret token       |
 | `PORT`        | `8080`  | HTTP listen port             |
 
 ## Docker
@@ -130,6 +155,7 @@ services:
       PORT: 8080
     volumes:
       - ./gitea-custom-api/data:/data
+      - ./gitea-custom-api/api-key:/data/api-key
     networks:
       - git-network