Scope
query.scope returns filters that the engine adds to every request of the resource. Use it for the tenant, authorization rules and soft-delete conditions: anything that must hold no matter what the client sends.
Without it, every route handler has to remember the tenant filter. One handler that forgets it exposes another tenant's rows.
Define a scope
const query = {
scope: (f: ExampleFilterBuilder, ctx: { orgId: string }) =>
f.and([f.is("customer.orgId", ctx.orgId)]),
};
f is a filter builder typed from the resource's relations. ctx is the context your server passes to query(...), never the client's request.
The scope is combined with the client's top-level filters with AND. A client can narrow the result further, but an OR group from the client stays inside the scope.
The client can't get around it
Below, the sample resource is scoped to acme, and the request tries to OR in another organisation. Open sql: the scope wraps the client's group in the WHERE, and every row is still acme's.
There is no way for a client to:
- remove a scope condition with a top-level
OR; - override it with a conflicting filter;
- see what the scope contains.
Scope through a relation
When the tenant key is on a related table, include that relation in relations so the builder offers the path:
const resourceConfig = {
relations: {
customer: true,
},
query: {
scope: (f: ExampleFilterBuilder, ctx: { orgId: string }) =>
f.and([f.is("customer.orgId", ctx.orgId)]),
},
};
Several conditions
const query = {
scope: (f: ExampleFilterBuilder, ctx: { orgId: string }) =>
f.and([f.is("customer.orgId", ctx.orgId), f.is("deletedAt", null)]),
};
No restriction for some callers
Return an empty group when the context allows access to everything, for example an internal admin:
const query = {
scope: (f: ExampleFilterBuilder, ctx: { isAdmin?: boolean; orgId: string }) => {
if (ctx.isAdmin) return f.and([]);
return f.and([f.is("customer.orgId", ctx.orgId)]);
},
};
Sharing a scope between resources
engine.defineScope(...) returns a callback you can pass as query.scope on several resources.
Scope and field rules
The scope decides which rows a caller can read. Field rules decide which fields clients can use: hide a field like customer.orgId from client filters, while the scope keeps using it.