|
| 1 | +--- |
| 2 | +status: in-progress |
| 3 | +depends: [admin-members-moderation] |
| 4 | +specs: |
| 5 | + - specs/screens/admin-members.md |
| 6 | + - specs/api/moderation.md |
| 7 | + - specs/api/auth.md |
| 8 | + - specs/api/saml.md |
| 9 | + - specs/api/webhooks.md |
| 10 | + - specs/behaviors/private-storage.md |
| 11 | + - specs/behaviors/spam-exclusion.md |
| 12 | +issues: [] |
| 13 | +pr: null |
| 14 | +--- |
| 15 | + |
| 16 | +# Plan: roster signals — origin, GitHub reputation, Slack SSO, bounces |
| 17 | + |
| 18 | +## Scope |
| 19 | + |
| 20 | +The first day on `/admin/members` showed the roster makes staff read four |
| 21 | +fields to reach "this is a throwaway": no sign-in, no avatar, free-mail |
| 22 | +address that doesn't match the name, zero footprint. And the signals that |
| 23 | +matter most — did they arrive through GitHub, is GitHub still vouching for |
| 24 | +them, have they ever used Slack, does their mailbox exist — were either |
| 25 | +invisible (origin), discarded at sign-in (GitHub profile facts), never |
| 26 | +recorded (Slack SSO), or never collected (bounces). Spammers are now arriving |
| 27 | +through GitHub OAuth, so GitHub's own moderation (suspended/deleted accounts) |
| 28 | +is the highest-value new signal. |
| 29 | + |
| 30 | +In: |
| 31 | + |
| 32 | +1. **Row-local signals** on the roster: origin (imported vs signed up here), |
| 33 | + name/email mismatch, bio link count / no bio, no avatar, sign-in count, an |
| 34 | + attention tint computed from those facts; origin filter; default vote |
| 35 | + filter "no vote yet"; `j`/`k`/`s`/`n`/`Enter` keys. |
| 36 | +2. **GitHub reputation** captured at every GitHub sign-in (account age, public |
| 37 | + repos, followers, following, type) into the private profile, and a |
| 38 | + **staleness-driven probe** (`GET /user/{id}` with the OAuth app's client |
| 39 | + credentials) that marks linked accounts `ok` / `gone` — run lazily for the |
| 40 | + rows on a roster page when older than a day. |
| 41 | +3. **Slack SSO stamp** — `lastSlackSsoAt` on the private profile whenever the |
| 42 | + IdP issues an assertion. |
| 43 | +4. **Postmark bounce webhook** — `POST /api/_webhooks/postmark/bounce` stores |
| 44 | + hard bounces / spam complaints on the private profile. |
| 45 | +5. **`probe-github` evaluator** in the private spam-detection repo: gone |
| 46 | + accounts → `spam` (0.95); old, active accounts → `legit` (0.9) so the prune |
| 47 | + never removes someone GitHub vouches for. |
| 48 | + |
| 49 | +Out: SMTP/RCPT probing (unreliable, gets the IP listed); Slack workspace |
| 50 | +membership on the roster (needs the pipeline to stamp it; later); bulk votes. |
| 51 | + |
| 52 | +## Implements |
| 53 | + |
| 54 | +- [screens/admin-members.md](../specs/screens/admin-members.md) — badges, |
| 55 | + attention tint, filters, keys. |
| 56 | +- [api/moderation.md](../specs/api/moderation.md) — new row fields |
| 57 | + (`origin`, `github`, `lastSlackSsoAt`, `signInCount`, `emailBounce`, |
| 58 | + `signals`), `origin` filter. |
| 59 | +- [api/auth.md](../specs/api/auth.md) — GitHub profile facts kept at sign-in. |
| 60 | +- [api/saml.md](../specs/api/saml.md) — assertion issuance stamps the profile. |
| 61 | +- [api/webhooks.md](../specs/api/webhooks.md) — the Postmark bounce endpoint. |
| 62 | +- [behaviors/private-storage.md](../specs/behaviors/private-storage.md) — |
| 63 | + `github`, `lastSlackSsoAt`, `emailBounce` on the profile record. |
| 64 | +- [behaviors/spam-exclusion.md](../specs/behaviors/spam-exclusion.md) — the |
| 65 | + `github-probe` evaluator. |
| 66 | + |
| 67 | +## Approach |
| 68 | + |
| 69 | +- `packages/shared`: extend `PrivateProfileSchema` (all new fields optional so |
| 70 | + existing `profiles.jsonl` lines still parse). |
| 71 | +- `auth/github-client.ts`: `fetchGitHubUser` keeps the reputation fields; |
| 72 | + `probeGitHubUser(id, clientId, clientSecret)` returns `{status, facts}` |
| 73 | + (404 → `gone`; other non-2xx → throw, caller keeps the old record). |
| 74 | +- `services/github-account.ts`: create / refresh / link all write |
| 75 | + `profile.github`. |
| 76 | +- `routes/saml.ts`: one helper stamps `lastSlackSsoAt` after each of the three |
| 77 | + `renderPostForm` sites. |
| 78 | +- `routes/webhooks.ts`: bounce endpoint, bearer or basic-auth secret |
| 79 | + (`POSTMARK_WEBHOOK_SECRET`), 503 when unset, 200 always once authenticated, |
| 80 | + resolves `Email` → person via the private store's email index. |
| 81 | +- `services/moderation.ts`: row assembly gains the new fields and `signals`; |
| 82 | + a `GitHubProbe` dependency (injected; absent in tests and when the OAuth app |
| 83 | + isn't configured) refreshes stale `github` records for the rows on the page |
| 84 | + with bounded concurrency before serialising. |
| 85 | +- Web: chips and tint per spec; `origin` filter; default `vote=none`; |
| 86 | + keyboard handler at the page level. |
| 87 | +- Private repo: `scripts/probe-github.ts` + `npm run probe-github`. |
| 88 | + |
| 89 | +## Validation |
| 90 | + |
| 91 | +- Unit: signals computed from fixtures (mismatch, links, no bio); probe |
| 92 | + results persisted; stale/fresh gating; bounce webhook auth + mapping; |
| 93 | + SAML stamp after `/launch` and `/sso`; GitHub facts captured on create and |
| 94 | + refresh. |
| 95 | +- Full gate: `npm run type-check && npm run lint && npm test`. |
| 96 | +- Live: roster shows origin/GitHub chips for the four linked accounts; a |
| 97 | + Postmark test bounce lands on a profile; Slack sign-in stamps the profile. |
| 98 | + |
| 99 | +## Follow-ups |
| 100 | + |
| 101 | +None. |
0 commit comments