<a id="dads-frameworkaccess"></a>

# `@dads-framework/access`

Define relationship-based permissions in TypeScript. Use the composed model to enforce permissions, generate a SpiceDB schema, or build scoped lists.

<a id="try-it"></a>

## Try it

In the generated starter, [`libraries/app-runtime/index.ts`](https://dadsframework.dev/docs/source/apps/kit-workbench/libraries/app-runtime/index.ts) defines account and tenant access handles shared by the domains. [`assembly/start-app.ts`](https://dadsframework.dev/docs/source/apps/kit-workbench/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.

```sh
npm install @dads-framework/access zod
npm install -D tsx
```

Save as `team-schema.mts` and run `npx tsx team-schema.mts`.

```ts
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.

<a id="use-it"></a>

## 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.

<a id="what-it-refuses-to-do"></a>

## 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.

<a id="contract"></a>

## 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.

<a id="checking-a-committed-spicedb-schema"></a>

### 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.

```ts
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.

<a id="enforcing-access-in-node"></a>

### 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](https://dadsframework.dev/docs/package-postgres-access) 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.

Canonical page: <https://dadsframework.dev/docs/package-access>
