Separate HMAC key from read token

README.md

@@ -61,16 +61,17 @@ CPU supports Kubernetes notation (`"2"` = 2 cores, `"500m"` = 0.5 cores). Memory
 HTTP service that stores metric summaries in SQLite (via GORM) and exposes a query API.
 
 ```bash
-./receiver --addr=:8080 --db=metrics.db --read-token=my-secret-token
+./receiver --addr=:8080 --db=metrics.db --read-token=my-secret-token --hmac-key=my-hmac-key
 ```
 
 **Flags:**
 
-| Flag           | Environment Variable  | Description                                    | Default      |
-| -------------- | --------------------- | ---------------------------------------------- | ------------ |
-| `--addr`       | —                     | HTTP listen address                            | `:8080`      |
-| `--db`         | —                     | SQLite database path                           | `metrics.db` |
-| `--read-token` | `RECEIVER_READ_TOKEN` | Pre-shared token for authentication (required)  | —            |
+| Flag           | Environment Variable  | Description                                           | Default      |
+| -------------- | --------------------- | ----------------------------------------------------- | ------------ |
+| `--addr`       | —                     | HTTP listen address                                   | `:8080`      |
+| `--db`         | —                     | SQLite database path                                  | `metrics.db` |
+| `--read-token` | `RECEIVER_READ_TOKEN` | Pre-shared token for read/admin endpoints (required)  | —            |
+| `--hmac-key`   | `RECEIVER_HMAC_KEY`   | Secret key for push token generation/validation (required) | —       |
 
 **Endpoints:**
 
@@ -105,7 +106,7 @@ curl -H "Authorization: Bearer my-secret-token" \  #gitleaks:allow
   http://localhost:8080/api/v1/metrics/repo/my-org/my-repo/ci.yml/build
 ```
 
-Push tokens are HMAC-SHA256 digests derived from the read token and the scope (org/repo/workflow/job). They are stateless — no database storage is needed.
+Push tokens are HMAC-SHA256 digests derived from `--hmac-key` and the scope (org/repo/workflow/job). They are stateless — no database storage is needed. The HMAC key is separate from the read token so that compromising a push token does not expose the admin credential.
 
 ## How Metrics Are Collected
 
@@ -175,11 +176,28 @@ All memory values are in **bytes**.
 ### Docker Compose
 
 ```bash
-docker compose -f test/docker/docker-compose-stress.yaml up -d
-# Wait for collection, then trigger shutdown summary:
+# Start the receiver (builds image if needed):
+docker compose -f test/docker/docker-compose-stress.yaml up -d --build receiver
+
+# Generate a scoped push token for the collector:
+PUSH_TOKEN=$(curl -s -X POST http://localhost:9080/api/v1/token \
+  -H "Authorization: Bearer dummyreadtoken" \
+  -H "Content-Type: application/json" \
+  -d '{"organization":"test-org","repository":"test-org/stress-test","workflow":"stress-test-workflow","job":"heavy-workload"}' \
+  | jq -r .token)
+
+# Start the collector and stress workloads with the push token:
+COLLECTOR_PUSH_TOKEN=$PUSH_TOKEN \
+  docker compose -f test/docker/docker-compose-stress.yaml up -d --build collector
+
+# ... Wait for data collection ...
+
+# Trigger shutdown summary:
 docker compose -f test/docker/docker-compose-stress.yaml stop collector
-# Query results:
-curl http://localhost:9080/api/v1/metrics/repo/test-org/test-org%2Fstress-test/stress-test-workflow/heavy-workload
+
+# Query results with the read token:
+curl -H "Authorization: Bearer dummyreadtoken" \
+  http://localhost:9080/api/v1/metrics/repo/test-org/test-org%2Fstress-test/stress-test-workflow/heavy-workload
 ```
 
 ### Local
@@ -188,8 +206,21 @@ curl http://localhost:9080/api/v1/metrics/repo/test-org/test-org%2Fstress-test/s
 go build -o collector ./cmd/collector
 go build -o receiver ./cmd/receiver
 
-./receiver --addr=:8080 --db=metrics.db
-./collector --interval=2s --top=10 --push-endpoint=http://localhost:8080/api/v1/metrics
+# Start receiver with both keys:
+./receiver --addr=:8080 --db=metrics.db \
+  --read-token=my-secret-token --hmac-key=my-hmac-key
+
+# Generate a scoped push token:
+PUSH_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/token \
+  -H "Authorization: Bearer my-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{"organization":"my-org","repository":"my-repo","workflow":"ci.yml","job":"build"}' \
+  | jq -r .token)
+
+# Run collector with the push token:
+./collector --interval=2s --top=10 \
+  --push-endpoint=http://localhost:8080/api/v1/metrics \
+  --push-token=$PUSH_TOKEN
 ```
 
 ## Internal Packages