1// Grant and remove membership in your Sentry organization, for an access
2// rule. After the request is approved, Risotto runs it with action "grant":
3// it invites the person with the role and team the rule pins, and Sentry
4// emails them the invite. When the access ends, Risotto runs it again with
5// action "remove".
6//
7// Before publishing: in Sentry, under Settings > Developer Settings, create
8// an internal integration whose Member permission is Admin, and set
9// SENTRY_AUTH_TOKEN to its token. Listing members needs member:read,
10// inviting needs member:write and removing needs member:admin. An
11// integration's token can only invite with the member role. Then pin
12// organization_slug, org_role and team_slug on the access rule.
13//
14// sentry.io reaches every organization. Your organization's region domain
15// (us.sentry.io or de.sentry.io) is faster; on self-hosted Sentry, use your
16// own host. Change it in `domains` and SENTRY below.
17
18export const input = z.object({
19 action: z.enum(["grant", "remove"]),
20 recipient_email: z.string(),
21 // Other emails of the same person, for a fallback lookup. Not other users.
22 recipient_email_aliases: z.array(z.string()).optional(),
23 organization_slug: z
24 .string()
25 .describe("The organization's slug, as in sentry.io/organizations/<slug>"),
26 org_role: z
27 .enum(["member", "billing", "manager", "owner", "admin"])
28 .describe("The organization role a grant gives"),
29 team_slug: z.string().describe("The team a grant adds the person to"),
30});
31
32// Inviting and removing members are writes, so the host needs "read_write".
33export const domains = { "sentry.io": "read_write" };
34
35const SENTRY = "https://sentry.io/api/0";
36
37type Member = { id: string; email: string; orgRole: string; pending: boolean };
38
39type SentryResponse = { status_code: number; body: unknown };
40
41const isObject = (value: unknown): value is Record<string, unknown> =>
42 typeof value === "object" && value !== null;
43
44const text = (value: unknown, key: string): string =>
45 isObject(value) && typeof value[key] === "string" ? value[key] : "";
46
47// What to check for the refusals a setup problem causes.
48const FIXES: Record<number, string> = {
49 401: "Check SENTRY_AUTH_TOKEN.",
50 403: "Check that the token has member:read, member:write and member:admin.",
51 404: "Check the organization_slug pinned on the access rule.",
52};
53
54// Ends the run with Sentry's status and reason, and the likely fix.
55function refused(doing: string, response: SentryResponse): never {
56 const said =
57 text(response.body, "detail") ||
58 JSON.stringify(response.body ?? "").slice(0, 300);
59 const fix = FIXES[response.status_code] ?? "";
60 const status = `Sentry returned ${response.status_code}`;
61 fail(`Couldn't ${doing}. ${status}: ${said} ${fix}`.trim());
62}
63
64const membersUrl = (org: string) => `${SENTRY}/organizations/${org}/members/`;
65
66// The member with this email, or null. An open invite is a member too, with
67// pending set.
68async function findMember(org: string, email: string): Promise<Member | null> {
69 const response = await http.get(membersUrl(org), {
70 query: { query: `email:${email}` },
71 auth: { type: "bearer", token: env.SENTRY_AUTH_TOKEN },
72 });
73 if (response.status_code !== 200) {
74 refused(`look up ${email} in ${org}`, response);
75 }
76 const first: unknown = Array.isArray(response.body) ? response.body[0] : null;
77 if (!isObject(first) || typeof first.id !== "string") {
78 return null;
79 }
80 return {
81 id: first.id,
82 email: text(first, "email"),
83 orgRole: text(first, "orgRole"),
84 pending: first.pending === true,
85 };
86}
87
88// Sentry emails them the invite. The team membership comes with it.
89async function invite(
90 org: string,
91 email: string,
92 role: string,
93 team: string,
94): Promise<string> {
95 const response = await http.post(membersUrl(org), {
96 auth: { type: "bearer", token: env.SENTRY_AUTH_TOKEN },
97 json: {
98 email,
99 orgRole: role,
100 teamRoles: [{ teamSlug: team, role: "contributor" }],
101 sendInvite: true,
102 },
103 });
104 if (response.status_code !== 201) {
105 refused(`invite ${email} to ${org}`, response);
106 }
107 return `Invited ${email} to ${org} as ${role} on team ${team}.`;
108}
109
110// Removing an open invite withdraws it.
111async function removeMember(org: string, member: Member) {
112 const response = await http.delete(`${membersUrl(org)}${member.id}/`, {
113 auth: { type: "bearer", token: env.SENTRY_AUTH_TOKEN },
114 });
115 if (response.status_code !== 204) {
116 refused(`remove ${member.email} from ${org}`, response);
117 }
118}
119
120export default async function run(params: z.infer<typeof input>) {
121 const org = params.organization_slug;
122 const email = params.recipient_email;
123
124 // **Find the person in Sentry**
125 // By their email first, then their other emails. An open invite counts.
126 let member: Member | null = null;
127 for (const address of [email, ...(params.recipient_email_aliases ?? [])]) {
128 // ??= looks up the next email only while there's no match.
129 member ??= await findMember(org, address);
130 }
131
132 if (params.action === "grant") {
133 // **Grant access**
134 // Sentry emails the invite. A current member keeps the role they have.
135 return member === null
136 ? await invite(org, email, params.org_role, params.team_slug)
137 : `${member.email} is already in ${org}. Nothing to change.`;
138 }
139
140 // **Remove access**
141 // Succeeds when they're not in Sentry, since Risotto may not have granted it.
142 if (member === null) {
143 return `${email} isn't in ${org}. Nothing to remove.`;
144 }
145 // Take away only the role this rule gives. Another role stays as it is.
146 if (member.orgRole !== params.org_role) {
147 return (
148 `${member.email} is ${member.orgRole} in ${org}, not ` +
149 `${params.org_role}, so they keep their access.`
150 );
151 }
152 await removeMember(org, member);
153 return member.pending
154 ? `Withdrew ${member.email}'s invite to ${org}.`
155 : `Removed ${member.email} from ${org}.`;
156}