Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

6.1 KB
Raw Blame
// Permission model for team roles. A role carries a matrix: for each resource the
// create/edit/read/delete flags. The matrix is stored as jsonb on team_role and
// enforced by the API (apps/api/src/shared/access.ts). Owners bypass the matrix
// entirely (full access).

const CORE_RESOURCES = [
  'work_items',
  'initiatives',
  'cycles',
  'dashboards',
  'documents',
  'views',
  'members_invite',
  'members_manage',
  'states',
  'issue_types',
  'labels',
  'ai_agents',
  'agent_schedules',
  'integrations',
  'agent_skills',
  'agent_tools',
  'agent_usage',
  'custom_fields',
  'issue_templates',
  'workflow_config',
  'actions',
  'webhooks',
  'repositories',
  'note_boards',
  'import_export',
  'danger_zone',
] as const;
export type PermissionResource = (typeof CORE_RESOURCES)[number];

// The resources in the order a matrix lists them, with those setPermissionExtensions added.
export const PERMISSION_RESOURCES: PermissionResource[] = [...CORE_RESOURCES];

export const PERMISSION_ACTIONS = ['create', 'edit', 'read', 'delete'] as const;
export type PermissionAction = (typeof PERMISSION_ACTIONS)[number];

export type ResourcePermissions = Record<PermissionAction, boolean>;
export type Permissions = Record<PermissionResource, ResourcePermissions>;

// Resources that do not carry the whole CRUD set: the danger zone is the project's
// settings page and its deletion, the workflow config is read and written, an invite
// is created and revoked but never edited, the repository settings are shown only to
// whoever may change them, and what the agents spent is only read. A resource left out
// here supports every action. Unsupported cells stay present and false, so a caller
// reads any cell without a lookup.
const RESOURCE_ACTIONS: Partial<Record<PermissionResource, readonly PermissionAction[]>> = {
  danger_zone: ['read', 'delete'],
  workflow_config: ['read', 'edit'],
  repositories: ['edit'],
  agent_usage: ['read'],
  members_invite: ['read', 'create', 'delete'],
};

// A resource a build splits out of one the core has.
export interface PermissionExtension {
  resource: string;
  // It is listed after this resource, supports the same actions unless `actions` says
  // otherwise, and a role saved before it existed holds here what it holds there.
  from: PermissionResource;
  actions?: readonly PermissionAction[];
}

const extensions = new Map<string, PermissionExtension>();

// For a build that extends the matrix: called at startup, before any request. Called with
// no argument it puts the core's matrix back, which is how a test undoes one.
export function setPermissionExtensions(list: PermissionExtension[] = []): void {
  extensions.clear();
  PERMISSION_RESOURCES.splice(0, PERMISSION_RESOURCES.length, ...CORE_RESOURCES);
  // In reverse, since each goes right after `from`: the list keeps its order.
  for (const extension of [...list].reverse()) {
    extensions.set(extension.resource, extension);
    PERMISSION_RESOURCES.splice(
      PERMISSION_RESOURCES.indexOf(extension.from) + 1,
      0,
      extension.resource as PermissionResource,
    );
  }
}

export function extendedFrom(resource: PermissionResource): PermissionResource | undefined {
  return extensions.get(resource)?.from;
}

export function resourceActions(resource: PermissionResource): readonly PermissionAction[] {
  const extension = extensions.get(resource);
  return extension?.actions ?? RESOURCE_ACTIONS[extension?.from ?? resource] ?? PERMISSION_ACTIONS;
}

function allowAll(resource: PermissionResource): ResourcePermissions {
  const allowed = resourceActions(resource);
  return Object.fromEntries(
    PERMISSION_ACTIONS.map((a) => [a, allowed.includes(a)]),
  ) as ResourcePermissions;
}

function denyAll(): ResourcePermissions {
  return { create: false, edit: false, read: false, delete: false };
}

// All flags false — the base a normalizer starts from.
export function emptyPermissions(): Permissions {
  return Object.fromEntries(PERMISSION_RESOURCES.map((r) => [r, denyAll()])) as Permissions;
}

// Every supported action allowed — the effective matrix for an owner (owners bypass
// checks, but this is returned so a member context always carries a resolved matrix).
export function fullPermissions(): Permissions {
  return Object.fromEntries(PERMISSION_RESOURCES.map((r) => [r, allowAll(r)])) as Permissions;
}

// The matrix of the default system role ("Member") as migrations 0160, 0162 and 0174 leave
// it. A member with no role resolves to it.
export function defaultMemberPermissions(): Permissions {
  const all = { create: true, edit: true, read: true, delete: true };
  const read = { read: true };
  const member: Partial<Record<PermissionResource, Partial<ResourcePermissions>>> = {
    work_items: all,
    initiatives: all,
    cycles: all,
    documents: all,
    note_boards: all,
    dashboards: read,
    views: read,
    ai_agents: read,
    agent_schedules: read,
    members_manage: read,
    members_invite: read,
  };
  return normalizePermissions(member);
}

function normalizeResource(resource: PermissionResource, entry: unknown): ResourcePermissions {
  const e = (entry && typeof entry === 'object' ? entry : {}) as Record<string, unknown>;
  const allowed = resourceActions(resource);
  return Object.fromEntries(
    PERMISSION_ACTIONS.map((a) => [a, allowed.includes(a) && e[a] === true]),
  ) as ResourcePermissions;
}

// Coerces arbitrary input (a jsonb blob or a request body) into the canonical
// matrix: every resource and action present, values coerced to booleans, unknown
// keys dropped, missing entries and actions the resource does not support
// defaulted to false.
export function normalizePermissions(input: unknown): Permissions {
  const src = (input && typeof input === 'object' ? input : {}) as Record<string, unknown>;
  return Object.fromEntries(
    PERMISSION_RESOURCES.map((resource) => {
      const from = extendedFrom(resource);
      return [resource, normalizeResource(resource, src[resource] ?? (from && src[from]))];
    }),
  ) as Permissions;
}

export function hasPermission(
  permissions: Permissions,
  resource: PermissionResource,
  action: PermissionAction,
): boolean {
  return permissions[resource]?.[action] === true;
}