Access Model

The access model is in beta.

Hand-written read and write rules work well for one or two tables. Once you have organizations, projects inside them, tasks inside projects, and people who hold different roles at each level, the same checks repeat in every rule. defineAccessModel from bijection/server lets you declare that structure once. It generates the bodies of your read, disclosure and write rules and gives your functions helpers to check permissions and manage grants. It is a library that runs inside your own rules, not a separate service: the rules are still queries you export, and Bijection enforces them as it does any other rule.

Concepts

The model has five parts.

Types. Everything you protect is an object of a type. A type is either backed by a table, where each row is an object, or key-only, such as an organization or a group, whose objects exist only as keys in grants. Types form a tree through a parent field on each row. A type without a parent hangs from the built-in root object, whose key is *.
Permissions. A permission is one capability on one type, written type:name, such as task:read or project:grant.viewer. Your code checks permissions, never roles.
Roles. A role is a named bundle of permissions on its own type and on descendant types. project:owner including task:* means a project’s owner can do anything to its tasks.
Grants. A grant says that a user, or the members of a group, hold a role on one object. Grants are rows of a grants table. A row field can also confer a role, such as a task’s assignee field conferring task:assignee on the user it names.
Restrictions. A restriction makes an object require its caller to pass another object, whatever roles they hold. The common case is a tenant: every project belongs to an organization, and only people who pass that organization can reach its projects.

Users are identified by their tokenIdentifier (see Auth in Functions). Grants and row fields that name users store that string.

Declaring a model

bijection/accessModel.ts

import { defineAccessModel } from "bijection/server";

export const access = defineAccessModel({
  categories: { tenant: "any" },
  types: {
    org: { permissions: ["pass", "administer"] },
    project: {
      table: "projects",
      parent: { field: "org", type: "org" },
      restrictions: { root: { type: "org", category: "tenant" } },
      read: { discover: ["_id", "_creationTime", "org", "name"], read: "rest" },
      rowGrants: { createdBy: "project:owner" },
    },
    task: {
      table: "tasks",
      parent: { field: "project", type: "project" },
      write: { edit: "rest", "edit.status": ["status"] },
      rowGrants: { assignee: "task:assignee" },
    },
  },
  roles: {
    "org:admin": ["org:*", "project:*", "task:*"],
    "org:member": ["org:pass", "project:discover", "project:create"],
    "project:owner": ["project:*", "task:*"],
    "project:viewer": ["project:discover", "project:read", "task:read"],
    "task:assignee": ["task:read", "task:edit.status"],
  },
});

defineAccessModel checks the declaration and throws if it is inconsistent, for example if a role names an undeclared permission, if the parents don’t form a tree, or if a role grants a read permission without the permission that makes the object visible.

Types

Field	Description
`table`	The table backing the type. Omit it for a key-only type.
`parent`	`{ field, type, index? }`: the row field holding the parent’s key, the parent’s type, and the index pinning the field (default `by_<field>`). Key-only types can’t have a parent.
`read`	Read permissions by the fields they cover. Every field belongs to exactly one; `"rest"` covers the fields no other permission lists. The permission covering `_id` decides whether the object is visible at all. Default `{ read: "rest" }`.
`write`	Write permissions by the fields they cover. Default `{ edit: "rest" }`.
`permissions`	Additional permission names. `create`, `delete` and one `grant.<role>` per role of the type are always declared.
`rowGrants`	Row fields conferring a role on the users they name, keyed by field name.
`restrictions`	`root: { type, category }`: the tenant the caller must pass. `field: { name, type }`: a row field listing restricting objects (markings). Descendants inherit both.
`category`	For a restricting type, the category of its objects: a fixed name, or `{ from: "key" }` for the prefix of the key before `:`.
`holders`	A permission of the type whose holders may see who holds grants on an object. Without it, only holders of a `grant.*` permission may.

Roles

A role is a list of permissions, written type:name, type:* or type:grant.*. It can also be an object:

Field	Description
`permissions`	The permissions the role bundles.
`maxDuration`	Grants of the role must expire within this many milliseconds, at most 366 days.
`justification`	Every grant of the role needs a written `reason`.
`selfGrant`	A permission of the type whose holders may grant the role to themselves. Such a role must also declare `maxDuration` and `justification`.

Restrictions and categories

categories names each restriction category and how it combines. In an "all" category a caller must pass every restricting object of that category an object carries; in an "any" category, at least one. Passing an object means holding its pass permission. A tenant is a restriction in an "any" category, as tenant above. Markings, such as data:pii, are key-only types listed in a row’s restriction field; adding a marking needs apply on it and removing one needs declassify.

Wiring the rules

The model supplies rule bodies. Export each one as a query, one set per type and one for the grants table:

bijection/access.ts

import {
  disclosureArgs,
  readAccessArgs,
  readAccessResults,
} from "bijection/server";
import { v } from "bijection/values";
import { internalMutation, internalQuery } from "./_generated/server";
import { access } from "./accessModel";

const decides = { args: readAccessArgs, returns: readAccessResults };
const releases = { args: disclosureArgs, returns: readAccessResults };
const governs = { args: { changes: v.array(v.any()) }, returns: readAccessResults };

export const projectRead = internalQuery({ ...decides, handler: access.read("project") });
export const projectDisclose = internalQuery({ ...releases, handler: access.disclose("project") });
export const projectWrite = internalQuery({ ...governs, handler: access.write("project") });

export const taskRead = internalQuery({ ...decides, handler: access.read("task") });
export const taskDisclose = internalQuery({ ...releases, handler: access.disclose("task") });
export const taskWrite = internalQuery({ ...governs, handler: access.write("task") });

export const grantsRead = internalQuery({ ...decides, handler: access.grantsRead });
export const grantsDisclose = internalQuery({ ...releases, handler: access.grantsDisclose });
export const grantsWrite = internalQuery({ ...governs, handler: access.grantsWrite });

// Deletes a grant once it has expired; see Granting and revoking.
export const expireGrant = internalMutation({
  args: { id: v.id("grants") },
  handler: access.expireGrant,
});

Then attach them in your schema. access.grantsTable() defines the grants table with its indexes, and access.inputs() lists the policy inputs every rule of the model reads:

bijection/schema.ts

import { defineSchema, defineTable, makeFunctionReference } from "bijection/server";
import { v } from "bijection/values";
import { access } from "./accessModel";

const rule = (name: string) => makeFunctionReference<"query">(`access:${name}`);
const reads = access.inputs();

export default defineSchema({
  grants: access
    .grantsTable()
    .access({ read: rule("grantsRead"), disclose: rule("grantsDisclose"), reads })
    .govern({ query: rule("grantsWrite"), reads, basis: "original" }),
  projects: defineTable({
    org: v.string(),
    name: v.string(),
    createdBy: v.optional(v.string()),
  })
    .index("by_org", ["org"])
    .index("by_createdBy", ["createdBy"])
    .access({ read: rule("projectRead"), disclose: rule("projectDisclose"), reads })
    .govern({ query: rule("projectWrite"), reads }),
  tasks: defineTable({
    project: v.string(),
    title: v.string(),
    status: v.string(),
    assignee: v.optional(v.string()),
  })
    .index("by_project", ["project"])
    .index("by_assignee", ["assignee"])
    .access({ read: rule("taskRead"), disclose: rule("taskDisclose"), reads })
    .govern({ query: rule("taskWrite"), reads }),
});

The grants table’s write rule uses basis: "original", so the authority to grant a role must exist before the transaction that grants it. Parent fields hold the parent’s key: an ID for a table-backed parent, any string for a key-only one. Each table needs the index its parent names, and each scalar row-grant field a by_<field> index for access.visible. The model doesn’t see your schema, so a missing index fails when a query needs it.

A generated read rule decides a range pinned on the parent field the same way for every row. Add rowsFollowRange: access.rowsFollowRange("task") to the table’s .access to let large ranges be decided once. See Large ranges.

What the generated rules decide

Reads.

Read	Permitted when
One object by ID	The caller passes its restrictions and holds the permissions for the properties read
A range pinned on the parent field	The caller passes the parent’s restrictions and holds the permissions on the parent or above
A range pinned on a row-grant field naming the caller	The role that field confers includes the permissions; each returned row is still decided alone
Any other range	The caller holds the permissions on the `root` object

A read of the whole document needs every read permission of the type. If a type puts a field in a read permission of its own, for example "read.finance": ["budget"], a caller without it can read the other fields only by selecting them. Writes.

Change	Requires
Insert	`create` on the parent. A row-grant field must name only the caller or be covered by the role’s `grant.*` permission. Each marking added needs `apply`.
Update	For each changed field, the write permission covering it, checked against the document before the change
Changed parent field	`delete` where the row was and `create` on the new parent; restrictions the row carried must still apply or be declassified
Changed row-grant field	The matching `grant.*` permission
Changed restriction field	`apply` on each marking added and `declassify` on each one removed
Delete	`delete` on the object, with no grants left on it and no child rows under it

Grants. Inserting a grant of role R on an object requires grant.R on it and respects the role’s maxDuration and justification. Grants are never edited: a change is a revocation plus a new grant. Revoking a grant needs the same grant.R permission, except that users may always remove their own grant and anyone may remove a grant that has expired. The last administrator of a top-level object can’t be removed.

Checking permissions in functions

The rules enforce access. In your functions, the model’s helpers answer questions about it, for example to show or hide a button:

Helper	Returns
`access.can(ctx, permission, type, key)`	`null` or `{ validUntil }` when permitted; throws a `BijectionError` of kind `AccessRefused` otherwise
`access.audited(ctx, permission, type, key)`	The same as `can`, and records the decision in the audit log when the model declares `audit`
`access.permissionsOn(ctx, type, key)`	The caller’s effective permissions on the object, including `create` of child types
`access.visible(ctx, type, { permission, limit })`	Keys of objects of the type the caller reaches; throws rather than truncating past `limit` (default 100)
`access.holders(ctx, type, key)`	The grants and row fields conferring roles on the object, visible to holders of a `grant.*` permission on it or of the type’s `holders` permission
`access.explain(ctx, permission, type, key)`	`{ allowed, path?, refusedBy? }`: how access is reached, or what refuses it

bijection/projects.ts

import { v } from "bijection/values";
import { mutation } from "./_generated/server";
import { access } from "./accessModel";

export const renameProject = mutation({
  args: { id: v.id("projects"), name: v.string() },
  handler: async (ctx, { id, name }) => {
    // A clear error up front. The write rule enforces it regardless.
    await access.can(ctx, "project:edit", "project", id);
    await ctx.db.patch("projects", id, { name });
  },
});

The helpers run as ordinary reads by the caller, so they only see what the caller may read. If a helper needs a row the caller can’t read, the calling function is refused rather than given a guess. Their answers are advisory; the rules decide.

Granting and revoking

Grant a role with access.grant inside a mutation. The grants table’s write rule checks the caller’s authority when the mutation commits:

bijection/sharing.ts

import { v } from "bijection/values";
import { internal } from "./_generated/api";
import { mutation } from "./_generated/server";
import { access } from "./accessModel";

export const shareProject = mutation({
  args: { project: v.id("projects"), user: v.string() },
  handler: async (ctx, args) => {
    await access.grant(
      ctx,
      {
        type: "project",
        object: args.project,
        role: "project:viewer",
        subject: { user: args.user },
        expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000,
      },
      { expire: internal.access.expireGrant },
    );
  },
});

A grant to the members of a group uses subject: { type: "group", key, permission: "member" }, with the group type listed in the model’s groups: { types: ["group"] }. A grant with expiresAt needs the expire option: access.grant schedules your expireGrant mutation at that time, so the grant’s deletion is an ordinary commit and live queries lose access when it happens. reason records why the grant was made. To delete an object, first revoke every grant on it with access.revokeAll(ctx, type, key); the grants write rule decides each revocation, so the caller needs the authority to revoke them.

The first administrator

In a fresh deployment nobody holds any role, so nobody could grant one. While the grants table and every table of the model are empty, a signed-in caller may insert exactly one grant: an administering role of a top-level type, such as org:admin, to themselves.

// In a mutation, as the signed-in user
const identity = await ctx.auth.getUserIdentity();
await access.grant(ctx, {
  type: "org",
  object: "acme",
  role: "org:admin",
  subject: { user: identity!.tokenIdentifier },
});

Model options

Option	Description
`types`	Required. The types, by name.
`roles`	Required. The roles, by `type:name`.
`grants`	The grants table’s name. Default `grants`.
`categories`	Restriction categories, each `"all"` or `"any"`.
`groups`	`{ types, depth }`: types whose members can hold grants, and how deeply groups nest (1 to 3).
`users`	`{ table, index, user }`: resolve callers to a local user key through an identity table keyed by `tokenIdentifier`, instead of using `tokenIdentifier` itself.
`audit`	Record decisions made through `access.audited`, and grant changes made through `access.grant`, `access.expireGrant` and `access.revokeAll`, in the audit log.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Concepts

Declaring a model

Types

Roles

Restrictions and categories

Wiring the rules

What the generated rules decide

Checking permissions in functions

Granting and revoking

The first administrator

Model options

​Concepts

​Declaring a model

​Types

​Roles

​Restrictions and categories

​Wiring the rules

​What the generated rules decide

​Checking permissions in functions

​Granting and revoking

​The first administrator

​Model options

Concepts

Declaring a model

Types

Roles

Restrictions and categories

Wiring the rules

What the generated rules decide

Checking permissions in functions

Granting and revoking

The first administrator

Model options