Skip to main content

Threat model

What the policy, the row rules and the agent checks protect against, what they do not, and which parts you must review yourself.

The two packages protect against mistakes in your application code and against agents that do more than a person allowed. They do not protect against application code written on purpose to get around them.

What is protected

RiskWhat stops it
A query forgets a tenant filter and returns another organization's rowsRow rules check every row a handler reads. The query fails instead of returning the row
A caller sends the ID of another tenant's rowThe tenant comes from the row, not from the caller. A tenant without a role does not exist for the caller
A handler writes a row the caller may only readThe write fails with FORBIDDEN
A new Convex query method hands out rows without a checkctx.db has only the methods the library checks. Others fail
A function is built with Convex's own builders and skips every checkThe no-bypass test fails. An operation that calls such a function fails and keeps nothing
Scheduled work runs after the person lost accessEach internal operation checks the caller, the role and the rows again
An agent calls a tool outside the scopes the person grantedThe host does not see the tool, and the call fails
An agent archives, publishes or deletes without askingActions with agents: { action: 'approve' } wait for a person
A write action gets no agent rule and an agent runs it on its ownA call that changes data and has no agent rule waits for a person
A person cancels a job that someone else scheduledctx.scheduler.cancel cancels only the caller's own jobs. Another job fails with NOT_FOUND
A person approves something that changed since the agent askedApproving fails with STALE
A host retries a writeThe same request_id runs once
An agent floods the applicationWrites per minute, open requests and IDs per call have limits. See Limits
Text from a row shows up as a link or HTML in an approval or a hostSummaries are one plain line for people, and inert markdown for agents
A person disconnects a host, signs out, or loses a membershipThe next call of that agent fails

Scheduled work stops once the person or agent that scheduled it loses access, so cleanup scheduled as them stops too. Give a status that must change soon a path of its own.

The guarantee is a test

Convex cannot inspect a function before it runs. So the rule that every function goes through defineFunctions is kept by a test, not at runtime: unguardedFunctions in Test your app. Run it in CI. The runtime checks (the argument shape, the result envelope, the rollback) are the second line.

A scheduled raw function runs later on its own, with no operation around it to fail, so the unguardedFunctions test in Test your app is what catches it.

What is not protected

  • Code that is written to get around the library. A handler can import Convex's raw builders, call trusted, or use a job's database without rules. The packages make this visible in review; they do not prevent it.
  • Your own rules. user, roleOf, the row rules and the policy are the source of truth. A roleOf that returns 'owner' for everyone gives everyone every action.
  • Files. ctx.storage is Convex's own. Row rules do not cover files, and a storage ID gives whoever holds it the file: getUrl hands it out and delete removes it. Take a storage ID from a row the call read through ctx.db, never from the input, except to attach a file the caller just uploaded. Even then, a caller can attach the storage ID of someone else's file to their own row, so treat storage IDs as secrets and never show one to a person who may not have the file. For a file from an agent, take an upload ID instead and call claimUpload: it checks that the caller sent the file (see Files from agents).
  • Effects outside the database. An action has no transaction. A message sent or a payment made before a later step fails stays done.
  • The auth component. Sessions, OAuth tokens and consent are checked by Better Auth through createBetterConvexAuth. See Security model.
  • What a model does with text. See the next section.

Prompt injection

A tool result can contain text that someone else wrote: a crawled page, a customer's message, the name of a project. A model can read instructions in that text and follow them. Escaping does not stop this. Inert markdown stops a link from rendering; it does not stop a model from obeying the words.

Plan for an agent that follows instructions from data:

  • Grant narrow scopes. A host that only needs to read gets only read scopes. It does not see the write tools.
  • Use approve for every destructive action: delete, archive, publish, send, pay, invite, or change a role. The person approves the plan your plan function builds, and the work changes only the rows it lists. The agent supplies data, never code: the limit is there for mistakes in your handlers, and calls to components stay your code's responsibility.
  • Keep the limits on. They bound what one connection can do in a minute.
  • Read the activity feed. Every agent write of a call with a tenant is in that tenant's feed, with the tool, the person and who approved it. A call without a tenant of its own is in no tenant's feed, only in the feed of the person the agent acts for (activity({})): crossTenant operations, and calls whose input names only rows of anyOf tables, such as a shared note.

Review these by hand

Search the code for each one and check the reason:

  • trusted( and trustedRoutes: functions and routes without the library.
  • unchecked(: tables without a row check.
  • job(: code that runs as the system, with every tenant's rows.
  • public in the policy: actions for signed-out visitors.
  • crossTenant: true: operations that move rows between tenants. Their agent writes are in no tenant's activity feed, and none of their writes are in a tenant's audit trail. See Audit log.
  • ctx.storage: every storage ID must come from a row the call read.
  • Agent rules set to 'allow' for actions that change data.