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; 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_SIGNUPSanyone can sign up. Otherwise only an address with an openorg_invitesrow can, or an admin creates the account. OnedatabaseHooks.user.create.beforegate 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_KEYset, better-auth’s captcha plugin asks for a passed Cloudflare Turnstile token, in thex-captcha-responseheader, onCAPTCHA_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 intest/api/captcha.test.ts. - Assurance level. The session carries
aal1oraal2. It is copied into the JWT and set asandon.aalfor the database (andon_private.mfa_satisfied()). A TOTP code, a backup code or a passkey makes anaal2session. 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 ataal1, and the same verify endpoint on that session steps it up. Once someone has a factor, managing factors needsaal2, so anaal1session 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 inandon_auth."user"with rolemachine, banned and with no account, so nobody can sign in as it, and every machine policy keeps readingauth_user_id = andon_auth.uid(). Its refresh token (andon_mrt_…) is stored as a SHA-256 hash inandon_private.machine_credentialsand rotated on every use at/api/machine/token. The next token is an HMAC of the one it replaces (a key derived fromANDON_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 withandon setup. A token rotated before this was HMAC-derived is answeredrefresh_token_reused, so the agent reloads its store. Access tokens are 15-minute HS256 JWTs with a key derived fromANDON_SECRET_KEY, audienceandon-machine, the identity assuband the machine asmid. 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_URLorANDON_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 429rate_limited. The client’s IP comes from Vercel’s headers, the socket on Node, orANDON_IP_HEADERSbehind 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:
- 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). - The allowlist. Tables, views, columns and functions come from
src/db/catalog.gen.ts, whichpnpm db:catalogreads from a migrated database: only whatandon_authenticatedorandon_anonwas granted. Embeds are the three insrc/db/embeds.ts, each on a named foreign key. - Compile (
src/query/compile.ts). The SQL text holds only fixed keywords,$nplaceholders 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. - Run (
src/query/run.ts) in one transaction:set local role andon_authenticated(orandon_anon), thenandon.uid,andon.role,andon.aal,andon.machine_id,andon.signed(thex-andon-signedheader),statement_timeout(15 s) andTimeZone(UTC), each withset_config(…, true). Row-level security decides the rows. Never a session-levelSETor a named prepared statement, so it works through transaction poolers. - 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 toandon_private.realtime_eventsand runsNOTIFY andon_rt, '<id>'. The table is unlogged. Events are pruned after 15 minutes, by the listener while one runs and by therealtime-prunetick otherwise. Broadcasts and presence changes are rows in the same table. - Listener. Each instance holds one
LISTENconnection (application_nameandon-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; thereadyevent 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: oneselect 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 andorg_id, and goes only to topics in its org. - Broadcast and presence. A POST writes an event row through
andon_private.realtime_sendorrealtime_track, which check the topic as the caller. A stream’s own broadcasts come back markedself. 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 withLast-Event-IDreplays 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 getsresync, and@andon/clientreportsSUBSCRIBEDagain so call sites reload. - Stream lifetime. A stream ends with an
endevent 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/clientreconnects at once. Apingevent goes out every 20 s, so a quiet stream’s nextLast-Event-IDis 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_terminalregistered for them, and never a machine’s control topic: they only send anopento 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_STORAGEpicks one; otherwises3whenS3_BUCKETis set,vercel-blobon Vercel, elsefs. Every driver keeps an object under<bucket>/<path>, and paths start<org_id>/.fs: files underANDON_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 byaws4fetch. One bucket (S3_BUCKET), keys underS3_PREFIX, path-style whenS3_ENDPOINTis set.vercel-blob: private Vercel Blob objects (BLOB_READ_WRITE_TOKEN, or OIDC withBLOB_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 needsinsert; overwriting,selectandupdate; removing,selectanddelete; 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 fromandon_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 fromANDON_SECRET_KEY). A week at most. - Objects are served with
nosniffand a sandboxing CSP, so an uploaded HTML or SVG file can’t run script on the server’s origin. A write whoseOriginisn’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.serviceis the owner (row-level security skipped,andon.role = 'service_role') overcatalog.service.gen.ts;ctx.user(req).clientis 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 (aGETfor the VAPID key), revoke-machine, start-work-plan, start-work-route, start-work-title, tracker-import and voice-session.mfa-recoveranswers 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 inandon_private.jobsand notifiesandon_jobs. The runner (jobs.ts) claims due rows withfor update skip lockedand 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 inandon_private.ticksin 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 aLISTEN andon_jobsconnection. On Vercel the work comes from three places, so don’t assume per-minute scheduling there:- Vercel Cron calls
/api/cron/tick(vercel-cron.tsbuilds the entry fromANDON_CRON, daily by default for the Hobby plan); - an agent’s
machine_heartbeatticks, at most every 15 s per instance; - a data API write or a function call starts a jobs drain.
- the former pg_cron jobs:
-
Voice: the token transport works everywhere; the
relayWebSocket (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.createServertakes 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-originandX-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.
