Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

docs: record the contracts the comments were inventing (#316)

OKNOTOKd0dbf160be65
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1208a61..eb561fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,22 +9,37 @@ project's [MIT License](LICENSE).
## Getting set up
-You need **Node ≥ 22** (CI runs on Node 24), plus **Postgres** and **Redis**
-running locally. Node 18 and 20 can no longer install the dependency tree —
-`@capacitor/cli` requires `node >= 22` and `@aws-sdk/client-s3` requires
-`node >= 20`.
+You need **Postgres** and **Redis** running locally. Node floors differ by
+artifact. The root `package.json` `engines` field is `>=20`, which is the
+install floor the production image proves. npm is not run with
+`engine-strict`, so a dependency's own engines field warns instead of
+failing `npm ci`.
+
+| Artifact | Node |
+| --- | --- |
+| Root `engines` | `>=20` |
+| CI typecheck, test, and deploy (`pr.yml`, `build.yml`, `deploy.yml`, `production-readback.yml`) | 24 |
+| `publish.yml` | 20 |
+| `server/docker/cumora-server.Dockerfile`, `server/docker/agent-computer.Dockerfile` | `node:20-bookworm-slim` |
+| `agent-cli/package.json` `engines` | `>=18` |
+| `@capacitor/cli` | `>=22` |
+
+Use Node 22 or newer for local app and mobile work. CI runs Node 24.
+Node 20 can install this tree — the server and agent images do it on every
+build. Node 18 is below the AWS SDK and Capacitor floors. Production images
+still run Node 20 while CI validates Node 24; those are different runtimes.
```bash
createdb -h localhost cumora
export OPENAI_API_KEY=sk-... # the only hard-required env var
-npm run setup # root + Email Worker dependencies
+npm run setup # root + email-gate + r2-gate dependencies
npm run dev:all # Vite renderer on :5180 + API server on :5181
```
Use `npm run setup` rather than a root-only `npm install`: the root test
-command also runs `workers/email-gate` tests, whose dependencies live in the
-Worker's separate `package.json`.
+command also runs `workers/email-gate` and `workers/r2-gate` tests, whose
+dependencies live in each worker's `package.json`.
Open http://localhost:5180 for the web app, or `npm run electron:dev` for the
desktop shell. Database migrations are applied via `npm run migrate` (run
@@ -33,7 +48,8 @@ sub2api LLM gateway) soft-disables when its env vars are unset — see
[`.env.example`](.env.example).
Component-specific setup lives in [`docs/`](docs/): `BYOA.md` (the local-engine
-daemon), `MOBILE_IOS.md`, `PUSH_NOTIFICATIONS.md`, `email.md`.
+daemon), `MOBILE_IOS.md`, `PUSH_NOTIFICATIONS.md`, `email.md`, `API.md`,
+`LIMITS.md`, `EGRESS.md`.
## Before you open a PR
@@ -69,12 +85,12 @@ rules are on; noisy or intentional-pattern style rules are off, while the a11y
rules are enforced incrementally (useButtonType, ARIA roles/props, and core
accessibility rules are active).
-Both TypeScript projects are `strict`. Tests live in four places, and
-`npm test` runs the first, third and fourth: `tests/` (frontend lib units),
-`server/src/__integration__` (integration, opt-in via the env var above),
-`server/src/__tests__` (server units), and `workers/email-gate/src`
-(Worker units — this is why you want `npm run setup` over a bare
-`npm install`).
+Both TypeScript projects are `strict`. Tests live in five places:
+`tests/` (frontend lib units), `server/src/__integration__` (integration,
+opt-in via the env var above), `server/src/__tests__` (server units),
+`workers/email-gate/src`, and `workers/r2-gate/src`. `npm test` runs all of
+those except integration. The worker glob is `workers/**/*.test.ts`, which
+is why `npm run setup` installs both workers instead of a bare `npm install`.
## Three architecture invariants (enforced in CI)
@@ -121,6 +137,46 @@ this project production time:
Transactional migrations that still lose a lock race are retried with backoff
before the Job fails, so a brief contention spike does not need a redeploy.
+`verifyRequiredIndexes` runs on every migration Job, including when nothing
+is pending. A name in `REQUIRED_SCHEMA_INDEXES` fails that Job if the index
+is missing or invalid. Several of those indexes are created only from the
+legacy baseline, so adding a name without a migration that builds it on
+databases already past version 1 blocks deploys, and nothing rebuilds it.
+Remove a name from the required list in the same commit that drops the
+index, and remove the name first. Do not drop
+`idx_conversations_members_gin` because an older comment mentioned a
+rollback window.
+
+`MIN_SUPPORTED_SCHEMA_VERSION` and `MAX_SUPPORTED_SCHEMA_VERSION` are both
+the manifest tip. Appending a migration moves the only schema this build
+will boot. The previous image then refuses the new ledger, so
+`kubectl rollout undo` is not a recovery plan for that deploy. See
+[`docs/RELEASE.md`](docs/RELEASE.md).
+
+Copy `server/src/db/migrations/0002-normalized-conversation-members.ts` when
+you add structure: it introduces the new table, names the foreign keys, and
+writes down `ON DELETE`. The checklist next to the files is
+[`server/src/db/migrations/README.md`](server/src/db/migrations/README.md).
+
+## Dependency advisories
+
+CI does not fail on `npm audit`. The deploy and benchmark workflows install
+with `--no-audit`. The repo has no Dependabot, Renovate, or CodeQL config.
+Until a gate exists, this is the process:
+
+- Before adding or upgrading a dependency, run `npm audit --omit=dev` in
+ the package you changed (the root, `agent-cli`, `workers/email-gate`, or
+ `workers/r2-gate`) and read advisories on packages you are introducing
+ or bumping.
+- In the PR, name each high or critical advisory you are not fixing: the
+ package, the advisory id, whether this repo can reach the vulnerable
+ code, who owns the exception, and the date it expires. Ninety days is
+ the default; say why if the window is different.
+- Do not add `--no-audit` or an audit override without that record.
+
+GitHub Actions in the existing workflows are referenced by tag. Changing
+that pin is a separate change; this policy does not require it.
+
The multi-agent coordination model (how N agents share a room without
colliding, and why the prompt is kept deliberately minimal) is documented in
[`docs/COORDINATION.md`](docs/COORDINATION.md) — read it before touching the
diff --git a/README.md b/README.md
index 1aa002c..227c0c9 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ Two "brain" paths:
```
- **Frontend** (`src/`) is pure UI: React 18 + Vite + TypeScript + Tailwind, with `desktop/`, `mobile/`, `web/`, and `admin/` shells over the same components.
-- **Backend** (`server/`) is a stateless Node service: Express + `ws`, Postgres as the source of truth (pg pool + Drizzle schema), Redis for pub/sub fan-out and presence. Durable board/document/calendar writes enqueue realtime invalidations in a transactional PostgreSQL outbox; Redis degradation delays live refresh but never changes the command result, and clients reconcile by pulling the API. Any number of instances can drain the outbox through leased `SKIP LOCKED` claims — see `server/src/realtime-outbox.ts`.
+- **Backend** (`server/`) is a stateless Node service: Express + `ws`, Postgres as the source of truth. Production DDL is the SQL in `server/src/db/migrate.ts` and `server/src/db/migrations/`; `server/src/db/schema.ts` is a partial Drizzle model and is not the schema. Redis is for pub/sub fan-out and presence. Durable board/document/calendar writes enqueue realtime invalidations in a transactional PostgreSQL outbox; Redis degradation delays live refresh but never changes the command result, and clients reconcile by pulling the API. Any number of instances can drain the outbox through leased `SKIP LOCKED` claims — see `server/src/realtime-outbox.ts`. Which other background jobs are safe on more than one replica is tabulated in [`server/k8s/gke.md`](server/k8s/gke.md). HTTP and WebSocket rules are in [`docs/API.md`](docs/API.md); ceilings are in [`docs/LIMITS.md`](docs/LIMITS.md); outbound fetches are in [`docs/EGRESS.md`](docs/EGRESS.md).
- **Agent runtime**: cloud agents live in per-agent Kubernetes pods (orchestrated via `kubectl` from the server; a Go FUSE driver mounts their server-side workspace); BYOA agents live wherever you run the daemon. Both act on the world through the same `cumora` CLI protocol, and every LLM call — cloud or BYOA — lands in one `llm_calls` cost ledger.
- **Coordination**: agents in the same room don't trample each other. The server arbitrates with a seen-cursor freshness gate (a stale reply is HELD and shown the newer messages to re-decide), atomic claims on real units of work, and a small-brain triage gate that shields the big model. Design notes in [`docs/COORDINATION.md`](docs/COORDINATION.md).
diff --git a/SECURITY.md b/SECURITY.md
index d65c581..0346a74 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -43,27 +43,52 @@ In scope — anything that lets someone:
Out of scope:
-- Findings that require a misconfigured self-hosted deployment the code
- actively warns against — e.g. running in production with a dev-default
- secret. The server refuses to boot in that state on purpose
- (`AGENT_RUNTIME_SECRET`); a report that assumes it was forced past that gate
- is a configuration issue, not a vulnerability.
-- Denial of service / volumetric abuse.
+- A production boot that was deliberately started with the public
+ dev-default `AGENT_RUNTIME_SECRET` after the startup check was bypassed.
+ That check runs only when `NODE_ENV === 'production'`
+ (`server/src/env.ts`). `NODE_ENV` defaults to `development`, and in that
+ mode the server does boot with the default. A report that the default
+ works outside production is describing the code, not a bypass.
+- Denial of service that is only volumetric flooding. An unauthenticated
+ endpoint that leaks data, forges a session, or crosses a tenant is in
+ scope under the bullets above. The server does not have a general HTTP
+ rate limit; that absence is not itself a vulnerability report.
- Reports from automated scanners without a demonstrated, exploitable impact.
- Social engineering, physical access, or attacks requiring a
compromised operator machine.
-## The trust model, in one paragraph
-
-The **server is the authorization boundary**. Every client — the web app, the
-Electron shell, the mobile shell, and the BYOA daemon — is untrusted and must
-have its input validated server-side. Agent identity on every `/runtime/*`
-call is pinned from a signed JWT, never from the request body. Tenants are
-isolated in SQL, not in the client. On a BYOA host, a second boundary protects
-the operator's machine: secure-default model tools are OS-sandboxed and receive
-neither the runtime JWT nor the daemon's environment/network authority. If you
-find a place where either boundary can be bypassed, that's a vulnerability we
-want to hear about.
+## Trust boundaries
+
+The **server is the authorization boundary** for the web app, the Electron
+shell, the mobile shell, and the BYOA daemon. Those clients are untrusted.
+Agent identity on every `/runtime/*` call is pinned from a signed JWT, never
+from the request body. Tenants are isolated in SQL, not in the client.
+
+On a **BYOA host**, a second boundary protects the operator's machine:
+secure-default model tools are OS-sandboxed and receive neither the runtime
+JWT nor the daemon's environment or network authority.
+
+The **cloud agent Pod is a weak boundary, on purpose**. Mounting FUSE on
+GKE's container-optimized OS needs `CAP_SYS_ADMIN` during bootstrap and
+leaves AppArmor unconfined for that phase. The long-running process is then
+dropped to uid 65532. Conversation content reaches a shell inside that Pod
+by design. What we want reported is a path from one tenant's agent to
+another tenant's Pod, data, or credentials, or a path from code in the Pod
+to the node or the control plane. The granted capabilities and the
+compensating controls are written down in
+[`server/k8s/gke.md`](server/k8s/gke.md) under "Agent policy and runtime
+security prerequisites".
+
+**Inbound email is not authenticated.** `workers/email-gate` accepts mail
+whose recipient domain is listed. It does not read `Authentication-Results`
+and does not check SPF, DKIM, or DMARC. The server then maps the `From:`
+header onto an agent or a human in the recipient's workspace. A spoofed
+`From:` can show up as an internal author and enter an agent's context.
+The HMAC on `/webhooks/email/inbound` authenticates the worker to the
+server. It says nothing about the sender. Details are in
+[`docs/email.md`](docs/email.md).
+
+A bypass of any of these boundaries is a vulnerability we want to hear about.
## Deploying Cumora securely
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..e8526c1
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,62 @@
+# HTTP and WebSocket contract
+
+There is no `/v1` prefix and no generated OpenAPI document. The machine-readable
+snapshot of the rules below is [`api-contract.json`](api-contract.json).
+Per-route request and response fields live in `src/api/client.ts` and
+`server/src/agents/runtime/client.ts`. Those TypeScript types are the schema.
+A test checks that `api-contract.json` names every `WsEvent` variant.
+
+## Authentication
+
+Human `/api/*` requests identify the caller with `Authorization: Bearer` or
+`x-session-token`. There is no cookie session. `authMiddleware` always calls
+`next()`; a handler that needs a user calls `requireAuth` or `requireCompany`
+itself. `requireCompany` falls back to the caller's oldest membership when
+`x-company-id` is absent or not one of theirs.
+
+`/runtime/*` is a different surface. The pod sends `Authorization: Bearer`
+with the agent-runtime JWT. Identity is taken from that token, not from the
+JSON body. It is mounted beside `/api`, not under it.
+
+`POST /webhooks/email/inbound` does not use either of those. It checks
+`x-cumora-signature` against `EMAIL_INBOUND_HMAC_SECRET`. The signature
+proves the worker sent the body. It does not prove who the `From:` header is.
+See [email.md](email.md).
+
+## Errors, pagination, idempotency
+
+Handlers that fail with `HttpError` respond `{ "error": "<message>" }` and
+an HTTP status. The process-level handler uses the same shape. That message
+is the server's text, not a stable error code.
+
+Pagination is not one vocabulary. Message history uses `before` (a sequence)
+and `limit`. Admin collections use `limit` and `offset` and return `total`.
+Other lists are unpaged. Clients must not assume a cursor field exists.
+
+Some creates accept a client `requestId` and store it in a partial unique
+index (`uniq_messages_client_id`, `uniq_participants_agent_creation_request`,
+`uniq_board_creation_request`, `uniq_document_creation_request`,
+`uniq_calendar_event_creation_request`). Those indexes are the idempotency
+mechanism. There is not one shared idempotency header.
+
+Numeric ceilings are in [LIMITS.md](LIMITS.md).
+
+## WebSocket
+
+The browser opens one socket per user, not per workspace. After the ticket
+handshake the server sends the frames below. Routed Redis events without a
+`companyId` are dropped. Delivery is then by user id
+(`resolveWsEventRecipientUserIds`), not by filtering the socket's company
+set. A connected user therefore receives frames for every workspace they
+belong to. The client `WsEvent` union records `companyId` only on
+`participants.added` (optional) and `workspace.membership`.
+
+`doc.sync`, `doc.update`, `doc.awareness`, and `doc.error` are per document
+subscription. The other variants are broadcast frames.
+
+## Daemon compatibility
+
+The BYOA daemon and this server are released from the same tree. There is
+no compatibility table that lets an older daemon speak a newer runtime.
+[BYOA.md](BYOA.md) describes the daemon's commands and endpoints; it is not
+a second schema.
diff --git a/docs/EGRESS.md b/docs/EGRESS.md
new file mode 100644
index 0000000..fbbe84e
--- /dev/null
+++ b/docs/EGRESS.md
@@ -0,0 +1,23 @@
+# Server egress
+
+The server does not have one shared HTTP client. Four call sites leave the
+process, and they do not enforce the same checks. There is no `guard-*.mjs`
+that fails CI when a fifth call site appears. This page is the contract each
+one actually implements.
+
+| Caller | Destination control | SSRF checks | Redirects | Bounds |
+| --- | --- | --- | --- | --- |
+| `server/src/og.ts` | Caller-supplied `http(s)` URL | DNS lookup, `BlockList`, connect to a resolved public address | Manual, each hop re-checked | 6s, 1 MB, 5 redirects, Redis cache |
+| `server/src/agents/image-fetcher.ts` `fetchImageBytes` | Caller-supplied image URL | Same shape as `og.ts`: reject the answer set if any address is non-public, then connect to a validated address | Manual, each hop re-checked | 5s, 10 MB, 5 redirects, content-type allowlist; failures are cached and dropped |
+| `server/src/agents/skills.ts` | Operator `SKILLHUB_URL` only. An agent cannot pass an install URL | None. No DNS or IP check | `redirect: 'error'` | 10s timeout; 100 files, 256 KB each |
+| `server/src/oauth.ts` `mirrorAvatar` | The URL returned by Google, GitHub, or a configured GitLab | None | `fetch` default | 5s, 2 MB, allowlisted image types. Failure returns the original URL |
+
+`router.ts` comments that centralizing fetches would let one place enforce
+size, time, and SSRF checks. That central client does not exist. New outbound
+calls should follow `og.ts` / `fetchImageBytes` unless the destination is an
+operator-configured base URL, and even then a redirect must not be able to
+leave that host.
+
+`mirrorAvatar` is the odd one out: the provider URL is not chosen by an
+end user today, and a failure must not block sign-in, but the fetch itself
+has no private-network check.
diff --git a/docs/I18N.md b/docs/I18N.md
index dc572e1..fae36f4 100644
--- a/docs/I18N.md
+++ b/docs/I18N.md
@@ -76,12 +76,16 @@ The picker itself needs no change; it renders from `LOCALES`.
## Current coverage
-The catalogue is fully mirrored: `zh-CN` carries every key `en` does, and
-every surface reads through `useT()` / `t()` — the conversation, board,
-calendar, document, agent and shipping views, the mobile screens, and the
-admin console included. Components that don't render text of their own
-(`Select`, `ContextMenu`, the peek panes) receive already-translated
-strings as props, so there is no hidden English inside them.
+`zh-CN` carries every key `en` does. UI copy is supposed to go through
+`useT()` / `t()`, including conversation, board, calendar, document, agent,
+shipping, mobile, and admin views. Components that don't render text of
+their own (`Select`, `ContextMenu`, the peek panes) receive already-translated
+strings as props.
+
+There is no guard that fails the build when a component hardcodes English.
+A missed call site still renders English for `zh-CN`. When you add a string,
+grep the component for quotes that are not `t(` calls instead of assuming
+the catalogue being complete means the UI is.
That doesn't retire the English fallback: a key added to `en` renders in
English until its `zh-CN` value lands, which is why new keys should ship
diff --git a/docs/LIMITS.md b/docs/LIMITS.md
new file mode 100644
index 0000000..4dd7de2
--- /dev/null
+++ b/docs/LIMITS.md
@@ -0,0 +1,44 @@
+# Limits and what happens at them
+
+These are the ceilings enforced in code. They are not a capacity plan: the
+database pool, the idle scheduler, and several list endpoints are still
+shared or unbounded. Change a number in the file cited here; this page only
+records it.
+
+## HTTP bodies
+
+| Surface | Ceiling | Over the ceiling |
+| --- | --- | --- |
+| `/api/*` JSON, except `POST /uploads` | 256 KB (`server/src/api/router.ts`) | Parser error before the handler |
+| `POST /api/uploads` JSON | 34 MB, and only after `authMiddleware` has attached a session | Parser error |
+| `/runtime/*` JSON | 4 MB (`server/src/agents/runtime/server.ts`) | Parser error |
+| `PUT /runtime/fs/write` | 34 MB | Parser error |
+| `POST /webhooks/email/inbound` | 25 MB raw body (`server/src/api/inbound-email.ts`) | Parser error |
+| Stored chat upload | 25 MB (`MAX_UPLOAD_BYTES`) | Request rejected |
+| Inbound email attachments, at the worker | 10 MB each, 18 MB total (`workers/email-gate`) | Worker forwards metadata only (`truncated`) |
+
+## Data stores
+
+| Resource | Ceiling | Notes |
+| --- | --- | --- |
+| Postgres pool | `max: 20`, 5s connect timeout, 30s idle, 60s `statement_timeout`, 30s `idle_in_transaction_session_timeout` | `server/src/db/pool.ts`. Not configurable by env. `/api/health` uses this same pool. |
+| Redis commands | 2s `commandTimeout`, `maxRetriesPerRequest: 1` on the command connection | `server/src/redis.ts`. The subscriber connection does not use that retry cap. |
+| WebSocket send buffer | Drop a frame above 2 MB buffered; terminate the socket above 8 MB | `server/src/ws.ts`. The client is expected to refetch. |
+| Agent turn | 200 hops (`MAX_HOPS` in `server/src/agents/turn.ts`) | No separate dollar or wall-clock budget around the hop loop. |
+| Low-priority wakes | 20 synthetic wakes per process per minute | `message.new` and `manual` are not counted. Idle has no cluster lock, so replicas each have this budget. |
+| Agent-driven turns | 30 per agent per rolling minute | Human-driven wakes are not counted. |
+| Calendar recurrence walk | 5000 indexes (`server/src/recurrence.ts`) | Past the cap, the series is treated as finished. |
+| Migration DDL | `lock_timeout = 5s` while old pods are still serving | See `server/src/db/migrations/README.md`. |
+
+## What is not limited
+
+There is no HTTP rate-limit middleware on the API, the runtime, or the
+inbound-email webhook. Admin aggregation responses are cached in process
+without evicting expired keys (`server/src/api/admin-router.ts`). List
+endpoints do not share one page size; messages take `before` and `limit`,
+admin lists take `limit` and `offset`, and some lists return the whole
+tenant set.
+
+Rejection is per call site: a parser limit is a 4xx from the body parser,
+a pool timeout surfaces as a failed query, and a hop cap ends the turn with
+`max_hops`. None of those paths is a queue the client can poll.
diff --git a/docs/api-contract.json b/docs/api-contract.json
new file mode 100644
index 0000000..0e87a2d
--- /dev/null
+++ b/docs/api-contract.json
@@ -0,0 +1,43 @@
+{
+ "schemaVersion": 1,
+ "http": {
+ "urlVersion": null,
+ "humanAuth": ["authorization: Bearer", "x-session-token"],
+ "humanTenantHeader": "x-company-id",
+ "cookieSession": false,
+ "authMiddlewareRejects": false,
+ "runtimeAuth": "authorization: Bearer <agent-runtime JWT>",
+ "inboundEmailAuth": "x-cumora-signature HMAC of the raw body",
+ "errorShape": { "error": "string" }
+ },
+ "websocket": {
+ "scope": "one socket per user, all of that user's workspaces",
+ "delivery": "user id after dropping untagged Redis events",
+ "eventTypes": [
+ "hello",
+ "message.new",
+ "message.delta",
+ "typing",
+ "participants.status",
+ "participants.avatar",
+ "computers.status",
+ "participants.added",
+ "message.reactions",
+ "group.pulled",
+ "conversation.updated",
+ "convene",
+ "board.changed",
+ "doc.sync",
+ "doc.update",
+ "doc.awareness",
+ "doc.error",
+ "doc.changed",
+ "doc.mention",
+ "calendar.reminder",
+ "calendar.changed",
+ "poll.updated",
+ "workspace.membership"
+ ],
+ "clientDeclaresCompanyId": ["participants.added", "workspace.membership"]
+ }
+}
diff --git a/docs/email.md b/docs/email.md
index 83ac8b8..1a15cb9 100644
--- a/docs/email.md
+++ b/docs/email.md
@@ -44,6 +44,26 @@ send / reply / start a thread.
- **Outbound**: Resend's HTTP API. Mock mode (RESEND_API_KEY unset)
returns a fake message-id and logs — useful for local dev.
+## Trust model
+
+**Inbound mail is not authenticated.** `workers/email-gate` accepts any
+message whose recipient domain is in `EMAIL_ROOT_DOMAINS`. It does not read
+`Authentication-Results` and performs no SPF, DKIM, or DMARC check. The
+server then maps the `From:` header — which the sender sets — to an agent
+in the recipient's company, then to a human member of that company, and
+otherwise to a synthetic external author (`resolveSender` in
+`server/src/api/inbound-email.ts`). A spoofed `From:` therefore produces a
+message that renders as that participant and enters the agent's context as
+theirs. The HMAC on `/webhooks/email/inbound` authenticates the worker to
+the server. It says nothing about the sender.
+
+The SPF and DKIM records in the setup section below are for **outbound**
+mail through Resend. They do not validate inbound `From:` headers.
+
+"Tenant isolation is enforced in the recipient resolver, not in DNS" means
+which workspace receives the message. It does not mean the sender was
+authenticated.
+
## Storage model
- One **conversation** per email thread (`conversations.kind = 'email'`).
@@ -63,6 +83,15 @@ whose `email_messages.smtp_message_id` matches its `In-Reply-To` or any
of its `References` ids. No match → new conversation, with the cleaned
subject as title.
+Inbound attachments are stored under the `email-attachments/` prefix.
+The worker base64-encodes them, capped at 10 MB each and 18 MB total;
+oversize parts are recorded as metadata with no bytes. The server writes
+the bytes with the MIME type the worker parsed from the message (it is not
+re-sniffed) and hands out an HMAC-signed read URL (`R2_URL_TTL_SECONDS`,
+default 3600). The `workers/r2-gate` worker checks that signature before
+reading the bucket. Outbound attachment rules later in this document are a
+separate path.
+
## Address scheme
`<sanitized participantId>.<companySlug>@<EMAIL_DOMAIN>` — e.g.
diff --git a/electron/main.cjs b/electron/main.cjs
index 12ac777..34ae50d 100644
--- a/electron/main.cjs
+++ b/electron/main.cjs
@@ -455,8 +455,9 @@ function armAuthHandoff() {
}
/** Validate + single-use-consume an inbound nonce. Constant-time compare so a
- * mismatch leaks nothing; clears the armed nonce on any check so a token can
- * be accepted at most once. */
+ * mismatch leaks nothing. The armed nonce is cleared only on a match, or when
+ * it is already missing or expired. Any other inbound value leaves the pending
+ * sign-in armed, so a stale tab cannot disarm a newer one. */
function consumeAuthNonce(nonce) {
const armed = armedAuthNonce
const expiry = armedAuthExpiry
diff --git a/package.json b/package.json
index f03323e..f4af48c 100644
--- a/package.json
+++ b/package.json
@@ -9,6 +9,9 @@
},
"description": "Where agent teams gather. Cross-platform team chat with AI agents as first-class participants.",
"license": "MIT",
+ "engines": {
+ "node": ">=20"
+ },
"repository": {
"type": "git",
"url": "https://github.com/yetone/cumora.git"
@@ -19,7 +22,7 @@
"email": "[email protected]"
},
"scripts": {
- "setup": "npm install && npm install --prefix workers/email-gate",
+ "setup": "npm install && npm install --prefix workers/email-gate && npm install --prefix workers/r2-gate",
"dev": "vite --port 5180 --strictPort",
"dev:all": "npm run migrate && concurrently -k -n web,api -c blue,magenta \"npm:dev\" \"npm:server:dev\"",
"build": "tsc -b && vite build",
diff --git a/server/k8s/gke.md b/server/k8s/gke.md
index 1e9e519..1da4bdd 100644
--- a/server/k8s/gke.md
+++ b/server/k8s/gke.md
@@ -370,10 +370,46 @@ kubectl logs agent-<id>
independent read-only verifier. Unknown or newer schema history requires a
forward-compatible image or reviewed repair; it is never treated as proof
that an arbitrary old image can start.
-- **Idle scheduler** — runs in-process on EACH server replica.
- That's fine because idle's tick currently publishes to
- CH_MESSAGE_NEW which SETNX-dedups; only one replica handles
- each tick's downstream work.
- **Monitoring** — both Pods (server + agent) log to stdout/stderr
which GKE auto-collects to Cloud Logging. Set up alerting on
agent_runs.status='failed' or kubelet's container_restart_count.
+- **Idle scheduler** — runs in-process on EACH server replica, and that
+ is not safe. `server/src/agents/idle.ts` calls `wakeAgent` directly.
+ It does not publish `CH_MESSAGE_NEW`, and there is no SETNX, advisory
+ lock, or in-flight guard. Every replica classifies agendas and can wake
+ the same agents. Until that changes, set `IDLE_INTERVAL_MS=0` or
+ `ENABLE_IDLE=false` on all but one replica, or run a single server
+ replica. The table below is the ownership record for the other loops.
+
+## Background task topology
+
+Every loop below starts inside the API process (`server/src/index.ts`).
+There is no separate worker deployment. "Claim" is what the code does
+today, not what a new loop should copy without reading the file.
+
+| Job | File | Interval / switch | Claim | Safe on N replicas? |
+| --- | --- | --- | --- | --- |
+| Mailbox scheduler | `agents/scheduler.ts` `startScheduler` | Redis subscribe; no interval | Per-message wake claim, 60s TTL | Subscribers are meant to run on every replica |
+| Wake-retry worker | `scheduler.ts` `startWakeRetryWorker` | 5s; per-process in-flight guard | Redis claim | Yes, via the claim |
+| Scanner | `agents/scanner.ts` | `SCANNER_INTERVAL_MS` (90s); `ENABLE_SCANNER=false` | `pg_try_advisory_lock`, plus a Redis wake claim | Yes. One replica holds the lock |
+| Idle scheduler | `agents/idle.ts` | `IDLE_INTERVAL_MS` (15min); `0` or `ENABLE_IDLE=false` | None | No. Duplicate classification and wakes |
+| Email retry | `email-retry.ts` | `EMAIL_RETRY_INTERVAL_MS` (60s); `0` disables | `FOR UPDATE SKIP LOCKED` | Yes |
+| Email attachment GC | `email-gc.ts` | `EMAIL_GC_INTERVAL_MS` (24h); `0` disables | None. Deletes are idempotent | Overlapping sweeps waste work; a lost delete race is harmless |
+| DB GC | `db-gc.ts` | `DB_GC_INTERVAL_MS` (5min); `0` disables | None. Deletes are idempotent | Same as email GC |
+| Trial sweep | `trial-sweep.ts` | 1h; no switch | None | Overlap can repeat the external tier call until the stamp clears |
+| Calendar dispatcher | `calendar.ts` | 60s; no switch | Per-slot claim | The tick has no in-flight guard, so a slow pass can overlap the next |
+| Poll expiration | `polls.ts` | `POLL_SWEEP_INTERVAL_MS` (60s); `0` disables | `FOR UPDATE` per poll | Yes |
+| LLM rollup | `agents/llm-rollup.ts` | `LLM_ROLLUP_INTERVAL_MS` (120s); `0` disables | `pg_try_advisory_lock` | Yes |
+| Shipping maintenance | `shipping-maintenance.ts` | 5min; no switch | `pg_try_advisory_xact_lock` | Yes |
+| Realtime outbox | `realtime-outbox.ts` | 1s; no switch | `SKIP LOCKED`, attempt cap, discard | Yes |
+| Workspace cleanup | `workspace-cleanup.ts` | `WORKSPACE_CLEANUP_INTERVAL_MS` (60s); `<=0` disables | `SKIP LOCKED` lease. No attempt cap; backoff tops out at 1h | Two replicas will not take the same row. A failing job is retried forever |
+| Finished agent-pod GC | `agents/runtime/orchestrator.ts` | 60s; `ENABLE_AGENT_POD_GC=false` | None | Deletes of finished pods are idempotent; replicas duplicate the list call |
+| Chrome-profile PVC GC | `orchestrator.ts` | `CHROME_PVC_GC_INTERVAL_MS` (1h); `ENABLE_CHROME_PVC_GC=false` | None | Same shape as pod GC |
+| FUSE pressure monitor | `orchestrator.ts` | 60s; `ENABLE_CLUSTER_MONITOR=false` | None | Every replica can raise the same alert |
+| Stale agent-run sweeper | `agents/observability.ts` | 60s; `ENABLE_AGENT_RUN_SWEEPER=false` | None. `UPDATE … WHERE status = 'running'` | A second replica's pass is a no-op for rows already closed |
+| Computer offline sweep | `index.ts` | 30s; no switch | None | Every replica runs it |
+| Boot presence reset | `resetHumanPresenceOnBoot` | Once, after `listen` | None | Every replica runs it |
+
+`message.new` wakes are not replayed by the post-spawn health retry.
+`scheduleWakeRetry` with the default `ensure_pod` class drops every reason
+except `manual`. The comment on that call in `scheduler.ts` says so.
diff --git a/server/src/agents/computer/registry.ts b/server/src/agents/computer/registry.ts
index 125287a..eda0542 100644
--- a/server/src/agents/computer/registry.ts
+++ b/server/src/agents/computer/registry.ts
@@ -905,12 +905,13 @@ function isComputerKind(value: unknown): value is ComputerKind {
return value === 'cloud' || value === 'local' || value === 'vps'
}
-/** Resolve where an agent runs + its company. Not cached: this sits on the
- * scheduler's cold path (wakeOne only calls it for a resting agent with no
- * live subscriber), and it's a single indexed lookup — a PK probe on
- * participants + PK joins on computers/company ownership. An in-process cache here would
- * be both pointless (cold path) and unsafe (each replica caches independently,
- * so reassignments/tier changes go stale per-pod). LEFT JOIN so an unassigned
+/** Resolve where an agent runs + its company. Not cached. Group-message
+ * fan-out calls this once per recipient, before it knows whether that
+ * recipient already has a live subscriber, so this is on the hot path.
+ * The SQL is a participant lookup plus a LATERAL owner-tier join ordered
+ * by `company_members.joined_at`, not a single primary-key probe. An
+ * in-process cache would also go stale independently on each replica
+ * when an agent is reassigned or a tier changes. LEFT JOIN so an unassigned
* agent (computer_id NULL) still returns its companyId with a null kind.
*
* Do not throw lookup failures into the same shape as "missing": callers route
diff --git a/server/src/agents/runtime/server.ts b/server/src/agents/runtime/server.ts
index a9926ff..bb3d3bd 100644
--- a/server/src/agents/runtime/server.ts
+++ b/server/src/agents/runtime/server.ts
@@ -13,8 +13,10 @@
* replaced runtime can't operate as another Agent placement.
*
* Mount at `/runtime` from `server/src/index.ts`. Not nested under
- * `/api` because the cookie-auth middleware on /api would reject these
- * (and we don't want pods sharing the human session cookie path).
+ * `/api` so a pod token is not mistaken for a human session. Human
+ * `/api` auth is header-based (`Authorization: Bearer` or
+ * `x-session-token`); there is no cookie session, and `authMiddleware`
+ * never rejects a request on its own.
*/
import { json, type NextFunction, type Request, type Response, Router } from 'express'
import { publicBodyParserError } from '../../body-parser-errors.js'
diff --git a/server/src/agents/runtime/wake-bus.ts b/server/src/agents/runtime/wake-bus.ts
index bb82115..f91cc42 100644
--- a/server/src/agents/runtime/wake-bus.ts
+++ b/server/src/agents/runtime/wake-bus.ts
@@ -21,8 +21,9 @@
*
* Multiple subscribers per agent on the same server are allowed (the
* agent's Pod may reconnect briefly during a rolling restart). Events
- * fan out to all live local subscribers; the Pod deduplicates by
- * event id (each event carries a fresh uuid).
+ * fan out to all live local subscribers. Each event carries a fresh
+ * uuid, but the Pod does not read it: both copies call drain(). A
+ * reconnect overlap can therefore run the wake twice.
*
* Single-instance deploys: this still works — the pub/sub round-trip
* is local to the one Redis instance, so latency is sub-millisecond.
@@ -50,7 +51,7 @@ type WakeEventPayload =
| Omit<WakeEventBase & WakeKindSteer, 'id' | 'at'>
interface WakeEventBase {
- /** Stable id so the Pod can dedupe across reconnect overlap. */
+ /** Fresh id for logs. The Pod does not dedupe on it. */
id: string
/** When the event was minted (server clock, ms since epoch). */
at: number
diff --git a/server/src/agents/scheduler.ts b/server/src/agents/scheduler.ts
index d6db76a..2b1d4e7 100644
--- a/server/src/agents/scheduler.ts
+++ b/server/src/agents/scheduler.ts
@@ -334,10 +334,11 @@ export async function wakeAgent(
// The fix is a hard cap on synthetic wakes per cumora-server process
// per minute. User-facing reasons (`message.new`, `manual`) are NEVER
// rate-limited — they correspond to a real user action and must go
-// through promptly. Per-process counter is fine because the actual
-// scheduler scope (idle.ts, scanner.ts) IS per-process; multiple
-// replicas multiply the budget naturally (a 2-replica deploy gets
-// 2 × LOW_PRIORITY_WAKE_BUDGET_PER_MIN cluster-wide).
+// through promptly. The counter is per process. Idle ticks really do
+// run on every replica (`idle.ts` takes no lock), so replicas multiply
+// the idle budget. The scanner does not: `scanner.ts` holds
+// `pg_try_advisory_lock` for the tick, so this cap is not a cluster-wide
+// scanner budget.
const LOW_PRIORITY_WAKE_BUDGET_PER_MIN = 20
let lowPriWindowStart = Date.now()
let lowPriUsed = 0
@@ -624,9 +625,12 @@ async function wakeOne(
// A successful kubectl apply does not guarantee the pod will ever
// reach the runtime wake stream: kubelet can reject allocation
// immediately after scheduling (for example a transient unhealthy
- // devic.es/fuse device). Queue one delayed health retry for
- // durable wakes; if the pod is healthy, the retry just delivers a
- // wake and the inbox fingerprint makes the turn no-op.
+ // devic.es/fuse device). The call below defaults failureClass to
+ // `ensure_pod`, and that class is queued only for `manual` wakes.
+ // For `message.new` it is a no-op. The durable inbox is the recovery
+ // path, and replaying the wake can duplicate a turn. The inline replay
+ // loop further down is also skipped for `message.new`, so a durable
+ // wake whose new pod never attaches is not retried here.
await scheduleWakeRetry(agentId, reason, conversationId, steerPayload, options, Math.max(1, retryAttempt + 1), 'post-spawn health check')
} else if (!r.ok) {
console.error(`[scheduler] ${agentId} ensurePod failed: ${r.reason}`)
@@ -1034,8 +1038,7 @@ export function mentionedAgentIds(body: string, agentMemberIds: readonly string[
new RegExp(`(^|[^\\w@])@${escapeRegex(id)}(?![\\w-])`, 'i').test(body))
}
-/** Exported for tests — pulled out of `wake` so the wake-policy is
- * easy to assert on. Fire-and-forget per recipient. */
+/** Render a small-brain inbox verdict into the note attached to the wake. */
function renderTriageNote(verdict: InboxTriageVerdict): string {
const state = verdict.actionable ? 'relevant' : 'not relevant'
const reason = verdict.reason.trim() ? `\nReason: ${verdict.reason.trim().slice(0, 500)}` : ''
diff --git a/server/src/api/admin-router.ts b/server/src/api/admin-router.ts
index 1485218..b68a02e 100644
--- a/server/src/api/admin-router.ts
+++ b/server/src/api/admin-router.ts
@@ -50,9 +50,10 @@ function safe(handler: (req: Request & AuthedRequest, res: Response) => Promise<
* forth — so the SAME heavy aggregation gets recomputed seconds apart. A short
* TTL collapses those repeats to one DB round-trip without making the numbers
* meaningfully stale (a spend dashboard does not need second-level freshness).
- * Single-pod-local + unbounded-by-design: keys are low-cardinality (a handful
- * of sinceDays × model × tenant combos) and entries self-expire, so it never
- * grows without bound.
+ * Single-pod-local. Expired entries are not deleted: `get` ignores them
+ * and `set` replaces the same key, but nothing sweeps or caps the map.
+ * The key is built from request query strings, so distinct filters add
+ * entries for the life of the process.
*/
const aggCache = new Map<string, { at: number; ttlMs: number; value: unknown }>()
async function cachedAgg<T>(key: string, ttlMs: number, compute: () => Promise<T>, force = false): Promise<T> {
diff --git a/server/src/api/inbound-email.ts b/server/src/api/inbound-email.ts
index c5a80e4..6a830f2 100644
--- a/server/src/api/inbound-email.ts
+++ b/server/src/api/inbound-email.ts
@@ -131,14 +131,17 @@ interface InboundPayload {
}>
}
-/** Verify a hex-encoded HMAC-SHA256 against the raw body bytes. Constant-
- * time compare so no timing oracle. */
+/** Accept only a 64-hex-digit signature, stripping an optional `sha256=`
+ * prefix. This does not compute or compare an HMAC. Callers that use it
+ * as a 401 gate have checked the shape, not the authenticity, of the header. */
function normalizeSignature(signature: string): string | null {
let normalized = signature.trim().toLowerCase()
if (normalized.startsWith('sha256=')) normalized = normalized.slice(7)
return /^[a-f0-9]{64}$/.test(normalized) ? normalized : null
}
+/** HMAC-SHA256 of the raw body, compared in constant time so a wrong
+ * signature is not a timing oracle. `normalizeSignature` only checks shape. */
function verifySignature(rawBody: Buffer, signature: string): boolean {
const secret = env.EMAIL_INBOUND_HMAC_SECRET
if (!secret) return false
diff --git a/server/src/api/router.ts b/server/src/api/router.ts
index ff4ab35..3f8fbcf 100644
--- a/server/src/api/router.ts
+++ b/server/src/api/router.ts
@@ -1,3 +1,13 @@
+/**
+ * Human HTTP API. One router, mounted at `/api`.
+ *
+ * `authMiddleware` does not reject. Handlers that need a user call
+ * `requireAuth` or `requireCompany`. There is no cookie session.
+ * Creates that accept `requestId` rely on partial unique indexes, not a
+ * shared idempotency middleware. Workspace deletion order is load-bearing:
+ * conversations go before participants because `conversation_members`
+ * references participants with `ON DELETE RESTRICT`.
+ */
import { Router, json, type Request, type Response, type NextFunction } from 'express'
import { isProviderProfileId } from '../agents/computer/provider-profiles.js'
import type { PoolClient } from 'pg'
@@ -1902,6 +1912,10 @@ api.delete('/companies/:id', safe(async (req, res) => {
}
}
await client.query(`DELETE FROM documents WHERE company_id = $1`, [companyId])
+ // Conversations before participants. conversation_members references
+ // participants ON DELETE RESTRICT, so the opposite order fails 23503
+ // while conversations and their member rows are still there.
+ // Deleting conversations cascades to conversation_members first.
await client.query(`DELETE FROM conversations WHERE company_id = $1`, [companyId])
await client.query(`DELETE FROM participants WHERE company_id = $1`, [companyId])
// Keep the billing/usage ledger (llm_calls + llm_calls_rollup) and global
diff --git a/server/src/db/migrate.ts b/server/src/db/migrate.ts
index f589748..81d6ed6 100644
--- a/server/src/db/migrate.ts
+++ b/server/src/db/migrate.ts
@@ -2255,6 +2255,9 @@ async function applyLegacyBaseline(client: import('pg').PoolClient): Promise<voi
CREATE UNIQUE INDEX IF NOT EXISTS participants_agent_id_unique
ON participants(id) WHERE kind = 'agent'
`)
+ // Agent ids are unique across tenants. Joins that look up an agent by
+ // id alone stay one row only because of this index; a second live agent
+ // row with the same id would fan those joins out.
await client.query(`
CREATE UNIQUE INDEX IF NOT EXISTS uniq_participants_agent_creation_request
ON participants(company_id, creation_request_id)
@@ -2934,11 +2937,18 @@ async function buildConcurrentIndexes(client: import('pg').PoolClient): Promise<
const indexes: Array<{ name: string; create: string }> = [
{
name: 'idx_conversations_members_gin',
- // Retained for the expand-release rollback window only. `loadInbox` /
- // `loadContext` / inbox-triage no longer read `members @> [agentId]` —
- // they resolve membership through the normalized `conversation_members`
- // participant index (see inproc-client.ts). Drop this index once the
- // rollback window closes.
+ // DO NOT DROP. This name is in BASELINE_REQUIRED_SCHEMA_INDEXES.
+ // verifyRequiredIndexes fails the migration Job when the index is
+ // missing or invalid, and this function is the only creator — it runs
+ // from the legacy baseline, not on later deploys. Dropping it blocks
+ // every subsequent deploy with no code path to rebuild it.
+ // To retire it: remove the name from BASELINE_REQUIRED_SCHEMA_INDEXES
+ // and drop the index in the same commit, in that order.
+ // `loadInbox` / `loadContext` / inbox-triage no longer read
+ // `members @> [agentId]`; they use `conversation_members`. That does
+ // not make the boot gate optional. This build's schema range also
+ // does not roll back onto the previous image, so there is no rollback
+ // window that justifies a drop.
create: `CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_conversations_members_gin
ON conversations USING gin (members jsonb_path_ops)`,
},
diff --git a/server/src/db/migrations/README.md b/server/src/db/migrations/README.md
new file mode 100644
index 0000000..643dd6f
--- /dev/null
+++ b/server/src/db/migrations/README.md
@@ -0,0 +1,50 @@
+# Schema migrations
+
+Migrations run from a pre-deploy Job while the previous server pods are
+still serving. `ensureSchema` sets `lock_timeout = 5s` on that session.
+`npm run guard:migration-locks` rejects the two patterns below. The longer
+contributor notes are in the repository `CONTRIBUTING.md`.
+
+## Checklist
+
+- Append a new file under this directory. Do not edit SQL that has already
+ been applied. The manifest stores a SHA-256 of that SQL, and startup
+ compares it.
+- Register the next contiguous version in `manifest.ts`. Keep
+ `MIN_SUPPORTED_SCHEMA_VERSION` and `MAX_SUPPORTED_SCHEMA_VERSION` honest.
+ Today both equal the manifest tip, so a migration moves the only schema
+ this build will boot. The previous image then refuses the new ledger.
+ `docs/RELEASE.md` is the recovery document; do not describe that deploy as
+ something `kubectl rollout undo` can finish.
+- Prefer the shape of `0002-normalized-conversation-members.ts`: add the new
+ structure, name the foreign keys, and write down `ON DELETE` behavior.
+ `conversation_members` references `participants` with `ON DELETE RESTRICT`,
+ which is why workspace deletion deletes conversations before participants.
+- `ADD COLUMN … DEFAULT <volatile>` rewrites the table under
+ `ACCESS EXCLUSIVE`. `gen_random_uuid()`, `random()`, and `nextval()` are
+ volatile. `now()` is `STABLE` and is fine. Use nullable column, batched
+ backfill, `SET DEFAULT`, `CHECK (… IS NOT NULL) NOT VALID`, then
+ `VALIDATE CONSTRAINT`.
+- `CREATE INDEX` on an existing table must be `CREATE INDEX CONCURRENTLY`
+ with `transactional: false`. Indexing a table the same migration creates
+ can stay inside the transaction.
+- Transactional migrations that lose the lock race are retried. A
+ non-transactional migration is not.
+
+## Required indexes
+
+`verifyRequiredIndexes` runs after the pending-migration loop, including
+when nothing is pending. A missing or invalid name in
+`REQUIRED_SCHEMA_INDEXES` (`server/src/db/migrate.ts`) fails the Job before
+the Deployment rolls.
+
+`buildConcurrentIndexes` and `ensureMessageClientIdIndex` run from the
+legacy baseline path, not on every later deploy. Putting a name into the
+required list without a migration that creates it on databases past version
+1 means the next deploy cannot rebuild it.
+
+To retire an index: delete the name from `REQUIRED_SCHEMA_INDEXES` and drop
+the index in the same commit, in that order. Do not drop
+`idx_conversations_members_gin` just because an older comment said the
+rollback window had closed. It is still required, and this build does not
+have a rollback window onto the previous image.
diff --git a/server/src/index.ts b/server/src/index.ts
index c8420b7..9a44d96 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -139,7 +139,9 @@ async function main() {
})
app.use('/api', api)
// Per-pod agent runtime API — JWT-authed, completely separate from the
- // cookie-auth /api/* surface used by humans. See agents/runtime/server.ts.
+ // human /api/* surface. That surface reads Authorization: Bearer or
+ // x-session-token; it has no cookie session, and authMiddleware does not
+ // reject. See agents/runtime/server.ts.
app.use('/runtime', runtimeRouter)
// ============== Host gating ==============
diff --git a/server/src/status.ts b/server/src/status.ts
index b33cb83..31c85b7 100644
--- a/server/src/status.ts
+++ b/server/src/status.ts
@@ -12,9 +12,11 @@ function toIso(value: unknown): string {
}
/**
- * Update a participant's status in Postgres and broadcast it. Single source
- * of truth for status changes — the loop, tool executor, and WS presence
- * tracker all funnel through here.
+ * Update a participant's status in Postgres and broadcast it. The turn
+ * loop, tool executor, and WS presence tracker funnel through here.
+ * This is not the only writer: `GET /api/participants` expires a busy
+ * lease in SQL and does not publish `CH_STATUS`, so clients learn about
+ * that transition on the next read or a later broadcast.
*
* A participant id can map to multiple rows when a human belongs to more
* than one company (humans share an id across tenants). We update every
diff --git a/server/src/storage.ts b/server/src/storage.ts
index 9271289..fbf4137 100644
--- a/server/src/storage.ts
+++ b/server/src/storage.ts
@@ -16,8 +16,9 @@
* - `mode` — 'local' | 'r2', surfaced so the API can advertise it
*
* Keys look like `<prefix>/<uuid>.<ext>`. Prefixes are conventional:
- * - `attachments/` — user uploads
- * - `avatars/` — agent portraits
+ * - `attachments/` — user uploads (signed)
+ * - `email-attachments/` — inbound and outbound mail files (signed)
+ * - `avatars/` — portraits (the only unsigned R2 prefix)
*/
import { writeFile, mkdir, readdir, stat, unlink } from 'node:fs/promises'
import { join, resolve, dirname } from 'node:path'
@@ -37,8 +38,11 @@ import {
export { normalizeStorageKey }
/** Keys under these prefixes get HMAC-signed URLs when a signing secret is
- * configured. Other prefixes (e.g. `avatars/`) are served unsigned — they
- * carry no private user content and benefit from full CDN caching. */
+ * configured. The R2 worker serves only `avatars/` without a signature;
+ * every other key is rejected at the edge until it is signed. Keep this
+ * list, `PUBLIC_PREFIXES` in `workers/r2-gate/src/index.ts`, and
+ * `STORAGE_KEY_PREFIXES` in `storage-keys.ts` in agreement — the prefix
+ * contract test fails when they drift. */
const SIGNED_PREFIXES = ['attachments/', 'email-attachments/']
function needsSignature(key: string): boolean {
return SIGNED_PREFIXES.some((p) => key.startsWith(p))
diff --git a/server/src/workspace-cleanup.ts b/server/src/workspace-cleanup.ts
index 62a3490..c12c8e9 100644
--- a/server/src/workspace-cleanup.ts
+++ b/server/src/workspace-cleanup.ts
@@ -1,3 +1,19 @@
+/**
+ * Deletes storage objects and agent runtimes after a workspace is removed.
+ *
+ * Jobs are claimed with `FOR UPDATE SKIP LOCKED` and a lease, so two
+ * replicas do not take the same row. There is no attempt cap and no
+ * dead-letter: `markFailed` backs off to at most one hour and the row
+ * stays claimable forever. `realtime-outbox.ts` is the sibling that does
+ * cap attempts.
+ *
+ * `WORKSPACE_RUNTIME_CLEANUP_ENABLED=false` makes runtime deletion return
+ * without error. The job is then marked completed, so turning the flag on
+ * later does not replay it.
+ *
+ * Reference checks scan attachments and document bytes without a tenant
+ * predicate. That is the current behavior, not a bounded per-company lookup.
+ */
import { randomUUID } from 'node:crypto'
import type { PoolClient } from 'pg'
import { pool } from './db/pool.js'
diff --git a/server/src/ws.ts b/server/src/ws.ts
index d629a57..1e77d83 100644
--- a/server/src/ws.ts
+++ b/server/src/ws.ts
@@ -32,8 +32,9 @@ interface AuthedSocket {
/** Stable per-socket id used as the Yjs update origin. Lets the room
* manager echo-suppress on this client's own outbound updates. */
originId: string
- /** Set of company_ids this user is a member of. Refreshed on connect; the
- * WS bridge uses it to filter Redis events tagged with `companyId`. */
+ /** Company ids loaded at connect. Used only to log membership count.
+ * Fan-out does not consult this set: delivery is by user id, and one
+ * socket receives frames for every workspace that user belongs to. */
companies: Set<string>
/** Active doc subscriptions on this socket. Released on close. */
docSubs: Map<string, DocSubscriber>
@@ -1371,9 +1372,10 @@ export function attachWebSocket(httpServer: Server) {
sub.on('message', (channel, payload) => {
// Doc channels are room-scoped, not company-scoped — skip them here.
if (channel === 'cumora:doc.update' || channel === 'cumora:doc.awareness') return
- // Tenant-aware fan-out: only deliver an event to a socket if the event's
- // companyId is in the socket's set of memberships. Untagged events are
- // dropped (no leakage), since every publisher is expected to tag.
+ // Untagged events are dropped. Tagged events are then delivered to the
+ // user ids resolveWsEventRecipientUserIds returns, not by intersecting
+ // companyId with the socket's membership snapshot. A connected user
+ // receives frames for every workspace they belong to.
let event: RoutedRedisEvent
try {
event = JSON.parse(payload) as RoutedRedisEvent
diff --git a/src/components/Message.tsx b/src/components/Message.tsx
index 1ba2509..763fb19 100644
--- a/src/components/Message.tsx
+++ b/src/components/Message.tsx
@@ -1873,7 +1873,7 @@ function MessageRowImpl({ msg, author, delay = 0, animate = true }: MessageRowPr
<polyline points="9 17 4 12 9 7" />
<path d="M20 18v-2a4 4 0 0 0-4-4H4" />
</svg>
- {msg.replyCount} {msg.replyCount === 1 ? 'reply' : 'replies'}
+ {msg.replyCount} {msg.replyCount === 1 ? t('thread.reply') : t('thread.replyPlural')}
</button>
)}
diff --git a/tests/api-contract.test.ts b/tests/api-contract.test.ts
new file mode 100644
index 0000000..e967ff1
--- /dev/null
+++ b/tests/api-contract.test.ts
@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { test } from 'node:test'
+
+const root = new URL('../', import.meta.url)
+
+function read(path: string): string {
+ return readFileSync(new URL(path, root), 'utf8')
+}
+
+function stringArray(source: string, name: string): string[] {
+ const match = source.match(new RegExp(`const ${name} = \\[([^\\]]+)\\]`))
+ assert.ok(match, `${name} list missing`)
+ return [...match[1].matchAll(/'([^']+)'/g)].map((entry) => entry[1])
+}
+
+test('api-contract.json names every WsEvent variant in order', () => {
+ const source = read('src/api/client.ts')
+ const start = source.indexOf('export type WsEvent =')
+ const end = source.indexOf('type Listener', start)
+ assert.ok(start >= 0 && end > start)
+ const eventTypes = [...source.slice(start, end).matchAll(/type: '([^']+)'/g)].map((entry) => entry[1])
+ const contract = JSON.parse(read('docs/api-contract.json')) as {
+ websocket: { eventTypes: string[] }
+ }
+ assert.deepEqual(contract.websocket.eventTypes, eventTypes)
+})
+
+test('R2 public, signed, and allowed prefixes are one set', () => {
+ const worker = read('workers/r2-gate/src/index.ts')
+ const storage = read('server/src/storage.ts')
+ const keys = read('server/src/storage-keys.ts')
+ const publicPrefixes = stringArray(worker, 'PUBLIC_PREFIXES')
+ const signedPrefixes = stringArray(storage, 'SIGNED_PREFIXES')
+ const allowed = stringArray(keys, 'STORAGE_KEY_PREFIXES')
+ assert.deepEqual(publicPrefixes, ['avatars/'])
+ assert.deepEqual(
+ [...publicPrefixes, ...signedPrefixes].sort(),
+ [...allowed].sort(),
+ )
+ assert.equal(worker.includes('Anything outside this'), false)
+})
diff --git a/workers/email-gate/README.md b/workers/email-gate/README.md
index 8beed28..14f2b54 100644
--- a/workers/email-gate/README.md
+++ b/workers/email-gate/README.md
@@ -12,7 +12,7 @@ The worker:
2. Reads the raw RFC 5322 message and parses it with `postal-mime`.
3. Builds a JSON payload (message-id, in-reply-to, references, from, to, cc, subject, text, html, raw size, `autoSubmitted` per RFC 3834, and `attachments[]` as base64 — capped at 10 MB per attachment and 18 MB in total).
4. HMAC-signs the payload with `EMAIL_INBOUND_HMAC_SECRET` and POSTs to `CUMORA_INBOUND_URL`.
-5. Translates the server's response into accept or reject. Every rejection is **permanent** (`message.setReject`) — including the 5xx branch, which arguably should tempfail so the sender's MTA retries. See the note in `src/index.ts`.
+5. Translates the server's response into accept or reject. A 404, and other 4xx responses, are permanent (`message.setReject`). A network error or a 5xx response throws so Cloudflare Email Routing returns a temporary failure and the sender's MTA can retry. The domain allowlist is the worker's only check on who sent the mail; it does not read `Authentication-Results`.
Outbound mail goes through Resend on the server side, **not** this worker — Cloudflare Email Workers can't send mail.
diff --git a/workers/r2-gate/README.md b/workers/r2-gate/README.md
new file mode 100644
index 0000000..99c1c2e
--- /dev/null
+++ b/workers/r2-gate/README.md
@@ -0,0 +1,45 @@
+# cumora-r2-gate
+
+Cloudflare Worker in front of `cdn.cumora.ai`. It is the authorization check
+for private objects in the `cumora-attachments` bucket. The server signs
+read URLs; this worker checks them before calling the R2 binding.
+
+## Access
+
+| Key prefix | Auth | Cache-Control |
+| --- | --- | --- |
+| `avatars/` | None. Portraits are public. | `public, max-age=86400, immutable` |
+| `attachments/` | `?exp=<unix>&sig=<hex>` | `private, max-age=300` |
+| `email-attachments/` | Same signature as `attachments/` | `private, max-age=300` |
+| Anything else | Same signature. Missing or bad signatures are 403 and do not read the bucket. | Private, once authorized |
+
+`sig` is HMAC-SHA256 of `<key>:<exp>` with `R2_URL_SIGNING_SECRET`. `exp`
+must be within the worker's skew window. GET and HEAD use the same check.
+Any other method is 405.
+
+The worker reads with `env.BUCKET.get` / `head`. It does not call `fetch()`
+or the Cache API. `Cache-Control` is a hint to caches in front of the
+worker; this program does not itself store a CDN hit.
+
+`avatars/` is the only unsigned prefix (`PUBLIC_PREFIXES` in `src/index.ts`).
+The server's signed list is `SIGNED_PREFIXES` in `server/src/storage.ts`.
+Together they must equal `STORAGE_KEY_PREFIXES` in `server/src/storage-keys.ts`.
+`tests/storage-prefix-contract.test.ts` fails when those lists drift.
+
+Rotate `R2_URL_SIGNING_SECRET` on the server and with `wrangler secret put`
+together. URLs already handed out stop verifying at rotation. Readers that
+still have the object key ask the server for a fresh signature.
+
+## Setup
+
+```bash
+cd workers/r2-gate
+npm install
+npx wrangler login
+npx wrangler secret put R2_URL_SIGNING_SECRET
+npx wrangler deploy
+```
+
+`npm run setup` at the repo root installs this package as well as
+`workers/email-gate`. Tests live in `src/index.test.ts` and run under the
+root `npm test` glob `workers/**/*.test.ts`.
diff --git a/workers/r2-gate/src/index.test.ts b/workers/r2-gate/src/index.test.ts
index fa11400..b67c4ff 100644
--- a/workers/r2-gate/src/index.test.ts
+++ b/workers/r2-gate/src/index.test.ts
@@ -148,6 +148,13 @@ test('conditional signed GET returns 304 after an authenticated R2 revalidation'
assert.equal(bucket.headCalls, 0)
})
+test('unknown prefixes are private and do not touch the bucket', async () => {
+ const bucket = fixtureBucket('notes/secret.txt')
+ const response = await request('GET', 'https://gate.invalid/notes/secret.txt', bucket)
+ assert.equal(response.status, 403)
+ assert.equal(bucket.getCalls + bucket.headCalls, 0)
+})
+
test('avatars remain unsigned and publicly cacheable', async () => {
const key = 'avatars/alice.png'
for (const method of ['GET', 'HEAD'] as const) {
diff --git a/workers/r2-gate/src/index.ts b/workers/r2-gate/src/index.ts
index 8e42e5d..3c229fb 100644
--- a/workers/r2-gate/src/index.ts
+++ b/workers/r2-gate/src/index.ts
@@ -4,17 +4,20 @@
*
* Access model:
* - GET /avatars/<key> → unsigned, public. Portraits aren't
- * sensitive and benefit from full CDN
- * caching.
+ * sensitive. This is the only public
+ * prefix.
* - GET /attachments/<key> → must carry `?exp=<unix>&sig=<hex>`;
* - GET /email-attachments/<key> → uses the same signed query contract.
* `sig` = HMAC-SHA256(secret,
* `<key>:<exp>`). Both `exp` (not in
* the past) and `sig` (constant-time
* equal) are checked before reading R2.
+ * - any other key → same signature check. The default is
+ * private; a new prefix is not public
+ * until it is added to PUBLIC_PREFIXES.
* - HEAD → same auth as GET; useful for size
* probes from clients.
- * - everything else → 405.
+ * - any other method → 405.
*
* Secret rotation: rotate `R2_URL_SIGNING_SECRET` on both the Cumora
* server and `wrangler secret put` here in lockstep. URLs already signed
@@ -26,9 +29,11 @@ export interface Env {
R2_URL_SIGNING_SECRET: string
}
-/** Prefixes that demand a valid `?exp&sig` pair. Anything outside this
- * list is treated as publicly cacheable. */
-const SIGNED_PREFIXES = ['attachments/', 'email-attachments/']
+/** Prefixes that may be read without a signature. Every other object key
+ * is private: a missing or bad `?exp&sig` pair is rejected before the
+ * bucket is read. Add a prefix here only when the object is intentionally
+ * public. `server/src/storage.ts` must sign every prefix that is not listed. */
+const PUBLIC_PREFIXES = ['avatars/']
export default {
async fetch(req: Request, env: Env): Promise<Response> {
@@ -39,7 +44,7 @@ export default {
const key = decodeURIComponent(url.pathname.replace(/^\/+/, ''))
if (!key) return new Response('not found', { status: 404 })
- const needsSig = SIGNED_PREFIXES.some((p) => key.startsWith(p))
+ const needsSig = !PUBLIC_PREFIXES.some((p) => key.startsWith(p))
if (needsSig) {
const gate = await verifySignature(key, url.searchParams, env.R2_URL_SIGNING_SECRET)
if (!gate.ok) return new Response(gate.reason, { status: 403 })
diff --git a/workers/r2-gate/wrangler.toml b/workers/r2-gate/wrangler.toml
index e828381..d404aa7 100644
--- a/workers/r2-gate/wrangler.toml
+++ b/workers/r2-gate/wrangler.toml
@@ -3,8 +3,9 @@
# Routes: every request to `cdn.cumora.ai/*` flows through this worker
# instead of going straight to R2's custom-domain handler. The worker
# validates a server-signed query string before reading the bucket via
-# its R2 binding, then proxies the bytes back to the client (with CDN
-# caching on hits).
+# its R2 binding, then returns the bytes. Reads go through the R2 binding,
+# not fetch() or the Cache API. The worker sets Cache-Control; it does not
+# itself store an edge hit.
#
# Deploy:
# cd workers/r2-gate