Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

7.8 KB
Raw Blame
// Roles and permissions — the one answer to "what may this role do?".
//
// Pure data, like scopes.ts: the server enforces it (route guards, handler
// checks) and the client reads the permission names the server hands back.
// Nothing outside this file compares role strings to decide what a user may
// do; it asks roleHasPermission instead.
//
// A role is a rung on a ladder: every role holds all the permissions of the
// roles below it. Each permission names the lowest role that holds it and the
// bearer-credential scope it needs, so a request is allowed only when BOTH the
// caller's role and (for API keys and OAuth tokens) its scopes admit it.

import type { ScopeRequirement } from "./scopes";

// Highest first.
//  - owner:  everything, including billing and deleting the organization
//  - admin:  members, teams, API keys, creating/deleting/transferring sites
//  - editor: configures sites — tracking settings, flags, experiments, imports,
//            Search Console — and manages everyone's saved segments/annotations
//  - member: builds reports — goals, funnels, dashboards, own segments/annotations
//  - viewer: reads everything the organization lets them see, changes nothing
export const ORG_ROLES = ["owner", "admin", "editor", "member", "viewer"] as const;
export type OrgRole = (typeof ORG_ROLES)[number];

const ROLE_RANK: Record<OrgRole, number> = {
  viewer: 1,
  member: 2,
  editor: 3,
  admin: 4,
  owner: 5,
};

export function isOrgRole(value: unknown): value is OrgRole {
  return typeof value === "string" && Object.prototype.hasOwnProperty.call(ROLE_RANK, value);
}

/**
 * Roles a site grant (a member's per-site access, or a team's) can carry.
 * Admin authority is organization-wide, so grants stop at editor.
 */
export const SITE_GRANT_ROLES = ["editor", "member", "viewer"] as const satisfies readonly OrgRole[];
export type SiteGrantRole = (typeof SITE_GRANT_ROLES)[number];

export function isSiteGrantRole(value: unknown): value is SiteGrantRole {
  return typeof value === "string" && (SITE_GRANT_ROLES as readonly string[]).includes(value);
}

/** Admins and owners: every site in the organization, never narrowed by site grants or teams. */
export function isAdminRole(role: string | null | undefined): boolean {
  return role === "admin" || role === "owner";
}

/** The higher of two roles; null when neither is a known role. */
export function higherRole(a: string | null | undefined, b: string | null | undefined): OrgRole | null {
  const left = isOrgRole(a) ? a : null;
  const right = isOrgRole(b) ? b : null;
  if (!left) return right;
  if (!right) return left;
  return ROLE_RANK[left] >= ROLE_RANK[right] ? left : right;
}

/**
 * "deny-scoped": the permission has no scope taxonomy resource (account and
 * billing surfaces), so scoped and organization-owned credentials never get it.
 */
export type PermissionScope = ScopeRequirement | "deny-scoped";

export interface PermissionSpec {
  /** The lowest role that holds this permission. */
  minRole: OrgRole;
  /** What a bearer credential must additionally be granted. */
  scope: PermissionScope;
}

const read = (resource: ScopeRequirement["resource"]): ScopeRequirement => ({ resource, action: "read" });
const write = (resource: ScopeRequirement["resource"]): ScopeRequirement => ({ resource, action: "write" });

export const PERMISSIONS = {
  // Reading a site's analytics and the organization it belongs to.
  "analytics:read": { minRole: "viewer", scope: read("analytics") },
  "sessions:read": { minRole: "viewer", scope: read("sessions") },
  "events:read": { minRole: "viewer", scope: read("events") },
  "users:read": { minRole: "viewer", scope: read("users") },
  "funnels:read": { minRole: "viewer", scope: read("funnels") },
  "goals:read": { minRole: "viewer", scope: read("goals") },
  "annotations:read": { minRole: "viewer", scope: read("annotations") },
  "segments:read": { minRole: "viewer", scope: read("segments") },
  "dashboards:read": { minRole: "viewer", scope: read("dashboards") },
  "flags:read": { minRole: "viewer", scope: read("flags") },
  "experiments:read": { minRole: "viewer", scope: read("experiments") },
  "replay:read": { minRole: "viewer", scope: read("replay") },
  "gsc:read": { minRole: "viewer", scope: read("gsc") },
  "sites:read": { minRole: "viewer", scope: read("sites") },
  "sql:read": { minRole: "viewer", scope: read("sql") },
  "org:read": { minRole: "viewer", scope: read("org") },

  // Building reports: shared analysis objects, and a member's own segments and
  // annotations (rows another user created need the :manage permission).
  "users:write": { minRole: "member", scope: write("users") },
  "funnels:write": { minRole: "member", scope: write("funnels") },
  "goals:write": { minRole: "member", scope: write("goals") },
  "dashboards:write": { minRole: "member", scope: write("dashboards") },
  "annotations:write": { minRole: "member", scope: write("annotations") },
  "segments:write": { minRole: "member", scope: write("segments") },

  // Configuring a site, and managing saved segments and annotations other people
  // created (org-wide ones are checked against the organization role).
  "annotations:manage": { minRole: "editor", scope: write("annotations") },
  "segments:manage": { minRole: "editor", scope: write("segments") },
  "users:delete": { minRole: "editor", scope: write("users") },
  "replay:delete": { minRole: "editor", scope: write("replay") },
  "flags:write": { minRole: "editor", scope: write("flags") },
  "experiments:write": { minRole: "editor", scope: write("experiments") },
  "gsc:write": { minRole: "editor", scope: write("gsc") },
  "sites:configure": { minRole: "editor", scope: write("sites") },
  "imports:read": { minRole: "editor", scope: read("sites") },
  "imports:write": { minRole: "editor", scope: write("sites") },

  // Administering the organization.
  "sites:create": { minRole: "admin", scope: write("sites") },
  "sites:delete": { minRole: "admin", scope: write("sites") },
  "sites:transfer": { minRole: "admin", scope: write("sites") },
  "members:manage": { minRole: "admin", scope: write("org") },
  "teams:manage": { minRole: "admin", scope: write("org") },
  "apikeys:manage": { minRole: "admin", scope: "deny-scoped" },
  // Enforced by better-auth's organization access control (orgRoles in the
  // server's auth.ts); listed here so the client can ask for it by name.
  "org:rename": { minRole: "admin", scope: "deny-scoped" },

  // Owning the organization.
  "billing:manage": { minRole: "owner", scope: "deny-scoped" },
  "org:delete": { minRole: "owner", scope: "deny-scoped" },
} as const satisfies Record<string, PermissionSpec>;

export type Permission = keyof typeof PERMISSIONS;

export const ALL_PERMISSIONS = Object.keys(PERMISSIONS) as Permission[];

export function roleHasPermission(role: string | null | undefined, permission: Permission): boolean {
  if (!isOrgRole(role)) {
    return false;
  }
  return ROLE_RANK[role] >= ROLE_RANK[PERMISSIONS[permission].minRole];
}

/** Every permission the role holds, in declaration order. */
export function permissionsForRole(role: string | null | undefined): Permission[] {
  return ALL_PERMISSIONS.filter(permission => roleHasPermission(role, permission));
}

/**
 * Whether someone holding `actorRole` may give another member `targetRole`:
 * they must manage members, and never grant a role above their own (only an
 * owner makes owners).
 */
export function canAssignRole(actorRole: string | null | undefined, targetRole: string): boolean {
  if (!isOrgRole(actorRole) || !isOrgRole(targetRole)) {
    return false;
  }
  return roleHasPermission(actorRole, "members:manage") && ROLE_RANK[actorRole] >= ROLE_RANK[targetRole];
}

/** The roles someone holding `actorRole` may give to others, highest first. */
export function assignableRoles(actorRole: string | null | undefined): OrgRole[] {
  return ORG_ROLES.filter(role => canAssignRole(actorRole, role));
}