feat: add scoped agent timekeeping API

[ECWireless]

Summary

• add the minimal agent_api_keys credential table and owner-authorized create, rotate, revoke, and metadata operations
• generate one-time ttk_v1 bearer keys while storing only SHA-256 secret hashes
• add the four /api/agent/v1 tree, child-creation, and timer operations
• enforce the selected node dynamic subtree inside the same transaction as credential revalidation and mutation
• return only allowlisted, non-cacheable JSON representations with stable safe errors
• preserve existing node lifecycle, inherited-rate snapshots, timer history, and deletion invariants

Why

This gives coding agents a narrow capability for reading one authorized node subtree, selecting or creating a session node, and recording repeated work intervals without granting access to parent, sibling, financial, or historical data.

Security and data integrity

• plaintext keys are returned only by successful creation or rotation and are never stored
• invalid secrets are rejected before the lock-heavy path, while the credential is locked and verified again for rotation and revocation linearization
• owner, ordered node, credential, and timer locks use a consistent order across dashboard and agent operations
• client-generated node IDs provide replay-safe creation without another table
• request bodies are bounded, numeric UTC offsets are rejected in favor of named IANA zones, and deep legal trees use iterative traversal

Verification

• pnpm db:check
• pnpm lint
• pnpm typecheck
• pnpm test — 102 tests passed
• pnpm test:integration — 89 tests passed
• pnpm build
• technical/data-integrity and security/privacy independent reviews for both commit units and the integrated PR diff

Scope

This PR is backend-only. The dashboard connection dialog and generated Codex harness setup remain in the next PR. The agreed single live end-to-end verification remains deferred until that UI/setup work is complete.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
timetree	Ready	Preview, Comment	Jul 23, 2026 3:54pm

[Copilot]

Pull request overview

This PR introduces a new backend-only, scope-limited “agent” API that can read a single authorized node subtree, create a child session node, and start/stop timers, backed by a new agent_api_keys credential table that stores only SHA-256 secret hashes.

Changes:

• Added agent_api_keys storage + server-side services for creating/rotating/revoking agent credentials and authorizing requests via ttk_v1 bearer keys.
• Added /api/agent/v1 routes for fetching the scoped tree, creating child nodes, and starting/stopping timers with bounded JSON parsing + stable error responses.
• Added unit + integration coverage for subtree ordering, time-zone handling, schema constraints, request validation/error behavior, and concurrency/locking races.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/agent-tree.test.ts	Unit tests for deterministic, iterative depth-first ordering of scoped subtrees.
tests/unit/agent-time-zone.test.ts	Unit tests for IANA time zone validation + deriving work dates from timestamps.
tests/integration/schema.test.ts	Integration assertions for new agent_api_keys constraints (uniqueness, FK ownership, hash check).
tests/integration/agent-api.test.ts	End-to-end integration tests for agent tree, node creation, and timer operations + safe responses.
tests/integration/agent-api-races.test.ts	Integration tests covering rotation/revocation/move/delete races against agent operations.
tests/integration/agent-api-keys.test.ts	Integration tests for key generation/parsing, persistence (hash-only), metadata, and cascade behavior.
tests/integration/agent-api-key-actions.test.ts	Integration tests for session-authorized key management server actions and owner boundaries.
src/lib/server/timer-service.ts	Refactors timer stop logic into reusable locked helpers; aligns lock ordering with node locks.
src/lib/server/node-service.ts	Exposes NodeTransaction/lockOwnerNodes/getSubtreeIds; locks agent credentials during deletion.
src/lib/server/agent-api-service.ts	Implements scoped agent tree response, child creation, and timer start/stop operations.
src/lib/server/agent-api-keys.ts	Session-authorized metadata lookup wrapper for dashboard/server usage.
src/lib/server/agent-api-key-token.ts	Implements ttk_v1 token generation, strict parsing, hashing, and constant-time secret verification.
src/lib/server/agent-api-key-service.ts	Implements create/rotate/revoke/metadata flows with node locking + linearization.
src/lib/server/agent-api-http.ts	Adds bounded JSON buffering/parsing and uniform no-store JSON success/error responses.
src/lib/server/agent-api-errors.ts	Defines typed agent API error container used by the HTTP wrapper.
src/lib/server/agent-api-authorization.ts	Implements two-phase credential verification + transactional scope/node locking and allowlist enforcement.
src/lib/agent/tree.ts	Adds iterative preorder ordering for scoped nodes with sibling ordering by position.
src/lib/agent/time-zone.ts	Adds IANA time zone validation and ISO8601 calendar date derivation.
src/lib/agent/contracts.ts	Defines agent API request/response and error contract types.
src/db/schema.ts	Adds agentApiKeys table schema, constraints, FK ownership, and exports in schema.
src/app/api/agent/v1/tree/route.ts	Adds GET route for returning the scoped tree with no-store JSON responses.
src/app/api/agent/v1/nodes/route.ts	Adds POST route for creating/replaying scoped child nodes with strict validation.
src/app/api/agent/v1/nodes/[nodeId]/timer/route.ts	Adds PUT/DELETE routes for starting/stopping scoped timers with time zone validation.
src/app/actions/agent-api-keys.ts	Adds server actions for create/rotate/revoke with session authorization and structured failures.
drizzle/meta/0002_snapshot.json	Drizzle snapshot update reflecting the new agent_api_keys table and constraints.
drizzle/meta/_journal.json	Drizzle journal entry for migration 0002_normal_korg.
drizzle/0002_normal_korg.sql	SQL migration creating agent_api_keys and adding FK ownership constraint.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.