Security / The security model

Tenant isolation

Two independent layers, either of which would be sufficient — and why that is the point.

The organization is the tenant boundary. Every resource in Veefore is reachable only through the organization that owns it.

Two layers enforce it, independently.

#Layer 1 — the repository scope guard

Every query in the data layer requires a tenant scope. Not "should have" — requires. A query without one is refused before it reaches the database.

tsCopy
// Every repository method takes a scope as its first argument.
await ctx.repos.agents.findById({ organizationId: actor.organizationId }, agentId);

Passing an id from another organization returns nothing, and a request that attempts it is refused with TENANT_MISMATCH.

Crossing the boundary requires an explicit, named justification in code. Background jobs use it — a job queue is inherently cross-tenant — and request handlers do not.

#Layer 2 — PostgreSQL row-level security

iniCopy
DATABASE_ENABLE_RLS=true

Migration 0009_row_level_security.ts applies RLS policies to every tenant-scoped table. With it enabled, the database itself refuses to return rows outside the current tenant context, regardless of what the query asked for.

#The hierarchy

textCopy
Organization                 ← the isolation boundary
└── Workspace                ← scoping, not isolation
    └── Environment          ← scoping, not isolation

Workspaces and environments divide resources within a tenant. They are useful for scoped role grants and for separating deployment tiers, and they are not a security boundary between tenants — because they are inside one.

#Scope headers

httpCopy
GET /v1/agents
Authorization: Bearer aos_sk_…
x-veefore-workspace: wsp_01JAV…
x-veefore-environment: env_01JAV…

Headers select a scope within your organization. They cannot select another organization — the tenant comes from the authenticated session, never from a header.

Supplying a workspace or environment you have no access to is refused. These are a filter over what you can already see, not a way to see more.

#Agents are bound to an environment

An agent belongs to exactly one environment. A staging identity cannot act in production — not because a policy forbids it, but because the agent is not there.

#Cross-tenant A2A

A2A is the one place agents from different organizations interact, and it is built so that interaction does not weaken isolation.

• A connection must be explicitly registered, with the remote party's public key.
• It starts PENDING and stays unusable until the remote passport verifies against that key.
• Every invocation runs the full twelve-stage pipeline on your side.
• Blocking is immediate and applies to in-flight sessions.

A verified remote agent gets to invoke the capabilities you registered on the connection, under your policy. It gets no access to your data model, no query surface, and no visibility into anything else in your tenant.

→ A2A

#What is shared across tenants

Almost nothing, and it is worth being precise about the exceptions:

#Verifying it

bashCopy
npm run test:security        # cross-tenant access cases
npm run test:integration     # repository scope guard behaviour
npm run smoke                # signup through enforcement, two organizations

The security suite includes cases that attempt to read, update and act on another organization's resources through every surface that accepts an id.

#Operational checklist

• [ ] DATABASE_ENABLE_RLS=true in production
• [ ] One organization per tenant
• [ ] Role grants scoped to a workspace where the team only needs one
• [ ] TENANT_MISMATCH in the audit trail reviewed, not ignored
• [ ] A2A connections registered with an out-of-band key, and re-verified on a schedule

#Related