Honor delegated hacker read and edit permissions in Blade

[DGoel1602]

Organizers granted READ_HACKERS and EDIT_HACKERS still cannot open the Hackers roster. Blade's navigation, admin layout, page gate, and all hacker API procedures require IS_OFFICER, despite the configurable permission labels promising hacker access.

Expected behavior:

• READ_HACKERS grants roster, search/filter, application details, and attendee event-history access without officer status.
• EDIT_HACKERS additionally grants application editing and existing status/points/deletion operations.
• Read-only users have no write controls or API write access.
• Blacklist information, blacklist changes, and hackathon configuration remain officer-only, with existing transition safeguards preserved.

Scope: Blade and the hacker-related API boundaries. Reuse the existing permission bits; no schema or dependency changes.

[coderabbitai]

Coding Plan

Summary

• Add packages/api/src/utils/hacker/access.ts with requireHackerRead/requireHackerEdit guards and replace the blanket officer gate in hacker.ts and listHackerEventAttendance, keeping setBlacklist and blacklist data officer-only.
• Add canAccessHackers/canEditHackers/canManageHackerBlacklist to Blade admin-access.ts, open the nav, layout, and page to readers, and thread capability props into the roster components to hide write and blacklist controls.
• Rewrite the router access test and add a guard unit test to pin the read/edit/officer tiers, and update the SRD to record the policy change.
• Preserve all existing transition safeguards; they run after the permission guard and apply to every tier.

Design Choices

Design Choice 1: Keep blacklist data officer-only when non-officer readers use the roster

Options Considered:

1. Strip blacklisted and blacklistReason from procedure output when the caller is not an officer.
2. Add separate read permission for blacklist.

Chosen Option: 1

Rationale: The SRD keeps blacklist strictly officer-only, so gate the fields on IS_OFFICER in the existing read procedures rather than add a new bit.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Split hacker API access into read, edit, and officer tiers

This phase replaces the single officer-only gate on the hacker API with three tiers. Read procedures accept READ_HACKERS or EDIT_HACKERS. Write procedures accept EDIT_HACKERS. Blacklist changes and hackathon configuration stay officer-only. Blacklist data is removed from output for non-officers. IS_OFFICER continues to satisfy every tier because controlPerms.or treats it as an unconditional pass.

Task 1: Create a hacker access utility

Add the guard functions the router and the attendance procedure will call.

• Create packages/api/src/utils/hacker/access.ts.
• Export requireHackerRead(ctx) that calls permissions.controlPerms.or(["READ_HACKERS", "EDIT_HACKERS"], ctx).
• Export requireHackerEdit(ctx) that calls permissions.controlPerms.or(["EDIT_HACKERS"], ctx).
• Export a helper that reports whether the caller is an officer (read ctx.session.permissions.IS_OFFICER) for blacklist gating and blacklist data stripping.
• Mirror the pattern in packages/api/src/utils/hackathon-events/access.ts.

Task 2: Apply the tiers in the hacker router

Replace the blanket assertCanManagePlatformConfig calls with per-procedure guards.

• Update packages/api/src/routers/hacker.ts.
• Use requireHackerRead(ctx) on read procedures: listHackathonOptions, filterOptions, get, listForHackathon, statusCounts, selectionSurvival, previewBulk.
• Use requireHackerEdit(ctx) on write procedures: setStatus, confirmBulk, awardPoints, updateProfile, deleteApplication.
• Keep assertCanManagePlatformConfig(ctx.session.permissions) on setBlacklist so blacklist changes stay officer-only.
• Preserve all existing transition safeguards (readiness gate, missing-template guard, blacklist guard, bulk preview/confirm snapshot) unchanged; these run after the permission guard and apply to every tier.
• Remove the assertCanManagePlatformConfig import only if no procedure still uses it.

Task 3: Remove blacklist data from non-officer read output

Keep blacklist information officer-only at the API boundary.

• In packages/api/src/routers/hacker.ts, in get and listForHackathon, omit blacklisted and blacklistReason from the returned rows when the caller is not an officer.
• Use the officer helper from Task 1.1.
• If filterOptions or statusCounts expose blacklist as a filter or count value, exclude that value for non-officers.

Task 4: Regate the hacker attendance procedure

Move the event-history read off the platform-config gate.

• Update listHackerEventAttendance in packages/api/src/routers/hackathon-event.ts to call requireHackerRead(ctx) instead of assertCanManagePlatformConfig(ctx.session.permissions).
• Leave getDiscordConfig and updateDiscordConfig on assertCanManagePlatformConfig.

🤖 Prompt for AI agents

Implement three permission tiers for the hacker API: read (`READ_HACKERS` or
`EDIT_HACKERS`), edit (`EDIT_HACKERS`), and officer-only (blacklist changes,
hackathon config). `IS_OFFICER` must pass every tier via `controlPerms.or`.

1. Create `packages/api/src/utils/hacker/access.ts`. Export
`requireHackerRead(ctx)` calling `permissions.controlPerms.or(["READ_HACKERS",
"EDIT_HACKERS"], ctx)`. Export `requireHackerEdit(ctx)` calling
`permissions.controlPerms.or(["EDIT_HACKERS"], ctx)`. Export an officer-check
helper reading `ctx.session.permissions.IS_OFFICER`, used for blacklist gating
and stripping. Mirror `packages/api/src/utils/hackathon-events/access.ts`.

2. In `packages/api/src/routers/hacker.ts`, replace
`assertCanManagePlatformConfig` calls: use `requireHackerRead(ctx)` on
`listHackathonOptions`, `filterOptions`, `get`, `listForHackathon`,
`statusCounts`, `selectionSurvival`, `previewBulk`. Use `requireHackerEdit(ctx)`
on `setStatus`, `confirmBulk`, `awardPoints`, `updateProfile`,
`deleteApplication`. Keep
`assertCanManagePlatformConfig(ctx.session.permissions)` on `setBlacklist`.
Preserve all existing transition safeguards (readiness gate, missing-template
guard, blacklist guard, bulk preview/confirm snapshot) unchanged; they run after
the permission guard for every tier. Remove the `assertCanManagePlatformConfig`
import only if unused afterward.

3. In `get` and `listForHackathon`, omit `blacklisted` and `blacklistReason`
from returned rows when the caller is not an officer, using the officer helper.
If `filterOptions` or `statusCounts` expose blacklist as a filter or count
value, exclude it for non-officers.

4. In `packages/api/src/routers/hackathon-event.ts`, change
`listHackerEventAttendance` to call `requireHackerRead(ctx)` instead of
`assertCanManagePlatformConfig`. Leave `getDiscordConfig` and
`updateDiscordConfig` on `assertCanManagePlatformConfig`.

Phase 2: Honor the tiers across the Blade roster UI

This phase lets READ_HACKERS users reach the roster, and threads capability flags into the roster components so write controls appear only for EDIT_HACKERS users and blacklist controls appear only for officers. hackathon.ts, club-teams.ts, discord-config.ts, and the hackathon configuration screens stay officer-only and need no change.

Task 1: Add read/edit/blacklist predicates

Provide the client-side capability checks.

• Update apps/blade/src/lib/admin-access.ts.
• Add canAccessHackers(permissions) returning IS_OFFICER === true || READ_HACKERS === true || EDIT_HACKERS === true.
• Add canEditHackers(permissions) returning IS_OFFICER === true || EDIT_HACKERS === true.
• Add canManageHackerBlacklist(permissions) returning IS_OFFICER === true.
• Model these on canAccessHackathonEvents/canEditHackathonEvents.
• Change getAdminNavigationAccess's hackers: field to use canAccessHackers instead of canAccessHackathonAdmin.
• Keep canAccessHackathonAdmin (officer-only) for the hackathon: field.

Task 2: Open the admin shell and page to readers

Let non-officer readers reach /admin/hackers.

• Update apps/blade/src/app/admin/layout.tsx to add canAccessHackers(permissions) to the top-level OR gate.
• Update apps/blade/src/app/admin/hackers/page.tsx to gate with canAccessHackers instead of canAccessHackathonAdmin.
• In the page, compute canEdit (via canEditHackers) and canManageBlacklist (via canManageHackerBlacklist) and pass them into HackerRoster.

Task 3: Thread capability props through the roster components

Hide write and blacklist controls from users who lack the tier.

• Add capability props (canEdit, canManageBlacklist) to hacker-roster.tsx and pass them down.
• In hacker-roster.tsx, render bulk "Move to " buttons only when canEdit is true.
• In hacker-detail-dialog.tsx, render status buttons, points editor, profile edit, and the DeleteApplicationDialog only when canEdit is true.
• In hacker-detail-dialog.tsx, render the blacklist toggle, blacklist reason input, and blacklist data display only when canManageBlacklist is true.
• In hacker-table.tsx, render the Blacklisted badge only when canManageBlacklist is true.
• In bulk-confirm-dialog.tsx, keep it reachable only through the canEdit-gated bulk buttons; pass canEdit if it needs its own guard.
• Keep all existing blocked/busy disabling logic and transition safeguards intact.
• hacker-event-attendance-panel.tsx needs no capability prop; it stays visible to any reader who can open the detail dialog.

🤖 Prompt for AI agents

Extend Blade's admin UI so `READ_HACKERS` and `EDIT_HACKERS` holders can access
the roster, with write and blacklist controls hidden per tier.

1. In `apps/blade/src/lib/admin-access.ts`, add `canAccessHackers(permissions)`
returning `IS_OFFICER === true || READ_HACKERS === true || EDIT_HACKERS ===
true`. Add `canEditHackers(permissions)` returning `IS_OFFICER === true ||
EDIT_HACKERS === true`. Add `canManageHackerBlacklist(permissions)` returning
`IS_OFFICER === true`. Model these on
`canAccessHackathonEvents`/`canEditHackathonEvents`. Change the `hackers:` field
in `getAdminNavigationAccess` to use `canAccessHackers` instead of
`canAccessHackathonAdmin`. Keep `canAccessHackathonAdmin` (officer-only) for the
`hackathon:` field.

2. In `apps/blade/src/app/admin/layout.tsx`, add `canAccessHackers(permissions)`
to the top-level OR gate. In `apps/blade/src/app/admin/hackers/page.tsx`, gate
with `canAccessHackers` instead of `canAccessHackathonAdmin`. Compute `canEdit`
via `canEditHackers` and `canManageBlacklist` via `canManageHackerBlacklist`,
and pass both into `HackerRoster`.

3. Add `canEdit` and `canManageBlacklist` props to `hacker-roster.tsx` and pass
them down. In `hacker-roster.tsx`, render bulk "Move to <status>" buttons only
when `canEdit` is true. In `hacker-detail-dialog.tsx`, render status buttons,
points editor, profile edit, and `DeleteApplicationDialog` only when `canEdit`
is true; render the blacklist toggle, blacklist reason input, and blacklist data
display only when `canManageBlacklist` is true. In `hacker-table.tsx`, render
the `Blacklisted` badge only when `canManageBlacklist` is true. Keep
`bulk-confirm-dialog.tsx` reachable only through the `canEdit`-gated bulk
buttons, passing `canEdit` if it needs its own guard. Keep all existing
`blocked`/`busy` disabling logic and transition safeguards intact. Do not add a
capability prop to `hacker-event-attendance-panel.tsx`; it stays visible to any
reader who can open the detail dialog.

Phase 3: Update tests and documentation

This phase updates the tests that pin the old officer-only behavior and records the policy change in the SRD.

Task 1: Add a unit test for the new guards

Cover the read/edit split directly.

• Create a guard unit test (for example packages/api/src/tests/hacker/access-guards.test.ts).
• Mirror packages/api/src/tests/hackathon-events/access.test.ts.
• Assert requireHackerRead passes for READ_HACKERS, EDIT_HACKERS, and IS_OFFICER.
• Assert requireHackerEdit passes for EDIT_HACKERS and IS_OFFICER, and throws for READ_HACKERS-only.

Task 2: Rewrite the router access test

Reflect the split tiers.

• Update packages/api/src/tests/hacker/access.test.ts.
• Partition PROCEDURES into read, write, and blacklist groups.
• Assert a READ_HACKERS-only caller succeeds on read procedures and gets FORBIDDEN on write and setBlacklist.
• Assert an EDIT_HACKERS-only caller succeeds on read and write procedures and gets FORBIDDEN on setBlacklist.
• Keep the IS_OFFICER positive control, the unauthenticated UNAUTHORIZED case, and the procedure-name sanity check.
• Add or update a case asserting get/listForHackathon omit blacklist fields for non-officer readers.

Task 3: Update the SRD access policy

Record the deviation from the documented officer-only decision.

• Update .forge/features/hacker-management/srd.md "Access policy" section.
• State that READ_HACKERS grants roster read and attendee event-history, EDIT_HACKERS grants status/points/profile/deletion writes, and blacklist plus hackathon configuration stay officer-only.

🤖 Prompt for AI agents

Update tests and documentation to match the new permission tiers.

1. Create a guard unit test, for example
`packages/api/src/tests/hacker/access-guards.test.ts`, mirroring
`packages/api/src/tests/hackathon-events/access.test.ts`. Assert
`requireHackerRead` passes for `READ_HACKERS`, `EDIT_HACKERS`, and `IS_OFFICER`.
Assert `requireHackerEdit` passes for `EDIT_HACKERS` and `IS_OFFICER`, and
throws for `READ_HACKERS`-only.

2. Update `packages/api/src/tests/hacker/access.test.ts`. Partition `PROCEDURES`
into read, write, and blacklist groups. Assert a `READ_HACKERS`-only caller
succeeds on read procedures and gets `FORBIDDEN` on write procedures and
`setBlacklist`. Assert an `EDIT_HACKERS`-only caller succeeds on read and write
procedures and gets `FORBIDDEN` on `setBlacklist`. Keep the `IS_OFFICER`
positive control, the unauthenticated `UNAUTHORIZED` case, and the
procedure-name sanity check. Add or update a case asserting
`get`/`listForHackathon` omit blacklist fields for non-officer readers.

3. Update the "Access policy" section of
`.forge/features/hacker-management/srd.md`. State that `READ_HACKERS` grants
roster read and attendee event-history, `EDIT_HACKERS` grants
status/points/profile/deletion writes, and blacklist plus hackathon
configuration stay officer-only.

Research

The Hackers feature spans the @forge/api routers (hacker.ts, and listHackerEventAttendance in hackathon-event.ts) and the Blade admin UI (apps/blade). Today every hacker procedure calls assertCanManagePlatformConfig, which throws unless IS_OFFICER === true.

Blade gates the roster at three layers: the nav item (admin-navigation.ts via admin-access.ts), the admin shell (admin/layout.tsx), and the page (admin/hackers/page.tsx), all through canAccessHackathonAdmin, which is IS_OFFICER-only.

The permission bits READ_HACKERS (idx 4) and EDIT_HACKERS (idx 5) already exist in packages/consts/src/permissions.ts, are selectable in the role editor, but are unused by this feature.

Sibling features (hackathon-events, events, companies) already model a read/edit split with controlPerms.or([...], ctx) guards and canAccessX/canEditX predicates.

The documented SRD (.forge/features/hacker-management/srd.md) states the officer-only gate is deliberate, so this change is a policy change that requires the SRD to be updated.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement three permission tiers for the hacker API: read (`READ_HACKERS` or
`EDIT_HACKERS`), edit (`EDIT_HACKERS`), and officer-only (blacklist changes,
hackathon config). `IS_OFFICER` must pass every tier via `controlPerms.or`.

1. Create `packages/api/src/utils/hacker/access.ts`. Export
`requireHackerRead(ctx)` calling `permissions.controlPerms.or(["READ_HACKERS",
"EDIT_HACKERS"], ctx)`. Export `requireHackerEdit(ctx)` calling
`permissions.controlPerms.or(["EDIT_HACKERS"], ctx)`. Export an officer-check
helper reading `ctx.session.permissions.IS_OFFICER`, used for blacklist gating
and stripping. Mirror `packages/api/src/utils/hackathon-events/access.ts`.

2. In `packages/api/src/routers/hacker.ts`, replace
`assertCanManagePlatformConfig` calls: use `requireHackerRead(ctx)` on
`listHackathonOptions`, `filterOptions`, `get`, `listForHackathon`,
`statusCounts`, `selectionSurvival`, `previewBulk`. Use `requireHackerEdit(ctx)`
on `setStatus`, `confirmBulk`, `awardPoints`, `updateProfile`,
`deleteApplication`. Keep
`assertCanManagePlatformConfig(ctx.session.permissions)` on `setBlacklist`.
Preserve all existing transition safeguards (readiness gate, missing-template
guard, blacklist guard, bulk preview/confirm snapshot) unchanged; they run after
the permission guard for every tier. Remove the `assertCanManagePlatformConfig`
import only if unused afterward.

3. In `get` and `listForHackathon`, omit `blacklisted` and `blacklistReason`
from returned rows when the caller is not an officer, using the officer helper.
If `filterOptions` or `statusCounts` expose blacklist as a filter or count
value, exclude it for non-officers.

4. In `packages/api/src/routers/hackathon-event.ts`, change
`listHackerEventAttendance` to call `requireHackerRead(ctx)` instead of
`assertCanManagePlatformConfig`. Leave `getDiscordConfig` and
`updateDiscordConfig` on `assertCanManagePlatformConfig`.
===============================================================================

Task: 2

Extend Blade's admin UI so `READ_HACKERS` and `EDIT_HACKERS` holders can access
the roster, with write and blacklist controls hidden per tier.

1. In `apps/blade/src/lib/admin-access.ts`, add `canAccessHackers(permissions)`
returning `IS_OFFICER === true || READ_HACKERS === true || EDIT_HACKERS ===
true`. Add `canEditHackers(permissions)` returning `IS_OFFICER === true ||
EDIT_HACKERS === true`. Add `canManageHackerBlacklist(permissions)` returning
`IS_OFFICER === true`. Model these on
`canAccessHackathonEvents`/`canEditHackathonEvents`. Change the `hackers:` field
in `getAdminNavigationAccess` to use `canAccessHackers` instead of
`canAccessHackathonAdmin`. Keep `canAccessHackathonAdmin` (officer-only) for the
`hackathon:` field.

2. In `apps/blade/src/app/admin/layout.tsx`, add `canAccessHackers(permissions)`
to the top-level OR gate. In `apps/blade/src/app/admin/hackers/page.tsx`, gate
with `canAccessHackers` instead of `canAccessHackathonAdmin`. Compute `canEdit`
via `canEditHackers` and `canManageBlacklist` via `canManageHackerBlacklist`,
and pass both into `HackerRoster`.

3. Add `canEdit` and `canManageBlacklist` props to `hacker-roster.tsx` and pass
them down. In `hacker-roster.tsx`, render bulk "Move to <status>" buttons only
when `canEdit` is true. In `hacker-detail-dialog.tsx`, render status buttons,
points editor, profile edit, and `DeleteApplicationDialog` only when `canEdit`
is true; render the blacklist toggle, blacklist reason input, and blacklist data
display only when `canManageBlacklist` is true. In `hacker-table.tsx`, render
the `Blacklisted` badge only when `canManageBlacklist` is true. Keep
`bulk-confirm-dialog.tsx` reachable only through the `canEdit`-gated bulk
buttons, passing `canEdit` if it needs its own guard. Keep all existing
`blocked`/`busy` disabling logic and transition safeguards intact. Do not add a
capability prop to `hacker-event-attendance-panel.tsx`; it stays visible to any
reader who can open the detail dialog.
===============================================================================

Task: 3

Update tests and documentation to match the new permission tiers.

1. Create a guard unit test, for example
`packages/api/src/tests/hacker/access-guards.test.ts`, mirroring
`packages/api/src/tests/hackathon-events/access.test.ts`. Assert
`requireHackerRead` passes for `READ_HACKERS`, `EDIT_HACKERS`, and `IS_OFFICER`.
Assert `requireHackerEdit` passes for `EDIT_HACKERS` and `IS_OFFICER`, and
throws for `READ_HACKERS`-only.

2. Update `packages/api/src/tests/hacker/access.test.ts`. Partition `PROCEDURES`
into read, write, and blacklist groups. Assert a `READ_HACKERS`-only caller
succeeds on read procedures and gets `FORBIDDEN` on write procedures and
`setBlacklist`. Assert an `EDIT_HACKERS`-only caller succeeds on read and write
procedures and gets `FORBIDDEN` on `setBlacklist`. Keep the `IS_OFFICER`
positive control, the unauthenticated `UNAUTHORIZED` case, and the
procedure-name sanity check. Add or update a case asserting
`get`/`listForHackathon` omit blacklist fields for non-officer readers.

3. Update the "Access policy" section of
`.forge/features/hacker-management/srd.md`. State that `READ_HACKERS` grants
roster read and attendee event-history, `EDIT_HACKERS` grants
status/points/profile/deletion writes, and blacklist plus hackathon
configuration stay officer-only.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---