# 0006 — API auth and LLM agent architecture

Date: 2026-07-03
Status: accepted (2026-07-04)

## Context

P1 needs a documented HTTP API with token auth coexisting with OIDC session auth, plus a provider-agnostic OpenAI-compatible agent that tool-calls the API. Tasks 87 (API surface) and 88 (agent chat) depend on these choices. Gitea: [#14](https://gitea.ginnoir.com/ginnoir/famapp/issues/14) (epic [#13](https://gitea.ginnoir.com/ginnoir/famapp/issues/13)).

Existing auth: Authentik OIDC via Auth.js, database sessions, household-scoped data via `getCurrentSession()`. Mutations today are server actions; a handful of route handlers exist under `/api/` for uploads, SSE, and auth.

## What we decided (2026-07-04)

| #   | Topic              | Choice                                                                                              |
| --- | ------------------ | --------------------------------------------------------------------------------------------------- |
| 1   | API token model    | **One shared household token** (not per-user)                                                       |
| 1b  | Token management   | **Household owner only** — create, revoke, view last-used                                           |
| 2   | API shape          | **REST JSON under `/api/v1/`** — additive versioning                                                |
| 3   | LLM provider       | **Env-configured OpenAI-compatible endpoint** (`LLM_BASE_URL`, optional `LLM_API_KEY`, `LLM_MODEL`) |
| 4   | Agent → API wiring | **Direct tools** (JSON-schema tools → HTTP calls). **No MCP server** in v1                          |

## Decision

### Token auth (coexists with OIDC session)

- Add a single **household-scoped API token** stored hashed in the database (`household_api_tokens` or equivalent).
- Non-browser clients send `Authorization: Bearer <token>`.
- `/api/v1/*` route handlers accept **either** a valid Auth.js session cookie **or** a valid household bearer token. Both resolve to the same household scope and permission checks.
- **OIDC / browser login is unchanged.** Middleware continues to guard pages; API routes perform their own auth (session or bearer).
- Token lifecycle UI on `/settings` (owner only): create (show raw token once), revoke, last-used timestamp.
- Activity log for API mutations may attribute `actorId` from session when present; bearer-token calls use `actorId = null` (same pattern as share-link anonymous mutations).

### API shape

- **REST** resources under `/api/v1/` with JSON request/response bodies.
- **Additive versioning**: new modules (journal, etc.) add routes under `/api/v1/` without breaking existing clients. No v2 until a breaking change is unavoidable.
- Task 87 covers: calendars, events, lists, list items, notes, garden (plants + containers), bangs. Dashboards deferred unless needed.
- **OpenAPI** spec committed as living docs (`docs/api/openapi.yaml` or generated from route definitions).
- Handlers call the same module server queries/actions as the web app — no parallel business logic.

### LLM provider (task 88)

- Famapp does **not** host a model. The agent client points at an external **OpenAI-compatible** HTTP API configured via environment variables.
- Compatible with Ollama, vLLM, LiteLLM proxy, or any `/v1/chat/completions`-style endpoint on the homelab.
- CI uses a **mock/stub provider** — no live LLM calls in tests.

### Agent tool-calling (task 88)

- **Direct tools**: the in-app agent defines tool schemas (name, description, parameters) that map to `/api/v1/` HTTP methods. The agent loop calls the API with the household bearer token.
- **No MCP server** in v1. Revisit if famapp needs to be a tool provider for Cursor or other MCP clients later.

## Consequences

### Positive

- One token to configure for scripts, wife's automations, and the agent — simple for a two-user household.
- REST + OpenAPI gives predictable integration and straightforward tool schema generation.
- Session and bearer auth share household scope; web app behavior unchanged.
- Direct tools avoid MCP transport, extra processes, and protocol overhead.

### Trade-offs

- Shared token: revoking it disables all non-browser clients at once; no per-person revocation.
- Bearer calls lack a user `actorId` in activity log unless we add optional token metadata later.
- Direct tools couple agent definitions to famapp's HTTP API; external MCP consumers would need a separate effort.

### Implementation notes (task 87)

- Schema: `household_api_tokens` with `household_id`, `token_hash`, `name` (e.g. "default"), `last_used_at`, `created_by` (owner), `revoked_at`.
- Middleware: exempt `/api/v1/` from session redirect; handlers enforce auth.
- Settings: owner-only card for token create/revoke.
- Tests: Vitest for bearer auth resolution, 401/403 paths, and representative CRUD handlers.

## References

- Task briefs: `docs/tasks/87-api-surface.md`, `docs/tasks/88-llm-agent-chat.md`
- Design: `docs/superpowers/specs/2026-07-03-backlog-triage-design.md`