From 1b06549c91656b1a156ae9a79be9636e45566da3 Mon Sep 17 00:00:00 2001 From: Dave Date: Sat, 26 Sep 2026 10:23:37 +0200 Subject: [PATCH] docs(agent-api): unset AGENT_API_TOKEN is 500 not 401; note Coolify deploy step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The design spec said an unset token gets a 401 like a missing/wrong one; the implementation (and the plan's own Definition of Done) has always treated unset/misconfigured as 500, matching CRON_SECRET's own behavior. Also extends the .env.example comment to spell out that this same value must be set in Coolify's environment too, not just .env.local — this app has no local PocketBase, so the token is checked against process.env on whichever environment actually receives the request. Co-Authored-By: Claude Sonnet 5 --- .env.example | 6 ++++++ .../specs/2026-09-25-phase-8-agent-api-design.md | 7 +++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/.env.example b/.env.example index 1f2ec27..0a1b294 100644 --- a/.env.example +++ b/.env.example @@ -21,4 +21,10 @@ PB_SUPERUSER_PASSWORD=replace-me # openssl rand -hex 32 # Anyone holding this can read every project and write comments/subtasks/ # moves as the owner — treat it like the superuser credentials above. +# This app has no local PocketBase — it always runs against the hosted +# Coolify instance — so this same value must ALSO be set in the deployed +# app's own environment variables in Coolify, not just in .env.local. The +# token is checked against process.env at request time on whichever +# environment is actually handling the request, so setting it in only one +# place leaves the other refusing every request with 500. AGENT_API_TOKEN=replace-me diff --git a/docs/superpowers/specs/2026-09-25-phase-8-agent-api-design.md b/docs/superpowers/specs/2026-09-25-phase-8-agent-api-design.md index fc8e4b9..0d9ed0c 100644 --- a/docs/superpowers/specs/2026-09-25-phase-8-agent-api-design.md +++ b/docs/superpowers/specs/2026-09-25-phase-8-agent-api-design.md @@ -52,8 +52,11 @@ Authorization: Bearer This is the exact pattern already used by `/api/cron/reconcile` (`CRON_SECRET`) — nothing new is being introduced to this codebase's security model, just a second secret of the same kind for a second machine caller. A request with -no token, a wrong token, or the token unset in the environment gets a 401 -without touching PocketBase. +no token or a wrong token gets a 401. If `AGENT_API_TOKEN` itself is unset, +too weak (shorter than 32 characters), or still the literal placeholder +`replace-me`, every request gets a 500 without touching PocketBase — the +route is treated as not configured at all, matching `CRON_SECRET`'s own +behavior for the same case. This is a full owner-equivalent credential. Anyone holding it can read every client's board and post/move/comment as the owner. It must be treated with