⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import { Elysia, type DocumentDecoration } from 'elysia';
import { workspaceScim as isScimPerWorkspace } from '@repo/auth';
import { authContext } from './auth-context';
import {
requireProjectAccess,
requireProjectPermission,
requireProjectOwner,
requireProjectAdmin,
requireTeamRunsProject,
requireMemberAdmin,
requireSelfOrMemberAdmin,
requireTeamMembership,
requireTeamPermission,
assertPermission,
assertMcpEnabled,
assertWritable,
assertFeatureEnabled,
type AuthUser,
} from './access';
import type { ProjectFeature } from './features';
import { getProjectById, type ProjectRow } from '#modules/projects/service';
import { runsTeam, teamMcpEnabled } from '#modules/teams/service';
import { requireWorkspaceManager } from '#modules/workspaces/service';
import { boundProjectId, isMcpRequest } from './mcp-request';
import { HttpError } from './lib';
import type { PermissionResource, PermissionAction } from './permissions';
// A [resource, action] pair naming one cell of the role permission matrix.
export type Permission = [PermissionResource, PermissionAction];
// The slice of the request context an entity guard reads. Annotated explicitly
// because the factory is defined outside a plugin, so there is no context to
// infer from. It is a supertype of Elysia's route context (params widened, user
// optional) so the resolve is assignable wherever the macro is used; `user` is
// populated at runtime by authContext.
type EntityGuardCtx = {
params: Record<string, unknown>;
user?: AuthUser | null;
request: Request;
};
// The permission a route requires, as an OpenAPI extension on its detail. Elysia
// deletes a macro's own key from the route once it expands the macro, so this is
// where the MCP tool table reads what a route requires (see generate.ts) rather than
// from a second list of the same pairs kept by hand. Every guard below states it;
// spread it into `detail` directly on a route that asserts its permission in the
// handler instead of through a guard.
export function requiresPermission(permission: Permission): { 'x-permission': Permission } {
return { 'x-permission': permission };
}
// Elysia merges a `detail` a macro returns into the route's own, which is how a
// guard reaches the route's detail at all. The cast is for the extension key alone:
// DocumentDecoration has every property optional, so an object carrying only an
// `x-` key shares none with it and TypeScript rejects it as a weak type.
function permissionDetail(permission: Permission) {
return { detail: requiresPermission(permission) as DocumentDecoration };
}
// Builds a feature-local macro for routes that address an entity by its own id
// (no :projectKey in the path). resolveProjectId maps the route params to the
// entity's owning project id (null means the entity was not found); it is handed the
// caller too, for an entity that only some members may see. The macro
// asserts the given action on `resource` and injects the resolved `projectId` into
// the handler context, so a handler that needs it does not resolve it again. `feature`
// names the optional section the entity belongs to, closing every route of the macro
// while the project has that section off. `check` is one more rule on the resolved
// project, run last. Used like:
//
// .macro({
// workItem: entityGuard("work_items", "Issue not found",
// (p) => getIssueProjectId(Number(p.issueId))),
// })
// .patch("/issues/:issueId", handler, { workItem: "edit" })
export function entityGuard(
resource: PermissionResource,
notFound: string,
resolveProjectId: (
params: Record<string, string>,
user: AuthUser | null | undefined,
) => Promise<number | null>,
feature?: ProjectFeature,
check?: (projectId: number) => Promise<void>,
) {
return (action: PermissionAction) => ({
...permissionDetail([resource, action]),
async resolve({ params, user, request }: EntityGuardCtx) {
const projectId = await resolveProjectId(params as Record<string, string>, user);
if (projectId == null) throw new HttpError(404, notFound);
await assertPermission(projectId, user, resource, action);
await assertProjectReachable(projectId, request, feature);
await check?.(projectId);
return { projectId };
},
});
}
// What a route that resolved its project by an object's id checks on it: the section
// it belongs to, the run binding and the MCP toggle (see assertMcpAllowed), and that an
// archived project is not written to. The project is read once, and only when a check
// needs it.
export async function assertProjectReachable(
projectId: number,
request: Request,
feature?: ProjectFeature,
): Promise<void> {
const mcp = isMcpRequest(request.headers);
const reads = request.method === 'GET' || request.method === 'HEAD';
const project = feature || mcp || !reads ? await getProjectById(projectId) : null;
if (project && feature) assertFeatureEnabled(project, feature);
assertBoundProject(projectId, request.headers);
if (!project) return;
assertMcpEnabled(project, mcp);
assertWritable(project, request.method);
}
// What the request carries about the project, for a route or a guard that resolved the
// project by an object's id rather than through one of the :projectKey macros: an
// internal agent's run is bound to its own project, and an MCP call obeys the
// per-project MCP toggle. A plain request passes untouched.
export async function assertMcpAllowed(projectId: number, headers: Headers): Promise<void> {
assertBoundProject(projectId, headers);
if (!isMcpRequest(headers)) return;
const project = await getProjectById(projectId);
if (project) assertMcpEnabled(project, true);
}
function assertBoundProject(projectId: number, headers: Headers): void {
const bound = boundProjectId(headers);
if (bound != null && bound !== projectId) {
throw new HttpError(403, 'Outside the project this run works in');
}
}
// The path param carried by every project-scoped route. The macros read it off
// the resolved params; Elysia always parses path segments, so it is present at
// runtime even on routes that do not declare a params schema.
type ProjectKeyParams = { projectKey: string };
// The path param carried by every team-scoped route, and its resolution to the
// caller's membership — shared by the three team macros below.
type TeamIdParams = { teamId: string };
type WorkspaceIdParams = { workspaceId: string };
function resolveTeam(params: unknown, user: AuthUser | undefined | null) {
return requireTeamMembership(Number((params as TeamIdParams).teamId), user);
}
// The team's MCP switch, for the team-scoped routes. Their resources — the agents,
// the skills, the tools, the roles and the integration credentials — belong to the
// team rather than to a project, so no project flag covers them; this is what does.
// A plain request passes untouched.
async function assertTeamMcpAllowed(params: unknown, headers: Headers): Promise<void> {
if (!isMcpRequest(headers)) return;
const teamId = Number((params as TeamIdParams).teamId);
if (!(await teamMcpEnabled(teamId))) throw new HttpError(403, 'MCP is disabled for this team');
}
// Declarative access guards for routes whose path carries :projectKey. Each
// macro resolves the project once, enforces access, and injects the resolved
// `project` row into the handler context, so a handler reads `project` instead
// of resolving and checking it itself.
//
// The plugin uses authContext, so `user` is on the context before a guard runs.
// A feature plugin with :projectKey routes does `.use(guards)` at the top of its
// chain and sets the guard in each route's options:
//
// .post("/projects/:projectKey/columns", ({ project, body }) => ..., {
// permission: ["states", "create"],
// })
//
// A guard that denies throws an HttpError, which the planner onError maps to the
// JSON error response.
export const guards = new Elysia({ name: 'guards' }).use(authContext).macro({
// Bare membership: any member of the project may proceed.
projectMember(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const project = await requireProjectAccess((params as ProjectKeyParams).projectKey, user);
assertMcpEnabled(project, isMcpRequest(request.headers));
assertWritable(project, request.method);
return { project };
},
};
},
// The optional section or sections a route belongs to, set beside the permission the route
// asserts. A section its project has turned off closes its routes, so what the
// settings page hides cannot be reached through the API either. It reads the project
// the route's guard resolved when that guard is set before it in the route options;
// otherwise it resolves the project through the membership check itself, so it
// belongs on a route that already requires membership.
feature(name: ProjectFeature | ProjectFeature[]) {
return {
async resolve(ctx) {
const project =
(ctx as { project?: ProjectRow }).project ??
(await requireProjectAccess((ctx.params as ProjectKeyParams).projectKey, ctx.user));
for (const feature of [name].flat()) assertFeatureEnabled(project, feature);
},
};
},
// A specific permission on the role matrix (owners bypass the matrix).
permission(permission: Permission) {
return {
...permissionDetail(permission),
async resolve({ params, user, request }) {
const project = await requireProjectPermission(
(params as ProjectKeyParams).projectKey,
user,
permission[0],
permission[1],
);
assertMcpEnabled(project, isMcpRequest(request.headers));
// Deleting the project is the one change an archived project still takes.
if (permission[0] !== 'danger_zone') assertWritable(project, request.method);
return { project };
},
};
},
// Owner-only actions (member management). A non-member gets 403 for access
// rather than leaking owner-ness, since membership is resolved before the owner
// check.
projectOwner(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const project = await requireProjectOwner((params as ProjectKeyParams).projectKey, user);
assertMcpEnabled(project, isMcpRequest(request.headers));
assertWritable(project, request.method);
return { project };
},
};
},
// The project's own settings — MCP access and the optional sections — which its
// owner and the team that runs it both govern.
projectAdmin(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const project = await requireProjectAdmin((params as ProjectKeyParams).projectKey, user);
assertMcpEnabled(project, isMcpRequest(request.headers));
assertWritable(project, request.method);
return { project };
},
};
},
// A project the caller's team runs, for what follows their rank in the team rather
// than any project role: copying the project into one of their own.
// Copying only reads the source, so an archived project can still be copied.
teamRunsProject(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const project = await requireTeamRunsProject((params as ProjectKeyParams).projectKey, user);
assertMcpEnabled(project, isMcpRequest(request.headers));
return { project };
},
};
},
// One member's own row, addressed by :userId: the member themselves act on it
// without a member permission, everyone else needs what memberAdmin asks for.
memberSelfOrAdmin(permission: Permission) {
return {
...permissionDetail(permission),
async resolve({ params, user, request }) {
const { projectKey, userId } = params as ProjectKeyParams & { userId: string };
const project = await requireSelfOrMemberAdmin(
projectKey,
userId,
user,
permission[0],
permission[1],
);
assertMcpEnabled(project, isMcpRequest(request.headers));
assertWritable(project, request.method);
return { project };
},
};
},
// The project's member list: a permission from the role matrix, or the standing of
// a team owner or manager, who run the team's projects without being in them.
memberAdmin(permission: Permission) {
return {
...permissionDetail(permission),
async resolve({ params, user, request }) {
const project = await requireMemberAdmin(
(params as ProjectKeyParams).projectKey,
user,
permission[0],
permission[1],
);
assertMcpEnabled(project, isMcpRequest(request.headers));
assertWritable(project, request.method);
return { project };
},
};
},
// Any member of the team may proceed. The team macros inject the resolved
// `membership` into the handler context.
teamMember(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const membership = await resolveTeam(params, user);
await assertTeamMcpAllowed(params, request.headers);
return { membership };
},
};
},
// Owner or manager. They run the team's projects: create, copy and update one. A
// member does not, and neither does an agent, whose standing in the team says only
// that it belongs to it.
teamManager(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const membership = await resolveTeam(params, user);
if (!runsTeam(membership.role))
throw new HttpError(403, 'Only a team owner or manager can do this');
await assertTeamMcpAllowed(params, request.headers);
return { membership };
},
};
},
// A resource the team owns and every project of it shares. Owners and managers of
// the team pass, so does an owner of one of its projects; anyone else passes when a
// project role of theirs in the team grants the permission.
teamPermission(permission: Permission) {
return {
...permissionDetail(permission),
async resolve({ params, user, request }) {
const { teamId } = params as TeamIdParams;
const membership = await requireTeamPermission(
Number(teamId),
user,
permission[0],
permission[1],
);
await assertTeamMcpAllowed(params, request.headers);
return { membership };
},
};
},
// The workspace's owner or an admin. The workspace macros inject the resolved
// `standing` into the handler context.
workspaceManager(_enabled: boolean) {
return {
async resolve({ params, user }) {
const standing = await requireWorkspaceManager(
Number((params as WorkspaceIdParams).workspaceId),
user,
);
return { standing };
},
};
},
// Only the owner appoints and removes the admins.
workspaceOwner(_enabled: boolean) {
return {
async resolve({ params, user }) {
const standing = await requireWorkspaceManager(
Number((params as WorkspaceIdParams).workspaceId),
user,
);
if (standing.role !== 'owner')
throw new HttpError(403, 'Only the workspace owner can do this');
return { standing };
},
};
},
// A workspace's own SCIM, where a build sets SCIM up per workspace (setWorkspaceScim in
// @repo/auth). Its provider attaches accounts to the workspace, so only the owner sets
// it up. Without it SCIM is the instance's, set up in god mode.
workspaceScim(_enabled: boolean) {
return {
async resolve({ params, user }) {
const standing = await requireWorkspaceManager(
Number((params as WorkspaceIdParams).workspaceId),
user,
);
if (!isScimPerWorkspace()) {
throw new HttpError(403, 'SCIM is set up for the whole instance in god mode');
}
if (standing.role !== 'owner') {
throw new HttpError(403, 'Only the workspace owner sets up SCIM provisioning');
}
return { standing };
},
};
},
// Owner-only actions (renaming the team, its roles, deleting a project). A
// non-member gets the same 404 as for an unknown team, since membership is
// resolved before the owner check.
teamOwner(_enabled: boolean) {
return {
async resolve({ params, user, request }) {
const membership = await resolveTeam(params, user);
if (membership.role !== 'owner') throw new HttpError(403, 'Only a team owner can do this');
await assertTeamMcpAllowed(params, request.headers);
return { membership };
},
};
},
});