members/index.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1/**
2 * People and roles for an app with staff (capsid docs/design/design-identity-roles.md). Each app keeps its own `members` and `member_audit` tables and its own
3 * titles; this module holds the rules every app shares, so they are tested once.
4 *
5 * Code checks permissions, never titles. A title is a named bundle of permissions on a layer:
6 *   0  primary_owner  Dustin only, from deployment configuration (PRIMARY_OWNER_EMAIL), never a row
7 *   1  owner          set on the members page by the Primary Owner only
8 *   2  leads          set by layers 0 and 1
9 *   3  members        set by layers 0 to 2
10 * Two rules decide every change: you manage only people below your own layer, and you grant nothing you
11 * do not hold. Owners and the Primary Owner hold every permission the app defines and never expire.
12 *
13 * Pure functions, no I/O, no dependencies. Dates are ISO calendar dates (YYYY-MM-DD) in UTC; a row is
14 * valid through the whole of its end date and expired from the next day.
15 *
16 * @typedef {{ id: string, label: string, layer: 2 | 3, permissions: string[], expires: boolean }} TitleSpec
17 * @typedef {{ id: string, label: string, layer: 0 | 1 | 2 | 3, permissions: string[], expires: boolean }} Title
18 * @typedef {{ permissions: string[], titles: Map<string, Title> }} Catalog
19 * @typedef {{ email: string, name?: string, title: string, end_date: string | null, status: "active" | "removed" | "expired" }} MemberRow
20 * @typedef {{ email: string, title: string, layer: number, permissions: Set<string> }} Actor
21 * @typedef {{ ok: true } | { ok: false, reason: string }} Verdict
22 */
23
24export const PRIMARY_OWNER = "primary_owner";
25export const OWNER = "owner";
26export const MANAGE_MEMBERS = "manage_members";
27/** How long before an end date a lead's review opens (ruling 5: three weeks). */
28export const REVIEW_DAYS = 21;
29
30const DAY_MS = 86_400_000;
31const ID = /^[a-z][a-z0-9_]*$/;
32const DATE = /^\d{4}-\d{2}-\d{2}$/;
33
34/** Lower-cased and trimmed, the form every comparison and every stored row uses. @param {string} email */
35export function normalizeEmail(email) {
36  if (typeof email !== "string" || !email.includes("@")) throw new TypeError(`not an email: ${email}`);
37  return email.trim().toLowerCase();
38}
39
40/**
41 * An app's titles, checked once at startup. `permissions` is every permission the app defines;
42 * `manage_members` is always among them. The two owner titles are added here and cannot be redefined.
43 * @param {{ permissions: string[], titles: TitleSpec[] }} spec
44 * @returns {Catalog}
45 */
46export function defineTitles({ permissions, titles }) {
47  if (!Array.isArray(permissions) || !Array.isArray(titles)) throw new TypeError("permissions and titles must be arrays");
48  const all = [...new Set([...permissions, MANAGE_MEMBERS])];
49  for (const p of all) if (typeof p !== "string" || !ID.test(p)) throw new TypeError(`permission ids are snake_case, got ${p}`);
50  const known = new Set(all);
51  /** @type {Map<string, Title>} */
52  const map = new Map([
53    [PRIMARY_OWNER, { id: PRIMARY_OWNER, label: "Primary Owner", layer: 0, permissions: all, expires: false }],
54    [OWNER, { id: OWNER, label: "Owner", layer: 1, permissions: all, expires: false }],
55  ]);
56  for (const t of titles) {
57    if (typeof t?.id !== "string" || !ID.test(t.id)) throw new TypeError(`title ids are snake_case, got ${t?.id}`);
58    if (map.has(t.id)) throw new TypeError(`title ${t.id} is defined twice or is reserved`);
59    if (t.layer !== 2 && t.layer !== 3) throw new TypeError(`title ${t.id}: an app's own titles sit on layer 2 or 3, got ${t.layer}`);
60    if (typeof t.label !== "string" || !t.label.trim()) throw new TypeError(`title ${t.id} needs a label`);
61    if (typeof t.expires !== "boolean") throw new TypeError(`title ${t.id}: say whether it expires`);
62    if (!Array.isArray(t.permissions)) throw new TypeError(`title ${t.id}: permissions must be an array`);
63    for (const p of t.permissions) if (!known.has(p)) throw new TypeError(`title ${t.id} names unknown permission ${p}`);
64    map.set(t.id, { id: t.id, label: t.label, layer: t.layer, permissions: [...new Set(t.permissions)], expires: t.expires });
65  }
66  return { permissions: all, titles: map };
67}
68
69/** @param {string} date */
70function dayStart(date) {
71  if (typeof date !== "string" || !DATE.test(date) || Number.isNaN(Date.parse(`${date}T00:00:00Z`))) throw new TypeError(`not a YYYY-MM-DD date: ${date}`);
72  return Date.parse(`${date}T00:00:00Z`);
73}
74
75/** Whether a row's end date has passed at `nowMs`. A null end date never passes. @param {MemberRow} row @param {number} nowMs */
76export function isExpired(row, nowMs) {
77  return row.end_date !== null && nowMs >= dayStart(row.end_date) + DAY_MS;
78}
79
80/** Whether the lead's "still on your team?" review is open for this row. @param {MemberRow} row @param {number} nowMs */
81export function reviewOpen(row, nowMs) {
82  return row.status === "active" && row.end_date !== null && !isExpired(row, nowMs) && nowMs >= dayStart(row.end_date) - REVIEW_DAYS * DAY_MS;
83}
84
85/**
86 * Who is asking. The Primary Owner comes from deployment configuration and has no row; anyone else needs an
87 * active, unexpired row with a title the app defines. Read the row on every request, uncached, so a removal
88 * or an expiry takes effect on the next click. Returns null for a person with no access.
89 * @param {string} email the verified Access email
90 * @param {MemberRow | null | undefined} row this email's row, if any
91 * @param {{ catalog: Catalog, primaryOwnerEmail: string, nowMs: number }} context
92 * @returns {Actor | null}
93 */
94export function resolveActor(email, row, { catalog, primaryOwnerEmail, nowMs }) {
95  const who = normalizeEmail(email);
96  if (!primaryOwnerEmail) throw new TypeError("PRIMARY_OWNER_EMAIL is not set");
97  if (who === normalizeEmail(primaryOwnerEmail)) return actorFor(who, catalog.titles.get(PRIMARY_OWNER));
98  if (!row || normalizeEmail(row.email) !== who || row.status !== "active" || isExpired(row, nowMs)) return null;
99  const title = catalog.titles.get(row.title);
100  if (!title || title.layer === 0) return null;
101  return actorFor(who, title);
102}
103
104/** @param {string} email @param {Title | undefined} title @returns {Actor} */
105function actorFor(email, title) {
106  if (!title) throw new TypeError("unknown title");
107  return { email, title: title.id, layer: title.layer, permissions: new Set(title.permissions) };
108}
109
110/** Whether the actor holds a permission. The only question a handler asks. @param {Actor | null} actor @param {string} permission */
111export function can(actor, permission) {
112  return !!actor && actor.permissions.has(permission);
113}
114
115/**
116 * The end date a title gets by default: the first of the app's term end dates after today. Titles that do
117 * not expire get null. Refuses when the Owner has not entered a future term end yet, so no row is written
118 * with an invented date.
119 * @param {Title} title
120 * @param {string[]} termEnds the app's semester or term end dates, entered once a year by an Owner
121 * @param {number} nowMs
122 * @param {string | null} [after] renew: the row's current end date, so the next term is the one after it
123 */
124export function defaultEndDate(title, termEnds, nowMs, after = null) {
125  if (!title.expires) return null;
126  const floor = Math.max(nowMs, after ? dayStart(after) + DAY_MS : nowMs);
127  const next = [...termEnds].map((d) => [d, dayStart(d)]).filter(([, t]) => t + DAY_MS > floor).sort((a, b) => a[1] - b[1])[0];
128  if (!next) throw new RangeError("no term end date after today: an Owner enters this year's dates first");
129  return next[0];
130}
131
132/**
133 * Whether `actor` may make `change`. Every rule is here, so the members page, its API and any agent
134 * acting for an app ask the same function.
135 *   add           { kind: "add", email, title, end_date }
136 *   change_title  { kind: "change_title", target, title, reason }
137 *   renew         { kind: "renew", target }
138 *   remove        { kind: "remove", target }
139 * `target` is the person's current row. The Primary Owner has no row, so nothing can remove or demote them.
140 * @param {Actor | null} actor
141 * @param {{ kind: "add" | "change_title" | "renew" | "remove", email?: string, title?: string, end_date?: string | null, target?: MemberRow, reason?: string }} change
142 * @param {{ catalog: Catalog, primaryOwnerEmail: string, termEnds: string[], nowMs: number }} context
143 * @returns {Verdict}
144 */
145export function checkChange(actor, change, { catalog, primaryOwnerEmail, termEnds, nowMs }) {
146  if (!actor) return refuse("not signed in as a member");
147  if (!can(actor, MANAGE_MEMBERS)) return refuse("you do not hold manage_members");
148  const primary = normalizeEmail(primaryOwnerEmail);
149
150  const email = change.kind === "add" ? change.email : change.target?.email;
151  if (typeof email !== "string") return refuse(change.kind === "add" ? "an email is required" : "the person's row is required");
152  const who = normalizeEmail(email);
153  if (who === primary) return refuse("the Primary Owner is set in deployment configuration, not here");
154
155  if (change.kind !== "add") {
156    const current = catalog.titles.get(/** @type {MemberRow} */ (change.target).title);
157    if (!current) return refuse(`unknown current title ${change.target?.title}`);
158    if (current.layer <= actor.layer) return refuse("you manage only people below your own layer");
159  }
160
161  if (change.kind === "add" || change.kind === "change_title") {
162    const title = catalog.titles.get(/** @type {string} */ (change.title));
163    if (!title || title.layer === 0) return refuse(`unknown title ${change.title}`);
164    if (title.layer <= actor.layer) return refuse("you can give only titles below your own layer");
165    const wider = title.permissions.filter((p) => !actor.permissions.has(p));
166    if (wider.length) return refuse(`you cannot grant what you do not hold: ${wider.join(", ")}`);
167    if (change.kind === "change_title") {
168      if (title.id === change.target?.title) return refuse("that is already their title");
169      if (typeof change.reason !== "string" || !change.reason.trim() || /[\r\n]/.test(change.reason)) return refuse("a one-line reason is required");
170    }
171    if (change.kind === "add") {
172      const limit = defaultEndDate(title, termEnds, nowMs);
173      if (limit === null) {
174        if (change.end_date != null) return refuse(`${title.label} does not expire`);
175      } else {
176        if (typeof change.end_date !== "string") return refuse("an end date is required");
177        const end = dayStart(change.end_date);
178        if (end > dayStart(limit)) return refuse(`the end date can be shortened, not lengthened past ${limit}`);
179        if (end + DAY_MS <= nowMs) return refuse("the end date has already passed");
180      }
181    }
182  }
183
184  if (change.kind === "renew") {
185    const title = /** @type {Title} */ (catalog.titles.get(/** @type {MemberRow} */ (change.target).title));
186    if (!title.expires) return refuse(`${title.label} does not expire`);
187    if (change.target?.status === "removed") return refuse("a removed person is added again, not renewed");
188  }
189  if (change.kind === "remove" && change.target?.status === "removed") return refuse("already removed");
190  return { ok: true };
191}
192
193/** @param {string} reason @returns {Verdict} */
194function refuse(reason) {
195  return { ok: false, reason };
196}
197
198/**
199 * The `member_audit` row for a change, written in the same batch as the member row. `cloudflare` starts
200 * "pending" and the sync's answer updates it, so a failed sync shows and is retried, never ignored.
201 * @param {{ actor: Actor, action: "add" | "change_title" | "renew" | "remove" | "expire", email: string, before: MemberRow | null, after: MemberRow | null, reason?: string, nowMs: number }} entry
202 */
203export function auditRow({ actor, action, email, before, after, reason, nowMs }) {
204  return {
205    at: new Date(nowMs).toISOString(),
206    actor: actor.email,
207    actor_title: actor.title,
208    action,
209    member_email: normalizeEmail(email),
210    before: before ? JSON.stringify(before) : null,
211    after: after ? JSON.stringify(after) : null,
212    reason: reason ?? null,
213    cloudflare: "pending",
214  };
215}
216
217/**
218 * The emails that belong on the app's Access allow list: every active, unexpired row whose title the app defines,
219 * the same rows resolveActor admits. The Primary Owner is not on it; admin surfaces list Dustin's emails directly in
220 * their own policies.
221 * @param {MemberRow[]} rows
222 * @param {number} nowMs
223 * @param {Catalog} catalog
224 */
225export function allowList(rows, nowMs, catalog) {
226  const admitted = (/** @type {MemberRow} */ r) => {
227    const title = catalog.titles.get(r.title);
228    return r.status === "active" && !isExpired(r, nowMs) && Boolean(title) && title?.layer !== 0;
229  };
230  return [...new Set(rows.filter(admitted).map((r) => normalizeEmail(r.email)))].sort();
231}