Transient Permissions Report

1. What does this feature do? (High-Level Overview)

This feature lets authorized managers grant time-limited permissions to active employees at a location without changing their permanent role, and provides a report to audit active grants and historical activity. This feature is currently available.

It is designed for short-term operational needs — for example, allowing a provider to export notes or bypass time limits for a few days — while keeping a full audit trail of who granted what, to whom, for how long, and who revoked it.

2. Who is this for? (Roles & Permissions)

• Owner: Can grant, revoke, and view transient permissions at their assigned locations (included by default in the OWNER role).
• Manager: Can grant, revoke, and view transient permissions at their assigned locations (included by default in the MANAGER role).
• BCBA / RBT / other roles: Do not have access unless a location role has been customized to include the required permission.

Required permission:

• manage_transient_permissions (location-scoped) — controls access to the report card, the listing, the Grant button, and the Revoke action.

3. Business Rules & Enforcements

• Rule 1: Only permissions included in the system allowlist can be granted as transient. The current allowlist is: ignore_time_limits, view_all_notes, view_all_clients, export_notes. Any other permission is rejected.
• Rule 2: Duration must be between 1 and 30 days. Values outside this range are rejected at validation.
• Rule 3: Expiration follows the Florida midnight rule — the grant expires at 00:00 America/New_York on the day (today + days). For example, a 1-day grant created at any time today expires at midnight tonight.
• Rule 4: The target user must have status active at the system level and must have an active assignment at the selected location. Inactive users and users not assigned to the location are rejected.
• Rule 5: A user cannot hold two active grants for the same permission at the same location at the same time. A second grant attempt is rejected until the existing one is revoked or expires.
• Rule 6: Granting and revoking require manage_transient_permissions at the current location. Requests without this permission are blocked with a 403 response.
• Rule 7: Expired grants are removed automatically every day at 00:05 America/New_York by a scheduled job. Expired records are marked with the reason “Expired automatically” and the underlying Spatie permission entry is removed.
• Rule 8: Revoking a grant immediately removes the Spatie permission entry and clears the user’s permission cache, so access is lost on the next authenticated request. An optional reason (up to 255 characters) can be stored with the revocation.
• Rule 9: All grant, revoke, and expiration events are written to the activity log under the transient_user_permissions log, capturing the target user, permission, location, duration, expiry, and actor.
• Rule 10: The listing is always scoped to the currently active location. Users never see grants from locations they are not acting on.

4. UI Placement

1. Reports portal: Main navigation → Reports → card “Transient Permissions Report” (icon: lock with user). The card is only visible to users with manage_transient_permissions.
2. Report screen: Route /reports/transient-permissions. Contains the filter bar, the Active/History toggle, the Grant Permission button, and the paginated table.
3. Grant dialog: Opens from the “Grant Permission” button on the report screen. Provides fields for employee, permission, and days.
4. Revoke confirmation: Opens from the “Revoke” button in the Actions column of the active list.

5. How-To Guide (Step-by-Step)

Scenario A: Grant a transient permission to an employee

1. Make sure you are acting on the correct location (location selector at the top of the app).
2. Open Reports and click the Transient Permissions Report card.
3. Click Grant Permission.
4. Search and select the target employee in the Employee field (only active employees at the current location are listed).
5. Select one of the allowed permissions in the Permission field.
6. Enter the number of Days (1–30). The dialog shows a hint: “Expires at midnight (ET) after the selected number of days.”
7. Click Grant. The new record appears in the Active list, and the permission becomes effective immediately for the target user.

Scenario B: Review active grants and revoke one

1. Open Transient Permissions Report.
2. Make sure the Active toggle is selected (default).
3. Optionally filter by Permission or by Role to narrow the list.
4. Locate the row you want to revoke and click Revoke in the Actions column.
5. Confirm the action in the dialog. Optionally provide a reason.
6. The record disappears from the Active list and becomes visible under History with the revocation timestamp.

Scenario C: Audit historical grants

1. Open Transient Permissions Report.
2. Click the History toggle. The list shows grants that were revoked manually or expired automatically.
3. Use the Permission and Role filters to narrow results.
4. Review the “Revoked At” column to see when each grant ended. Grants that expired on schedule will show a revocation reason of “Expired automatically”.

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if an employee is deactivated while holding an active transient grant?

  • A: The grant remains in the database and will be cleaned up when it expires, but the user loses all access the moment they are deactivated because they can no longer authenticate at the location. Revoking manually is recommended for a clean audit trail.

• Q: Can the same user receive the same permission twice at the same location?

  • A: Not while one is still active. The system rejects a duplicate grant with the message “User already has an active transient grant for '' at this location.” Once the existing grant is revoked or expires, a new one can be created.

• Q: What if I grant a 1-day permission late at night — does it last only a few hours?

  • A: Yes. Expiration is set to 00:00 America/New_York on (today + days). A 1-day grant created at 9:00 PM ET expires at midnight that same night (3 hours later). If the user needs full access for the following day, choose 2 days instead of 1.

• Q: What happens if the daily cleanup job does not run?

  • A: Expired grants remain in transient_user_permissions but are no longer active from the system’s perspective because the expired() scope filters them out of reads. However, the underlying Spatie model_has_permissions row is only removed by the job or by a manual revoke, so the permission may still be effective until the job runs. Keep the scheduler healthy to avoid this gap.

• Q: Can I grant a permission that is not in the allowlist (for example, manage_claims)?

  • A: No. The allowlist is defined in config/permissions.php under transient_allowed_permissions. Adding a permission to the allowlist is a code change and requires review — it is not a runtime configuration.