PRD: Contributor Role and Autopilot Permissions for Reports¶
Overview¶
Status: Draft
Author: nguyenhuuca
Date: 2026-10-23
Version: 1.1
Tracking: N/A (added to docs/tracking.md after approval)
PR-FAQ: N/A. This extends an internal tool (PRD-in-app-report); it is not a new user-facing initiative.
Stakeholders: nguyenhuuca (owner, SUPER_ADMIN), admins, contributors
Builds on: ADR-0026 In-App Report (D6 "Future CONTRIBUTOR"), ADR-0025 Auto Gates, ADR-0015 Bitwise Permissions
Problem Statement¶
The owner is the bottleneck for every autopilot run that comes from a report.
- Only the SUPER_ADMIN can put
autopilot:autoorautopilot:auto-mergeon a report (ReportServiceImpl.java:103, ADR-0026 line 67). A report from anyone else gets plainautopilot, so the owner must comment/approveat Gate 1 and merge at Gate 2 before a fix reaches prod. - There is no role for a trusted person who should send reports but not manage the site. The only way to give someone the Report menu today is ADMIN, which also opens every admin tab: videos, accounts, jobs and drive sync (
WebSecurityConfig.java:54,AppShell.jsx:160-161).
Evidence¶
Quantitative Evidence:
- Each plain
autopilotreport needs 2 owner actions (Gate 1/approve, Gate 2 merge) before it ships (ADR-0022, ADR-0025). - Admin reports are capped at 10 a day (
ReportServiceImpl.java:59). At full use, that is up to 20 owner actions a day that this feature can remove for trusted reporters.
Qualitative Evidence:
- Owner (2026-10-23): "the role contributor có thể có permission auto, auto-merge dựa trên SA cấp quyền cho … tùy theo permission được cấp mà trigger autopilot full auto hoặc auto."
- ADR-0026 D6 already planned a
CONTRIBUTORrole betweenUSERandADMINfor reports, but kept the auto labels SUPER_ADMIN-only. This PRD revisits that part.
Goals & Success Metrics¶
| Goal | Metric | Target |
|---|---|---|
| Remove owner clicks for trusted reporters | Share of reports from granted non-SA users that pass both gates with no owner action | ≥ 50% within 30 days of launch |
| Keep prod safe | Reverts or prod incidents traced to an auto / auto-merge run started by a non-SA report | 0 in the first 30 days |
| Least privilege | CONTRIBUTOR accounts that can reach a non-report admin endpoint | 0 (covered by tests) |
User Stories¶
Owner (SUPER_ADMIN)¶
- As the owner, I want to give a person the CONTRIBUTOR role so that they can send reports without getting the admin tabs.
- Acceptance: in the account table, the SUPER_ADMIN or an ADMIN can set a USER to CONTRIBUTOR and back. The CONTRIBUTOR sees the Report menu and no Admin menu.
- As the owner, I want to grant or revoke
auto-mergeandautoper account (CONTRIBUTOR or ADMIN) so that only people I trust can skip my gates.- Acceptance: two toggles in the account's permission editor. Only the SUPER_ADMIN can change them. They are off for every account until granted, including existing admins.
- As the owner, I want a revoke to take effect on the next report so that I can stop someone at once.
- Acceptance: after a revoke, the next create or retry by that account gets 403 for an auto label, with no re-login needed.
Contributor / Admin with a grant¶
- As a granted reporter, I want to pick an autopilot option on the report form, limited to what I was granted, so that my fix ships without waiting for the owner.
- Acceptance: the form shows "No auto" (default), plus "Auto-merge" if granted
auto-mergeorauto, plus "Full auto" if grantedauto. The issue gets the matching label.
- Acceptance: the form shows "No auto" (default), plus "Auto-merge" if granted
- As a reporter with no grant, I want my report to still start autopilot so that the owner only has to approve.
- Acceptance: the form shows no autopilot option; the issue gets
autopilotand the type label, as an ADMIN report does today.
- Acceptance: the form shows no autopilot option; the issue gets
Contributor¶
- As a contributor, I want to see all reports and their GitHub state so that I know whether a problem was already reported and handled.
- Acceptance: the Report list shows every report, as it does for admins today (owner decision, 2026-10-23). The issues are public on GitHub anyway.
Requirements¶
Functional Requirements¶
| ID | Requirement | Priority | Notes |
|---|---|---|---|
| FR-1 | New role CONTRIBUTOR between USER and ADMIN in UserRole |
Must Have | ADR-0026 D6. Roles are stored as strings and ranked by outranks, so inserting it is safe |
| FR-2 | CONTRIBUTOR can call only the report endpoints (create, list, retry). Every other /admin/** endpoint stays ADMIN or above |
Must Have | The endpoints stay at /v1/funny-app/admin/reports (owner decision). Today /admin/** is hasAnyRole("ADMIN","SUPER_ADMIN") (WebSecurityConfig.java:54), so /admin/reports/** needs its own rule placed before it, and AdminReportController.java:32 moves to hasRole('CONTRIBUTOR') |
| FR-3 | The SUPER_ADMIN and ADMINs can set or remove the CONTRIBUTOR role | Must Have | Owner decision. Already allowed by the rank rule: an ADMIN may assign roles lower than its own (AdminAccountServiceImpl.java:46,105). An ADMIN still cannot touch the autopilot bits (FR-5) |
| FR-4 | Two new permission bits: AUTOPILOT_AUTO_MERGE and AUTOPILOT_AUTO |
Must Have | AUTOPILOT_AUTO implies auto-merge when checked (owner decision Q6). They are stored as independent bits |
| FR-5 | Only the SUPER_ADMIN can set or clear the two autopilot bits, on CONTRIBUTOR or ADMIN accounts | Must Have | updatePermissions (AdminAccountServiceImpl.java:73) must reject a change to these bits by an ADMIN |
| FR-6 | New bits are not granted by default: not by defaultPermissions(), not by a role change, and not by a backfill migration of existing admins |
Must Have | UserRole.defaultPermissions() returns ALL_BITS today. ALL_BITS must not grow to include them, or a split mask must be used |
| FR-7 | Report create and retry accept autoLabel when the caller holds the right bit at request time: AUTO_MERGE needs AUTOPILOT_AUTO_MERGE or AUTOPILOT_AUTO; AUTO needs AUTOPILOT_AUTO. Otherwise 403 error.report.autoLabelForbidden |
Must Have | Read from the user row in the DB, not from the JWT claim (JwtProvider.java:116), so a revoke is immediate. SUPER_ADMIN keeps every option |
| FR-8 | A CONTRIBUTOR or ADMIN report with no auto label gets autopilot + type label (current ADMIN behaviour) |
Must Have | Owner decision Q4b |
| FR-9 | Daily cap: one shared cap of 10 per rolling 24 h across all non-SA reports that carry autopilot (ADMIN and CONTRIBUTOR). Over the cap, the issue is created with neither autopilot nor an auto label |
Must Have | Owner decision Q4c. The cap query and its index count only reporter_role = 'ADMIN' today (ReportServiceImpl.java:197, 202610200001-create-app-report.sql:27-28) |
| FR-10 | Report form shows the autopilot options allowed by the caller's bits; no option when there is none | Must Have | ReportPage.jsx:52,88 shows it only to SUPER_ADMIN today. The server check in FR-7 is the real gate |
| FR-11 | Account table: role choice includes CONTRIBUTOR; permission editor shows the two autopilot toggles to the SUPER_ADMIN only | Must Have | AdminAccountTable.jsx:11,68, utils/permissions.js |
| FR-12 | Report menu visible to CONTRIBUTOR, ADMIN and SUPER_ADMIN; Admin menu stays ADMIN and above | Must Have | AppShell.jsx:160-161,382 use isAdmin for both today |
| FR-13 | Report list: CONTRIBUTOR sees all reports, like admins | Must Have | Owner decision; no change to list() |
| FR-14 | Issue body says who reported by role: "the SUPER_ADMIN", "an ADMIN" or "a CONTRIBUTOR" | Should Have | ReportIssueContent.java:45. Still no email, name or id (BR-7) |
| FR-15 | Grant, revoke and role changes are written to the audit log | Must Have | Reuse @AuditLog; no new screen (history UI is out of scope) |
| FR-16 | Role change keeps the autopilot bits when the new role is CONTRIBUTOR or ADMIN, and clears them when the new role is USER | Must Have | Owner decision. updateRole overwrites the whole mask today (AdminAccountServiceImpl.java:53). Keeping prevents an ADMIN from silently wiping a SA grant; clearing on USER stops a dormant grant from coming back on a later promotion |
Non-Functional Requirements¶
| ID | Requirement | Target |
|---|---|---|
| NFR-1 | Performance | Report create p95 stays < 3 s (PRD-in-app-report NFR-1). The permission check adds no extra DB call beyond loading the current user |
| NFR-2 | Security: authZ | Server-side checks for every rule (FR-2, FR-3, FR-5, FR-7); hiding UI is never the check. Tests prove a CONTRIBUTOR gets 403 on every non-report admin endpoint |
| NFR-3 | Security: least privilege | New bits default to off everywhere (FR-6); revocation is effective on the next request (FR-7) |
| NFR-4 | Compatibility | Existing accounts keep their role and current bits; existing JWTs keep working. No change to the headless workflow or its labels |
| NFR-5 | i18n | All new UI strings in en and vi (ADR-0020) |
| NFR-6 | Coverage | LINE coverage stays ≥ api/.coverage-threshold |
Scope¶
In Scope¶
CONTRIBUTORrole (backend enum, security rules, account table, navigation)- Two autopilot permission bits, grantable by the SUPER_ADMIN to CONTRIBUTOR and ADMIN accounts
- Report create/retry: auto-label check by bit instead of by role; shared daily cap across ADMIN and CONTRIBUTOR
- Report form and list changes for contributors
- ADR amending ADR-0026 (auto labels from non-owner accounts)
Out of Scope¶
- A history screen for grants and revokes (v1 relies on
@AuditLog) - Self sign-up or "request access" for contributors; the SUPER_ADMIN assigns role and bits
- Notifying a person when they are granted or revoked
- Auto-revoking a grant after a revert of a run they started
- A per-user cap or a separate cap for auto-labelled reports (owner chose one shared cap)
- Any change to
.github/workflows/autopilot.yml, the auto-merge script, or the ADR-0025 checks
Dependencies¶
| Dependency | Owner | Status | Risk |
|---|---|---|---|
In-app report (ReportServiceImpl, AdminReportController, ReportPage.jsx) |
nguyenhuuca | Live (ADR-0026) | Low |
Bitwise permissions + PermissionService (Permission.java, ADR-0015) |
nguyenhuuca | Live | Med: ALL_BITS and defaultPermissions() grant every bit to admins today |
Harness flag permission_enforcement_enabled |
nguyenhuuca | On in prod since 2026-10-23 13:31 UTC | Med: with the flag off, @HasPermission checks are skipped. FR-7 must not depend on that flag |
| Headless autopilot + auto labels (ADR-0022, ADR-0025) | nguyenhuuca | Live | Low: unchanged; it trusts any label on an issue created with the owner's PAT |
| GitHub PAT of the owner on the server (ADR-0026 D1) | nguyenhuuca | Live | Med: every granted account acts as the owner toward autopilot |
Risks & Mitigations¶
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
A granted non-owner account (or a stolen session) ships bad code to prod through autopilot:auto |
M | H | Grants are per account, off by default, SUPER_ADMIN-only, revocable at once (FR-5/6/7). Headless runs keep plan review, code review, QA ×2 and the auto-merge check (protected paths, LOC limit). Shared daily cap of 10 |
New bits leak to all admins through ALL_BITS / defaultPermissions() or the 2026-10-18 backfill pattern |
M | H | FR-6, with tests on role change and on updatePermissions |
CONTRIBUTOR reaches other admin endpoints because /admin/** is matched by role |
M | H | FR-2 and NFR-2 tests over every admin controller |
| Permission checks skipped when the Harness flag is turned off | L | H | The auto-label check is a plain service check, not @HasPermission, so it does not depend on the flag |
| Stale JWT claim keeps a revoked grant alive | M | M | FR-7 reads the bits from the DB at request time |
| Prompt injection in a contributor's report text | M | M | Unchanged from ADR-0022 D3: issue text is data, denylist paths are refused, the merge script blocks protected paths |
Inserting CONTRIBUTOR shifts ordinal() |
L | M | Roles are stored as strings and ranked by outranks (ADR-0026 D6). Check for any ordinal() use or DB check constraint on role |
Open Questions¶
- [x] May an ADMIN make a USER a CONTRIBUTOR? Yes (FR-3)
- [x] Report endpoint path? Keep
/admin/reportswith a path-specific rule (FR-2) - [x] Can contributors see all reports? Yes (FR-13)
- [x] Do the autopilot bits survive a role change? Kept between CONTRIBUTOR and ADMIN, cleared on USER (FR-16)
Appendix¶
Mockups/Wireframes¶
No new screens. Two existing screens change:
- Report form (
ReportPage.jsx): the autopilot select, today SUPER_ADMIN only, is shown with the options the caller is allowed. - Account table (
AdminAccountTable.jsx): CONTRIBUTOR badge and role choice, plus two "Autopilot" toggles in the permission editor (SUPER_ADMIN only).
Research¶
- PRD-in-app-report: FR-6 (auto labels SUPER_ADMIN only), NFR-8 (future CONTRIBUTOR)
- ADR-0026: D1 PAT trust model, D3 cap, D6 future CONTRIBUTOR
- ADR-0025: what
autopilot:autoandautopilot:auto-mergedo
Approval¶
| Role | Name | Date | Status |
|---|---|---|---|
| Product | nguyenhuuca | Pending | |
| Engineering | nguyenhuuca | Pending | |
| Design | N/A (no new screens) | N/A |
Next Steps & Handoffs¶
After PRD approval:
-
[ ] Architect Review: trust model for non-owner auto labels, report endpoint path, bit layout vs
ALL_BITS- Trigger:
/architect - Output: ADR (
docs/adr/0030-contributor-autopilot-permissions.md), amending ADR-0026
- Trigger:
-
[ ] UI/UX Designer: not needed; two existing screens get small changes (see Mockups)
-
[ ] Spec + sequence diagrams:
/spec→docs/specs/spec-contributor-autopilot-permissions.md,docs/sequence/sequence-contributor-autopilot-permissions.md -
[ ] Engineering Estimate: Implementation Plan (
docs/plans/plan-contributor-autopilot-permissions.md) -
[ ] Track it: add the feature row to
docs/tracking.md- Then decompose:
/swarm-plan <spec or PRD path>
- Then decompose:
Related Artifacts:
- ADR: ADR-0030 (Accepted)
- Design Spec: N/A
- Implementation Plan: TBD
Version History¶
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-10-23 | nguyenhuuca | Initial draft from /scope (Q1–Q6 answered by the owner) |
| 1.1 | 2026-10-23 | nguyenhuuca | Open questions answered: ADMIN may assign CONTRIBUTOR, endpoints stay at /admin/reports, contributors see all reports, autopilot bits on role change (FR-16) |