Multi-tenancy (row)
Scope reads and writes to a subject's scope with one field marker — RBAC, RLS and audit together.
WeaveKit's tenancy is row-based: one database, one set of tables, and a scope column that fences every row. It is opt-in and per object — an object without a scope column behaves exactly as before, and a subject without a scope runs single-scope.
Enable
// weavekit.config.ts
export default {
// ...
scope: { enabled: true, defaultScope: 'acme' },
};When scope.enabled is on, a subject that lacks a scope is stamped with defaultScope
(withDefaultScope), so existing auth sources keep working. Then mark one field on each
scope-fenced object:
// objects/invoice/schema.json
{
"name": "invoice",
"fields": [
{ "name": "id", "type": "string", "primary": true },
{ "name": "tenant_id", "type": "string", "scope": true },
{ "name": "amount", "type": "number" }
]
}The "scope": true marker is engine-recognized (not a name convention). You choose the column name.
How isolation is enforced (three layers)
- RBAC row scope —
buildRowScopeANDs ascope = <subject.scopeId>predicate onto every read, even forread: "all". A query run as an agent on behalf of another scope simply returns nothing. - Native PostgreSQL RLS — the policy adds
current_setting('weavekit.scope_id', true) = "<col>". The restricted-SQL role (this.db.query) sets theweavekit.scope_idGUC, so a GUC-less query fails closed (reads zero rows, never over-exposes). Withrls.enforcethe engine's own object queries are bounded by the same scope predicate in PostgreSQL as well. - Audit — every event carries
scopeId; the audit query and SSE stream filter by the subject's scope, so an ordinary identity only sees its own scope's trail.
Write rules
- Forced on create — the scope column is set from the subject; a client cannot create a row in another scope (the input value is ignored).
- Immutable on update — moving a row to another scope is rejected with
object.scope.immutable. There is no reassignment path. - Cross-scope writes are invisible to the row scope, so they surface as
data.recordNotFound.
System actors
A system principal may carry a scope (systemPrincipal(capability, reason?, scopeId?)) so background
work (workflow timers, timers/scripts) is confined to the right scope. Without a scope it is
unrestricted, as in single-scope mode.
Scope boundary
Tenant lifecycle (onboarding, offboarding, data residency) and schema-per-tenant isolation are the enterprise layer. The engine provides exactly the row mechanism above and the seams to build on.
Related
- RBAC — the row-scope / permission model the scope predicate layers on
- Identity — where
subject.scopeIdcomes from - Audit —
scopeIdon events and the scope-scoped query - Enterprise seams