feat(teams): fire the four events, and the routes that configure them

The roster sync tickles at most ONCE per stream per run, not once per member: a
tickle is content-free, so five people joining in one sweep is five identical
notifications and one piece of information. Suppressed on a Team's FIRST roster,
the same condition the activity feed uses and the half where it matters more —
importing a 155-member guild would otherwise wake every one of their phones.

Forum notifications fire from the CONTROLLER, not from the forum model. That file
takes an already-resolved access decision and reads no membership table by design;
the fan-out reads both to compute its recipients, so calling it from inside would
make the forum model transitively depend on exactly what its header says it must
not touch. The model returns a `notify` key the controller destructures out before
the response, so the API's answer to "did my post save" is unchanged.

`pageUrlTemplate` joins the team provider — the one thing phase 6 found that the
design of record had not anticipated. Phase 3 left core with no Team page and
therefore no way to LINK to one, so a notification email could name a Team and not
take you to it. It is data rather than a callback: a function would put a module
hook on the mail path to produce a string that never varies. Relative paths only,
and protocol-relative is refused with absolute.

The unsubscribe endpoint is the only write in the public tier and the only route
with no `siteMode` — the reader is in their mail client, and the mail went out
before the site went into maintenance. POST always answers 200, valid token or
forged: distinguishing them would be an oracle for which (user, Team) pairs exist.
GET redirects and acts on nothing, so a mail client's link scanner cannot mute
Teams nobody asked to leave.

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

server/src/router/v1/public/teams.controller.js

@@ -6,6 +6,8 @@
 
 const teams = require('../../../model/teams/teams.model')
 const teamActivity = require('../../../model/teams/teamActivity.model')
+const teamPrefs = require('../../../model/teams/teamNotify.model')
+const unsubscribeToken = require('../../../utils/unsubscribeToken')
 
 const log = require('../../../utils/logger')('teams')
 
@@ -98,4 +100,52 @@ async function getActivity(req, res) {
   }
 }
 
-module.exports = { listTeams, getTeam, getTeamByExternalId, getRoster, getActivity }
+/**
+ * POST /public/teams/unsubscribe/:token — one-click unsubscribe (TEAMS.md §6.4).
+ *
+ * **The one write in this tier, and it is unauthenticated on purpose.** A person
+ * reading their mail is not logged into the site, and an unsubscribe that first
+ * demands a login is an unsubscribe most people do not complete. The token is what
+ * stands in for the session, and the capability it carries is deliberately the
+ * narrowest one that does the job: set `muted` for ONE (user, Team) pair. It reads
+ * nothing, cannot un-mute, and names no other Team.
+ *
+ * **Always 200, whatever the token was.** A response that distinguished a valid
+ * token from a forged one would turn this into an oracle for which (user, Team)
+ * pairs exist, on an endpoint with no session behind it. The page says "you will
+ * not receive further emails about this team" either way, which is true either way.
+ *
+ * Reached two ways with the same effect: a mail client's RFC 8058 one-click POST
+ * (the `List-Unsubscribe-Post` header), and the site's own /unsubscribe page,
+ * which POSTs here after a human clicks the link in the body.
+ */
+async function unsubscribe(req, res) {
+  const claim = unsubscribeToken.verify(req.params.token)
+  if (claim) {
+    try {
+      await teamPrefs.mute(claim.userId, claim.teamId)
+    } catch (err) {
+      // Logged, not surfaced. A failed write here is worth an operator's
+      // attention and is not worth telling an anonymous caller about — and a 500
+      // would make a mail client retry a request it should not repeat.
+      log.error('unsubscribe', err)
+    }
+  }
+  return res.json({ ok: true })
+}
+
+/**
+ * GET on the same path — for a mail client that shows the `List-Unsubscribe` URL
+ * as a link and has no one-click support.
+ *
+ * Redirects to the site's own page rather than acting, because a GET must not
+ * mutate: a link prefetcher or a mail client's link scanner would otherwise
+ * silently mute Teams nobody asked to leave. The page it lands on does the POST
+ * once a human is looking at it.
+ */
+function unsubscribeLanding(req, res) {
+  const base = (process.env.APP_BASE_URL || 'http://localhost:5173').replace(/\/+$/, '')
+  return res.redirect(302, `${base}/unsubscribe/${encodeURIComponent(req.params.token)}`)
+}
+
+module.exports = { listTeams, getTeam, getTeamByExternalId, getRoster, getActivity, unsubscribe, unsubscribeLanding }

server/src/router/v1/public/teams.router.js

@@ -90,4 +90,38 @@ teamsRouter.get(
   ctrl.getActivity,
 )
 
+// ── One-click unsubscribe (TEAMS.md §6.4) ──────────────────────────────────
+//
+// Declared last, and the shadowing question is worth answering rather than
+// assuming: these are two segments, so the one-segment '/:slug' cannot take them,
+// and the two-segment '/:slug/members' and '/:slug/activity' both pin a LITERAL
+// second segment. Only a token spelled exactly "members" or "activity" could
+// collide, and a token is `<v>.<uid>.<tid>.<mac>`.
+//
+// No `siteMode`, unlike every other route in this file. An unsubscribe has to work
+// while the site is in maintenance: the mail that carried the link went out before
+// the site went down, and "we are doing maintenance" is not an answer to "stop
+// emailing me".
+teamsRouter.post(
+  '/unsubscribe/:token',
+  // #swagger.tags = ['Public · Teams']
+  // #swagger.summary = 'Unsubscribe from one Team’s notification emails'
+  // #swagger.description = 'Honours the tokened link in a Team notification email, including RFC 8058 one-click. Sets the same per-Team mute the account screen shows. Always answers 200 — a response that distinguished a valid token from a forged one would be an oracle for which (user, Team) pairs exist.'
+  // #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The signed token from the email link.' }
+  // #swagger.security = [{}]
+  /* #swagger.responses[200] = { description: 'Acknowledged', content: { "application/json": { schema: { $ref: "#/components/schemas/OkFlag" } } } } */
+  ctrl.unsubscribe,
+)
+
+teamsRouter.get(
+  '/unsubscribe/:token',
+  // #swagger.tags = ['Public · Teams']
+  // #swagger.summary = 'Land a human on the unsubscribe page'
+  // #swagger.description = 'For mail clients that render the List-Unsubscribe URL as an ordinary link. Redirects to the site’s own confirmation page and changes nothing — a GET must not mutate, or a link scanner would mute Teams nobody asked to leave.'
+  // #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The signed token from the email link.' }
+  // #swagger.security = [{}]
+  /* #swagger.responses[302] = { description: 'Redirect to the site’s unsubscribe page' } */
+  ctrl.unsubscribeLanding,
+)
+
 module.exports = teamsRouter