feat(teams): the grant flow, announcements, and the routes behind both guards

Path 3's WRITE half. The resolver landed in phase 2; this is who may hand access
out, to whom, and what stops a leader turning a Team forum into open hosting on
the operator's site.

Two authorities, and not one authority with different reach. Staff may act on any
Team, uncapped, and may revoke anything. A leader may grant and revoke ordinary
access on their own Team, is capped at `teams_max_grants_per_team` (default 50),
is rate-limited, and may NOT revoke a staff-issued grant — which is what stops a
leader undoing a moderation decision. The issuer's role is checked at revoke time
rather than stored, so an account that has since lost its staff role stops
protecting the grants it made.

Nothing on this path writes team_members, in either direction. A grant may name any
account, including one with no linked game identity — that is the point of it — and
that account stays off the roster, out of every count, and ineligible for external
platforms.

Announcements are a degenerate thread rather than their own object, so phase 5 adds
no migration. Moderation records WHICH authority was exercised: a staff action also
writes activity_log, a leader's writes only the Team's own ledger. Merging the two
would make a guild leader locking a thread an appealable Discord sanction.

Every forum route answers 404 while the switch is off, and 404 — never 403 — to a
caller with no access: in a private room the contents and the existence are the
same secret. The grant routes deliberately answer even while the forum is OFF,
because a toggle-off revokes no grant and the access list has to stay manageable.

Under /player rather than /admin: a leader is a player, and the /admin tier gate is
requireRole('admin','editor','moderator') — putting a leader endpoint behind it
would mean widening that gate.

Co-Authored-By: Claude <noreply@anthropic.com>

server/src/model/teams/teamGrants.model.js

@@ -0,0 +1,165 @@
+// ── The grant/revoke flow (TEAMS.md §2.5 path 3) ───────────────────────────
+//
+// The RESOLVER lives in teamAccess.model.js and answers "may this account use the
+// forum". This file is the WRITE half: who may hand that access out, to whom, and
+// what stops a leader turning a Team forum into open hosting on the operator's
+// site.
+//
+// **Two authorities, and they are not the same authority with different reach.**
+//
+//   staff  (admin | moderator) — any Team, no cap, may revoke anything
+//   leader (path 2, on THIS Team) — own Team, capped, may not revoke a staff grant
+//
+// The last clause is the one worth stating: a leader who could revoke a
+// staff-issued grant could undo a moderation decision, which is the whole reason
+// `granted_by` is retained rather than collapsed into a boolean.
+//
+// **Nothing here writes `team_members`, in either direction, ever.** A grant is
+// not a membership: it may name any Runic Gateway account, including one with no
+// linked game identity at all — that is the point of it, since letting an unlinked
+// guildmate into the forum must not be a staff ticket. `teams.model.js` keeps such
+// an account off the roster and out of every membership count, and path 4 keeps it
+// off external platforms.
+
+const accessDb = require('./teamAccess.db')
+const teamsDb = require('./teams.db')
+const access = require('./teamAccess.model')
+const usersDb = require('../users/users.db')
+const settingsDb = require('../settings/settings.db')
+
+// The per-Team ceiling on ACTIVE leader-issued grants. A leader admitting
+// unlimited arbitrary accounts to a private space on the operator's host is a
+// quiet way to turn a Team forum into free hosting; the cap is what makes it a
+// decision the operator made rather than one a leader made for them.
+const CAP_KEY = 'teams_max_grants_per_team'
+const DEFAULT_CAP = 50
+
+const STAFF_ROLES = ['admin', 'moderator']
+
+async function grantCap() {
+  const raw = await settingsDb.get(CAP_KEY)
+  const n = Number.parseInt(raw, 10)
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_CAP
+}
+
+const isStaff = (actor) => STAFF_ROLES.includes(actor?.role)
+
+/**
+ * What may this actor do with grants on this Team?
+ *
+ * Resolved once and returned whole, so the controller asks a question rather than
+ * assembling the answer from three booleans — the shape that lets a leader check
+ * and a staff check drift apart.
+ */
+async function authorityFor(teamId, actor) {
+  if (isStaff(actor)) return { may: true, as: 'staff' }
+  const leads = await access.isLeaderByUser(teamId, actor?.id)
+  return { may: leads, as: leads ? 'leader' : null }
+}
+
+/**
+ * Issue a grant. Returns the model result shape the Teams controllers translate:
+ * `{ ok }` or `{ ok: false, status, error }`.
+ *
+ * `warning` on a staff grant past the cap is deliberate and is not an error:
+ * staff are exempt, and silently exceeding a ceiling the operator configured is
+ * worth saying out loud on the way past.
+ */
+async function grant({ team, actor, userId, username, reason }) {
+  const authority = await authorityFor(team.id, actor)
+  if (!authority.may) return { ok: false, status: 403, error: 'Not a leader of this Team' }
+
+  const target = userId
+    ? await usersDb.findById(userId)
+    : await usersDb.findByUsername(username)
+  if (!target) return { ok: false, status: 404, error: 'No such account' }
+
+  const existing = await accessDb.activeGrant(team.id, target.id)
+  if (existing) return { ok: false, status: 409, error: 'That account already has an active grant' }
+
+  const cap = await grantCap()
+  const count = await accessDb.activeGrantCount(team.id)
+  let warning = null
+  if (count >= cap) {
+    if (authority.as === 'leader') {
+      return { ok: false, status: 409, error: `This Team has reached its limit of ${cap} forum guests` }
+    }
+    warning = `This Team is past the configured limit of ${cap} forum guests`
+  }
+
+  await accessDb.insertGrant({
+    teamId: team.id,
+    userId: target.id,
+    username: target.username,
+    grantedBy: actor.id,
+    grantedUsername: actor.username,
+    reason,
+  })
+  return { ok: true, as: authority.as, grantee: target.username, ...(warning ? { warning } : {}) }
+}
+
+/**
+ * Revoke a grant.
+ *
+ * The one asymmetry with `grant`: a leader may not revoke what staff issued.
+ * Checked against `granted_by`'s role AT REVOKE TIME rather than against a stored
+ * flag, so an account that has since lost its staff role stops protecting the
+ * grants it made — which is the behaviour an operator demoting someone expects.
+ */
+async function revoke({ team, actor, userId, reason }) {
+  const authority = await authorityFor(team.id, actor)
+  if (!authority.may) return { ok: false, status: 403, error: 'Not a leader of this Team' }
+
+  const existing = await accessDb.activeGrant(team.id, userId)
+  if (!existing) return { ok: false, status: 404, error: 'No active grant for that account' }
+
+  if (authority.as === 'leader' && existing.granted_by) {
+    const issuer = await usersDb.findById(existing.granted_by)
+    if (isStaff(issuer)) {
+      return { ok: false, status: 403, error: 'That access was granted by staff and only staff may revoke it' }
+    }
+  }
+
+  await accessDb.revokeGrant({
+    teamId: team.id,
+    userId,
+    revokedBy: actor.id,
+    revokedUsername: actor.username,
+    reason,
+  })
+  return { ok: true, as: authority.as, grantee: existing.username }
+}
+
+/**
+ * The Team's forum guests — active grants for accounts that are NOT members.
+ *
+ * The subtraction is the §3.2 "Forum guests" list: someone who is both a member
+ * and a grantee is a member, listed on the roster, and appears here not at all.
+ * Both facts stay true in the ledger; only the presentation picks one.
+ */
+async function forumGuests(teamId) {
+  const [grants, members] = await Promise.all([
+    accessDb.activeGrants(teamId),
+    teamsDb.membersByTeam(teamId, { includeDeparted: false }),
+  ])
+  const memberUserIds = new Set(members.map((m) => m.user_id).filter((id) => id != null))
+  return grants
+    .filter((g) => g.user_id == null || !memberUserIds.has(g.user_id))
+    .map((g) => ({
+      userId: g.user_id,
+      username: g.username,
+      grantedBy: g.granted_username,
+      grantedAt: g.granted_at,
+      reason: g.reason,
+    }))
+}
+
+module.exports = {
+  CAP_KEY,
+  DEFAULT_CAP,
+  grantCap,
+  authorityFor,
+  grant,
+  revoke,
+  forumGuests,
+}