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.

21.0 KB
Raw Blame
import { Elysia, t } from 'elysia';
import { mcpTool } from '#mcp/generate';
import { noContent } from '#shared/http';
import { paginate } from '#shared/pagination';
import { authContext } from '#shared/auth-context';
import { guards } from '#shared/guards';
import {
  assertGrantablePermissions,
  checkMemberAdmin,
  mayGrantPermissions,
  requireUser,
  type AuthUser,
} from '#shared/access';
import { inviteValidSince } from '@repo/auth';
import { hasConfiguredEmailProvider } from '@repo/db';
import { HttpError } from '#shared/lib';
import { accessErrors, commonErrors, errors } from '#shared/responses';
import { getAssignableRole } from '#modules/roles/service';
import type { ProjectRow } from '#modules/projects/service';
import { teamParams } from '#modules/teams/model';
import {
  receivedInvitesQuery,
  ReceivedInvitePageResponse,
  AcceptInviteResponse,
  InviteCreateResponse,
  InviteEmailResponse,
  InviteRowListResponse,
  InviteViewResponse,
  createInviteBody,
  createTeamInviteBody,
  inviteCandidatesQuery,
  InviteCandidateListResponse,
  inviteParams,
  teamInviteParams,
  tokenParams,
} from './model';
import {
  listReceivedInvites,
  createInvite,
  mayGrantInviteRanks,
  listProjectInvites,
  listTeamInvites,
  listInviteCandidates,
  type ListedInvite,
  deleteProjectInvite,
  deleteTeamInvite,
  getInviteById,
  getInviteByToken,
  getInviteRowByToken,
  getInviteGrant,
  renewInvite,
  acceptInvite,
  rejectInvite,
} from './service';
import { enqueueInviteEmail, sendTeamInviteEmail } from './email';

// Shared by accept and reject: an invite is actionable only by the account whose
// email it names, and only while it is still pending.
async function loadActionableInvite(token: string, user: AuthUser | undefined | null) {
  const current = requireUser(user);
  const invite = await getInviteRowByToken(token);
  if (!invite) throw new HttpError(404, 'Invite not found');
  if (invite.status !== 'pending') throw new HttpError(409, 'This invite is no longer pending');
  const since = await inviteValidSince();
  if (since && invite.createdAt < since) throw new HttpError(409, 'This invite has expired');
  if ((current.email ?? '').toLowerCase() !== invite.email) {
    throw new HttpError(403, 'This invite was sent to a different email');
  }
  return { invite, current };
}

// The ranks are checked again here, against the sender's standing now: a link that
// grants project or team ownership must not outlive the standing that issued it, and
// the sender can be demoted or gone between the two.
async function assertStillGrantable(invite: {
  teamId: number;
  projectId: number | null;
  teamRole: string;
  projectRole: string | null;
  invitedByUserId: string | null;
}): Promise<void> {
  if (!(await mayGrantInviteRanks(invite, invite.invitedByUserId))) {
    throw new HttpError(
      409,
      'Whoever sent this invite can no longer grant the rank it carries. Ask for a new one.',
    );
  }
}

// What a created or renewed invite reports about its email. Without a provider nothing
// was sent and the link is to be shared by hand; a provider whose send fails is told
// apart, so nobody goes looking for a missing configuration.
async function mailOutcome(send: () => Promise<boolean>) {
  if (!(await hasConfiguredEmailProvider())) return { emailQueued: false, emailFailed: false };
  try {
    const sent = await send();
    return { emailQueued: sent, emailFailed: !sent };
  } catch (err) {
    console.error('[invites] invite email failed:', err);
    return { emailQueued: false, emailFailed: true };
  }
}

// A link hands out its invite's role to whoever holds it, so a viewer who could not grant
// that role does not get the link either.
async function hideLinksBeyondGrant(
  project: ProjectRow,
  viewer: AuthUser,
  invites: ListedInvite[],
): Promise<ListedInvite[]> {
  const grantable = new Map<number, boolean>();
  return Promise.all(
    invites.map(async (invite) => {
      if (!invite.token || invite.roleId == null) return invite;
      if (!grantable.has(invite.roleId)) {
        const role = await getAssignableRole(project.teamId, invite.roleId);
        grantable.set(
          invite.roleId,
          !role || (await mayGrantPermissions(project, viewer, role.permissions)),
        );
      }
      return grantable.get(invite.roleId) ? invite : { ...invite, token: null };
    }),
  );
}

export const inviteRoutes = new Elysia({ name: 'invites', detail: { tags: ['Invites'] } })
  .use(authContext)
  .use(guards)

  .get(
    '/me/invites',
    async ({ user, query, set }) => {
      set.headers['cache-control'] = 'private, no-store';
      return paginate(query, (window) =>
        listReceivedInvites(requireUser(user).email ?? '', window),
      );
    },
    {
      beforeHandle: ({ user }) => {
        requireUser(user);
        if (!user?.emailVerified || !user.email) {
          throw new HttpError(403, 'Confirm your email before viewing invitations');
        }
      },
      query: receivedInvitesQuery,
      response: { 200: ReceivedInvitePageResponse, ...errors(400, 401, 403) },
      detail: {
        summary: 'List invitations received by your verified email',
        description:
          'Pending, unexpired invitations for the signed-in account. Open an invitation to review its role and explicitly accept or decline it.',
      },
    },
  )

  .post(
    '/projects/:projectKey/invites',
    async ({ project, body, user, set }) => {
      // Ownership is not one of the ranks the member permission carries: an owner
      // bypasses the role matrix, so only a project owner or someone who runs the team
      // hands it out — an invite is the third way to make one, beside members/.
      const invitedBy = requireUser(user).id;
      if (
        !(await mayGrantInviteRanks(
          {
            teamId: project.teamId,
            projectId: project.id,
            teamRole: 'member',
            projectRole: body.role,
          },
          invitedBy,
        ))
      ) {
        throw new HttpError(
          403,
          'Only a project owner or a team owner or manager can invite an owner',
        );
      }
      // For a member invite, an explicit roleId must name a role of this project's
      // team or a system role; null (or omitted) falls back to the default role on accept. An
      // owner invite ignores roleId (owners bypass roles).
      const roleId = body.role === 'member' ? (body.roleId ?? null) : null;
      if (roleId != null) {
        const role = await getAssignableRole(project.teamId, roleId);
        if (!role) throw new HttpError(400, "roleId does not belong to this project's team");
        await assertGrantablePermissions(project, user, role.permissions);
      }
      const invite = await createInvite({
        teamId: project.teamId,
        projectId: project.id,
        email: body.email,
        // An invite into a project brings its invitee into the team as a plain
        // member; the rank above that is granted by an invite into the team itself.
        teamRole: 'member',
        projectRole: body.role,
        roleId,
        invitedByUserId: invitedBy,
      });
      // Creating the invite link is the primary operation: a failed email must not
      // discard a valid link that can still be copied.
      const email = await mailOutcome(() => enqueueInviteEmail(project, invite));
      set.status = 201;
      return { ...invite, ...email };
    },
    {
      body: createInviteBody,
      memberAdmin: ['members_invite', 'create'],
      response: { 201: InviteCreateResponse, ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Create an invite',
        description:
          'Create an invite link for an email and role (owner or member). For a member, roleId ' +
          "picks the custom role, or null for the default role. Accepting it joins the project's " +
          'team as well. Queues an email when the instance email provider is configured; ' +
          'emailFailed reports an email the provider could not send, the link still valid.',
        ...mcpTool('create_invite'),
      },
    },
  )

  .post(
    '/projects/:projectKey/invites/:inviteId/email',
    async ({ project, params }) => {
      const invite = await getInviteById(params.inviteId);
      if (!invite || invite.projectKey !== project.key) {
        throw new HttpError(404, 'Invite not found');
      }
      if (invite.status !== 'pending') {
        throw new HttpError(409, 'This invite is no longer pending');
      }
      // Mailing a dead link only leads the invitee to an error; renewing sends a live one.
      if (invite.expiresAt && new Date(invite.expiresAt) < new Date()) {
        throw new HttpError(409, 'This invite has expired. Renew it to send a new link.');
      }
      return { emailQueued: await enqueueInviteEmail(project, invite) };
    },
    {
      params: inviteParams,
      memberAdmin: ['members_invite', 'create'],
      response: { 200: InviteEmailResponse, ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Send an invite email',
        description:
          'Queue an email for a pending project invite. Returns false when the instance email ' +
          'provider is not configured. An expired invite is refused: renew it instead.',
        ...mcpTool('send_invite_email'),
      },
    },
  )

  .post(
    '/projects/:projectKey/invites/:inviteId/renew',
    async ({ project, params, user, set }) => {
      const renewedBy = requireUser(user).id;
      const grant = await getInviteGrant(params.inviteId);
      if (!grant || grant.projectId !== project.id) throw new HttpError(404, 'Invite not found');
      // Renewing hands the grant out again, so it is held to the same rules as creating it.
      if (!(await mayGrantInviteRanks(grant, renewedBy))) {
        throw new HttpError(
          403,
          'Only a project owner or a team owner or manager can invite an owner',
        );
      }
      if (grant.roleId != null) {
        const role = await getAssignableRole(project.teamId, grant.roleId);
        if (role) await assertGrantablePermissions(project, user, role.permissions);
      }
      const invite = await renewInvite(grant, renewedBy);
      const email = await mailOutcome(() => enqueueInviteEmail(project, invite));
      set.status = 201;
      return { ...invite, ...email };
    },
    {
      params: inviteParams,
      memberAdmin: ['members_invite', 'create'],
      response: { 201: InviteCreateResponse, ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Renew an expired invite',
        description:
          'Replace an expired project invite with a new one for the same email and role: a new ' +
          'link, valid again for the instance invite lifetime. Emails it when the instance ' +
          'email provider is configured. An invite that has not expired is refused.',
        ...mcpTool('renew_invite'),
      },
    },
  )

  .get(
    '/projects/:projectKey/invites',
    async ({ project, user }) => {
      const viewer = requireUser(user);
      const mayInvite = await checkMemberAdmin(project, viewer, 'members_invite', 'create');
      const invites = await listProjectInvites(project.id, mayInvite ? viewer.id : null);
      return hideLinksBeyondGrant(project, viewer, invites);
    },
    {
      memberAdmin: ['members_invite', 'read'],
      response: { 200: InviteRowListResponse, ...accessErrors },
      detail: {
        summary: "List a project's invites",
        description:
          'The token is null on an invite the caller could not have sent: without permission ' +
          'to create invites, or on an owner invite the caller may not grant.',
        ...mcpTool('list_invites'),
      },
    },
  )

  .delete(
    '/projects/:projectKey/invites/:inviteId',
    async ({ project, params }) => {
      const removed = await deleteProjectInvite(project.id, params.inviteId);
      if (!removed) throw new HttpError(404, 'Invite not found');
      return noContent();
    },
    {
      params: inviteParams,
      memberAdmin: ['members_invite', 'delete'],
      response: { 204: t.Void(), ...commonErrors },
      detail: {
        summary: 'Delete an invite',
        description: 'Revoke a project invite.',
        ...mcpTool('delete_invite'),
      },
    },
  )

  // Team invites carry no project: the invitee joins the team alone, and reaches its
  // projects through a membership added afterwards.
  .post(
    '/teams/:teamId/invites',
    async ({ membership, body, set }) => {
      if (
        !(await mayGrantInviteRanks(
          { teamId: membership.teamId, projectId: null, teamRole: body.role, projectRole: null },
          membership.userId,
        ))
      ) {
        throw new HttpError(403, 'Only a team owner can invite an owner or a manager');
      }
      const invite = await createInvite({
        teamId: membership.teamId,
        projectId: null,
        email: body.email,
        teamRole: body.role,
        projectRole: null,
        roleId: null,
        invitedByUserId: membership.userId,
      });
      // As for a project invite: the link is the primary result and stays valid.
      const email = await mailOutcome(() => sendTeamInviteEmail(membership.teamId, invite));
      set.status = 201;
      return { ...invite, ...email };
    },
    {
      teamManager: true,
      params: teamParams,
      body: createTeamInviteBody,
      response: { 201: InviteCreateResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Invite someone to a team',
        description:
          'Create an invite link into the team, as a member, a manager or an owner. Only an ' +
          'owner can invite a manager or another owner. Emails the link when the instance ' +
          'email provider is configured; emailFailed reports an email the provider could not ' +
          'send, the link still valid.',
      },
    },
  )

  .get(
    '/teams/:teamId/invites',
    async ({ membership }) => {
      return listTeamInvites(membership.teamId, membership.userId);
    },
    {
      teamManager: true,
      params: teamParams,
      response: { 200: InviteRowListResponse, ...errors(401, 403, 404) },
      detail: {
        summary: "List a team's invites",
        description:
          'Every invite into the team, including the ones that also name one of its projects. ' +
          'The token is null on an invite granting a rank only a team owner may grant.',
      },
    },
  )

  .get(
    '/teams/:teamId/invites/candidates',
    ({ membership, query }) => listInviteCandidates(membership.teamId, query.search),
    {
      teamManager: true,
      params: teamParams,
      query: inviteCandidatesQuery,
      response: { 200: InviteCandidateListResponse, ...commonErrors },
      detail: {
        summary: 'Search people to invite to a team',
        description:
          'Up to 8 accounts of the instance whose name or address contains the search, ' +
          'leaving out the members of the team and the AI agents. Whoever may invite to the ' +
          'team may search, while the instance owner has the search turned on.',
      },
    },
  )

  // The team list also shows the invites that name one of its projects, so this mails
  // those too, as their project would.
  .post(
    '/teams/:teamId/invites/:inviteId/email',
    async ({ membership, params }) => {
      const grant = await getInviteGrant(params.inviteId);
      if (!grant || grant.teamId !== membership.teamId) {
        throw new HttpError(404, 'Invite not found');
      }
      const invite = await getInviteById(params.inviteId);
      if (!invite) throw new HttpError(404, 'Invite not found');
      if (invite.status !== 'pending') {
        throw new HttpError(409, 'This invite is no longer pending');
      }
      if (invite.expiresAt && new Date(invite.expiresAt) < new Date()) {
        throw new HttpError(409, 'This invite has expired. Renew it to send a new link.');
      }
      // Without a provider there is nothing to send, and the caller is told to share the
      // link; a provider that fails is an error, not that.
      if (!(await hasConfiguredEmailProvider())) return { emailQueued: false };
      if (grant.projectId == null) {
        if (!(await sendTeamInviteEmail(membership.teamId, invite))) {
          throw new HttpError(502, 'The invite email could not be sent');
        }
        return { emailQueued: true };
      }
      if (invite.projectName == null) return { emailQueued: false };
      return {
        emailQueued: await enqueueInviteEmail(
          { id: grant.projectId, name: invite.projectName },
          invite,
        ),
      };
    },
    {
      teamManager: true,
      params: teamInviteParams,
      response: { 200: InviteEmailResponse, ...errors(401, 403, 404, 409, 502) },
      detail: {
        summary: 'Send an invite email of the team',
        description:
          'Email a pending invite into the team, or into one of its projects, again: the same ' +
          'link. Returns false when the instance email provider is not configured, and 502 when ' +
          'it is configured but the email to the team alone could not be sent. An expired ' +
          'invite is refused: renew it instead.',
      },
    },
  )

  // The team list also shows the invites that name one of its projects, so this renews
  // those too, mailing them as their project would.
  .post(
    '/teams/:teamId/invites/:inviteId/renew',
    async ({ membership, params, set }) => {
      const grant = await getInviteGrant(params.inviteId);
      if (!grant || grant.teamId !== membership.teamId) {
        throw new HttpError(404, 'Invite not found');
      }
      if (!(await mayGrantInviteRanks(grant, membership.userId))) {
        throw new HttpError(403, 'Only a team owner can invite an owner or a manager');
      }
      const invite = await renewInvite(grant, membership.userId);
      const { projectId } = grant;
      const projectName = invite.projectName;
      const email = await mailOutcome(async () => {
        if (projectId == null) return sendTeamInviteEmail(membership.teamId, invite);
        if (projectName == null) return false;
        return enqueueInviteEmail({ id: projectId, name: projectName }, invite);
      });
      set.status = 201;
      return { ...invite, ...email };
    },
    {
      teamManager: true,
      params: teamInviteParams,
      response: { 201: InviteCreateResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Renew an expired invite of the team',
        description:
          'Replace an expired invite into the team, or into one of its projects, with a new one ' +
          'for the same email and rank: a new link, valid again for the instance invite ' +
          'lifetime. Emails it when the instance email provider is configured.',
      },
    },
  )

  .delete(
    '/teams/:teamId/invites/:inviteId',
    async ({ membership, params }) => {
      const removed = await deleteTeamInvite(membership.teamId, params.inviteId);
      if (!removed) throw new HttpError(404, 'Invite not found');
      return noContent();
    },
    {
      teamManager: true,
      params: teamInviteParams,
      response: { 204: t.Void(), ...errors(401, 403, 404) },
      detail: {
        summary: 'Delete an invite of the team',
        description: 'Revoke an invite into the team or into one of its projects.',
      },
    },
  )

  // Unguarded by membership: the invitee is not a member yet. The token is
  // unguessable, so any authenticated caller holding one may read the invite.
  .get(
    '/invites/:token',
    async ({ params }) => {
      const invite = await getInviteByToken(params.token);
      if (!invite) throw new HttpError(404, 'Invite not found');
      return invite;
    },
    {
      params: tokenParams,
      response: { 200: InviteViewResponse, ...errors(400, 401, 404) },
      detail: {
        summary: 'Get an invite',
        description: 'Get an invite by its token, with its team, project and role.',
        ...mcpTool('get_invite'),
      },
    },
  )

  .post(
    '/invites/:token/accept',
    async ({ params, user }) => {
      const { invite, current } = await loadActionableInvite(params.token, user);
      await assertStillGrantable(invite);
      return acceptInvite(invite, current.id);
    },
    {
      params: tokenParams,
      response: { 200: AcceptInviteResponse, ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Accept an invite',
        description:
          'Accept an invite (email must match your session). An invite into a project you are ' +
          'already a member of is refused: accepting it would rewrite the membership you hold.',
        ...mcpTool('accept_invite'),
      },
    },
  )

  .post(
    '/invites/:token/reject',
    async ({ params, user }) => {
      const { invite } = await loadActionableInvite(params.token, user);
      await rejectInvite(invite.id);
      return noContent();
    },
    {
      params: tokenParams,
      response: { 204: t.Void(), ...commonErrors, ...errors(409) },
      detail: {
        summary: 'Reject an invite',
        description: 'Reject an invite (email must match your session).',
        // Rejecting consumes the invite; it has to be issued again to rejoin.
        ...mcpTool('reject_invite', { destructiveHint: true }),
      },
    },
  );