Skip to content
AndonDocs
GitHub
Change Andon

The server

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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; the schema side is in 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).

  • 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.