# The server

`apps/server` is Andon's backend, on any Postgres 15+: sign-in, a data API, live updates, file storage, the functions
and the scheduled work. Read this before you change it. Its routes, entry points
and tests are in [its README](https://github.com/psci-labs/andon/blob/main/apps/server/README.md); the schema side is in [`db/README.md`](https://github.com/psci-labs/andon/blob/main/db/README.md).

The functions live only here (`src/functions`); there is no Supabase copy to keep in step.

## Auth

The board uses better-auth's HttpOnly session cookie. Event streams and the agent send `Authorization: Bearer <JWT>`
(EdDSA, 15 minutes, from `/api/auth/token`). A token that doesn't verify is a 401, never a quiet fall back to `anon`.
`resolveCaller` in `src/auth/caller.ts` tries, in order: a machine's access token, a JWT, the session cookie (without
refreshing it), then `anon`.

- **Sign-ups.** With `ALLOW_SIGNUPS` anyone can sign up. Otherwise only an address with an open `org_invites` row can,
  or an admin creates the account. One `databaseHooks.user.create.before` gate covers password, email-code and social
  sign-ups. A refused sign-up gets the same reply as one that went through, so the reply never says whether an address
  has an invite.
- **Email confirmation.** A password account gets no session until the 6-digit code emailed at sign-up confirms the
  address (`/email-otp/verify-email`). A sign-in before that is refused and a new code is sent. A social sign-in needs
  an address its provider verified. A password reset signs every other session out.
- **Bot protection.** With `TURNSTILE_SECRET_KEY` set, better-auth's captcha plugin asks for a passed Cloudflare
  Turnstile token, in the `x-captcha-response` header, on `CAPTCHA_PATHS` (`src/auth/auth.ts`): sign-up, password
  sign-in and every endpoint that emails a code without a session. The plugin matches whole paths. A new endpoint
  that checks a password or emails a stranger goes in that list, with a case in `test/api/captcha.test.ts`.
- **Assurance level.** The session carries `aal1` or `aal2`. It is copied into the JWT and set as `andon.aal` for the
  database (`andon_private.mfa_satisfied()`). A TOTP code, a backup code or a passkey makes an `aal2` session.
  better-auth asks for the second factor only after a password sign-in, so an email-code or social sign-in of someone
  with two-factor starts at `aal1`, and the same verify endpoint on that session steps it up. Once someone has a
  factor, managing factors needs `aal2`, so an `aal1` session can't mint itself a way up. The deployment admin's
  `/admin/*` endpoints need it too.
- **Machines** (`src/auth/machines.ts`). Enrolling gives a machine an identity row in `andon_auth."user"` with role
  `machine`, banned and with no account, so nobody can sign in as it, and every machine policy keeps reading
  `auth_user_id = andon_auth.uid()`. Its refresh token (`andon_mrt_…`) is stored as a SHA-256 hash in
  `andon_private.machine_credentials` and rotated on every use at `/api/machine/token`. The next token is an HMAC of
  the one it replaces (a key derived from `ANDON_SECRET_KEY`), so until the new token is used the old one gets the
  same new one again: a refresh whose answer was lost (the network dropped mid-refresh, then the machine was away for
  any length of time) or two processes refreshing at once both end up with the current token. Once the new one is
  used the old one is refused, and the agent stops asking and says to re-enroll with `andon setup`. A token rotated
  before this was HMAC-derived is answered `refresh_token_reused`, so the agent reloads its store. Access
  tokens are 15-minute HS256 JWTs with a key derived from `ANDON_SECRET_KEY`, audience `andon-machine`, the identity as
  `sub` and the machine as `mid`. Revoking a machine stops it at once and ends its refresh token. A machine's token is
  never a person to the functions.
- **Cookie writes.** A write with the session cookie and no Authorization header must come from the board's origin
  (`ANDON_URL` or `ANDON_BOARD_ORIGINS`), else 403, and must be JSON, else 415, except a storage upload. Every body is
  limited to 1 MB before any route, tracker import to 7 MB, and a machine's repository memory sync
  (`machine_repo_memory_sync`, a clone's whole `.andon/` index in one call) to 16 MB.
- **Rate limits** are better-auth's, in memory per instance, stricter on sign-in, sign-up, email codes and two-factor.
  They reset on restart, so they are not a security boundary. Start Work's plan, route and title calls also have
  per-person and per-org limits in `fn_rate_hits` (`src/functions/shared/rate-limit.ts`); over them a call answers 429 `rate_limited`. The client's IP comes from Vercel's headers, the socket
  on Node, or `ANDON_IP_HEADERS` behind a proxy you trust.

## The data API

`@andon/client` turns supabase-js-shaped calls (`db.from(t).select('a, b:c, orgs(id)').eq(…).or('…')`) into a query
AST. Nothing else speaks to these routes. On the server:

1. The body must be JSON, at most 1 MB (16 MB for `machine_repo_memory_sync`) and 32 levels deep, and match the AST schema (`packages/shared/src/query-ast.ts`,
   zod, strict).
2. **The allowlist.** Tables, views, columns and functions come from `src/db/catalog.gen.ts`, which `pnpm db:catalog`
   reads from a migrated database: only what `andon_authenticated` or `andon_anon` was granted. Embeds are the three in
   `src/db/embeds.ts`, each on a named foreign key.
3. **Compile** (`src/query/compile.ts`). The SQL text holds only fixed keywords, `$n` placeholders and identifiers from
   the catalog. Values, JSON path keys, output names and LIKE patterns are always parameters, and casts come from a
   fixed list. Rows are built as JSON by Postgres, so values look the way PostgREST sends them.
4. **Run** (`src/query/run.ts`) in one transaction: `set local role andon_authenticated` (or `andon_anon`), then
   `andon.uid`, `andon.role`, `andon.aal`, `andon.machine_id`, `andon.signed` (the `x-andon-signed` header),
   `statement_timeout` (15 s) and `TimeZone` (UTC), each with `set_config(…, true)`. Row-level security decides the
   rows. Never a session-level `SET` or a named prepared statement, so it works through transaction poolers.
5. Errors keep PostgREST's shape (`{ code, message, details, hint }`) and status, so call sites written for supabase-js
   keep working.

The catalog can never grant more than the database does: it is a second fence, and row-level security is the real
control, because every statement runs as the caller's role.

What's supported is the subset the board and the agent use: column lists with aliases, casts and JSON paths; the three
embeds; `eq neq gt gte lt lte like ilike in is`, `not`, nested `and` and `or`; `order` (with `nullsFirst`), `limit`,
`range`; exact counts with or without rows; `single` and `maybeSingle`; `insert`, `upsert` (`onConflict`,
`ignoreDuplicates`), `update` and `delete`, with an optional returning list. Reads stop at 1000 rows (`ANDON_MAX_ROWS`),
like Supabase's PostgREST. Updates and deletes need a filter.

To add a shape: a new member of the AST union needs compiler support, a hostile-input test in the style of
`test/query/injection.test.ts`, and a test at the call site that uses it.

Known gaps: `offset` isn't clamped, `count: 'exact'` runs an unbounded `count(*)` under row-level security, and
`/api/db/*` has no rate limit.

## Live updates

Postgres is the bus, so several server instances need nothing extra (`src/realtime/`, `db/migrations/*_realtime.sql`;
the wire format is `packages/shared/src/realtime.ts`).

- **Source.** A trigger on each subscribed table (`andon_private.realtime_watch(table)` adds one) writes the change to
  `andon_private.realtime_events` and runs `NOTIFY andon_rt, '<id>'`. The table is unlogged. Events are pruned after 15
  minutes, by the listener while one runs and by the `realtime-prune` tick otherwise.
  Broadcasts and presence changes are rows in the same table.
- **Listener.** Each instance holds one `LISTEN` connection (`application_name` `andon-realtime`) on the direct URL,
  only while a stream is open. It closes 5 s after the last stream ends, so Neon's compute can suspend. It fetches the
  rows it is told about, and reconnects by itself, replaying from a little before its high-water mark, deduplicated by
  id.
- **Who hears what.** A stream joins only the topics `andon_private.can_join_topic(topic)` allows; the `ready` event
  says which. A table change goes to the subscriptions whose table, event and filter match, only for the org the topic
  names, and only after a row-level security check as that subscriber: one `select pk … where pk in (…)` per caller
  and table. A change to a row that is already gone, or no longer visible, is dropped. Columns members can't select are
  dropped. A delete carries only its key and `org_id`, and goes only to topics in its org.
- **Broadcast and presence.** A POST writes an event row through `andon_private.realtime_send` or `realtime_track`,
  which check the topic as the caller. A stream's own broadcasts come back marked `self`. Presence rows expire 30 s
  after their last refresh, and the client refreshes every 15 s.
- **Reconnects.** Every event's SSE id is `<epoch>.<id>`. A stream opened with `Last-Event-ID` replays from the table
  through the same check, starting 1000 ids early because ids can commit out of order. If the epoch changed (Postgres
  lost the unlogged table in a crash) or pruning passed the id, the stream gets `resync`, and `@andon/client` reports
  `SUBSCRIBED` again so call sites reload.
- **Stream lifetime.** A stream ends with an `end` event when its access token expires (15 minutes; a cookie stream
  after 15 minutes too) and, on Vercel, `ANDON_STREAM_MAX_SECONDS` (295) after it opened. `@andon/client` reconnects at
  once. A `ping` event goes out every 20 s, so a quiet stream's next `Last-Event-ID` is never one pruning has passed.
- A machine's stream joins its control topics, its runs' terminals and its delegations' threads.
- A person's stream joins a run's terminal topic only for a viewer `open_terminal` registered for them, and never a
  machine's control topic: they only send an `open` to it.

Topic access is checked when a stream subscribes. A removed member keeps getting broadcasts until the stream ends.

## Storage

`@andon/client`'s `db.storage.from(bucket)` keeps supabase-js' `upload`, `download`, `remove` and
`createSignedUrl(s)`.

- **Drivers** (`src/storage/`): `ANDON_STORAGE` picks one; otherwise `s3` when `S3_BUCKET` is set, `vercel-blob` on
  Vercel, else `fs`. Every driver keeps an object under `<bucket>/<path>`, and paths start `<org_id>/`.
  - `fs`: files under `ANDON_STORAGE_DIR` (default `.andon/storage`), written to a temporary file and renamed into place.
  - `s3`: AWS S3, R2, B2, MinIO or Supabase Storage's S3 endpoint, signed with SigV4 by `aws4fetch`. One bucket
    (`S3_BUCKET`), keys under `S3_PREFIX`, path-style when `S3_ENDPOINT` is set.
  - `vercel-blob`: private Vercel Blob objects (`BLOB_READ_WRITE_TOKEN`, or OIDC with `BLOB_STORE_ID`).
- **Who may do what** is the database's decision: `andon_private.can_access_object(bucket, path, op)`, the Supabase
  Storage policies ported into one function, asked under the caller's role. A new object needs `insert`; overwriting,
  `select` and `update`; removing, `select` and `delete`; reading and signing, `select`. A path someone can't read is a
  404, the same as a missing one. The service context skips the check.
- **Metadata** is a row in `andon_private.objects` (owner, size, type), claimed before the bytes are written, so two
  uploads of a new path can't both win. **Bucket rules** come from `andon_private.buckets`: a size limit (413) and
  allowed types (415).
- **Signed URLs**: S3 and Vercel Blob presigned GETs; for `fs`, the server's own HMAC token (`src/storage/signer.ts`, a
  key derived from `ANDON_SECRET_KEY`). A week at most.
- Objects are served with `nosniff` and a sandboxing CSP, so an uploaded HTML or SVG file can't run script on the
  server's origin. A write whose `Origin` isn't one of the board's is refused.
- **Limit:** uploads go through the server, and a Vercel function takes at most 4.5 MB per request. On Node the limit is
  the bucket's.

A new storage path starts `<org_id>/` and needs a rule in `can_access_object()`.

## Secrets

`src/secrets.ts` replaces Vault: `andon_private.secrets(org_id, name, key_id, nonce, ciphertext)`, AES-256-GCM with a
key derived from `ANDON_SECRET_KEY` (HKDF, its own label) and the secret's name as associated data, so a ciphertext
copied onto another name doesn't decrypt. The database never sees a plaintext. `key_id` names the key: to change
`ANDON_SECRET_KEY`, list the old one in `ANDON_SECRET_KEY_PREVIOUS`, run `andon-server rotate-secrets`, then remove it.
better-auth's JWT keys are encrypted with its own secret, derived from the same key.

Integration tokens and webhook secrets are kept here too. The functions' service client answers `integration_save`,
`integration_set_webhook_secret`, `integration_token` and `integration_webhook_secrets` itself
(`src/functions/secret-rpcs.ts`), because this database's `vault_put` raises.

## Functions, jobs and scheduled work

`src/functions/` runs the 31 functions that began as Supabase Edge Functions. Their pure logic is in
`src/functions/shared/` (tested in `test/functions/shared/`), and rules the board or the agent also need come from
`@andon/shared`. A handler reads config, not the environment, writes as the owner through `ctx.service`, acts as the
caller through `ctx.user(req)`, and defers work with `ctx.waitUntil`.

- **The database as a handler sees it** (`db.ts`): `@andon/client`'s shapes, run in-process through the same
  compiler. `ctx.service` is the owner (row-level security skipped, `andon.role = 'service_role'`) over
  `catalog.service.gen.ts`; `ctx.user(req).client` is the caller, over the data API's own allowlist and row-level
  security. A service-role handler must check team visibility itself.
- **Over HTTP** (`http-fns.ts`, `HTTP_FNS`, 22 functions at `/api/fn/<name>`): assistant, asana-webhook, capture,
  enroll-approve, enroll-poll, enroll-redeem, enroll-start, integration-secrets, invite-prepare, jira-import,
  linear-import, linear-webhook, links-resolve, mfa-recover, org-export, push-send (a `GET` for the VAPID key),
  revoke-machine, start-work-plan, start-work-route, start-work-title, tracker-import and voice-session. `mfa-recover`
  answers 410: recovery codes are better-auth's backup codes now. A call with the session cookie must be JSON; capture
  answers any origin without cookies.
- **Jobs** (`jobs-fns.ts`, `JOB_FNS`, 11 functions with no route): attention-triage, auto-build-plan, exports-prune,
  finish-classify, links-sync, links-writeback, org-purge, push-send, recipe-detect, tracker-import and
  webhooks-deliver. `andon_private.call_function(fn, body)` queues a row in `andon_private.jobs` and notifies
  `andon_jobs`. The runner (`jobs.ts`) claims due rows with `for update skip locked` and a 10-minute lease. It deletes a
  row whose handler answered below 500, and otherwise retries after 30 s, 2, 8 and 32 minutes, then an hour. After 6
  attempts the row stays as a dead letter (`dead = true`).
- **Scheduled work** (`scheduler.ts`, `db/migrations/*_run_due_ticks.sql`): `andon.run_due_ticks()` runs each due tick
  in `andon_private.ticks` in its own subtransaction, under an advisory lock. The ticks:
  - the former pg_cron jobs: `auto-build`, `exports-prune`, `links-sync`, `org-purge`, `outbox-prune`, `push`,
    `schedules`, `triage`, `usage-retry`;
  - `realtime-prune`;
  - added later: `auto-archive`, `cycles`, `memory-upkeep`, `webhooks`.

  Node runs it every `ANDON_TICK_MS` (15 s) and keeps a `LISTEN andon_jobs` connection. On Vercel the work comes from
  three places, so don't assume per-minute scheduling there:
  - Vercel Cron calls `/api/cron/tick` (`vercel-cron.ts` builds the entry from `ANDON_CRON`, daily by default for the
    Hobby plan);
  - an agent's `machine_heartbeat` ticks, at most every 15 s per instance;
  - a data API write or a function call starts a jobs drain.
- **Voice:** the token transport works everywhere; the `relay` WebSocket (`voice-relay.ts`) only on Node
  ([Voice providers](https://andon-docs.pages.dev/contributing/voice-providers.md)).
- **Storage as the service** (`ctx.service.storage`, no object check): capture's files, Linear images, the org export,
  purge and exports-prune.
- **Broadcasts** from a function are event rows the owner writes (`serviceBroadcast`), and enroll-poll and
  enroll-redeem issue the server's own machine tokens. `createServer` takes fakes for both in tests.

New background work needs both paths: the Node timer or `LISTEN`, and the Vercel cron and drain.

## Serving the board

On Node, the server serves the built board too (`src/board.ts`; `ANDON_BOARD_DIR`, else `apps/board/dist`). On Vercel
the CDN serves it (`vercel.ts`), and in Compose, Caddy sits in
front (`deploy/compose/Caddyfile`). All three send the same headers: hashed assets cached for a year, everything else
revalidated, and the board's security headers, `BOARD_SECURITY_HEADERS` in `src/board.ts`:

- a content security policy: scripts only from the board, Cloudflare Turnstile and `blob:` (voice's audio worklet),
  never inline; connections and frames to any https origin, since connected instances, previews, a machine's direct
  terminal and the voice relay are addresses known only at run time; plain http and ws only on this machine;
  `frame-ancestors 'none'`;
- `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` and `X-Frame-Options: DENY`.

`vercel.ts` can't import the constant (Vercel reads it without running it), so the policy is written out in each file,
and `src/board.test.ts` fails when one differs. A board change that loads something new from somewhere new needs the
policy changed in all four; the browser's console names what it refused.

One file is outside the policy: `/page-frame.html`, a page output's wrapper (`apps/board/src/lib/page-frame.ts`). A
frame's `srcdoc` inherits its parent's policy, so under the board's, a page's inline scripts wouldn't run. The wrapper
carries the page's own locked-down policy in a meta tag, and its headers say only the board may frame it.

The desktop app's own pages (the rail, the panel, the search bar) have their policy in
`apps/desktop/src-tauri/tauri.conf.json`; an instance's board, loaded from its own URL, gets the instance's headers.
