Human accounts, event webhooks, claim recommendations, and test coverage

- Human accounts: signup/login/dashboard with session auth, X-Human-Key header
  for API claiming, POST /agents/claim, auto-claim on POST /agents
- Event webhooks: fire-and-forget POST to calendar webhook_url on event CRUD,
  HMAC-SHA256 signing via webhook_secret, POST /calendars/:id/webhook/test
- Claim recommendations: GET /man and GET /changelog suggest unclaimed agents
  with events should be claimed by a human account
- Docs: split "Feeds & Webhooks" into "Feeds & Inbound Email" + "Event Webhooks",
  clarified inbound email vs event webhook terminology throughout
- Tests: 19 new tests covering human auth flow, POST /agents/claim, calendar
  view (GET /view), webhook test endpoint; helpers now support custom headers
- Docker: NODE_ENV passthrough in docker-compose for test rate limit bypass

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: plc

CALDAVE_SPEC.md

@@ -69,16 +69,19 @@ Agents need to know when it's time to act. Two mechanisms:
 
 **Polling (primary):** Agents call `GET /calendars/:id/upcoming` to check what's next. Simple, stateless, works with any agent framework.
 
-**Webhooks (optional, per-calendar):** A calendar can register a webhook URL. CalDave sends a POST to that URL at configurable offsets before an event starts (e.g. 5 minutes before). Webhook delivery uses a simple retry policy (3 attempts, exponential backoff).
+**Webhooks (optional, per-calendar):** A calendar can register a webhook URL. CalDave sends a POST to that URL whenever events are created, updated, deleted, or responded to — whether via the API or inbound email. Payloads are signed with HMAC-SHA256 if a `webhook_secret` is set. Delivery is fire-and-forget.
 
 ---
 
 ## Auth Model
 
 | Concept | Details |
 |---------|---------|
-| **API Key** | Bearer token, one per agent. Sent as `Authorization: Bearer <key>` |
+| **Agent API Key** | Bearer token, one per agent. Sent as `Authorization: Bearer sk_live_...` |
+| **Human API Key** | One per human account. Passed as `X-Human-Key` header for claiming agents. |
 | **Provisioning** | `POST /agents` returns `agent_id` + `api_key`. Agent must store these — the key is shown once. |
+| **Human Accounts** | Humans sign up at `/signup` to get a dashboard and human API key (`hk_live_...`). |
+| **Agent Claiming** | Humans claim agents by providing the agent's `sk_live_` key — via dashboard or `POST /agents/claim` with `human_key`. |
 | **Scoping** | An API key grants access to all calendars owned by that agent. No cross-agent access. |
 
 ---
@@ -88,7 +91,12 @@ Agents need to know when it's time to act. Two mechanisms:
 ### Agent Provisioning
 
 #### `POST /agents`
-Creates a new agent identity. No auth required. Optionally accepts `name` and `description` to identify the agent.
+Creates a new agent identity. No auth required. Optionally accepts `name` and `description` to identify the agent. Pass the `X-Human-Key` header to associate with a human account.
+
+**Headers (optional):**
+| Header | Description |
+|--------|-------------|
+| `X-Human-Key` | Human API key (`hk_live_...`) to auto-associate the new agent |
 
 **Request (optional):**
 ```json
@@ -105,7 +113,35 @@ Creates a new agent identity. No auth required. Optionally accepts `name` and `d
   "api_key": "sk_live_abc123...",
   "name": "My Assistant",
   "description": "Manages team calendars and sends meeting reminders",
-  "message": "Store these credentials securely. The API key will not be shown again."
+  "message": "Store these credentials securely. The API key will not be shown again.",
+  "owned_by": "hum_abc123..."
+}
+```
+
+The `owned_by` field only appears when `X-Human-Key` header is provided.
+
+#### `POST /agents/claim`
+Claim an existing agent by providing its API key. Requires `X-Human-Key` header.
+
+**Headers:**
+| Header | Description |
+|--------|-------------|
+| `X-Human-Key` | **Required.** Human API key (`hk_live_...`) |
+
+**Request:**
+```json
+{
+  "api_key": "sk_live_abc123..."
+}
+```
+
+**Response:**
+```json
+{
+  "agent_id": "agt_x7y8z9",
+  "agent_name": "My Assistant",
+  "claimed": true,
+  "owned_by": "hum_abc123..."
 }
 ```
 
@@ -444,26 +480,29 @@ Set or update webhook configuration:
 }
 ```
 
-**Webhook payload (POST to the registered URL):**
+#### Webhook Event Types
+
+When a calendar has a `webhook_url` configured, CalDave automatically delivers a webhook POST whenever events change — via the API or inbound email.
+
+| Type | Trigger |
+|------|---------|
+| `event.created` | New event via POST or inbound email |
+| `event.updated` | Event modified via PATCH or inbound email update |
+| `event.deleted` | Event deleted via DELETE or inbound email CANCEL |
+| `event.responded` | Event accepted/declined/tentative via POST respond |
+
+**Payload:**
 ```json
 {
-  "type": "event.upcoming",
-  "calendar_id": "cal_a1b2c3",
-  "event": { ... },
-  "fires_at": "2025-02-15T08:55:00-07:00",
-  "offset": "-5m",
-  "signature": "sha256=..."
+  "type": "event.created",
+  "calendar_id": "cal_...",
+  "event_id": "evt_...",
+  "event": { "id": "evt_...", "title": "Meeting", ... },
+  "timestamp": "2026-02-17T12:00:00.000Z"
 }
 ```
 
-Signature is HMAC-SHA256 of the body using `webhook_secret`.
-
-#### `GET /calendars/:id/webhook-logs`
-List webhook delivery attempts for a calendar. Supports query params:
-- `status` — filter by `pending` / `delivered` / `failed`
-- `limit` / `offset` — pagination
-
-Useful for debugging failed deliveries.
+If `webhook_secret` is set, the payload is signed with HMAC-SHA256 and sent in the `X-CalDave-Signature` header. Delivery is fire-and-forget (no retries). Use `POST /calendars/:id/webhook/test` to verify your endpoint.
 
 ---
 
@@ -477,9 +516,9 @@ Read-only iCalendar feed. Can be subscribed to from Google Calendar, Apple Calen
 ### Inbound Email
 
 #### `POST /inbound/:token`
-Per-calendar webhook endpoint for receiving forwarded emails containing `.ics` calendar invite attachments.
+Per-calendar endpoint for receiving forwarded emails containing `.ics` calendar invite attachments. Creates, updates, or cancels events based on the iCal METHOD.
 
-No Bearer auth. The unguessable `inbound_token` in the URL authenticates the request. Each calendar gets its own unique webhook URL (returned at creation as `inbound_webhook_url`).
+No Bearer auth. The unguessable `inbound_token` in the URL authenticates the request. Each calendar gets its own unique inbound URL (returned at creation as `inbound_webhook_url`).
 
 Supports multiple email-to-webhook providers:
 - **Postmark Inbound** — attachments include base64 content inline in the webhook payload
@@ -691,18 +730,32 @@ For local development or offline use, run the STDIO server directly:
 - `calendars(email)` — for inbound email lookup
 - `calendars(inbound_token)` — partial index for webhook URL lookup
 
-### `webhook_deliveries`
+### `humans`
 | Column | Type | Notes |
 |--------|------|-------|
-| `id` | `text` PK | `whd_` prefixed |
-| `calendar_id` | `text` FK | |
-| `event_id` | `text` FK | |
-| `offset` | `text` | e.g. `-5m` |
-| `status` | `text` | `pending` / `delivered` / `failed` |
-| `attempts` | `integer` | Number of delivery attempts |
-| `last_attempt_at` | `timestamptz` | |
-| `response_status` | `integer` | HTTP status from webhook target |
-| `error` | `text` | Nullable, error message on failure |
+| `id` | `text` PK | `hum_` prefixed |
+| `name` | `text` | |
+| `email` | `text` UNIQUE | Case-insensitive index on `LOWER(email)` |
+| `password_hash` | `text` | bcryptjs, 12 salt rounds |
+| `api_key_hash` | `text` | SHA-256 hash of the human API key (`hk_live_...`) |
+| `created_at` | `timestamptz` | |
+
+### `human_agents`
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `text` PK | `ha_` prefixed |
+| `human_id` | `text` FK | → humans(id) CASCADE |
+| `agent_id` | `text` FK | → agents(id) CASCADE |
+| `claimed_at` | `timestamptz` | |
+
+UNIQUE(human_id, agent_id)
+
+### `human_sessions`
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `text` PK | `sess_` prefixed |
+| `human_id` | `text` FK | → humans(id) CASCADE |
+| `expires_at` | `timestamptz` | 7-day expiry, cleaned up hourly |
 | `created_at` | `timestamptz` | |
 
 ---
@@ -748,7 +801,7 @@ Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-R
 
 1. **Agent provisioning auth** — Open, no operator key. Rate-limited (see Rate Limits section).
 2. **Feed authentication** — Token required. Feed URLs include a token param: `/feeds/:calendar_id.ics?token=feed_abc123`. Token is generated at calendar creation and returned in the response.
-3. **Webhook logs** — Failed deliveries are queryable via `GET /calendars/:id/webhook-logs`.
+3. **Webhook delivery** — Fire-and-forget on event mutations. Use `POST /calendars/:id/webhook/test` to verify endpoint reachability.
 4. **Domain** — `caldave.ai` for v1. Email addresses: `cal-abc123@caldave.ai`.
 5. **Event size limits** — 64KB for description, 16KB for metadata JSON.
 6. **Outbound email** — Implemented. Creating/updating events with attendees sends METHOD:REQUEST invite emails via Postmark. Responding to inbound invites sends METHOD:REPLY emails to the organiser. Requires `POSTMARK_SERVER_TOKEN` env var; gracefully skipped if not set.
@@ -758,7 +811,6 @@ Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-R
 
 ## Out of Scope (v1)
 
-- Web UI / dashboard
 - Calendar sharing between agents
 - Attachments on events
 - Free/busy lookups

CHANGELOG.md

@@ -7,6 +7,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
+- **Webhook delivery on event mutations** — Calendars with a `webhook_url` now receive automatic webhooks when events are created, updated, deleted, or responded to. Works for both API operations and inbound email invites. Event types: `event.created`, `event.updated`, `event.deleted`, `event.responded`. Payloads are signed with HMAC-SHA256 if `webhook_secret` is set. Delivery is fire-and-forget (no retries).
+- **Human accounts with agent key claiming** — Humans can sign up at `/signup`, log in at `/login`, and manage their agent keys from a `/dashboard`. Agents are claimed by providing the agent's secret key (`sk_live_...`) — if you have the key, you own it. No calendar invites needed.
+  - **Human API keys** (`hk_live_...`) — pass via `X-Human-Key` header to `POST /agents` to auto-associate new agents, or to `POST /agents/claim` to claim existing agents programmatically.
+  - **Dashboard** — web UI to view claimed agents, claim new ones by pasting a secret key, and release agents.
+  - **Session auth** — cookie-based sessions for the dashboard (7-day expiry, automatic cleanup).
+  - New tables: `humans`, `human_agents`, `human_sessions`.
+
 - **MCP server at full parity with API** — Added 16 new MCP tools covering all documented API endpoints. Previously the MCP server only had 8 core tools; it now exposes 24 tools matching every REST endpoint:
   - **Agent management**: `caldave_get_agent`, `caldave_update_agent`
   - **SMTP configuration**: `caldave_set_smtp`, `caldave_get_smtp`, `caldave_delete_smtp`, `caldave_test_smtp`
@@ -48,7 +55,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Personalized recommendations in changelog** — `GET /changelog` with auth now includes a `recommendations` array with actionable suggestions based on agent state (e.g. name your agent, create your first calendar, add a description).
 - **API changelog endpoint** — `GET /changelog` returns a structured list of API changes with dates and docs links. With optional Bearer auth, highlights changes introduced since the agent was created. Designed for agents to poll ~weekly.
 - **Agent metadata** — `POST /agents` now accepts optional `name` and `description` fields to identify agents. New `GET /agents/me` returns the agent's profile. New `PATCH /agents` updates metadata without changing the API key. Agent name and description are surfaced in `GET /man` context.
-- **Outbound calendar invites** — when an event is created or updated with attendees, CalDave sends METHOD:REQUEST iCal invite emails via Postmark. Invites include `.ics` attachments that work with Google Calendar, Outlook, and Apple Calendar. From address is the calendar's email so replies route back through the inbound webhook.
+- **Outbound calendar invites** — when an event is created or updated with attendees, CalDave sends METHOD:REQUEST iCal invite emails via Postmark. Invites include `.ics` attachments that work with Google Calendar, Outlook, and Apple Calendar. From address is the calendar's email so replies route back through inbound email.
 - **Agent name in outbound emails** — when an agent has a name set (via `PATCH /agents`), outbound invite and RSVP reply emails use `"Agent Name" <calendar-email>` as the From address, so recipients see a friendly display name instead of just the calendar email.
 - **Outbound RSVP replies** — when an agent responds to an inbound invite via `POST /respond`, CalDave sends a METHOD:REPLY iCal email back to the organiser with the agent's acceptance, decline, or tentative status.
 - **Graceful degradation** — if `POSTMARK_SERVER_TOKEN` is not set, outbound emails are silently skipped. All API endpoints continue to work normally.
@@ -111,8 +118,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - Uses `rrule` npm package for RRULE parsing and expansion
 - **API documentation page** (`GET /docs`) — self-contained HTML docs with curl examples for every endpoint, copy buttons, quick start guide, and dark theme matching the status page
 - Full API spec in `CALDAVE_SPEC.md`
-- **Inbound email support** — receive calendar invites via per-calendar webhook URLs
-  - `POST /inbound/:token` — unique webhook URL per calendar (token in URL authenticates)
+- **Inbound email support** — receive calendar invites via per-calendar inbound URLs
+  - `POST /inbound/:token` — unique inbound URL per calendar (token in URL authenticates)
   - Each calendar gets an `inbound_webhook_url` returned at creation and in GET responses
   - Parses `.ics` attachments from inbound emails using `node-ical`
   - Creates events with `source: inbound_email`, `status: tentative`
@@ -134,7 +141,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Rate limiting** — replaced stub headers with real enforcement via `express-rate-limit` (200/min API, 5/hour agent creation, 60/min inbound webhooks)
 - **Security headers** — added `helmet` middleware (X-Content-Type-Options, X-Frame-Options, HSTS, CSP, etc.)
 - **Request body size limit** — explicit 512KB limit on `express.json()` to prevent oversized payloads
-- **Inbound webhook token hardening** — invalid tokens now return 200 (not 404) to prevent token validity enumeration
+- **Inbound token hardening** — invalid tokens now return 200 (not 404) to prevent token validity enumeration
 - **RRULE frequency restriction** — reject `FREQ=SECONDLY` and `FREQ=MINUTELY` (expansion blocks event loop for 18s+)
 - **init-db.sh SQL quoting** — `CREATE DATABASE` now uses quoted identifier to prevent SQL injection via `DB_NAME`
 - **Input validation** — length limits on calendar name (255), timezone (64), event title (500), location (500); webhook URL format validation
@@ -151,7 +158,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Schema uses `CREATE TABLE IF NOT EXISTS` — no migration tool needed for v1
 - nanoid (v5) used for all ID generation with alphanumeric alphabet
 - API keys use SHA-256 (not bcrypt) for deterministic lookup by hash
-- Webhook columns exist in schema but webhook delivery is deferred
+- Webhook delivery fires on all event mutations (event.created, event.updated, event.deleted, event.responded)
 - Port 3720 generated from `get-port.sh caldave`
 
 ---

SPEC.md

@@ -27,7 +27,16 @@ fly deploy
 | `GET /` | No | Status page |
 | `GET /health` | No | Server health check |
 | `GET /health/db` | No | Database health check |
-| `POST /agents` | No | Create agent (returns API key) |
+| `POST /agents` | No (optional `X-Human-Key`) | Create agent (returns API key). With human key, auto-claims. |
+| `POST /agents/claim` | `X-Human-Key` | Claim an existing agent by providing its `sk_live_` key |
+| `GET /signup` | No | Human account signup page |
+| `POST /signup` | No | Create human account |
+| `GET /login` | No | Human account login page |
+| `POST /login` | No | Authenticate human |
+| `POST /logout` | Cookie | Log out (clear session) |
+| `GET /dashboard` | Cookie | Dashboard — manage claimed agents |
+| `POST /dashboard/claim` | Cookie | Claim agent via dashboard |
+| `POST /dashboard/agents/:id/release` | Cookie | Release agent ownership |
 | `GET /man` | Optional | Machine-readable API manual (JSON), personalized if authenticated |
 | `POST /calendars` | Yes | Create calendar |
 | `GET /calendars` | Yes | List agent's calendars |
@@ -61,10 +70,14 @@ src/
 │   ├── outbound.js       — Outbound email (iCal invite/reply generation, Postmark sending)
 │   └── recurrence.js     — RRULE parsing, materialization, horizon management
 ├── middleware/
-│   ├── auth.js           — Bearer token auth
-│   └── rateLimitStub.js  — Stub rate limit headers
+│   ├── auth.js           — Bearer token auth (agents)
+│   ├── humanAuth.js      — Session cookie + X-Human-Key auth (humans)
+│   └── rateLimit.js      — Rate limiting (express-rate-limit)
+├── lib/
+│   ├── passwords.js      — bcryptjs password hashing
 └── routes/
-    ├── agents.js         — POST /agents
+    ├── agents.js         — POST /agents, POST /agents/claim
+    ├── humans.js         — Signup, login, dashboard, claim, release
     ├── man.js            — GET /man (machine-readable API manual)
     ├── calendars.js      — Calendar CRUD
     ├── events.js         — Event CRUD + upcoming + respond
@@ -78,7 +91,7 @@ scripts/
 
 ## Database Schema
 
-Five tables: `agents`, `calendars`, `events`, `postmark_webhooks`, `error_log`. Schema auto-created on startup.
+Eight tables: `agents`, `calendars`, `events`, `postmark_webhooks`, `error_log`, `humans`, `human_agents`, `human_sessions`. Schema auto-created on startup.
 
 See `CALDAVE_SPEC.md` for full column definitions.
 
@@ -117,14 +130,14 @@ Events can be created with `all_day: true`. When set:
 
 ## Auth Model
 
-- API keys: `sk_live_` prefix + 32 alphanumeric chars
-- Stored as SHA-256 hash (direct DB lookup, no iteration)
+- **Agent API keys**: `sk_live_` prefix + 32 alphanumeric chars, SHA-256 hashed
+- **Human API keys**: `hk_live_` prefix + 32 alphanumeric chars, SHA-256 hashed
+- **Human sessions**: `sess_` prefix + 32 chars, cookie-based (7-day expiry)
+- **Human passwords**: bcryptjs with 12 salt rounds
 - Agent scoping: each agent only sees their own calendars/events
+- Human-agent ownership: humans claim agents by providing the agent's secret key
 
 ## Deferred
 
 - DST-aware recurrence (times currently repeat at same UTC offset, may drift ±1h across DST)
 - iCal feed with RRULE + EXDATE (currently emits individual VEVENTs)
-- Webhooks / push notifications (pg-boss)
-- MCP tools
-- Real rate limiting (headers are stubbed)

docker-compose.yml

@@ -32,6 +32,7 @@ services:
     ports:
       - "${PORT:-3000}:${PORT:-3000}"
     environment:
+      - NODE_ENV=${NODE_ENV:-development}
       - DATABASE_URL=postgres://plc:postgres@host.docker.internal:5432/${DB_NAME:-caldave}
       - PORT=${PORT:-3000}
       - INBOUND_WEBHOOK_SECRET=${INBOUND_WEBHOOK_SECRET:-}

package.json

@@ -20,6 +20,8 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "bcryptjs": "^3.0.3",
+    "cookie-parser": "^1.4.7",
     "express": "^4.18.2",
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",