RBAC — roles, permissions, and row scopes
You write permissions once, and every surface obeys them.
You write permissions once, and every surface obeys them. Enforcement lives in the data-access layer, so REST, MCP, and the protocol adapters you enable all get the same rules for free — there is no per-interface permission code to maintain.
Permission model (default-denied when a map is present)
{
"permissions": {
"admin": { "read": "all", "create": true, "update": true, "delete": true },
"sales": { "read": "own", "create": true, "update": ["title", "status"], "delete": true },
"sales_mgr": { "read": "department", "manage": "department", "update": ["status"], "delete": false },
"finance": { "read": "all", "fields": { "exclude": ["commission"] } },
"auditor": { "read": "all", "manage": "own" }
}
}Per role:
read:all|own|department— the row scope for readsmanage:all|own|department— the row scope for writes (update/delete/transition); defaults toreadwhen omittedcreate: booleanupdate:true(all fields) or an array of field names the role may update (empty = none); omitted or false = nonedelete: booleanfields.exclude: columns stripped from every response — the data never leaves the database
Semantics (model B):
- No
permissionsmap → open mode: full CRUD for any authenticated subject. - Map present → roles not listed are denied. A listed role is denied for any operation it doesn't explicitly grant.
- Multiple roles merge →
read/managetake the most permissive scope;updateandexcludeare unioned.
Row scopes
own and department filter rows by a marker column you declare:
{ "fields": [
{ "name": "owner_id", "type": "string", "ownership": true },
{ "name": "department_id", "type": "string", "department": true }
] }own— rows where theownershipcolumn identifies the subject (= subject.id).department— rows whose department is the subject's department or a descendant. The department is taken from thedepartmentcolumn if declared; otherwise it is derived from the record's owner (owner → weavekit_user.department_id). The subtree recurses overweavekit_department. A subject withoutdepartmentIdgets a 403 (rbac.departmentId.missing).all— no row filter.
A role that uses own/department must declare a matching field; validation rejects the schema
otherwise (permission.own.ownershipField / permission.department.missingField).
Where a scope column's ids come from
A marker column holds ids in one of two spaces (ownershipSource / departmentSource):
{ "name": "sales_rep_id", "type": "string", "ownership": true, "ownershipSource": "external" }internal(default) — the engine's own ids (weavekit_user/weavekit_departmentuuids).external— the customer's ids (e.g. from the synced identity source); the engine translates them throughweavekit_user.external_id/weavekit_department.external_id.
This lets you filter an untouched customer table by its own ownership column without rewriting it.
Authenticated subject
Authentication maps a credential to a subject { id, roles, departmentId? }:
{
auth: {
source: {
'sk-rep': { id: 'u100', roles: ['sales'], departmentId: 'd-east' },
'sk-mgr': { id: 'u300', roles: ['sales_mgr'] },
},
},
}Or authenticate through the engine identity directory (see Identity): a verifier turns a credential into an identity, the directory resolves it to the internal subject (roles + department).
HTTP behavior
| Condition | Status | Code |
|---|---|---|
| Missing / invalid API key | 401 | auth.missingKey / auth.invalidKey |
| Role denied an operation | 403 | rbac.denied.read/create/update/delete |
| Field not updatable | 403 | rbac.denied.field |
department scope without a department | 403 | rbac.departmentId.missing |
| Role uses a scope with no matching field | 403 | rbac.scope.columnMissing |
| Row outside scope (read/update/delete) | 404 | data.recordNotFound — does not leak existence |
Example
sales with read: own, manage: own, exclude: ["secret"], department d-east:
find()returns only their own rows, without thesecretcolumn.findOne()/update()on another user's row → 404.sales_mgrwithread: departmentsees the wholed-eastsubtree;managescopes writes the same way.
Database-enforced row scope (rls.enforce)
By default the row scope is enforced by the application layer (the generated WHERE clauses); the
engine's own queries run as the table owner, which PostgreSQL RLS does not restrict. Turn on
object-path RLS to have PostgreSQL re-check the same matrix as a second line of defense:
// weavekit.config.ts
export default { /* ... */ rls: { enforce: true /* , role: 'weavekit_object' */ } };weave migrateprovisions the role (weavekit_objectby default, granted to the migrating account) and, per object table,TO <role>policies generated from the same row-scope builder as the application layer:SELECTcovers read ∪ manage,UPDATE/DELETEthe manage scope,UPDATE … WITH CHECKonly the scope column. Department subtrees, external-id ownership, details children (through the parent) and thescopeboundary are all covered.- At runtime, user-principal reads/updates/deletes run under
SET LOCAL ROLE <role>with the subject inweavekit.*session GUCs. A missing application filter therefore cannot expose rows: the database returns only what the policies allow. System principals and inserts still run as the owner (the engine stamps the scope column itself). - Fail-closed startup: with
enforceon, the engine refuses to start (engine.rls.notProvisioned) until the role, policies and privileges exist;weave doctorreports the same asobject-rls. - Existing (brownfield) tables are only touched when the object opts into
"alter": trueand the migrating account owns the table — enabling RLS on a shared table also hides its rows from other non-owner roles, so this stays explicit. - Default off in 1.x. Policies carry a definition digest (
COMMENT ON POLICY), so editing the permission matrix updates them on the next migrate.
Script SQL (RLS)
Inside *.server.js, this.db.query runs under a restricted PG role with row-level security derived
from the same matrix. Its own/department predicates are flat equality on internal ids (they do
not expand the department subtree or translate external ids) — use this.db.objects for those. Flat
equality is strictly narrower, so RLS never over-exposes.
Workflow actions and row scope
submit is an owner action: the record must be inside the caller's manage scope (otherwise
data.recordNotFound). approve / reject / forward are authorized by the assigned workitem and
withdraw / cancel by originator-or-workitem, so an approver outside the record's row scope can still
act. Workflow status and history are visible inside the read scope or to participants (originator /
any workitem holder).
Details children inherit their parent
A details child is an owned part of its parent record, so its permissions are derived from the
parent object rather than defined on the child:
- A child with no
permissionsis exactly its parent's — read/manage scope and create/update/ delete are taken from the parent. - A child may narrow (declare stricter permissions) but never broaden: the two are intersected
(scope = the narrower one, operations = AND, hidden fields = union). A child declaring broader
permissions than its parent is rejected at load (
permission.detailsChild.broader). - A child belongs to exactly one parent — a shared child must use
relation/multiRelation, notdetails(graph.details.multiParent). - Row scopes are inherited through the parent link: a child row is visible iff its
parent_idpoints at a parent row the subject can read.
Cross-object formula references (relation.target_field, SUM(lines.qty)) are resolved under the
same rules: if the subject cannot read the referenced target (object read permission + row scope +
field exclude), the reference resolves to null rather than leaking data.
Related
- Identity — where the subject and its roles come from
- Multi-tenancy — the scope predicate layered on top of the row scope
- Audit — denied reads/writes are recorded