# RBAC Permissions for Terreno — API Design

**Status:** Draft — API design for discussion (full IP to follow)
**Target package:** `@terreno/api` (new `src/rbac/` module), with surfaces in `admin-backend`, `admin-frontend`, `admin-spa`, `rtk`, and the modelRouter MCP work
**Depends on:** `better-auth/plugins/access` (already a dependency via the Better Auth provider)

---

## 1. Summary

Terreno currently has a binary privilege model: `User.admin: boolean`, plus per-route
`PermissionMethod<T>[]` arrays (`Permissions.IsAdmin`, `IsOwner`, …) with AND semantics. This
plan replaces that with a first-class RBAC module in `@terreno/api`:

- **Permission vocabulary** (resources → actions) is statically defined by the consuming app,
  merged with Terreno defaults, using Better Auth's `createAccessControl` as the engine.
- **Roles** are DB-backed Mongoose documents editable at runtime through the Terreno admin,
  hydrated into Better Auth `Role` objects (`ac.newRole(permissionsFromDb)`) at check time.
  Terreno ships standard roles; consuming apps add their own (SuperUser, PatientGuide, …).
- **Users hold many roles**; effective permissions are the union of all their roles plus any
  grants from **external permission sources** (e.g. a Healthie adapter).
- **Document-level scopes** and **field-level views** cover the dynamic cases RBAC alone can't
  ("any PG can view any patient, but only edit patients on their panel"; "patients see fewer
  fields than staff").
- **One `can()` check** is enforced across REST (modelRouter + custom routes), websockets
  (subscribe + emit), MCP tools, and the admin panel.
- **Everything has a function escape hatch** so consuming apps (Flourish) can migrate
  incrementally without a big-bang rewrite.

Nothing in this design is Flourish-specific; PatientGuide/Healthie examples below are
illustrations of consuming-app usage.

## 2. Concepts

| Concept | What it is | Where it lives |
|---|---|---|
| **Statement** | Map of resource → allowed actions (`{patient: ["read", "update"]}`) | Static, in code, per app (merged with Terreno defaults) |
| **Permission** | One resource:action pair (`patient:update`) | Derived from statements |
| **Role** | Named bundle of permissions (`PatientGuide`) | DB (`RbacRole` collection), editable in admin; Terreno ships defaults |
| **Grant** | Roles/permissions attached to a user | `user.roles: string[]` (+ external sources) |
| **Scope** | Per-document predicate/query narrowing an action (`patient:update` only on panel) | Code, registered by app as functions |
| **Field view** | Per-permission read/write field mask (Patient vs Staff vs SuperUser view) | Code, registered by app |
| **Permission source** | External system contributing grants (Healthie) | Code, adapter interface |

The split is deliberate: **what can be granted** (statements, scopes, views) is code — typed,
reviewed, versioned. **Who has what** (roles, assignments) is data — editable at runtime in the
admin UI. This mirrors Better Auth's own design, where dynamic roles can only recombine a
statically defined vocabulary, and it is what makes "permissions can be dynamically added by the
consuming app but not limited by Terreno" work.

## 3. Module layout

```
api/src/rbac/
  index.ts            # Public exports
  statements.ts       # terrenoStatements, mergeStatements
  access.ts           # createAccess, TerrenoAccess class (wraps better-auth ac)
  roleModel.ts        # RbacRole Mongoose model + terrenoDefaultRoles seed
  userPlugin.ts       # rbacUserPlugin (adds roles: string[] to user schema)
  scopes.ts           # ResourceScope types + evaluation
  fieldViews.ts       # Field view types + apply/pick logic
  middleware.ts       # requireAccess() express middleware, IsPermitted() adapter
  resolve.ts          # Role resolution + caching + PermissionSource merging
  routes.ts           # rbacRouter (roles CRUD, catalog, previews)
  betterAuthBridge.ts # Mirror ac/roles into better-auth admin plugin when enabled
```

Exports land in `@terreno/api` root: `createAccess`, `terrenoStatements`, `terrenoDefaultRoles`,
`rbacUserPlugin`, `rbacRouter`, `IsPermitted`, `requireAccess`, plus all types.

---

## 4. API designs

### 4.1 Permission vocabulary (statements)

Terreno re-exports Better Auth's engine and ships default statements for everything the
framework itself gates today:

```typescript
// api/src/rbac/statements.ts
export const terrenoStatements = {
  // Admin panel access + admin-only surfaces
  admin: ["access", "runScripts", "viewBackgroundTasks"],
  // Managing the RBAC system itself
  rbac: ["read", "manageRoles", "assignRoles"],
  // The framework user model (auth surfaces, admin user CRUD)
  user: ["create", "list", "read", "update", "delete", "impersonate", "setPassword"],
  // Feature flag / configuration app
  configuration: ["read", "update"],
} as const;

export type Statements = Record<string, readonly string[]>;

// Same {resource: [actions]} shape better-auth uses everywhere
export type PermissionSet = {[resource: string]: readonly string[]};
```

The consuming app defines its own vocabulary and merges:

```typescript
// consuming app: src/access.ts
import {createAccess, terrenoStatements} from "@terreno/api";

export const statements = {
  ...terrenoStatements,
  patient: ["create", "read", "update", "delete", "readClinical", "updateClinical"],
  careplan: ["create", "read", "update", "approve"],
  staff: ["create", "read", "update"],
} as const;
```

Notes:

- `as const` is required (Better Auth's literal-type inference).
- Actions are arbitrary strings — apps can model verbs beyond CRUD (`approve`,
  `readClinical`), which is how "abilities" attach to roles.
- Adding a resource/action is a code change + deploy. That is a feature: the vocabulary is the
  contract that scopes, field views, routes, and the admin UI compile against.

### 4.2 `createAccess` — the central object

```typescript
// api/src/rbac/access.ts
import {createAccessControl} from "better-auth/plugins/access";

export interface AccessOptions<S extends Statements> {
  statements: S;
  // Code-defined roles seeded into the DB on boot (upsert; admin can then edit non-locked ones)
  defaultRoles?: RoleDefinition[];
  // Document-level scopes per resource (see 4.5)
  scopes?: ResourceScopes<S>;
  // Field-level views per resource (see 4.6)
  fieldViews?: ResourceFieldViews<S>;
  // External grant providers, e.g. Healthie (see 4.10)
  sources?: PermissionSource[];
  // Actions treated as "read-ish" when expanding the auditor read-only sentinel
  // (READ_ONLY_ROLE_PERMISSIONS — see 4.3). Defaults to READ_ACTIONS; apps add
  // verbs like "readClinical".
  readActions?: readonly string[];
  // Role resolution cache TTL in ms (default 30_000). Roles are DB-backed;
  // checks must not hit Mongo on every request. Keep this short for compliance:
  // revoking a role or assignment must not linger on other replicas until TTL
  // expiry (see cross-instance invalidation on `invalidateCache` in 4.2).
  cacheTtlMs?: number;
  // Escape hatch: full custom resolution of a user's permission set
  resolvePermissions?: (args: {user: User}) => Promise<PermissionSet | null>;
  // Optional human-readable labels for the admin permission matrix
  // (resource → action → description). Returned by GET /rbac/statements.
  statementDescriptions?: Record<string, Record<string, string>>;
}

export const createAccess = <S extends Statements>(options: AccessOptions<S>): TerrenoAccess<S>;
```

`TerrenoAccess` is the one object apps pass around (to `TerrenoApp`, modelRouter options,
realtime, MCP):

```typescript
export interface AccessCheckArgs<S extends Statements> {
  user?: User;
  // Same shape as better-auth: {resource: [actions]}, ANDed across entries
  permissions: PermissionRequest<S>;
  // When present, document scopes for the resource are also evaluated
  doc?: unknown;
  // Extra context threaded into scope functions (req, socket, etc.)
  context?: Record<string, unknown>;
}

export interface AccessResult {
  allowed: boolean;
  // Which layer denied — drives 403 vs 405 and admin debugging UI
  deniedBy?: "role" | "scope" | "source";
  reason?: string;
}

export interface TerrenoAccess<S extends Statements> {
  readonly statements: S;
  // better-auth access controller, exposed for direct use / bridging
  readonly ac: ReturnType<typeof createAccessControl>;

  // The single authorization entry point (role check + optional doc scope check)
  can(args: AccessCheckArgs<S>): Promise<AccessResult>;

  // Union of a user's effective permissions (roles + sources) — powers /auth/me,
  // client gating, and the admin "what does this user have" view. Cached.
  getPermissions(args: {user: User}): Promise<PermissionSet>;

  // Query fragment for list endpoints/subscriptions from the resource's scopes.
  // null means "no access" (empty list), {} means unrestricted.
  queryFilter(args: {
    user?: User;
    resource: keyof S & string;
    action: string;
    context?: Record<string, unknown>;
  }): Promise<Record<string, unknown> | null>;

  // Field mask for a doc + user (see 4.6). Used by responseHandler, realtime, MCP.
  // Mirrors fieldViews.select: `doc` is optional and `undefined` during create
  // (no document exists yet), and `phase` tells the resolver which enforcement
  // point is calling so the same selector yields read/write/create masks. Create
  // resolves the mask from user + permissions alone (see 4.6 "Create-time view
  // resolution"). modelRouter/realtime/MCP call sites pass `phase` explicitly.
  fieldMask(args: {
    user?: User;
    resource: keyof S & string;
    doc?: unknown; // undefined during create
    phase?: "read" | "write" | "create"; // default "read"
  }): Promise<FieldMask>;

  // Express middleware for custom routes (see 4.8)
  middleware(permissions: PermissionRequest<S>, options?: {getDoc?: DocLoader}): RequestHandler;

  // Adapter producing a legacy PermissionMethod so existing modelRouter
  // permission arrays keep working during migration (see 4.7)
  permission(permissions: PermissionRequest<S>): PermissionMethod<unknown>;

  // Role management used by rbacRouter + admin (see 4.9)
  roles: RoleManager;

  // Drop cached role/source hydrations for one user or all users on this process.
  // Production multi-replica deployments (e.g. Cloud Run) also need a shared
  // invalidation channel (Redis pub/sub, version stamp on `RbacRole.updated`, …)
  // so every instance drops stale hydrations when roles are edited — otherwise
  // `/auth/me`, websocket permission resolution, and `getPermissions()` on
  // other replicas serve the old set until `cacheTtlMs` expires. The IP will
  // specify the default transport; apps can plug a custom broadcaster.
  invalidateCache(args?: {userId?: string}): void;
}
```

Check semantics (matches Better Auth): within one resource entry, all listed actions must be
allowed; across resources, entries are ANDed. A user passes a role check if **any** of their
roles authorizes the request (union across roles) — then scopes, which are restrictions, are
ANDed on top.

### 4.3 Roles: DB-backed, hydrated through Better Auth

Why not use Better Auth's role objects directly? Released Better Auth only supports **static**
global roles (dynamic access control exists for the org plugin; the admin-plugin port is an
unmerged PR). The supported escape hatch is to store role → permission JSON ourselves and build
role objects at check time with `ac.newRole()` — that's exactly what we do, and it works
identically whether the app's auth provider is JWT/Passport or Better Auth.

```typescript
// api/src/rbac/roleModel.ts
export interface RbacRoleDocument {
  _id: ObjectId;
  // Stable machine name stored on users ("superadmin", "patientGuide")
  name: string;
  displayName: string;
  description?: string;
  // The better-auth permission JSON: {resource: [actions]}, validated
  // against access.statements on write
  permissions: PermissionSet;
  // Role exclusion rules: users cannot hold this role together with any of
  // these (e.g. patientGuide excludes familyGuide). Enforced symmetrically
  // on assignment.
  excludesRoles: string[];
  // Shipped by Terreno or the app via defaultRoles; locked roles cannot be
  // deleted or have their name changed (permissions remain editable unless
  // sealed — see isSealed).
  isLocked: boolean;
  // When true, the role is immutable through the admin API: name, description,
  // permissions, and excludesRoles cannot be changed or deleted. Only Terreno
  // seeds ship sealed (today: `superadmin`). Locked-but-not-sealed roles (e.g.
  // `admin`, `auditor`) keep a stable name while their permission matrix remains
  // editable in the admin UI.
  isSealed: boolean;
  created: Date;
  updated: Date;
}
```

Default-role `permissions` accept a `RolePermissionSpec`: either a concrete `PermissionSet`, or
one of two **seed-time expansion sentinels** resolved against the *merged* statements when the
role is upserted, so app-defined resources are covered without the app editing Terreno's roles:

```typescript
// api/src/rbac/roleModel.ts
export type RolePermissionSpec =
  | PermissionSet
  | "*" // every action of every resource (superadmin)
  | typeof READ_ONLY_ROLE_PERMISSIONS; // auditor: every read-ish action

// "read-ish" = the intersection of each resource's actions with READ_ACTIONS.
// Terreno's default list; apps can extend via createAccess({readActions}).
export const READ_ACTIONS = ["read", "list", "access", "view"] as const;

// Seed-time sentinel for auditor-style read-only expansion. Reference this
// constant in defaultRoles (`permissions: READ_ONLY_ROLE_PERMISSIONS`).
export const READ_ONLY_ROLE_PERMISSIONS = {readOnly: true} as const;

// Structural check — accepts both the exported constant and any hand-rolled
// `{readOnly: true}` object (TypeScript's structural typing allows the latter).
const isReadOnlySentinel = (
  spec: RolePermissionSpec,
): spec is typeof READ_ONLY_ROLE_PERMISSIONS =>
  typeof spec === "object" &&
  spec !== null &&
  !Array.isArray(spec) &&
  Object.keys(spec).length === 1 &&
  (spec as {readOnly?: unknown}).readOnly === true;

// Applied at seed time inside createAccess, using the merged statements as the source.
export const expandRolePermissions = (
  spec: RolePermissionSpec,
  statements: Statements,
  readActions: readonly string[],
): PermissionSet => {
  if (spec === "*") {
    return mapValues(statements, (actions) => [...actions]);
  }
  if (isReadOnlySentinel(spec)) {
    return filterMapValues(statements, (actions) =>
      actions.filter((a) => readActions.includes(a)),
    );
  }
  return spec;
};
```

Terreno ships default roles (generic names — app-agnostic):

```typescript
// api/src/rbac/roleModel.ts
export const terrenoDefaultRoles: RoleDefinition[] = [
  {
    name: "superadmin", // the "SoftwareEngineer" role, generically named
    displayName: "Super Admin",
    permissions: "*", // expands to every statement action at seed time
    isLocked: true,
    isSealed: true,
  },
  {
    name: "admin",
    displayName: "Admin",
    permissions: {
      admin: ["access"],
      user: ["create", "list", "read", "update"],
      configuration: ["read", "update"],
    },
    isLocked: true,
  },
  {
    name: "auditor",
    displayName: "Auditor",
    // Read-only *everywhere*, including app resources: expands at seed time to
    // every resource's read-ish actions from the merged statements (parallel to
    // superadmin's "*"). Not a hand-listed subset — see expandRolePermissions.
    permissions: READ_ONLY_ROLE_PERMISSIONS,
    isLocked: true,
  },
  {name: "member", displayName: "Member", permissions: {}, isLocked: true},
];
```

Because expansion runs against the merged statements at seed/upsert time, the stored
`RbacRoleDocument.permissions` is always a concrete `PermissionSet` (the sentinel is never
persisted), so runtime checks, the admin matrix, and diffs all see the fully expanded set.

At check time, roles resolve through Better Auth:

```typescript
// api/src/rbac/resolve.ts (internal)
const hydrateRole = (roleDoc: RbacRoleDocument) => ac.newRole(roleDoc.permissions);
// role.authorize({patient: ["update"]}) -> {success: boolean; error?: string}
```

When the app uses the Better Auth provider, `betterAuthBridge.ts` also passes `ac` and the
seeded roles into the better-auth `admin` plugin config so `authClient.admin.checkRolePermission`
(sync, client-side, static roles) and `auth.api.userHasPermission` work natively; DB-edited
roles remain authoritative server-side via `access.can()`.

### 4.4 Assigning roles to users

```typescript
// api/src/rbac/userPlugin.ts
export interface RbacUser {
  // Role names; effective permissions are the union
  roles: string[];
}

export const rbacUserPlugin = (schema: Schema<any, any, any, any>): void => {
  schema.add({
    roles: {
      type: [String],
      default: [],
      index: true,
      description: "RBAC role names assigned to this user",
    },
  });
};
```

Assignment goes through `RoleManager` (never raw writes) so exclusion rules and audit hooks run:

```typescript
export interface RoleManager {
  list(): Promise<RbacRoleDocument[]>;
  create(args: {actor: User; role: RoleInput}): Promise<RbacRoleDocument>;
  update(args: {actor: User; roleName: string; changes: Partial<RoleInput>}): Promise<RbacRoleDocument>;
  remove(args: {actor: User; roleName: string}): Promise<void>;

  // Throws APIError 409 with the conflicting rule if excludesRoles is violated
  assign(args: {actor: User; userId: string; roleNames: string[]}): Promise<void>;
  unassign(args: {actor: User; userId: string; roleNames: string[]}): Promise<void>;

  // Diff previews for the admin UI (see 4.11)
  previewRoleChange(args: {roleName: string; permissions: PermissionSet}): Promise<RoleDiff>;
  previewAssignment(args: {userId: string; roleNames: string[]}): Promise<UserPermissionDiff>;
}

export interface RoleDiff {
  gained: PermissionSet;
  lost: PermissionSet;
  affectedUserCount: number;
}

export interface UserPermissionDiff {
  gained: PermissionSet; // net-new after union with their other roles
  lost: PermissionSet;
  resulting: PermissionSet;
}
```

Guardrails baked into `RoleManager` (borrowed from Better Auth's dynamic access control):

- **No escalation**: an actor can only grant (or edit a role to include, or assign) permissions
  the actor **themselves currently holds**. Holding `rbac:manageRoles` lets an actor *manage*
  roles but never lets them hand out actions they lack — a role editor cannot bootstrap
  privileges they do not have. The **only** exception is `superadmin`, which (via its `"*"`
  expansion) holds every permission and so can grant anything; this is a property of *what
  superadmin holds*, not a special "manageRoles can escalate" rule. Concretely: the check is
  `actorPermissions ⊇ permissionsBeingGranted`, evaluated against the actor's effective set.
- **Vocabulary validation**: every `resource:action` in `permissions` must exist in
  `access.statements` — writes with unknown pairs are 400s.
- **Managing roles requires** `rbac:manageRoles`; assigning requires `rbac:assignRoles`. These
  gate *access* to the operation and are additive to (not a substitute for) the no-escalation
  subset check above.
- **`excludesRoles` remediation**: assignment-time 409s are not enough when an admin later
  *adds* an exclusion to a role that conflicts with roles users already hold. `RoleManager.update`
  rejects the role change (400) until every affected user is remediated — the error payload lists
  conflicting `(userId, roleA, roleB)` tuples. Admins resolve via `previewRoleChange` (shows
  affected users) and explicit `unassign` calls; Terreno never silently leaves a violated
  invariant in place.
- **Audit (required)**: every successful `RoleManager` create/update/remove/assign/unassign
  **must** emit an `RbacAudit` record (built-in collection and/or pluggable sink — see 7.4).
  Denied escalation attempts (actor tried to grant permissions they lack) are also logged at
  `warn` with actor, target, and the rejected permission delta for abuse detection.

### 4.5 Document-level scopes (the dynamic layer)

RBAC answers "can PatientGuides update patients?" Scopes answer "**this** patient?" They are
functions in code (typed against the app's models), keyed by resource and action:

```typescript
// api/src/rbac/scopes.ts
export interface ScopeArgs<TDoc> {
  user: User;
  action: string;
  doc?: TDoc; // absent during pre-flight (create/list) checks
  context?: Record<string, unknown>; // req, socket, mcp session...
}

export interface ResourceScope<TDoc = unknown> {
  // Object-level predicate; runs after the role check passes.
  // Return true/false, or a PermissionSet to demand extra permissions
  // (e.g. editing a doc in "final" status requires careplan:approve).
  check?: (args: ScopeArgs<TDoc>) => boolean | PermissionSet | Promise<boolean | PermissionSet>;
  // Mongo query fragment for list/subscription filtering — the same
  // constraint as `check`, expressed as a query. null = no access.
  filter?: (args: ScopeArgs<TDoc>) => Promise<Record<string, unknown> | null>;
}

// Keyed "resource.action"; "resource.*" applies to all actions of the resource
export type ResourceScopes<S extends Statements> = {
  [key: string]: ResourceScope;
};
```

**Coupling `check` and `filter` (no drift).** A per-document `check` and a list/subscription
`filter` that express *different* constraints silently corrupt authorization: a list could
return rows a per-doc read would reject, or vice versa. The design forbids that two ways:

1. **`defineScope` factory (preferred).** A scope is derived from a single predicate expressed
   once as a Mongo query fragment. The factory produces the `filter` (the fragment) and the
   `check` (the same fragment evaluated against the in-memory doc via a lightweight matcher),
   so the two can never disagree:

   ```typescript
   export interface ScopeDefinition<TDoc> {
     // The one source of truth: the constraint as a query fragment (null = no access).
     matches: (args: ScopeArgs<TDoc>) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
     // Optional elevation that skips the constraint for both check and filter.
     adminBypass?: (args: ScopeArgs<TDoc>) => boolean | Promise<boolean>;
     // How to read a field path off a loaded doc before comparison (defaults to
     // dot-path lookup). Used when a fragment references populated refs — unwrap
     // and normalize (e.g. string-coerce ObjectIds) here. The generated `check`
     // evaluates the full `matches` fragment against the in-memory doc using the
     // same semantics as Mongo (equality, `$in`, `$eq`, …) via a lightweight
     // matcher — not only flat String equality on a single leaf.
     fieldOf?: (doc: TDoc, path: string) => unknown;
   }

   // Returns {check, filter} whose logic is guaranteed identical.
   export const defineScope = <TDoc>(def: ScopeDefinition<TDoc>): ResourceScope<TDoc>;
   ```

2. **Parity tests for hand-written scopes.** When an app supplies a raw `{check, filter}` pair
   (needed for constraints not expressible as a static fragment), Terreno ships a
   `assertScopeParity(scope, {samples})` test helper and requires each such scope key to have a
   conformance test that feeds sample docs/users through both `check` and the `filter`-derived
   query and asserts they agree. `createAccess` warns (dev) when a scope defines both `check`
   and `filter` by hand without a registered parity test.

Consuming-app example (the PatientGuide panel case) — **`defineScope` so check and filter
cannot drift**:

```typescript
// One helper encodes the constraint once; both list/subscription filter and per-doc
// check evaluate the same predicate (supervisor-of-pod, on-panel, or active PTO coverage).
const patientUpdateScope = defineScope<PatientDocument>({
  matches: async ({user, doc}) => {
    const staff = user as unknown as StaffDocument;
    const editableIds = await editablePatientIds(staff); // shared: panel + PTO + supervised pods
    if (!editableIds.length) {
      return null;
    }
    // List/subscription: constrain to the same id set the per-doc check uses.
    return {_id: {$in: editableIds}};
  },
  // Per-doc check: fragment value vs doc._id (String equality, ObjectId-safe).
  fieldOf: (doc, path) => (path === "_id" ? String(doc._id) : undefined),
});

const access = createAccess({
  statements,
  scopes: {
    // Any role with patient:read can read any patient — no read scope.
    "patient.update": patientUpdateScope,
    "careplan.approve": defineScope<CareplanDocument>({
      matches: ({user}) => (user ? {assignedPsychiatristId: user.id} : null),
      fieldOf: (doc, path) =>
        path === "assignedPsychiatristId" ? String(doc.assignedPsychiatristId) : undefined,
    }),
  },
});
```

When a scope truly cannot be expressed as one Mongo fragment (rare), supply a hand-written
`{check, filter}` pair **and** register `assertScopeParity(scope, {samples})` covering every
branch (panel vs PTO vs cross-pod supervisor, etc.). `createAccess` warns in dev if both are
hand-written without a parity test — the anti-pattern is divergent predicates, not hand-writing
per se.

Semantics:

- Scopes are **restrictions only** — they can never grant an action the user's roles don't
  include. Role check first, scope second. (`superadmin` does not bypass scopes by default;
  a scope can opt in by checking permissions itself.)
- `check` without a `doc` (create pre-flight) is only called if defined for the action; scopes
  that need a doc are skipped pre-flight and enforced post-load — same two-phase flow the
  current `permissionMiddleware` already implements (405 pre-object, 403 post-object).
- `filter` is merged (`$and`) with `queryFields`/`defaultQueryParams` in list handlers and
  websocket query subscriptions — replacing today's ad-hoc `queryFilter`/`OwnerQueryFilter`.

Terreno ships the common scope as a helper, replacing `Permissions.IsOwner` + `OwnerQueryFilter`.
Its per-document behavior must preserve today's `IsOwner` semantics exactly: **admins bypass
ownership** — `IsOwner` returns `true` for `user.admin === true` on any document. Note the current
`OwnerQueryFilter` does *not* share that bypass: it always narrows list queries to
`{ownerId: user.id}` and never checks `user.admin`, so today an admin's per-document access and
their list access disagree (admins can read/update any single owned-model doc but list endpoints
still scope them to their own rows). `OwnerScope` deliberately unifies the two behind one
`adminBypass` predicate (default: the legacy `user.admin` flag) applied to **both** the per-doc
`check` and the list/subscription `filter` (where the bypass yields `{}` — no narrowing), so
admins get consistent unrestricted read/update/delete/list access and migrated flows lose no
privilege:

```typescript
export interface OwnerScopeOptions {
  field?: string; // owner id path, default "ownerId"
  // Elevated actors that skip the ownership constraint entirely.
  // Default preserves legacy IsOwner behavior (user.admin === true) and also
  // treats holders of the superadmin role as unrestricted.
  adminBypass?: (args: {user?: User}) => boolean | Promise<boolean>;
}

export const OwnerScope = (options: string | OwnerScopeOptions = {}): ResourceScope => {
  const {field = "ownerId", adminBypass = defaultAdminBypass} =
    typeof options === "string" ? {field: options} : options;
  return defineScope<unknown>({
    // One predicate drives both check and filter (see below); adminBypass short-circuits both.
    adminBypass,
    // Mongo filter matches the raw stored ownerId (an ObjectId) against the user id.
    matches: ({user}) => (user ? {[field]: user.id} : null),
    // The in-memory check must mirror IsOwner exactly: unwrap a *populated*
    // ownerId (`{_id}`) and normalize to a string so ObjectId, string, and
    // populated-document shapes all compare equal. defineScope's generated
    // `check` applies String(...) equality between the fragment value and this
    // return (see fieldOf note in 4.5), matching Mongo's ObjectId coercion — so
    // a populated `ownerId` is never falsely denied.
    fieldOf: (doc) => {
      const owner = (doc as Record<string, unknown> | undefined)?.[field];
      const ownerId = (owner as {_id?: unknown} | null | undefined)?._id ?? owner;
      return ownerId == null ? undefined : String(ownerId);
    },
  });
};

// defaultAdminBypass = ({user}) => Boolean((user as any)?.admin) || hasRole(user, "superadmin")
```

Because `OwnerScope` bypasses for admins, the "superadmin does not bypass scopes by default"
rule in 4.5 is a rule about *generic* scopes; ownership-style scopes opt into elevation
explicitly through `adminBypass` so no privilege is silently lost during migration.

### 4.6 Field-level views (attribute permissions)

Named projections per resource, chosen by a function of user + doc, applied everywhere a
document is serialized (REST responses, realtime emits, MCP tool output) and validated on write:

```typescript
// api/src/rbac/fieldViews.ts
export interface FieldMask {
  read: string[] | "*"; // dot paths; "*" = all
  write: string[] | "*";
  omit?: string[]; // always stripped even from "*" (hash, salt, ...)
}

export interface ResourceFieldViews<S extends Statements> {
  [resource: string]: {
    views: Record<string, FieldMask>;
    // Pick a view for this user + (maybe) doc. Function escape hatch: return a
    // FieldMask directly for fully dynamic cases.
    //
    // `doc` is OPTIONAL because it is absent at create time (no document exists
    // yet). `phase` tells the selector which enforcement point is calling:
    //   - "read"  : serializing a loaded doc (doc always present)
    //   - "write" : validating an update body against an existing doc (doc present)
    //   - "create": validating a create body — doc is undefined; the selector
    //               must decide from user + permissions alone.
    // Selectors that branch on `doc` fields must handle `doc === undefined` for
    // the create phase (see create-time resolution below).
    select: (args: {
      user?: User;
      doc?: unknown; // undefined during create
      permissions: PermissionSet; // the user's effective set, pre-resolved
      phase: "read" | "write" | "create";
    }) => string | FieldMask | Promise<string | FieldMask>;
  };
}
```

**Create-time view resolution.** Because no document exists yet, create validation resolves the
write mask from the user's permissions only:

- The selector is called with `phase: "create"` and `doc: undefined`. It should return a view
  keyed off `user`/`permissions` (the common case — the `patient` example below already does
  this, since its branches read only `permissions`).
- If a selector *needs* a doc and returns nothing usable when `doc` is undefined, `createAccess`
  requires an explicit `createView?: string | FieldMask` (or `createView: "deny"`) per resource
  as the fallback; omitting it while a selector dereferences `doc` is a boot-time config error,
  not a silent full-access default.
- The chosen mask's `write` paths are the create allow-list; body keys outside it are rejected
  exactly as in update. `read`/`omit` from the same mask then shape the create response.

Consuming-app example (Patient vs Staff vs SuperUser views):

```typescript
fieldViews: {
  patient: {
    views: {
      self: {read: ["name", "email", "appointments", "careTeam"], write: ["name", "email"]},
      staff: {read: "*", write: ["name", "email", "podId", "notes"], omit: ["ssn"]},
      full: {read: "*", write: "*", omit: []},
    },
    select: ({user, doc, permissions}) => {
      if (permissions.patient?.includes("updateClinical")) {
        return "full";
      }
      if (permissions.staff?.includes("read")) {
        return "staff";
      }
      return "self";
    },
  },
},
```

Enforcement points:

- **Read**: `defaultResponseHandler` and `realtimeResponseHandler` call
  `access.fieldMask()` and strip; MCP handlers do the same.
- **Write**: create/update handlers reject (400 with field-level errors) any body key outside
  the mask's `write` — replacing the deprecated `TerrenoTransformer.transform`. Update resolves
  the mask with the loaded doc (`phase: "write"`); create resolves it without a doc
  (`phase: "create"`) per the create-time rule above.
- The OpenAPI spec documents the superset; masks are runtime behavior (same as today's
  responseHandler stripping).

### 4.7 modelRouter integration

New `access` option; `permissions` arrays stay supported (deprecated) for migration:

```typescript
export interface ModelRouterAccessOptions {
  // Must be a key of access.statements
  resource: string;
  // Optional REST-method → action override. Defaults:
  // list → "list" if the resource declares it, else "read"; read → "read";
  // create → "create"; update → "update"; delete → "delete".
  actions?: Partial<Record<RESTMethod, string | null>>; // null disables the method
  // Per-route additions layered on the registry-level config
  scope?: ResourceScope;
  // Per-method function escape hatch, same signature as today's
  // PermissionMethod — ANDed after the RBAC check
  also?: Partial<Record<RESTMethod, PermissionMethod<unknown>[]>>;
  allowAnonymous?: boolean;
}

export interface ModelRouterOptions<T> {
  /** @deprecated use `access` */
  permissions?: RESTPermissions<T>;
  access?: ModelRouterAccessOptions;
  // queryFilter still works and is $and-merged with scope filters
  // ...
}
```

Usage:

```typescript
export const patientRouter = modelRouter("/patients", Patient, {
  access: {
    resource: "patient",
    actions: {delete: null}, // disabled, like today's []
  },
  queryFields: ["_id", "podId", "status"],
  sort: "-created",
});
```

Route behavior (unchanged status semantics): missing role permission pre-object → 405 with the
verb omitted from OpenAPI only when statically disabled (`actions.delete = null`); scope denial
post-object → 403. `instanceActions`/`collectionActions` gain the same
`access?: {resource, action}` option alongside their `permissions` arrays.

For apps not ready to restructure a router, the adapter keeps the old shape working:

```typescript
permissions: {
  create: [IsPermitted(access, {patient: ["create"]})],
  list: [IsPermitted(access, {patient: ["read"]})],
  read: [IsPermitted(access, {patient: ["read"]})],
  update: [IsPermitted(access, {patient: ["update"]}), SomeLegacyCheck],
  delete: [],
},
```

`IsPermitted` returns a standard `PermissionMethod` — it calls `access.can()` with the doc when
present, so it slots into existing arrays and AND-composes with legacy checks.

### 4.8 Custom routes, websockets, MCP

**Custom routes** — one middleware replaces the ad-hoc `adminGuard`s:

```typescript
router.post("/patients/:id/discharge", [
  authenticateMiddleware(),
  access.middleware({patient: ["update"], careplan: ["approve"]}, {
    getDoc: (req) => Patient.findOneOrThrow({_id: req.params.id}), // enables scope checks
  }),
  createOpenApiBuilder(options)./* ... */.build(),
], asyncHandler(async (req, res) => { /* ... */ }));
```

**Websockets** — `RealtimeApp` swaps its internals to the same object:

- `subscribe:model` / `subscribe:query` → `access.can({permissions: {[resource]: [listAction]}})`
  plus `access.queryFilter()` merged into the subscription query.
- Per-event emission (`canReadDocument`) → `access.can({..., doc})`, then
  `access.fieldMask()` before serializing — so a patient and a staff member in the same room
  receive different payloads.
- **Identity**: socket users are currently rebuilt from JWT claims only. Because roles are
  DB-editable, the socket path resolves roles through `access.getPermissions()` (cached,
  invalidated on role edit) rather than trusting `decodedToken.admin`. `generateJWTPayload`
  may still embed `roles` as a hint, but the DB is authoritative.

**MCP** — the planned modelRouter MCP handlers (docs/tasks/model-router-mcp.md) already route
through `checkPermissions()`; they call `access.can()`/`fieldMask()` instead, with
`context: {transport: "mcp"}` so scopes can distinguish transports if needed.

### 4.9 RBAC HTTP surface

Mounted by registering the router (a `TerrenoPlugin`), colocated with the admin basePath:

```typescript
new TerrenoApp({userModel: User, accessControl: access})
  .register(rbacRouter({access, userModel: User}))
  .register(patientRouter)
  .start();
```

| Method | Path | Permission | Purpose |
|---|---|---|---|
| GET | `/rbac/statements` | `rbac:read` | Full vocabulary (+ optional `statementDescriptions`) for the admin UI |
| GET | `/rbac/roles` | `rbac:read` | List roles with permissions + user counts |
| POST | `/rbac/roles` | `rbac:manageRoles` | Create role |
| PATCH | `/rbac/roles/:name` | `rbac:manageRoles` | Edit role (validates vocabulary, escalation, locks) |
| DELETE | `/rbac/roles/:name` | `rbac:manageRoles` | Delete (blocked for locked roles / roles in use) |
| POST | `/rbac/roles/:name/preview` | `rbac:manageRoles` | `RoleDiff`: permissions gained/lost + affected user count |
| GET | `/rbac/users/:id/permissions` | `rbac:read` | Effective `PermissionSet` + which role/source grants each |
| PUT | `/rbac/users/:id/roles` | `rbac:assignRoles` | Replace assignments (409 on exclusion conflicts) |
| POST | `/rbac/users/:id/roles/preview` | `rbac:assignRoles` | `UserPermissionDiff` for the confirmation modal |

`GET /auth/me` additionally returns `roles: string[]` and `permissions: PermissionSet` so
clients can gate UI without extra round-trips (server remains authoritative).

### 4.10 External permission sources (Healthie)

Healthie (and future integrations) contribute grants without owning the model:

```typescript
// api/src/rbac/resolve.ts
export interface PermissionSourceGrants {
  roles?: string[]; // must exist in RbacRole
  permissions?: PermissionSet; // direct grants, validated against statements
  deny?: PermissionSet; // hard denials — win over every grant
}

export type StaleOnFailurePolicy =
  | "deny" // default — drop this source's grants on refresh failure (fail closed)
  | "use-stale" // reuse last successful grants (never for elevation-only sources)
  | "use-stale-bounded"; // reuse stale grants only if younger than staleMaxAgeMs

export interface PermissionSource {
  name: string;
  ttlMs?: number; // per-source cache (default: access cacheTtlMs)
  // What to do when getGrants() fails after a prior successful fetch.
  // Default "deny": external grants are omitted; local DB roles still apply.
  // Sources that can elevate beyond local roles must use "deny" or
  // "use-stale-bounded" with a short staleMaxAgeMs — never unbounded stale reuse.
  staleOnFailure?: StaleOnFailurePolicy;
  staleMaxAgeMs?: number; // required when staleOnFailure === "use-stale-bounded"
  getGrants(args: {user: User}): Promise<PermissionSourceGrants | null>;
}
```

Consuming-app sketch:

```typescript
const healthieSource: PermissionSource = {
  name: "healthie",
  ttlMs: 5 * 60_000,
  getGrants: async ({user}) => {
    const staff = await Staff.findOneOrNone({userId: user.id});
    if (!staff?.healthieId) {
      return null;
    }
    const healthieRole = await healthieClient.getProviderRole(staff.healthieId);
    return {roles: [healthieRoleMap[healthieRole] ?? "member"]};
  },
};
```

Resolution order inside `getPermissions()` / `can()`:
`union(user.roles, source roles, source permissions)` minus `source denies`.

**Source refresh failures (fail closed by default).** When `getGrants()` throws or times out,
behavior is per-source `staleOnFailure` (default `"deny"`):

| Policy | Behavior |
|---|---|
| `"deny"` (default) | Omit this source's grants for the request. Local `user.roles` and other sources still apply. Revoked upstream access cannot linger because a dependency is down. |
| `"use-stale-bounded"` | Reuse the last successful grants only if younger than `staleMaxAgeMs` (hard cap). Suitable for read-only hints, not elevation. |
| `"use-stale"` | Reuse last successful grants until TTL expiry. **Not permitted** for sources that can grant roles/permissions beyond what local roles already provide — elevation paths must fail closed. |

`PermissionSource.deny` already fails closed; grant caching matches that posture for elevation.
Logged at `warn` with source name and policy applied.

### 4.11 Admin UI (first-class)

New screens in `admin-frontend` / `admin-spa`, driven entirely by the 4.9 endpoints:

- **Roles list** (`/admin/roles`): every role, its permission matrix (resources × actions
  grid from `/rbac/statements`), user count, locked/sealed badges.
- **Role editor**: checkbox matrix; on save, shows the `/preview` `RoleDiff` in a confirmation
  modal — "PatientGuide will **gain** `careplan:approve` and **lose** `user:create`; affects
  212 users."
- **User role assignment** (embedded in the admin user detail): multi-select of roles with
  exclusion conflicts surfaced inline; confirmation modal shows `UserPermissionDiff` (total
  permissions gained/lost after union with their remaining roles).
- **Effective permissions inspector**: per user, each permission annotated with its source
  ("via PatientGuide", "via healthie").

The admin panel itself migrates from `IsAdmin` to `admin:access` (+ per-model resources), which
finally makes graded admin access possible (the `auditor` role gets `admin:access` + read-only
model permissions).

### 4.12 Client-side helpers

- `@terreno/rtk`: `useSelectPermissions()` / `useCan({patient: ["update"]})` selectors reading
  the `permissions` from `/auth/me`. When the Better Auth provider is active, static roles also
  work with `authClient.admin.checkRolePermission` via the bridge.
- `@terreno/ui`: nothing required; apps gate with `useCan` + existing components.

---

## 5. Migration path

1. **Ship the module inert.** `createAccess` etc. exist; nothing changes unless an app passes
   `access` options. Legacy `Permissions.*` remain exported.
2. **Legacy shims.** `Permissions.IsAdmin` becomes `IsPermitted(access, {admin: ["access"]})`
   semantics when an access registry is configured: seed maps `user.admin === true` →
   `superadmin` role (a one-time backfill script Terreno provides:
   `bunx terreno rbac:backfill-admins --role-map ./rbac-role-map.json`). The map file is
   required when legacy role names do not match Terreno defaults (e.g. Flourish StaffRole →
   RBAC role name); the script dry-runs by default and supports per-tenant overrides.
   `IsOwner`/`OwnerQueryFilter` → `OwnerScope`.
3. **Router-by-router adoption** in consuming apps via `IsPermitted` in existing arrays, then
   the full `access:` option. The `also:` escape hatch and function-based scopes mean any
   existing bespoke check can be ported verbatim as a function first, refined later.
4. **Flip the admin packages** to `admin:access`, ship the roles UI.
5. **Realtime + MCP** switch internally to `access.can()` (no consumer API change).
6. Deprecate `RESTPermissions` arrays in a future major.

## 6. Staff roles — recommendation (open for discussion)

The question posed: single staff role (PG/FG/Therapist/Psychiatrist) vs. rules that disallow
combinations.

**Recommendation: keep StaffRole as consuming-app domain data, and use `excludesRoles` for the
constraint** rather than forcing single-role:

- `excludesRoles` (4.3) gives "cannot be both PG and FG" declaratively, enforced at assignment
  time with a clear 409, and is visible in the admin UI. It generalizes (Supervisor+Auditor
  could also be excluded) without a schema change.
- A hard single-role rule couples Terreno to one org design and dies the first time someone is
  legitimately dual-hatted (Therapist who supervises). Exclusion rules express the actual
  invariant ("these two conflict") instead of a blanket cardinality.
- StaffRole-as-domain-concept (what appears on schedules, care team displays, Healthie sync)
  should *reference* an RBAC role for its permissions but remain a separate model in the
  consuming app — permissions are what the RBAC system owns; job titles are not. The Healthie
  source (4.10) maps Healthie provider types onto RBAC roles the same way.
- The pod-scoped supervisor problem ("Onyx PG Supervisor shouldn't touch Lilac PGs") is
  deliberately **not** a role: it's a scope (4.5) keyed on the supervision relationship, so one
  `supervisor` role works across pods without a role-per-pod explosion.

New scoped roles like "Human Resources" (`staff:create`, `user:create`, no `patient:*`) then
fall out of the admin UI with zero code — the exact win the RBAC move is for.

## 7. Resolved decisions (formerly open questions)

1. **Top role name**: **`superadmin`** (generic machine name; apps customize `displayName`).
2. **Should scopes ever grant?** **No — restrictions only.** Grant cases use extra actions
   (`readClinical`) instead.
3. **Per-permission scope bypass for superadmin**: **Default off**; opt in per scope via
   `adminBypass` (as `OwnerScope` does).
4. **Role assignment audit trail**: **Separate `RbacAudit` collection** from consuming-app
   audit logs (e.g. Flourish `AuditLogEvent`), but **every** successful role/assignment write
   must emit an audit record — built-in and/or pluggable sink; optional/minimal logging is not
   sufficient for HIPAA consumers. Fields: actor, action, target role/user, permission delta,
   timestamp. Denied escalation attempts are logged too (see 4.4).
5. **JWT `roles` claim**: **Hint only** (DB authoritative, cached). Multi-replica cache
   invalidation is part of the IP so `/auth/me` and websockets do not lag role edits across
   Cloud Run instances (see `invalidateCache` in 4.2).
6. **Deny semantics**: **Only `PermissionSource.deny`** — roles do not carry negative
   permissions (union semantics stay simple; matches Better Auth).

## 8. Phasing sketch (full task breakdown in the IP)

1. **Core**: statements/merge, `createAccess`, resolve+cache, `RbacRole` model + seeds,
   `rbacUserPlugin`, `IsPermitted`, `requireAccess` middleware. Tests.
2. **modelRouter**: `access` option, scope-aware permission middleware, filter merging,
   field-mask response handling, actions support.
3. **HTTP surface**: `rbacRouter`, previews, `/auth/me` extension, backfill script.
4. **Admin**: roles screens, diffs, user assignment, `admin:access` migration.
5. **Realtime + MCP**: swap internals to `access.can()`/`fieldMask()`.
6. **Sources + client**: `PermissionSource`, rtk selectors, Better Auth bridge, docs +
   example-backend/-frontend demonstration (example app gets a `manager` role and a scoped
   todo example).