@dads-framework/access
On this page
Define relationship-based permissions in TypeScript. Use the composed model to enforce permissions, generate a SpiceDB schema, or build scoped lists.
Try it
In the generated starter, libraries/app-runtime/index.ts
defines account and tenant access handles shared by the domains.
assembly/start-app.ts composes the selected API's declarations into one
model before opening its services.
Use Node.js 22 or later. This example emits schema text locally and needs no authorization datastore.
npm install @dads-framework/access zod
npm install -D tsx
Save as team-schema.mts and run npx tsx team-schema.mts.
import {
access,
accessModel,
emitZed,
entityHandle,
} from "@dads-framework/access";
import { z } from "zod";
const user = entityHandle({ wireName: "user", idSchema: z.string() });
const team = entityHandle({
wireName: "team",
idSchema: z.string(),
kind: "scope",
});
const teamAccess = access(team, {
roles: { member: user },
permissions: (roles) => ({ view: [roles.member] }),
});
const userAccess = access(user, { roles: {}, permissions: () => ({}) });
const model = accessModel([userAccess, teamAccess]);
console.log(emitZed(model));
The output includes permission view = member on the team definition.
In a service using this model, test a team member and a user with no member
relationship. The first should see the team's records. The second should
receive a denial or an empty scoped list, according to the operation.
Use it
Define handles and permissions in the packages that own them. At application startup, pass their declarations and optional scopeBindings to accessModel. The model resolves permission expressions after the declaration modules have loaded. Use the same model for schema generation, route registration, and record lookup guards.
For permissions that customers may grant, grantable takes the app's scope names and direct subject handle. Use membersOf to declare an optional group subject. Use lifecycleTrigger(name) to name a grant removal event. The application handles the event and removes the grant.
What it refuses to do
Composition rejects duplicate entity names or scope bindings for an omitted definition. A scope plan with an unbound role or cyclic traversal fails to compile.
Contract
emitAccessIr(model) returns plain data and emitZed(model) produces SpiceDB schema text. checkAccessConformance(model.definitions) checks grant metadata and grant requirements. checkScopeBindings(model) checks the default view permission of each bound record.
Permission expressions support relationship traversal, unions, intersections, and exclusions. Contextual conditions and SpiceDB caveats are outside the compiler's supported syntax.
Checking a committed SpiceDB schema
If your project commits generated Zed, compare that artifact with the output of its current composed model in your schema-generation test. The artifact writer recognizes a Zed file by the exact first line emitted by this kit.
expect(readFileSync(schemaPath, "utf8")).toBe(emitZed(model));
Run the test in CI. Doctor's generated-access check covers edits in Git history. The test checks the file against the model. Apps that emit directly to SpiceDB or run the Postgres adapter need no checked-in Zed file.
Enforcing access in Node
Use @dads-framework/access/runtime for the authorization port, route decisions,
scope answers, and request-local consistency. The runtime entry point keeps
Node request context separate from the model and emitters. Supply a concrete
authorization provider when composing a server. The Postgres adapter
uses the model with relationship facts in the application database. Use its
protected transaction helper when a permission decision guards a business
write in that database. Tests can use @dads-framework/access/testing for
in-memory calls and recorded answers.
Schema migration runners can use @dads-framework/access/schema to plan and
apply a Zed schema through a supplied store. The authorization package binds
that work to SpiceDB and supplies the Postgres outbox, catalog queries, and
optional datastore snapshots.