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.mdindex 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.```bashcreatedb -h localhost cumoraexport 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 dependenciesnpm 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 thedesktop 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 a11yrules are enforced incrementally (useButtonType, ARIA roles/props, and coreaccessibility 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 backoffbefore 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 withoutcolliding, and why the prompt is kept deliberately minimal) is documented in[`docs/COORDINATION.md`](docs/COORDINATION.md) — read it before touching thediff --git a/README.md b/README.mdindex 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.mdindex 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 acompromised 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 securelydiff --git a/docs/API.md b/docs/API.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 inEnglish until its `zh-CN` value lands, which is why new keys should shipdiff --git a/docs/LIMITS.md b/docs/LIMITS.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mdindex 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 anyof its `References` ids. No match → new conversation, with the cleanedsubject 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.cjsindex 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 = armedAuthNonceconst expiry = armedAuthExpirydiff --git a/package.json b/package.jsonindex 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.mdindex 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 aforward-compatible image or reviewed repair; it is never treated as proofthat 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/stderrwhich GKE auto-collects to Cloud Logging. Set up alerting onagent_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.tsindex 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 routediff --git a/server/src/agents/runtime/server.ts b/server/src/agents/runtime/server.tsindex 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.tsindex 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: numberdiff --git a/server/src/agents/scheduler.ts b/server/src/agents/scheduler.tsindex 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 = 20let 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.tsindex 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.tsindex 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_SECRETif (!secret) return falsediff --git a/server/src/api/router.ts b/server/src/api/router.tsindex 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 globaldiff --git a/server/src/db/migrate.ts b/server/src/db/migrate.tsindex 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<voiCREATE UNIQUE INDEX IF NOT EXISTS participants_agent_id_uniqueON 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_requestON 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_ginON conversations USING gin (members jsonb_path_ops)`,},diff --git a/server/src/db/migrations/README.md b/server/src/db/migrations/README.mdnew file mode 100644index 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.tsindex 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.tsindex 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 everydiff --git a/server/src/storage.ts b/server/src/storage.tsindex 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.tsindex 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.tsindex 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: RoutedRedisEventtry {event = JSON.parse(payload) as RoutedRedisEventdiff --git a/src/components/Message.tsx b/src/components/Message.tsxindex 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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tomlindex 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