Tenant scoping and isolation

A tenant in ErmisAI is a string. Every durable row and every runtime state key is filed under it, and every query that should stay inside one workspace has to say so itself.

The tenant scope id

Two shapes, and only two:

A signed-in user with no organization is not "unscoped". They are the sole owner of their own tenant (src/lib/auth/clerk-session.ts:217). There is no third state.

resolveTenantScopeIdFromSessionClaims (src/lib/auth/clerk-session.ts:334-356) is the resolver almost every route should call:

1. If the compact Clerk org claim o.id is present, return org:<id>.
2. Otherwise, for a live session, return user:<lower-cased userId>.
3. The clerk_users DB snapshot is consulted only for claim-less contexts — background jobs and webhooks. A comment at clerk-session.ts:343-348 records why: falling through to the snapshot for live sessions made Clerk's org switcher cosmetic, because the server kept resolving the org scope and the personal workspace became unreachable.

Note the casing asymmetry: user ids are lower-cased (normalizeSessionUserId, clerk-session.ts:91-99), organization ids are only trimmed (getString, clerk-session.ts:60-69). Clerk ids are mixed case — a real fixture in this repo is user_3CRBRtElWWumw8Gk5rRxZE9RGc8 (tests/ai-runtime-telemetry.vitest.ts:27).

The pattern for a tenant-scoped route

Every API handler carries its own gate; middleware matchers are defence-in-depth only (src/proxy.ts:3-6). The canonical order is authenticate, resolve session metadata, check a capability, then derive the scope — as in src/app/api/stories/route.ts:57-71:

const { userId, sessionClaims } = await auth()

if (!userId) {
  return Response.json({ error: 'Unauthorized' }, { status: 401 })
}

const sessionMetadata = await getResolvedClerkSessionMetadata(userId, sessionClaims)

if (!canEditStories(sessionMetadata.appRole, sessionMetadata.tenantRole)) {
  return Response.json({ error: 'Forbidden' }, { status: 403 })
}

const tenantScopeId = await resolveTenantScopeIdFromSessionClaims(userId, sessionClaims)

The scope comes from verified session claims. It never comes from a query parameter, a request body, or a header.

The three resolvers, and how they differ

src/lib/platform/shared/tenant-scope.ts exports two more resolvers that platform code passes an explicit scope into. They do not behave the same way:

Both of the latter run assertCallerAuthorizedForTenantScope before trusting an override.

The explicit-override guard

assertCallerAuthorizedForTenantScope (tenant-scope.ts:50-108) is defence-in-depth against a future caller forwarding client input as a scope:

• user: scopes authorize only that same user, with no database round trip.
• org: scopes authorize only a caller holding a tenant_memberships row for that org.
• An unrecognized scope shape is refused rather than trusted.

Failures:

The 503 is deliberate: the repository disables itself for a 60-second cooldown after one error (createRepositoryAvailability, src/lib/runtime/repository-availability.ts:11, 43-53), so passing through on unavailability would silently switch the guard off for the rest of that window. Only the local/test fallback mode, which has no membership snapshots at all, passes through unchecked (tenant-scope.ts:83-85).

Scope without a Clerk session: the integration API key

The three published integration endpoints have no session at all. resolveApiKeyAccess(rawKey) hashes the presented x-ermis-api-key and returns { keyId, userId, tenantScopeId } from the matching tenant_integration_api_keys row (src/lib/platform/integrations/keys-and-wordpress.ts:466-496). The scope is a property of the key, not of the request.

The CMS export then calls getTenantStoryDetail(authorization.userId, item.id, authorization.tenantScopeId) (src/lib/platform/integrations/public-cms-story-export.ts:133) — passing the key owner's user id alongside the explicit scope, so the membership guard above does run on this path rather than being bypassed by a null actor. The endpoints themselves are documented in Public integration API.

The relational layer

17 of the 25 tables in src/lib/db/schema.ts carry a tenant_scope_id column. The scope is part of the key, not an afterthought:

The eight tables with no scope column are billing_plans, clerk_users, clerk_webhook_events, billing_webhook_events, source_catalog_entries, source_catalog_dataset_versions, platform_state, and platform_state_hash. The first six are platform-global by design. The last two are covered below.

Composite primary keys do most of the work here: an insert or upsert that forgets the scope fails loudly rather than writing into the wrong tenant. Prefer that shape for new tables.

The key-value layer

platform_state has a single-column primary key — key (schema.ts:873). There is no scope column and no constraint. Isolation in the KV layer is entirely a key-naming convention.

buildScopedPlatformKey(domain, id) produces platform:<domain>:<lower-cased id> (src/lib/platform/shared/runtime-state.ts:10-12, 18-20). Most per-tenant keys pass the tenant scope id as that second segment. Some builders interpolate the scope directly without normalizing — buildEditorQueueStateKey and buildStoryNotesStateKey (runtime-state.ts:22-27) — so both a lower-cased and a verbatim form can exist in the same keyspace.

Payloads are zod-validated on read and on write, but resolveLocalPlatformStateSchemaByKey falls through to z.unknown() for any key family it does not match (src/lib/platform/shared/state-schemas.ts:381). A typo'd key family gets no schema enforcement and no warning.

Keys and rows that are deliberately not tenant-scoped

Not everything under platform: is per-tenant. These are global on purpose, and reading them is reading across tenants:

Who you are: two independent role axes

Isolation answers which tenant. Roles answer what you may do inside it, and the two axes resolve from different sources on purpose (clerk-session.ts:251-275):

• appRole — the platform staff claim super_admin | editor | ops | unassigned — is always read from the live Clerk JWT and never from the DB snapshot, so a demoted staff member loses access on the next token refresh rather than when a webhook catches up.
• tenantRole — owner | admin | member — is DB-authoritative, read from tenant_memberships for the active scope.

The tenant-role fallback is least-privilege: no org means owner of your own personal scope, Clerk org:admin means owner, and any unrecognized custom Clerk org role resolves to member (clerk-session.ts:209-217). A comment there records that defaulting to owner was a fail-open gate. super_admin bypasses every tenant capability check (hasAdminBypass, src/lib/auth/newsroom-roles.ts:51-53); editor and ops get no tenant-side bypass at all.

The full capability matrix lives in Team, roles and permissions.

Story ids collide across tenants

Story ids are content-derived, not tenant-derived. An article id is an FNV-1a hash of sourceId|url|publishedAt|headline (rss-aggregation.ts:1288-1296, 1583-1586); a cluster id hashes the earliest member article (:2108); the story takes the cluster id (:3261). The same wire item in two newsrooms produces the same story-<hash> on both.

That is why:

• editorial_story_drafts is keyed (tenant_scope_id, story_id), never story_id alone.
• Every admin review mutation requires a tenantScopeId in the request body and returns 400 {"error":"tenantScopeId is required"} without one (src/app/api/admin/review/[storyId]/approve/route.ts:13-18, 38-40). The comment there states the reason directly.
• /admin/review/[storyId] renders Missing tenant scope. Open this story from the review queue so the tenant context is carried along - admin review acts on tenant data. when the ?tenantScopeId= query parameter is absent (admin/review/[storyId]/page.tsx:41-50). A bare story-id deep link is not usable.

Cross-tenant surfaces that exist on purpose

Details of each screen are in The operations console.

Erasure depends on the key convention

The GDPR tenant purge deletes 16 tables by tenant_scope_id, then finds the tenant's KV slice with LIKE '%<escaped scope id>%' against platform_state and platform_state_hash (src/lib/db/data-erasure-repository.ts:122, 257-268). A blank scope would degrade that to LIKE '%%' and wipe every tenant, so purgeTenantData refuses an empty scope outright (:115-120).

The practical consequence for anyone adding state: if your key does not embed the tenant scope id, erasure will not find it. The feed cache is correctly exempt — it holds no tenant-authored content — but a new per-tenant key named without the scope would silently survive a purge.

Checklist for anything tenant-scoped