Role-Based Security & Workflow Permissions

1. Business Summary

A status-driven row-level security engine that determines which user can view/create/update/delete each record of each entity, based on the entity's current status, the event being performed, the actor field on the record, and traversed relationships across the data graph. Privileges are pre-computed and stored in Security{Entity} and Security{Entity}User tables; updates are queued via cron_job_sqs and rebuilt by background cron.

2. Business Value

Allows confidentiality and accountability across many roles (PM, AM, VM, Finance, vendors) with brand/account/job-level partitioning, while keeping run-time access checks fast (lookup against pre-computed tables).

3. Users / Stakeholders

All roles (system enforces).
Configuration owners: administrators / security engineers.

4. Workflows

A. Configuring an entity for security
- Mark Entity.secured = 1.
- Define EntityStatus records (with priority) and EntityStatusDetail field/criteria/path conditions.
- Define Event rows for create/update/delete actions per entity/brand.
- Define EventEntityStatus linking events to statuses.
- Define EventPrivilegeRole linking event-status to actor field, relation type, path/path_flow.
- Define EntityActorField mapping entity to fields holding the actor (created_by, assignee_id, etc.).

B. Real-time access check
- SecuritySystemBehavior::checkGrant($model, $action, $item_id) — for view, query Security{Model}User for the user/item/role; for create, evaluate checkEntityCreatePriv; for update/delete, validate against event_privilege_role_id.
- Admin (Auth.User.is_admin) bypasses checks.

C. Privilege rebuild on change
- On entity create/update/delete an entry is inserted into cron_job_sqs (action c|u|d).
- SecurityCronJobsController::callSecurityCronJobs() (or batch original) processes queue.
- SecuritySystemComponent::setPrivilegesWithCronJob() resolves event/status, evaluates conditions (path traversal), rebuilds Security{Entity} and Security{Entity}User rows, and queues parent items for cascading rebuild.
- Statuses: done = 0 pending, 1 success, 2 error, 3 retry, 4 skipped (too many relations).

D. Audit & overrides
- basicUser and on_behalf_id in session captured for attribution.
- Admin override at run-time.

5. Sub-Features

• Privilege Templates (PrivilegeTemplate / PrivilegeTemplateDetail).
• Entity Statuses with priority and condition path traversal (EntityStatus, EntityStatusDetail).
• Events, EventEntityStatus, EventPrivilegeRole.
• EntityActorFields for actor identification.
• Path flows: desc, reverse, desc_user, root, all_users, all_users_brands.
• Security cron rebuild + retry + blacklist.

6. Business Rules

• Only entities flagged secured = 1 enforce row-level security.
• Statuses are priority-ordered; first matching status wins.
• Hardcoded blacklist of large/heavy price_books IDs in SecuritySystemComponent.php skipped with status=4.
• Admin (is_admin = 1) and unsecured entities bypass all checks.

7. Data Entities

• Entity, EntityStatus, EntityStatusDetail, EntityActorField, Event, EventEntityStatus, EventPrivilegeRole.
• PrivilegeTemplate, PrivilegeTemplateDetail.
• Security{Entity}, Security{Entity}User tables (per-entity row-level grants).
• cron_job_sqs (queue), retry table.
• TreeRelation, TreeRelationPrefix, TreeView (relationship topology used by traversal).

8. Entry Points

• Admin UI: security/security_engine index, events, entity_statuses, templates, actors.
• Background: SecurityCronJobsController actions (queue processing).
• Test runners: SecurityCronJobsTestsController, TestSecurityCronJobsController, SecurityCronJobsTestThread*.

9. Inputs & Outputs

• Inputs: entity changes, configuration via admin UI, queue messages.
• Outputs: pre-computed Security{Entity} rows, queue completions, audit logs.

10. Integrations

• AWS SQS (queue dispatch — sendSQSMessage()).
• Internal email/messaging (links to viewers).

11. Calculations / Logic

• Path traversal across model relationships, evaluated dynamically.
• path_flow=desc cascades to children; reverse traverses upward and re-applies; root apply to root parent.

12. Status Lifecycle

• For each item: status flows through configured EntityStatus values; transitions trigger privilege re-eval.

13. Permissions

• Configuration restricted to administrators (Security plugin).
• All user actions filtered through checkGrant.

14. Reports & KPIs

• Cron queue depth, error counts, retries.

15. Risks & Observations

• Hard-coded blacklist of PriceBook IDs → operational hack rather than systemic fix.
• on_behalf_id not validated → potential audit/abuse vector.
• Security skipped if Entity.secured = 0 — silent privilege removal possible.
• Path traversal evaluates arbitrary string paths, not whitelisted.
• Recursion in cascading cron rebuild risks infinite loops on cyclic graphs.
• Hard-coded special handling for ResourceSelection/Task/VendorInvoice paths.

16. Source Code Evidence

• app/Plugin/Security/Controller/SecurityEngineController.php.
• app/Plugin/Security/Model/{EntityStatus, EntityStatusDetail, Event, EventEntityStatus, EntityActorField, PrivilegeTemplate, PrivilegeTemplateDetail}.php.
• app/Plugin/admin/Controller/EventPrivilegeRolesController.php, app/Plugin/admin/Model/EventPrivilegeRole.php.
• app/Controller/SecurityCronJobsController.php :: callSecurityCronJobs, callSecurityCronJobsOriginal.
• app/Controller/Component/SecuritySystemComponent.php :: setPrivilegesWithCronJob, hard-coded ID list ~lines 90–93, special-case path handling ~lines 211–215.
• app/Model/Behavior/SecuritySystemBehavior.php :: checkGrant, hasSecurity, checkEntityCreatePriv.