resolve.ts · Source

resolve.tspackages/permissions/src/resolve.tsraw ← src11,726 B← Back to the app
1/**
2 * @factory/permissions — the permission decision engine.
3 *
4 * Pure and deterministic: no I/O, no DB, no auth. The API layer resolves the
5 * request context (user, their teams, their workspace role, the ancestor
6 * chain from the workspace root to the resource, the grants and shares that
7 * apply) and gets back an explainable {@link PermissionLevel}.
8 *
9 * ## Resolution contract (Phase-3 decision — the API codes against this)
10 *
11 * For a request `req`:
12 *
13 * a) `workspaceRoot := req.resourceType === "workspace"`.
14 *
15 * b) **base** — role baseline:
16 *    `owner → full_access`, `admin → full_access`,
17 *    `member → edit` (workspace root) **or `view`** (any descendant),
18 *    `guest → view` (workspace root) **or `none`** (any descendant).
19 *    (Rationale for the descendant collapse to `view`/`none`: the baseline
20 *    exists so that workspace sharing has something to act on; a guest has no
21 *    default access at all below the workspace root.)
22 *
23 * c) **inherited** — grants on an *ancestor*: walk `req.ancestorChain` from
24 *    the nearest ancestor up to the root (the resource itself is the last
25 *    chain entry and is excluded; the workspace-root entry is simply the
26 *    farthest ancestor — grants on the workspace inherit to everything
27 *    below). The **nearest ancestor that has ≥1 applicable grant wins** and
28 *    its max applicable level is `inherited`; a nearer ancestor whose grants
29 *    do not match the requester is skipped, not a block. No applicable grant
30 *    on any ancestor → `"none"`. (A grant on a closer ancestor always beats
31 *    a grant on a farther one — no `max` across levels.)
32 *
33 * d) **explicit** — grants on the *exact* resource (`resourceType` +
34 *    `resourceId` both match), max applicable level, `"none"` if none.
35 *    **Applicable** grantee match: `user` → `granteeId === userId`,
36 *    `team` → `granteeId ∈ userTeams`, `role` → `granteeId === workspaceRole`.
37 *
38 * e) **share** — max level over the shares visible to the requester
39 *    ({@link shareVisibility}): `"public"` → its level, `"workspace"` → its
40 *    level, `"team"` → its level iff the user is in `teamId`'s team,
41 *    `"users"` → its level iff the user is in `userIds`, `"private"` → never.
42 *    No visible share → `"none"`.
43 *
44 * f) **final** —
45 *    `final = explicit !== "none" ? explicit : maxLevel(inherited, maxLevel(base, share))`
46 *
47 * Explicit grants therefore **override everything and can RESTRICT below the
48 * role baseline** (that is the point of per-resource grants); otherwise the
49 * effective level is the **max** of inheritance, role baseline and shares
50 * (shares are always a floor, never a ceiling).
51 *
52 * Every step appends human-readable strings to `reasons`, so any decision is
53 * explainable and auditable (the API logs them / attaches them to FORBIDDEN
54 * errors via {@link check}).
55 */
56 
57import { ApiError, ErrorCodes } from "@factory/shared/errors";
58 
59import {
60  levelAtLeast,
61  maxLevel,
62  type PermissionLevel,
63  type ResourceType,
64  type WorkspaceRole,
65} from "./levels.js";
66import { shareVisibility, type Share } from "./rules.js";
67 
68/** Who a grant applies to (prisma `Permission.granteeType`). */
69export type GranteeType = "user" | "team" | "role";
70 
71/**
72 * A permission grant (DTO mirror of the prisma `Permission` model —
73 * granteeType/granteeId/resourceType/resourceId/level/inheritsFrom).
74 */
75export interface Grant {
76  granteeType: GranteeType;
77  /** userId | teamId | role name — plain refs, same as prisma. */
78  granteeId: string;
79  resourceType: ResourceType;
80  resourceId: string;
81  level: PermissionLevel;
82  /** Id of the parent grant this one was derived from (inheritance chains). */
83  inheritsFrom?: string;
84}
85 
86/** One step of the path from the workspace root down to the requested resource. */
87export interface AncestorRef {
88  resourceType: ResourceType;
89  id: string;
90}
91 
92/** Everything the engine needs to decide; the API builds it from the DB. */
93export interface PermissionRequest {
94  userId: string;
95  userName?: string;
96  /** Ids of all teams the user belongs to (team grants + team shares). */
97  userTeams: string[];
98  workspaceRole: WorkspaceRole;
99  workspaceId: string;
100  resourceType: ResourceType;
101  resourceId: string;
102  /**
103   * Path from the workspace root down to the resource, e.g.
104   * `[{workspace, wsp_1}, {teamspace, tms_1}, {page, pg_1}]` for a page.
105   * The last entry is the resource itself. May be omitted; in that case
106   * inheritance (step c) is simply `"none"`.
107   */
108  ancestorChain?: AncestorRef[];
109  grants: Grant[];
110  shares: Share[];
111}
112 
113/** Result of {@link resolvePermission}: the level plus the audit trail. */
114export interface PermissionResult {
115  level: PermissionLevel;
116  reasons: string[];
117}
118 
119const ROLE_BASE_AT_ROOT: Record<WorkspaceRole, PermissionLevel> = {
120  owner: "full_access",
121  admin: "full_access",
122  member: "edit",
123  guest: "view",
124};
125 
126const ROLE_BASE_ON_DESCENDANTS: Record<WorkspaceRole, PermissionLevel> = {
127  owner: "full_access",
128  admin: "full_access",
129  member: "view",
130  guest: "none",
131};
132 
133/** Does the grant's grantee match the requester (step d of the contract)? */
134function grantAppliesToUser(
135  grant: Grant,
136  req: Pick<PermissionRequest, "userId" | "userTeams" | "workspaceRole">,
137): boolean {
138  switch (grant.granteeType) {
139    case "user":
140      return grant.granteeId === req.userId;
141    case "team":
142      return req.userTeams.includes(grant.granteeId);
143    case "role":
144      return grant.granteeId === req.workspaceRole;
145  }
146}
147 
148function describeGrantee(grant: Grant): string {
149  switch (grant.granteeType) {
150    case "user":
151      return `user ${grant.granteeId}`;
152    case "team":
153      return `team ${grant.granteeId}`;
154    case "role":
155      return `role ${grant.granteeId}`;
156  }
157}
158 
159/** Max applicable level among `grants` that exactly match the target, or "none". */
160function maxApplicable(grants: Grant[], req: PermissionRequest): PermissionLevel {
161  let best: PermissionLevel = "none";
162  for (const grant of grants) {
163    if (grantAppliesToUser(grant, req) && grant.level !== "none") {
164      best = maxLevel(best, grant.level);
165    }
166  }
167  return best;
168}
169 
170/** Step b — role baseline. */
171function baselineFor(req: PermissionRequest, workspaceRoot: boolean): PermissionLevel {
172  return (workspaceRoot ? ROLE_BASE_AT_ROOT : ROLE_BASE_ON_DESCENDANTS)[req.workspaceRole];
173}
174 
175/** Step c — nearest-ancestor inheritance. */
176function inheritedFromAncestors(
177  req: PermissionRequest,
178): { level: PermissionLevel; ancestor: AncestorRef } | null {
179  const chain = req.ancestorChain;
180  if (chain === undefined || chain.length === 0) return null;
181  // Ancestors of the resource, nearest first. The last entry is the resource
182  // itself (excluded); the workspace-root entry participates as the farthest
183  // ancestor (its role *baseline* is step b — grants on the workspace are
184  // ordinary inheritance grants here).
185  for (let i = chain.length - 2; i >= 0; i--) {
186    const ancestor = chain[i];
187    if (ancestor === undefined) continue;
188    const applicable = req.grants.filter(
189      (g) =>
190        grantAppliesToUser(g, req) &&
191        g.resourceType === ancestor.resourceType &&
192        g.resourceId === ancestor.id,
193    );
194    if (applicable.length > 0) {
195      let level: PermissionLevel = "none";
196      for (const grant of applicable) level = maxLevel(level, grant.level);
197      return { level, ancestor };
198    }
199  }
200  return null;
201}
202 
203/**
204 * Resolve the effective permission level for `req` (pure, deterministic —
205 * see the contract in this module's header).
206 */
207export function resolvePermission(req: PermissionRequest): PermissionResult {
208  const reasons: string[] = [];
209  const workspaceRoot = req.resourceType === "workspace";
210  const who = req.userName !== undefined ? ` (${req.userName})` : "";
211 
212  // (b) role baseline
213  const base = baselineFor(req, workspaceRoot);
214  reasons.push(
215    workspaceRoot
216      ? `role ${req.workspaceRole}${who} → baseline ${base} at workspace root`
217      : `role ${req.workspaceRole}${who} → baseline ${base} on descendant resource`,
218  );
219 
220  // (e) shares
221  const visibleShares = req.shares.filter((share) => shareVisibility(share, req));
222  let shareLevel: PermissionLevel = "none";
223  for (const share of visibleShares) {
224    shareLevel = maxLevel(shareLevel, share.level);
225    if (share.scope === "public") {
226      reasons.push(`public share → floor ${share.level}`);
227    } else if (share.scope === "workspace") {
228      reasons.push(`workspace share → floor ${share.level}`);
229    } else if (share.scope === "team") {
230      reasons.push(`team share (${share.teamId}) → floor ${share.level}`);
231    } else if (share.scope === "users") {
232      reasons.push(`share to listed users → floor ${share.level}`);
233    }
234  }
235  if (visibleShares.length === 0) {
236    reasons.push("no shares visible to requester → no share contribution");
237  }
238 
239  // (c) inheritance from the nearest ancestor that has an applicable grant
240  const inherited = inheritedFromAncestors(req);
241  let inheritedLevel: PermissionLevel = "none";
242  if (inherited !== null) {
243    inheritedLevel = inherited.level;
244    reasons.push(
245      `inherited from ${inherited.ancestor.resourceType} ${inherited.ancestor.id} → ${inheritedLevel}`,
246    );
247  } else {
248    reasons.push("no applicable grant on any ancestor → no inheritance");
249  }
250 
251  // (d) explicit grants on the exact resource
252  const explicit = maxApplicable(
253    req.grants.filter(
254      (g) => g.resourceType === req.resourceType && g.resourceId === req.resourceId,
255    ),
256    req,
257  );
258  if (explicit !== "none") {
259    const matched = req.grants
260      .filter(
261        (g) =>
262          g.resourceType === req.resourceType &&
263          g.resourceId === req.resourceId &&
264          grantAppliesToUser(g, req),
265      )
266      .map((g) => describeGrantee(g));
267    reasons.push(
268      `explicit grant on ${req.resourceType} ${req.resourceId} by ${matched.join(", ")} → ${explicit}`,
269    );
270  }
271 
272  // (f) final
273  let level: PermissionLevel;
274  if (explicit !== "none") {
275    level = explicit;
276    const superseded = [
277      inheritedLevel !== "none" ? `inherited ${inheritedLevel}` : null,
278      base !== "none" ? `baseline ${base}` : null,
279      shareLevel !== "none" ? `shares ${shareLevel}` : null,
280    ]
281      .filter((part): part is string => part !== null)
282      .join(", ");
283    reasons.push(
284      superseded.length > 0
285        ? `final = explicit ${explicit} (overrides ${superseded})`
286        : `final = explicit ${explicit}`,
287    );
288  } else {
289    level = maxLevel(inheritedLevel, maxLevel(base, shareLevel));
290    reasons.push(
291      `final = max(inherited ${inheritedLevel}, baseline ${base}, shares ${shareLevel}) = ${level}`,
292    );
293  }
294 
295  return { level, reasons };
296}
297 
298/**
299 * Whether the resolved level satisfies `required`.
300 * `can(req, "edit")` ⇔ `resolvePermission(req).level ≥ required` (a `none`
301 * level never satisfies anything).
302 */
303export function can(req: PermissionRequest, required: Exclude<PermissionLevel, "none">): boolean {
304  return levelAtLeast(resolvePermission(req).level, required);
305}
306 
307/**
308 * Assert the resolved level satisfies `required`; otherwise throw a
309 * {@link ApiError} with code `FORBIDDEN` (HTTP 403) whose `details` carry
310 * `{ required, granted, reasons }` — audit-friendly, no re-resolution by the
311 * API layer.
312 */
313export function check(req: PermissionRequest, required: Exclude<PermissionLevel, "none">): void {
314  const { level, reasons } = resolvePermission(req);
315  if (!levelAtLeast(level, required)) {
316    throw new ApiError(ErrorCodes.FORBIDDEN, {
317      message: `Permission denied: requires ${required}, granted ${level}`,
318      details: { required, granted: level, reasons },
319    });
320  }
321}
322