Skip to content

Commit 7673a14

Browse files
chore(plans): add roster-signals
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LFyA5poHwrhAktrnsKrUiQ
1 parent 94b6dad commit 7673a14

1 file changed

Lines changed: 101 additions & 0 deletions

File tree

‎plans/roster-signals.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
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

Comments
 (0)