Browse documentation

@dads-framework/authorization

On this page

Keep access decisions tied to the same relationship model across route guards, list filters, and writes. This package exposes those operations and supplies a SpiceDB adapter, an outbox, and a fake for tests.

Try it

The generated starter uses Postgres for authorization in assembly/services.ts. For the SpiceDB adapter, see the repository's SpiceDB integration test, which checks a permitted grant and denies a subject with no relationship.

Use Node.js 22 or later and a fresh local SpiceDB datastore. This example replaces the datastore's entire schema. The Docker command starts an ephemeral testing instance with its gRPC port bound to loopback.

Shell
npm install @dads-framework/authorization
npm install -D tsx
docker run --rm -p 127.0.0.1:50051:50051 authzed/spicedb:v1.57.0 serve-testing

In another terminal, save this as check-access.mts and run npx tsx check-access.mts.

TypeScript
import {
  SpiceDbAuthorization,
  relationshipWrite,
} from "@dads-framework/authorization";

const authorization = new SpiceDbAuthorization({
  endpoint: "127.0.0.1:50051",
  presharedKey: "quickstart",
  insecure: true,
  consistency: "fully-consistent",
});

await authorization.writeSchema(`
definition user {}
definition project {
  relation viewer: user
  permission view = viewer
}
`);

const resource = { type: "project", id: "project-1" };
const subject = { type: "user", id: "alice" };
const query = { resource, subject, permission: "view" };

console.log(await authorization.check(query));
await authorization.writeRelationships([
  relationshipWrite(resource, "viewer", subject),
]);
console.log(await authorization.check(query));

The first run prints false and then true. Restart the container to clear the grant before repeating the example. For unit tests of direct grants, use FakeAuthorization from @dads-framework/authorization/testing.

Use it

Create a SpiceDbAuthorization for the application's datastore. Wrap it in GuardedAuthorization with the guard thresholds and authorizationKinds(model), using the same model as the HTTP routes. Use DEFAULT_AUTHORIZATION_GUARD_MARKS for the default thresholds.

For scoped lists, planScopedList(model, resourceType, permission) compiles the scope at startup. answerScope looks up the scope IDs for the authenticated caller. Pass the answer, the record's SQL bindings, and any related bindings to scopePredicate to build the filter. Use keepPermitted to recheck the selected rows.

What it refuses to do

The guard refuses to enumerate visible IDs for records unless the model declares a sparse direct grant or an active dated exception. The SQL renderer refuses to traverse a record without supplied SQL bindings.

Contract

Authorization provides permission checks, ID lookups, and relationship writes. RequestSubject resolves a request's authenticated subject. The testing fake implements direct relationships for unit tests. WireResourceRef (also exported as ResourceRef) contains the string kind and ID passed to the adapter.

createApplyAccessChangesAfterCommit projects a save's own authorization facts after commit. If another worker holds those facts, it briefly polls their status before returning. The durable outbox makes the remaining work replayable.

The authorization client, outbox, and migration helpers use the shared @dads-framework/access/runtime port. Their existing authorization exports are available for consumers of this package. An HTTP adapter can use the runtime port without loading a database or SpiceDB client.