wood-fired-tasks 1.18.2 → 2.0.1

package/CHANGELOG.md

@@ -13,6 +13,91 @@ vulnerabilities, supply-chain pinning) are always called out under `Security`.
 
 _No changes yet._
 
+## [v2.0.1] - 2026-06-08
+
+### Fixed
+- **`tasks setup` interactive "Remote" selection no longer crashes.** Choosing
+  option **3) Remote** from the interactive setup menu threw
+  `remote onboarding requires a --remote <url> base URL.` because the menu set
+  the mode but never captured the server URL — only the `--remote <url>` flag
+  did. The interactive remote path now prompts for the base URL when it is not
+  supplied as a flag, guarded by a TTY check so non-interactive/CI callers still
+  fail fast with the same clear message instead of hanging on stdin.
+- **DB-path legacy-adopt tests are now hermetic.** `migrate-db-path.test.ts` and
+  `config-path-e2e.test.ts` exercise the "adopt `./data/tasks.db` when the OS
+  app-data DB is absent" precedence, but probed the real filesystem and so
+  failed on any dev machine where the `tasks` CLI had already created
+  `~/.local/share/wood-fired-tasks/tasks.db` (they passed on clean CI by luck).
+  `resolveMigrateDbPath`/`migrateCli` now forward the resolver's existing
+  injectable `exists` seam (default `fs.existsSync`, no behavior change), and the
+  tests inject a probe that hides the app-data DB — making the precedence-2
+  cases deterministic regardless of the developer's local state.
+
+## [v2.0.0] - 2026-06-07
+
+The **identity auth cutover** — a breaking major. The legacy `X-API-Key`
+shared-secret auth path is **removed**; every API call now authenticates with a
+per-user **Bearer personal access token (PAT)** minted through the identity
+system. Onboarding gains an OIDC device flow and explicit setup modes, and the
+CLI grows `statusline` and `link-project` commands. **No credential migration is
+required** — pre-identity (`is_legacy=1`) rows are left **inert** and read back
+unchanged — and the one schema migration that touches existing data
+(migration 005) was hardened to preserve child rows (see _Fixed_).
+
+### Changed
+- **Auth is now Bearer-PAT only.** Every authenticated REST/MCP request carries
+  `Authorization: Bearer <pat>`; the previously-supported `X-API-Key` shared-key
+  header is no longer accepted. PATs are per-user, revocable, and optionally
+  expiring (see [`docs/SETUP.md`](docs/SETUP.md)). This is the breaking change
+  that makes v2.0 a major.
+- **`setup` gains explicit Local/Service/Remote modes + an OIDC device flow.**
+  Running `wood-fired-tasks setup` with no args on a TTY presents a
+  Local/Service/Remote menu; `--local` / `--service` / `--remote <url>` pick a
+  path non-interactively. `setup --remote <url>` probes the server's OIDC state
+  and picks **device-flow** (OIDC ready) vs **manual-PAT** (OIDC
+  disabled/degraded) automatically, replacing the old key-paste onboarding. The
+  remote MCP entry is **URL-only** — the PAT is cached in the CLI credentials
+  file, never written into `~/.claude.json` (#810).
+- **`API_KEYS` is no longer an auth method.** It only seeds inert `is_legacy=1`
+  identity rows; the dead production boot-gate that required it was removed.
+
+### Added
+- **OIDC device-flow onboarding** for `setup --remote`, minting a PAT without a
+  hand-copied shared key when the server has OIDC enabled.
+- **`statusline` CLI command** for a compact at-a-glance status line, and
+  **`link-project`** to write a `.wft/project` marker that pins the working
+  directory to a project (consumed by `statusline` and CLI project resolution).
+- **`/tasks:update` slash command** (the packaged `/tasks:*` skill set is now 19).
+- **Update-available notifier** with an opt-out: set `WFT_NO_UPDATE_CHECK=1`
+  (env) or `update_check = false` (CLI config) to disable the best-effort
+  "newer version available" check.
+
+### Fixed
+- **Unified DB-path resolution — fixes silent data loss on upgrade.** `serve`/the
+  API defaulted `DATABASE_PATH` to the OS app-data dir while `migrate` and the
+  `tasks db*` commands hardcoded `./data/tasks.db`; with `DATABASE_PATH` unset
+  they could open **different** databases, silently abandoning an upgrading
+  user's `./data/tasks.db`. A single `resolveDbPath()`
+  ([`src/config/db-path.ts`](src/config/db-path.ts)) is now the source of truth:
+  explicit `DATABASE_PATH` (or the `DB_PATH` alias) > adopt an existing legacy
+  `./data/tasks.db` > app-data default.
+- **Migration 005 no longer cascade-deletes data.** `PRAGMA foreign_keys = OFF`
+  is a no-op inside a transaction, so 005's table rebuild CASCADE-deleted
+  `task_comments` / `dependencies` / `tags` when run against a populated pre-005
+  database. The migration now snapshots and restores child rows around the
+  rebuild (covered by a populated-DB round-trip test).
+
+### Security
+- **Removed the `X-API-Key` shared-secret auth path entirely** (the v2.0
+  cutover). A single long-lived shared key was the broadest part of the auth
+  surface; replacing it with per-user, individually-revocable Bearer PATs scopes
+  credentials to a user, makes revocation surgical, and bounds blast radius on
+  leak. Legacy `is_legacy=1` rows are left inert — **no credential migration is
+  required**.
+- **Closed an upgrade-time data-loss path** (the migration-005 cascade delete;
+  see _Fixed_) — a data-integrity fix for anyone upgrading across migration 005
+  with populated tables.
+
 ## [v1.18.2] - 2026-06-06
 
 A patch release: a Windows `self-update` fix plus two install-experience
@@ -561,7 +646,8 @@ and the task/project/dependency/comment/subtask domain model.
 - Task hierarchy (subtasks), dependency service, comments, time estimates
   (phase 06).
 
-[Unreleased]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v1.15...HEAD
+[Unreleased]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v2.0.0...HEAD
+[v2.0.0]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v1.18.2...v2.0.0
 [v1.15]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v1.14...v1.15
 [v1.14]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v1.13...v1.14
 [v1.13]: https://github.com/Wood-Fired-Games/wood-fired-tasks/compare/v1.12...v1.13

package/README.md

@@ -16,7 +16,7 @@ Wood Fired Tasks is open-source coordination infrastructure for fleets of AI cod
 
 - `/tasks:*` skill files implementing the plan→decompose→loop→audit lifecycle (ship as Claude Code slash commands; the recipes are vendor-neutral)
 - MCP server with 27 tools for native agent integration (local SQLite or remote HTTP modes) + cross-platform installers (Linux/macOS and Windows)
-- REST API with 47 route handlers across `src/api/routes/` (1 public `/health`; the rest authenticated; a single instance serves up to 40 — OIDC-disabled stubs are mutually exclusive with the live OIDC routes) and a `tasks` CLI with 34 commands
+- REST API with 52 route handlers across `src/api/routes/` (1 public `/health`; the rest authenticated; a single instance serves up to 45 — OIDC-disabled stubs are mutually exclusive with the live OIDC routes) and a `tasks` CLI with 42 commands
 - Atomic task claiming with optimistic locking + workflow automation (parent auto-complete, dependency auto-unblock) for multi-agent coordination
 - Real-time Server-Sent Events (SSE) for task/project change notifications
 - SQLite database with WAL mode, FTS5 full-text search, and automatic migrations
@@ -133,7 +133,7 @@ development instead? See [docs/SETUP.md → Development Setup](docs/SETUP.md#dev
 
 For self-hosted production deploys (including the fork-and-deploy workflow for OSS operators): provision a host once with `deploy/install.sh`, then ship every subsequent release in place with `deploy/upgrade.sh` (atomic backup, migrate, restart, `/health` probe, manual rollback recipe on failure). The full walkthrough — first-time install, in-place upgrades, deploying your fork, manual rollback, and the migration safety contract — lives at [Self-hosting and upgrades](docs/SETUP.md#self-hosting-and-upgrades). When a deploy or a reboot goes sideways, the [Troubleshooting & Recovery runbook](docs/TROUBLESHOOTING.md) covers boot failures (`exit 78`), wrong/stale-database symptoms, and safe backup/restore.
 
-**Sharing one server across a team.** The common shape is a single on-prem server with a fleet of Windows, Linux, and macOS workstations all pointed at it in remote mode (each client proxies its MCP tool calls to the shared REST API, so everyone sees one backlog). The end-to-end recipe — make the server reachable behind TLS, mint one revocable PAT per machine, and run the installer in `--mode remote` on each OS — is the [Multi-OS client fleet](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server) section.
+**Sharing one server across a team.** The common shape is a single on-prem server with a fleet of Windows, Linux, and macOS workstations all pointed at it in remote mode (each client proxies its MCP tool calls to the shared REST API, so everyone sees one backlog). The end-to-end recipe — make the server reachable behind TLS, mint one revocable PAT per machine, and run `wood-fired-tasks setup --remote <url> --token wft_pat_…` on each OS — is the [Multi-OS client fleet](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server) section.
 
 ## Automation (event-driven)
 
@@ -153,28 +153,27 @@ a single task unblock, the MCP server also exposes a `wait_for_unblock` tool
 
 ## Security Model
 
-**Read this before deploying.** Wood Fired Tasks is built for trusted multi-agent coordination. As of **v1.6** the REST API authenticates every `/api/v1` request through a three-strategy chain (`src/api/plugins/auth/index.ts`), tried in order — the first strategy that produces a valid user wins, and that user's id is stamped onto every write (`created_by_user_id`, `assignee_user_id`, …) and the per-request audit log (`user_id`, `token_id`, `auth_method`):
+**Read this before deploying.** Wood Fired Tasks is built for trusted multi-agent coordination. As of **v2.0** the REST API authenticates every `/api/v1` request through a two-strategy chain (`src/api/plugins/auth/index.ts`), tried in order — the first strategy that produces a valid user wins, and that user's id is stamped onto every write (`created_by_user_id`, `assignee_user_id`, …) and the per-request audit log (`user_id`, `token_id`, `auth_method`):
 
 | Order | Strategy | Credential | Wire format |
 |-------|----------|------------|-------------|
 | 1 | **PAT** — recommended for machines/agents | row in `api_tokens` (SHA-256 hash stored) | `Authorization: Bearer wft_pat_<…>` |
 | 2 | **Session** — recommended for humans | OIDC sign-in → sealed-box cookie | `Cookie: wft_session=<…>` |
-| 3 | **Legacy** — deprecated but still supported (see below) | entry in `API_KEYS` env list | `X-API-Key: <…>` |
 
-PATs are minted from a logged-in `/me` web session or offline via `tasks db mint-token`; the raw value is shown **once** at mint time (only a hash is stored) and revoked via the `/me` UI, `DELETE /me/tokens/:id`, or `tasks logout`. Sessions come from OIDC (`/auth/login` → provider → `/auth/callback`, protected by PKCE + state), are sealed-box-encrypted with `SESSION_COOKIE_SECRET`, and expire after 8h. The CLI and remote MCP client auto-select the header from the `wft_pat_` prefix, so the same env var accepts a PAT or a legacy key. Full detail: [SECURITY.md → Authentication Architecture](SECURITY.md#authentication-architecture).
+PATs are minted from a logged-in `/me` web session or offline via `tasks db mint-token`; the raw value is shown **once** at mint time (only a hash is stored) and revoked via the `/me` UI, `DELETE /me/tokens/:id`, or `tasks logout`. Sessions come from OIDC (`/auth/login` → provider → `/auth/callback`, protected by PKCE + state), are sealed-box-encrypted with `SESSION_COOKIE_SECRET`, and expire after 8h. The CLI and remote MCP client send the PAT as `Authorization: Bearer`. Full detail: [SECURITY.md → Authentication Architecture](SECURITY.md#authentication-architecture).
 
 ### ⚠️ Authentication is NOT authorization — every identity is admin
 
 **Read this before exposing the service to anything but trusted callers.**
 
 - **Authentication ≠ authorization.** The auth chain only *identifies* the caller; it does **not** scope what they may do.
-- **Every authenticated identity is effectively an admin.** Any valid credential — PAT, OIDC session, or legacy `X-API-Key` — can read, write, and delete **every** task, project, comment, and dependency across **every** project in the database.
+- **Every authenticated identity is effectively an admin.** Any valid credential — PAT or OIDC session — can read, write, and delete **every** task, project, comment, and dependency across **every** project in the database.
 - **There is NO RBAC, NO ACL, and NO per-project / per-tenant isolation.** These are not implemented; scoped/role-based permissions are tracked only as future work.
 - **Do NOT expose this service on a public network, and do NOT run it multi-tenant, without an external authorization layer** (e.g. an authenticating reverse proxy that enforces its own per-tenant access control in front of the API). Treat any issued credential as full admin access to all data.
 
-### Legacy `X-API-Key` is still supported (PAT / OIDC preferred)
+### Legacy `X-API-Key` was removed in v2.0
 
-The legacy `X-API-Key` strategy **still works today** — it is strategy #3 in the live auth chain (`src/api/plugins/auth/index.ts`), and `API_KEYS` is currently a **required** env var (see Configuration), so every deployment has at least one working key. It is marked **deprecated as of v1.6**: PAT and OIDC sessions are the preferred credentials going forward, but legacy keys have **not** been removed. Legacy-authed responses carry advisory RFC 8594 `Deprecation: true` + `Sunset: <LEGACY_AUTH_SUNSET_DATE>` headers (operator-controlled, default `2026-12-31`) and emit a `legacy_auth_used` warn log so operators can track migration progress. New deployments should issue **PATs** — one per machine/agent, so you can revoke an individual token without disturbing others — or use OIDC sessions. The `API_KEYS` env accepts a comma-separated list of `key` or `key:label` entries (the label surfaces in audit logs as `apiKeyLabel`; the raw key is never logged). See [SECURITY.md → Legacy Auth Sunset Timeline](SECURITY.md#legacy-auth-sunset-timeline) and `tasks db migrate-identities` for the planned migration path.
+The legacy `X-API-Key` shared-secret strategy was **removed entirely in v2.0** (`src/api/plugins/auth/index.ts` no longer accepts it). A request carrying only `X-API-Key` now gets **401**. `API_KEYS` is no longer an auth method and is **not** a required env var — it is not in the Zod env schema. If set, it only (optionally) seeds inert legacy `users` rows (`is_legacy=1`) for display/back-reference; those rows hold no usable credential. Every deployment must now issue **PATs** — one per machine/agent, so you can revoke an individual token without disturbing others — or use OIDC sessions. PATs are minted from a `/me` web session or offline via `tasks db mint-token`. See [SECURITY.md → Authentication Architecture](SECURITY.md#authentication-architecture) and `tasks db migrate-identities` for the migration path off legacy keys.
 
 ### Defense in depth
 
@@ -210,7 +209,7 @@ flowchart TB
   end
 
   subgraph guards[Auth and validation]
-    Auth[auth plugin<br/>X-API-Key]
+    Auth[auth plugin<br/>Bearer PAT / session]
     RL[Rate limiter<br/>RATE_LIMIT_*]
     Zod[Zod schemas<br/>request/response]
   end
@@ -237,7 +236,7 @@ flowchart TB
   end
 
   HumanCLI --> CLI
-  HTTPAgent -->|HTTP + X-API-Key| REST
+  HTTPAgent -->|HTTP + Bearer PAT| REST
   ClaudeMCP -->|stdio JSON-RPC| MCP
   SlackUser -->|Socket Mode| Slack
 
@@ -281,9 +280,9 @@ flowchart TB
 
 | Interface | Access Method | Transport | Auth |
 |-----------|--------------|-----------|------|
-| REST API | HTTP endpoints | Port 3000 (configurable) | PAT (`Authorization: Bearer`), session cookie, or legacy `X-API-Key` |
-| CLI | `tasks` command | HTTP to API server (most cmds); direct SQLite for offline ops (`backup`, `doctor`, `stats`, `db-check`, `completed`) | `API_KEY` env var (accepts a PAT or legacy key) |
-| MCP Server | stdio JSON-RPC (local) or HTTP (remote variant) | MCP client integration | None for stdio (local access); Bearer PAT or `X-API-Key` for remote |
+| REST API | HTTP endpoints | Port 3000 (configurable) | PAT (`Authorization: Bearer`) or OIDC session cookie |
+| CLI | `tasks` command | HTTP to API server (most cmds); direct SQLite for offline ops (`backup`, `doctor`, `stats`, `db-check`, `completed`) | `API_KEY` env var (holds a PAT, sent as `Authorization: Bearer`) |
+| MCP Server | stdio JSON-RPC (local) or HTTP (remote variant) | MCP client integration | None for stdio (local access); Bearer PAT for remote |
 | Slack subprocess | Slack Socket Mode | WebSocket to Slack | Slack signing secret + bot token |
 
 All entry points share the same TypeScript services
@@ -341,7 +340,7 @@ The `priority` enum is **augmented, not replaced**, by WSJF: once a project has
 
 ## API Summary
 
-All `/api/v1` endpoints require authentication — a PAT (`Authorization: Bearer wft_pat_…`), an OIDC session cookie, or a legacy `X-API-Key` header (deprecated). `GET /health` is public; the OIDC sign-in flow lives under `/auth/*` (outside `/api/v1`).
+All `/api/v1` endpoints require authentication — a PAT (`Authorization: Bearer wft_pat_…`) or an OIDC session cookie. `GET /health` is public; the OIDC sign-in flow lives under `/auth/*` (outside `/api/v1`).
 
 Base URL: `http://localhost:3000`
 
@@ -417,14 +416,14 @@ The OIDC/session/PAT surface backing the auth model lives partly outside the tas
 | GET | /auth/callback | OIDC redirect callback → sets the session cookie |
 | POST | /auth/logout | Revoke the active PAT and clear the session |
 | GET | /auth/error | OIDC/session error landing page (session-expiry, 403 destinations) |
-| GET | /api/v1/me | Current authenticated user's profile (accepts session, PAT, or legacy auth) |
+| GET | /api/v1/me | Current authenticated user's profile (accepts PAT or session) |
 | GET | /api/v1/me/tokens | List the caller's personal access tokens |
 | DELETE | /api/v1/me/tokens/active | Revoke the caller's currently-active token |
 | DELETE | /api/v1/me/tokens/:id | Revoke a personal access token by ID |
 
 A device-authorization flow under `/auth/device*` (`GET /auth/device`, `POST /auth/device/code`, `POST /auth/device/token`, `POST /auth/device/verify`) supports headless PAT minting. When OIDC is **not** configured, the `/auth/*` and `/auth/device/*` routes are replaced by disabled-stub handlers (HTTP 501), so they exist in both modes but only one set is live per instance. When `SESSION_COOKIE_SECRET` is set, top-level HTML web routes (`GET /login`, `GET /me`, `GET /me/tokens`, `POST /me/tokens/:id/revoke`) are also served for the browser sign-in UI.
 
-This brings the full registered surface to **47 route handlers** under `src/api/routes/` — derived by counting `fastify.<verb>(` / `server.<verb>(` registrations across the route files (excluding tests). A single running instance serves up to **40** of them: the 7 OIDC-disabled stub handlers are mutually exclusive with the 8 live OIDC `/auth/*` routes.
+This brings the full registered surface to **52 route handlers** under `src/api/routes/` — derived by counting `fastify.<verb>(` / `server.<verb>(` registrations across the route files (excluding tests). A single running instance serves up to **45** of them: the 7 OIDC-disabled stub handlers are mutually exclusive with the live OIDC `/auth/*` routes.
 
 For detailed API documentation including request/response schemas, see [docs/API.md](docs/API.md).
 
@@ -627,15 +626,15 @@ Wood Fired Tasks streams real-time task and project change notifications via Ser
 
 ```bash
 # Subscribe to all events
-curl -N -H "X-API-Key: your-key" \
+curl -N -H "Authorization: Bearer wft_pat_<your-pat>" \
   http://localhost:3000/api/v1/events
 
 # Filter by project
-curl -N -H "X-API-Key: your-key" \
+curl -N -H "Authorization: Bearer wft_pat_<your-pat>" \
   "http://localhost:3000/api/v1/events?project_id=1"
 
 # Filter by event type
-curl -N -H "X-API-Key: your-key" \
+curl -N -H "Authorization: Bearer wft_pat_<your-pat>" \
   "http://localhost:3000/api/v1/events?event_types=task.created,task.claimed"
 ```
 
@@ -644,7 +643,7 @@ curl -N -H "X-API-Key: your-key" \
 Include `Last-Event-ID` header to resume from where you left off:
 
 ```bash
-curl -N -H "X-API-Key: your-key" \
+curl -N -H "Authorization: Bearer wft_pat_<your-pat>" \
   -H "Last-Event-ID: 42" \
   http://localhost:3000/api/v1/events
 ```
@@ -658,13 +657,13 @@ Multiple agents can race to claim the same task. Exactly one wins; the rest rece
 ```bash
 # Claim a task
 curl -X POST http://localhost:3000/api/v1/tasks/42/claim \
-  -H "X-API-Key: your-key" \
+  -H "Authorization: Bearer wft_pat_<your-pat>" \
   -H "Content-Type: application/json" \
   -d '{"assignee": "agent-1"}'
 
 # With idempotency key (safe to retry)
 curl -X POST http://localhost:3000/api/v1/tasks/42/claim \
-  -H "X-API-Key: your-key" \
+  -H "Authorization: Bearer wft_pat_<your-pat>" \
   -H "X-Idempotency-Key: unique-key-123" \
   -H "Content-Type: application/json" \
   -d '{"assignee": "agent-1"}'
@@ -710,10 +709,10 @@ The four WSJF MCP tools (`wsjf_ranking`, `wsjf_history`, `rescore_project`, `wsj
 |----------|-------------|---------|
 | PORT | HTTP server port | 3000 |
 | HOST | HTTP server host. Defaults to loopback only; set to `0.0.0.0` (or a specific LAN IP) to expose on the network. | 127.0.0.1 |
-| API_KEYS | Comma-separated legacy API keys (`key` or `key:label`). **Required** — the Zod config schema rejects an empty/unset value (`src/config/env.ts`), so the server exits with code 78 (`EX_CONFIG`) at startup when it is missing. There is no "auth-disabled" mode. | (required — no default) |
+| API_KEYS | Optional, legacy-only. **Not an auth method and not required** — it is not in the Zod config schema. If set (comma-separated `key` or `key:label`), it only seeds inert legacy `users` rows (`is_legacy=1`) for display/back-reference; those rows carry no usable credential. Auth is PAT (Bearer) or OIDC session. | (optional — no default) |
 | LOG_LEVEL | Logging level (debug, info, warn, error) | info |
 | NODE_ENV | Environment (development, production) | (none) |
-| DATABASE_PATH | Path to SQLite database file (canonical; MCP server also accepts legacy `DB_PATH`) | ./data/tasks.db |
+| DATABASE_PATH | Path to SQLite database file (canonical; MCP server also accepts legacy `DB_PATH`). Resolution precedence: explicit `DATABASE_PATH` > legacy `./data/tasks.db` auto-adopt (used with a one-time warning when `DATABASE_PATH` is unset, a legacy `./data/tasks.db` exists, and the app-data DB does not) > OS app-data default. | OS app-data dir — `~/.local/share/wood-fired-tasks/tasks.db` (Linux), `~/Library/Application Support/wood-fired-tasks/tasks.db` (macOS), `%APPDATA%\wood-fired-tasks\tasks.db` (Windows) |
 | API_BASE_URL | Base URL for CLI API calls | http://localhost:3000 |
 | API_KEY | API key for CLI authentication | (none) |
 | SLACK_BOT_TOKEN / SLACK_APP_TOKEN / SLACK_SIGNING_SECRET | Optional Slack integration (all three required together) — see [docs/SLACK.md](docs/SLACK.md) | (none) |
@@ -733,7 +732,7 @@ variables) lives in [docs/SETUP.md → Environment Variables](docs/SETUP.md#envi
 # Development mode with hot reload
 npm run dev
 
-# Run tests (2640 tests across 204 files)
+# Run tests (~2600+ tests)
 npm test
 
 # Watch mode for tests
@@ -771,7 +770,7 @@ SQLite with better-sqlite3 driver, WAL mode, and automatic migrations via Umzug.
 
 ### Testing
 
-2640 tests across 204 test files covering:
+~2600+ tests covering:
 - Service layer unit tests
 - API route integration tests (all endpoints)
 - MCP tool tests (all tools)

package/SECURITY.md

@@ -76,7 +76,7 @@ We will:
 Issues we will prioritize include, but are not limited to:
 
 - Authentication bypass on any endpoint — reaching a `/api/v1` route
-  without a valid PAT, session, or `X-API-Key` credential, or bypassing
+  without a valid PAT or session credential, or bypassing
   the SSE auth path. (Note: there is no separate authorization layer to
   bypass — see "Authentication Is Not Authorization" below. Any valid
   credential is already full-access.)
@@ -102,7 +102,7 @@ Thank you for helping keep wood-fired-tasks and its users safe.
 
 ## Authentication Architecture
 
-As of v1.6, the REST API supports three authentication strategies, tried
+As of v2.0, the REST API supports two authentication strategies, tried
 in order by a Fastify chain plugin (`src/api/plugins/auth/index.ts`). The
 first strategy that produces a valid `request.user` wins; the request
 proceeds with that user's id stamped onto every write (`created_by_user_id`,
@@ -113,11 +113,10 @@ log (`user_id`, `token_id`, `auth_method`).
 |-------|----------|------------|-------------|
 | 1 | **PAT (Personal Access Token)** | A token row in `api_tokens` | `Authorization: Bearer wft_pat_<…>` |
 | 2 | **Session** | An OIDC-derived sealed-box session cookie | `Cookie: wft_session=<…>` |
-| 3 | **Legacy** | An entry in the `API_KEYS` env list | `X-API-Key: <…>` |
 
-The three strategies coexist intentionally — legacy keeps existing
-deployments running while operators migrate; PAT is the recommended
-machine credential; session is the recommended user credential.
+PAT is the recommended machine credential; session is the recommended
+user credential. (The legacy `X-API-Key` shared-secret strategy was
+**removed in v2.0** — see [Legacy `X-API-Key` Status — Removed in v2.0](#legacy-x-api-key-status--removed-in-v20) below.)
 
 ### PAT lifecycle
 
@@ -147,10 +146,10 @@ for hygiene:
   the PAT auth strategy: once `expires_at` is in the past the token fails
   with `reasonCode: expired`.
 
-The PAT prefix (`wft_pat_`) is part of the wire format: the remote MCP
-server and the CLI HTTP client switch their auth header based on the
-prefix, so the same env var (`WFT_API_KEY` for MCP, `API_KEY` for CLI)
-transparently accepts a PAT or a legacy key.
+The PAT prefix (`wft_pat_`) is part of the wire format. The remote MCP
+server and the CLI HTTP client read the PAT from their respective env var
+(`WFT_API_KEY` for MCP, `API_KEY` for CLI) and send it as
+`Authorization: Bearer <pat>`.
 
 ### Session lifecycle
 
@@ -192,9 +191,7 @@ Every authenticated request emits a structured pino log line carrying:
   guarantees they exist).
 - `token_id` — the `api_tokens.id` when strategy=PAT; NULL
   otherwise.
-- `auth_method` — one of `pat`, `session`, `legacy`.
-- `apiKeyLabel` — the human-friendly label for legacy keys, e.g.
-  `key_alice-laptop`. Absent for PAT / session.
+- `auth_method` — one of `pat`, `session`.
 
 Failures emit a counterpart `tag: auth.failure` line with a coarse
 `reasonCode` (`missing_credential`, `unknown_token`, `revoked_token`, …)
@@ -202,66 +199,32 @@ so secret values never appear in logs. The `auth-audit` helper enforces
 this — it is the **only** sanctioned way for the auth plugin to
 log into the request.
 
-## Legacy `X-API-Key` Status
-
-The legacy `X-API-Key` strategy is **deprecated but still fully
-supported as of v1.11.** It remains the third link in the auth chain
-(`src/api/plugins/auth/index.ts` walks PAT → session → legacy), so a
-request carrying a valid `API_KEYS` entry still authenticates and
-mutates data. PAT and OIDC session are the preferred credentials; legacy
-keys exist to keep older deployments running while operators migrate.
-
-There is **no scheduled removal version.** Earlier drafts of this
-document described a "v1.7 sunset" that would drop `API_KEYS` support —
-that never happened. v1.7 through v1.11 shipped with the legacy strategy
-intact, and no removal date is currently committed.
-
-Legacy authentication is surfaced so operators can track migration
-progress, not blocked:
-
-- Every legacy-authed REST response carries two RFC 8594 headers:
-
-  ```
-  Deprecation: true
-  Sunset: 2026-12-31
-  ```
-
-  The `Sunset` value comes from the `LEGACY_AUTH_SUNSET_DATE` env var
-  (default `2026-12-31`, must be `YYYY-MM-DD`). It is an advisory
-  migration target, **not** an enforced cutoff — the strategy keeps
-  working past that date. PAT-authed and session-authed requests carry
-  **neither** header.
-
-- Every legacy-authed request also emits a `warn`-level log line:
-
-  ```json
-  {
-    "level": 40,
-    "event": "legacy_auth_used",
-    "userId": 1,
-    "apiKeyLabel": "key_alice-laptop",
-    "requestId": "…",
-    "requestUrl": "/api/v1/tasks",
-    "sunset": "2026-12-31"
-  }
-  ```
-
-  Aggregate `legacy_auth_used` over a rolling window to gauge migration
-  readiness — a steady decline to zero means clients have all moved to
-  PAT or session. New deployments should issue PATs (one per
-  machine/agent) or use OIDC sessions rather than `API_KEYS`.
-
-If a future release does remove the legacy strategy, the
+## Legacy `X-API-Key` Status — Removed in v2.0
+
+The legacy `X-API-Key` shared-secret strategy was **removed entirely in
+v2.0.** The auth chain (`src/api/plugins/auth/index.ts`) now walks only
+PAT → session; a request carrying only an `X-API-Key` header gets **401**.
+There is no "auth-disabled" mode and no shared-secret fallback.
+
+`API_KEYS` is **no longer an auth method and is no longer a required env
+var** — it is not in the Zod config schema (`src/config/env.ts`). If set,
+it is read only as an optional seed for inert legacy `users` rows
+(`is_legacy=1`) so historical identities still render; those rows carry
+**no usable credential** and cannot authenticate a request.
+
+Every deployment must now authenticate with a per-user **PAT** (one per
+machine/agent, individually revocable) or an **OIDC session**. The
 `tasks db migrate-identities` tool (idempotent; backfills identity FKs
-for historical rows that carry only the legacy TEXT identity columns)
-is the supported pre-upgrade step. It is safe to run today.
+for historical rows that carry only the legacy TEXT identity columns) is
+the supported step to fold pre-identity data forward; it is safe to run
+at any time.
 
 ## CORS
 
 The REST API **does not register a CORS plugin** — there is no
 `@fastify/cors` (or equivalent) registration anywhere in `src/api/`, and
 `cors` is not a project dependency. This is intentional: the API is built
-for server-to-server and agent traffic (PAT / `X-API-Key` in headers),
+for server-to-server and agent traffic (PAT in the `Authorization: Bearer` header),
 plus a same-origin browser surface (`/auth/*`, `/me`, `/login`) that does
 not need cross-origin access. With no `Access-Control-Allow-Origin`
 header emitted, browsers block cross-origin reads of API responses by
@@ -283,7 +246,7 @@ default.
 Authentication identifies the caller; it does **not** scope what the
 caller may do. Wood Fired Tasks has **no RBAC, no ACL, and no tenant /
 project isolation.** Every authenticated identity — whether it arrived
-via PAT, OIDC session, or a legacy `X-API-Key` — is effectively an
+via PAT or OIDC session — is effectively an
 admin: it can read, write, and delete **every** task, project, comment,
 dependency, and Slack subscription across **every** project in the
 database. The `--scopes` minted onto a PAT are advisory metadata only and

package/dist/api/plugins/auth/index.d.ts

@@ -2,7 +2,9 @@
  * Phase 28 (Plan 28-04) — unified auth chain plugin.
  *
  * Replaces the legacy single-strategy plugin at `src/api/plugins/auth.ts`
- * with a three-strategy chain (PAT → session-stub → legacy API_KEYS). The
+ * with a two-strategy chain (PAT → session). The legacy X-API-Key strategy
+ * was removed in the v2.0 auth cutover (Phase 0, task #799); a request that
+ * bears only an X-API-Key header now falls through to the catch-all 401. The
  * file at `src/api/plugins/auth.ts` survives as a thin re-export shim so
  * existing `import authPlugin from './plugins/auth.js'` callers (server.ts,
  * auth-logging.test.ts) keep working without churn.
@@ -11,28 +13,24 @@
  *   1. Decorate `FastifyRequest` with `user`, `authMethod`, `tokenId`,
  *      `apiKeyLabel` at plugin load (Fastify requires decoration before any
  *      route registers).
- *   2. Validate `process.env.API_KEYS` in production (throws synchronously,
- *      which Fastify bubbles up to createServer → exits with non-zero).
- *   3. Pre-compute SHA-256 hashes of every configured API_KEYS entry once
- *      at register time; feed the result into the legacy strategy on every
- *      request so it never re-hashes.
- *   4. Register a `preHandler` hook that:
+ *   2. Register a `preHandler` hook that:
  *      a. Short-circuits when `request.routeOptions.config.skipAuth === true`.
- *      b. Walks PAT → session-stub → legacy. First match wins. PAT failure
- *         does NOT fall through to legacy — see `enforceSessionOnly` /
- *         strategy-fail short-circuit below.
+ *      b. Walks PAT → session. First match wins. PAT failure does NOT fall
+ *         through to session — see `enforceSessionOnly` / strategy-fail
+ *         short-circuit below.
  *      c. On a successful match, populates `request.user`, `request.authMethod`,
- *         `request.tokenId` (and `request.apiKeyLabel` for legacy), re-childs
- *         the request logger with `{ user_id, token_id, auth_method,
- *         apiKeyLabel }` so every downstream log line carries audit fields,
- *         and enforces `config.sessionOnly` post-auth.
+ *         `request.tokenId`, re-childs the request logger with
+ *         `{ user_id, token_id, auth_method, apiKeyLabel }` so every
+ *         downstream log line carries audit fields, and enforces
+ *         `config.sessionOnly` post-auth.
  *      d. On a strategy `fail` outcome, emits one `auth.failure` warn log via
  *         the Phase 27 `logAuthFailure` helper and returns a uniform 401
  *         (the distinct `reasonCode` lives ONLY in the audit log — never in
  *         the response body).
  *      e. On total fall-through (every strategy returned `skip`), emits a
  *         catch-all `auth.failure` log tagged `strategy: 'legacy'`,
- *         `reasonCode: 'missing_credential'` (per Plan-04 Decision Q6).
+ *         `reasonCode: 'missing_credential'` (the tag name is retained for
+ *         audit-feed continuity even though the legacy strategy is gone).
  *
  * Side-effect contracts:
  *   - PAT match schedules `setImmediate(() => apiTokenRepository.touchLastUsed(

package/dist/api/plugins/auth/index.js

@@ -1,10 +1,7 @@
 import fp from 'fastify-plugin';
-import { parseApiKeyEntries, config } from '../../../config/env.js';
-import { validateApiKeysForProduction } from './keys.js';
 import { logAuthFailure } from '../../../services/auth-audit.js';
 import { tryAuth as tryPat } from './strategies/pat.js';
 import { tryAuth as trySession } from './strategies/session.js';
-import { tryAuth as tryLegacy, precomputeHashedEntries } from './strategies/legacy.js';
 import { shouldTouchLastUsed } from '../../../services/pat-touch-debounce.js';
 /**
  * Throws if `preHandler` has not run yet (or if `skipAuth` was set). Use in
@@ -151,20 +148,16 @@ function sendInternalError(request, reply, err) {
     reply.code(500).send({ error: 'INTERNAL_ERROR' });
 }
 const authChainImpl = async (fastify) => {
-    // Parse and (in production) validate API_KEYS at register time so a
-    // misconfigured prod boot fails fast. Same fail-fast semantics as the
-    // pre-split plugin — `validateApiKeysForProduction` throws synchronously
-    // and Fastify bubbles the error up to createServer which closes the
-    // server and disposes the App (server.ts:345-363 catch).
-    const entries = parseApiKeyEntries(process.env['API_KEYS']);
-    const keys = entries.map((e) => e.key);
-    if (process.env['NODE_ENV'] === 'production') {
-        validateApiKeysForProduction(keys);
-    }
-    else if (entries.length === 0) {
-        fastify.log.warn('No API keys configured in API_KEYS env var. All API requests will be rejected.');
-    }
-    const hashedEntries = precomputeHashedEntries(entries);
+    // v2.0 auth cutover (#799/#801): the legacy X-API-Key REST strategy was
+    // removed — REST authenticates via PAT → session only. `API_KEYS` no longer
+    // gates REST access, so the old production fatal gate
+    // (`validateApiKeysForProduction`, which threw on an empty/unset API_KEYS and
+    // aborted boot) is dead and was actively hostile to upgraders who correctly
+    // dropped API_KEYS. It is removed here. A server with no users still boots
+    // and serves OIDC/PAT auth. (`parseApiKeyEntries` survives because the MCP
+    // stdio actor-resolution path still matches a legacy WFT_API_KEY against
+    // API_KEYS — see src/mcp/identity-resolution.ts — but that is an MCP concern,
+    // not a REST boot gate.)
     // Decorators MUST land before any route registers in this scope. The fp()
     // wrap below lifts these into the parent scope so sibling /api/v1/* routes
     // see populated slots after a successful preHandler run.
@@ -224,64 +217,18 @@ const authChainImpl = async (fastify) => {
                     return;
                 return;
             }
-            // 3. Legacy API_KEYS
-            const legacyOutcome = await tryLegacy(request, {
-                userRepository: fastify.userRepository,
-                hashedEntries,
-            });
-            if (legacyOutcome.kind === 'fail') {
-                return sendUnauthorized(request, reply, 'legacy', legacyOutcome.reasonCode);
-            }
-            if (legacyOutcome.kind === 'match') {
-                applyPrincipal(request, legacyOutcome.result, legacyOutcome.label);
-                // Plan 31-05 (MIGR-02): emit one warn log per legacy-authed request
-                // so operators can grep their log feed for sunset-readiness reporting
-                // (`event: 'legacy_auth_used'`). The onSend hook below stamps the
-                // RFC 8594 Deprecation/Sunset headers; this line is the canonical
-                // audit signal — the headers are advisory to the client, the log
-                // is the operator-side source of truth.
-                request.log.warn({
-                    event: 'legacy_auth_used',
-                    userId: legacyOutcome.result.user.id,
-                    apiKeyLabel: legacyOutcome.label,
-                    requestId: request.id,
-                    requestUrl: request.url,
-                    sunset: config.LEGACY_AUTH_SUNSET_DATE,
-                }, 'legacy_auth_used');
-                if (enforceSessionOnly(request, reply))
-                    return;
-                return;
-            }
-            // 4. Catch-all — no strategy saw a credential. Per Plan-04 Decision
-            // Q6, the audit log records `strategy: 'legacy', reasonCode:
-            // 'missing_credential'` so the failure mode matches the pre-split
-            // plugin's "missing X-API-Key" branch.
+            // 3. Catch-all — no strategy saw a credential (the legacy X-API-Key
+            // strategy was removed in the v2.0 auth cutover, Phase 0). A request
+            // bearing only an X-API-Key header and no PAT/session now falls
+            // through to here and receives a uniform 401. The audit log records
+            // `strategy: 'legacy', reasonCode: 'missing_credential'` so the
+            // failure mode still classifies as a missing-credential event.
             return sendUnauthorized(request, reply, 'legacy', 'missing_credential');
         }
         catch (err) {
             return sendInternalError(request, reply, err);
         }
     });
-    // Plan 31-05 (MIGR-02): RFC 8594 Deprecation + Sunset response headers
-    // for every legacy-X-API-Key-authed request. Gated strictly on
-    // `request.authMethod === 'legacy'` so PAT, session, anonymous (skipAuth),
-    // and failed-auth responses NEVER carry the headers (Pitfall 4 in
-    // 31-RESEARCH §Common Pitfalls).
-    //
-    // Callback-style (4-arg) signature is used INTENTIONALLY rather than async
-    // — registering an async onSend hook inside this fp()-wrapped plugin
-    // delays `reply.sent` from becoming true synchronously when the preHandler
-    // calls `reply.send()` (e.g. from `enforceSessionOnly`'s 403). The
-    // me-tokens session-only tests then see the route handler run after the
-    // 403 reply was queued. The synchronous callback form keeps reply.send()
-    // synchronous, preserving the Phase 28 sessionOnly invariant.
-    fastify.addHook('onSend', (request, reply, payload, done) => {
-        if (request.authMethod === 'legacy') {
-            reply.header('Deprecation', 'true');
-            reply.header('Sunset', config.LEGACY_AUTH_SUNSET_DATE);
-        }
-        done(null, payload);
-    });
 };
 /**
  * Wrap with fastify-plugin to escape the encapsulated scope. Without `fp()`