Station signup: manager API for reveal, rotate, revoke, clear-cooldown, status, and approve

[jakebromberg]

Problem

Managers need to operate the passcode and clear the review queue. Without these endpoints the feature is unmanageable: no way to rotate the sticky-note code, no way to recover from a cooldown, no way to mark an account reviewed.

Desired end state

Endpoints in apps/auth/, mounted beside the other admin routes:

• Reveal — returns the current plaintext code. Readable storage exists precisely so a manager can read the code to a stranded DJ by phone without rotating (rotating under the two-row cap can invalidate the note the rest of the room is using).
• Rotate — generates a new code, returns the plaintext, refuses beyond two active rows.
• Revoke — manual kill switch, sets revoked_reason = 'manual'.
• Clear cooldown — writes a cooldown_cleared row that acts as a floor on the failure window. This is the escape hatch that keeps the cooldown from being a lockout: a sustained attacker can otherwise hold the endpoint in cooldown with nothing in the product able to clear it. Cheap, same auth gate, and it turns "wait for a manager who is not on site" into one phone call.
• Status — active code state (expired / revoked with reason, last_used_at, use_count / max_uses), cooldown state, recent failure counts.
• Approve account — sets self_signup_reviewed_at / _reviewed_by.

Every reveal writes a passcode_revealed row carrying actor_user_id. Readable storage removes the structural guarantee show-once storage had for free — that only whoever rotated ever saw the code — so the audit log is what replaces it, and it makes "who could have seen this?" answerable after a suspected leak.

Auth gate — state it precisely

Use the admin-flag check the sibling endpoint uses: session.user.role !== 'admin' -> 403 (apps/auth/app.ts:253-256). requirePermissions lives in the backend app, not here.

Be explicit that this is not "stationManager only": via grantsAdminFlag it also admits stray admin/owner membership rows. That is the right trade — /auth/admin/provision-user, which creates accounts at any role including stationManager, already sits behind exactly this gate, so passcode rotation is not a wider grant than what it protects. A true stationManager-only gate would need a membership-role read that nothing in apps/auth does today; if that is wanted it is its own change with its own test.

The approve action must not go through public POST /update-user. The three review columns carry input: false, which blocks that route by design (that is the point — it is what stops a DJ approving themselves). Use the admin plugin route or a dedicated endpoint. The BS#2297 comment confirms both internalAdapter writes and the admin plugin's adminUpdateUser bypass input filtering, so either works.

Acceptance criteria

• All six operations behind the admin-flag gate
• Reveal writes a passcode_revealed audit row with actor_user_id
• Rotate refuses beyond two active rows
• Clear-cooldown writes a floor row and deletes nothing
• Approve does not use public /update-user
• Integration tests in tests/integration/*.spec.js (plain JS — see jest.config.json testMatch)

Context

Plan: ~/Downloads/wxyc-station-passcode-signup-plan.md.

Related

Blocked by the lifecycle module. Blocks the dj-site passcode panel.

Blocked by

• Station signup: station-passcode.ts lifecycle module (encrypt, verify, rotate, cooldown) #2359

[jakebromberg]

The approve endpoint needs a position on already-downgraded accounts

#2364 just landed auth_user.self_signup_downgraded_at (migration 0161) — the terminal marker jobs/station-signup-review stamps when it auto-downgrades an unreviewed self-signup from dj to member after 30 days. It exists because the downgrade deliberately does not stamp self_signup_reviewed_at (that predicate is this queue, and dj-site's roster filter, so stamping it would empty the manager's queue and make the account invisible), which meant a downgraded account never left the pending cohort and got re-downgraded every time a manager re-promoted it. The marker makes the actuator fire at most once per account.

That leaves three things for the approve endpoint to decide, none of which are covered by the current acceptance criteria.

1. What does approving an already-downgraded account mean? Approve as specified sets self_signup_reviewed_at / _reviewed_by and nothing else. For an account the job already demoted, that clears it out of the review queue while leaving it at member — a manager who clicks "approve" on a DJ they know and trust gets a reviewed account that still cannot write to the flowsheet, with no signal anywhere that the two facts are related. Approve almost certainly should not silently restore dj either; the point is that a human decides. But it has to decide something, and the panel has to show which case it is in.

2. Couple approve with an optional promote, so panel users never hit the re-promote trap. The marker closed the automatic re-fire loop, but the manual sequence it creates is still awkward: approve here, then go to the roster and change the role there, two surfaces for one decision. POST /admin/station-signup/approve taking an optional role (or an explicit restoreRole: true) and doing both in one transaction is the shape that matches what a manager is actually doing. The write path is the same one BS#2364 established as safe for this pair specifically — grantsAdminFlag is normalizeRole(role) === 'stationManager', so neither dj nor member touches the auth_user.role='admin' flag. Anything involving stationManager is a different problem and needs the hook.

3. self_signup_downgraded_at should survive approval as history. Do not clear it. It is the record of what happened to the account, and it is the only way to answer "was this person auto-demoted, or did they always hold member?" after the review queue has been cleared. The job never clears it either — a role edit is not a history edit.

Also worth surfacing in Status (or a per-account variant): the field is deliberately returned: true in additionalFields, precisely so it reaches admin/list-users and the panel can render "auto-downgraded 2026-08-06" next to a pending account. returned is global, not audience-scoped, so hiding it would have hidden it from the roster too — see the writeup at shared/authentication/src/auth.definition.ts and docs/authentication.md.

Suggested extra acceptance criteria:

• Approve has a defined, tested behaviour for an account with self_signup_downgraded_at IS NOT NULL
• Approve accepts an optional role restore and applies it in the same transaction as the review stamp
• Approve leaves self_signup_downgraded_at untouched, with a test pinning it

[jakebromberg]

One more item for the acceptance criteria, from the #2369 review: the downgrade job's apply transaction currently re-checks only member.role = 'dj', not self_signup_reviewed_at IS NULL or the on-air guard, so once this endpoint exists a review that lands during the job's plan->notify window would still be followed by a downgrade, and the marker stamp makes that terminal. Today the window is the SES round trip once per day and nothing in-tree writes self_signup_reviewed_at, which is why it shipped as-is — but the endpoint this issue adds creates the first real writer. The cheap hardening is to re-select self_signup_reviewed_at/self_signup_downgraded_at inside the apply transaction and abort the flip when either is non-null; it should land with or before this endpoint.