task-l.3

plans/task-l.3.md

@@ -0,0 +1,663 @@
+# Task L.3: Full CRM Scope Enforcement & Security Validation
+
+## Objective
+
+Complete CRM authorization by enforcing resolved CRM access consistently across all CRM modules.
+
+After Task L.3:
+
+```txt
+Resolved CRM Access
+```
+
+becomes the single source of truth for:
+
+```txt
+Visibility
+Ownership
+Branch Scope
+Product Scope
+Approval Authority
+Pricing Visibility
+Dashboard Access
+Settings Access
+```
+
+No CRM module may rely solely on UI filtering or legacy membership role behavior.
+
+---
+
+# Background
+
+Completed:
+
+```txt
+Task L
+Task L.1
+Task L.2
+```
+
+Current state:
+
+```txt
+CRM Role Profiles
+CRM User Role Assignments
+Effective Access Resolver
+User Management Integration
+```
+
+Remaining risk:
+
+Some modules may still:
+
+```txt
+filter in UI only
+use organization visibility
+ignore branch scope
+ignore product scope
+ignore ownership scope
+```
+
+Task L.3 closes those gaps.
+
+---
+
+# Scope L3.1 Access Enforcement Inventory
+
+Create a complete inventory of CRM endpoints.
+
+Audit:
+
+```txt
+Customers
+Contacts
+Leads
+Enquiries
+Quotations
+Approvals
+Dashboard
+Document Artifacts
+CRM Settings
+```
+
+For each endpoint classify:
+
+```txt
+Protected
+Partially Protected
+Not Protected
+Legacy Protected
+```
+
+Output:
+
+```txt
+docs/security/crm-access-enforcement-inventory.md
+```
+
+---
+
+# Scope L3.2 Resolver Adoption Audit
+
+Verify every CRM route uses:
+
+```txt
+resolveCrmAccess()
+```
+
+or equivalent centralized helper.
+
+Remove direct dependency on:
+
+```txt
+membership.businessRole
+membership.role
+manual permission arrays
+```
+
+except compatibility fallback inside resolver.
+
+---
+
+# Scope L3.3 Customer Enforcement
+
+Apply:
+
+```txt
+Branch Scope
+Product Scope
+Ownership Scope
+```
+
+Rules:
+
+Sales:
+
+```txt
+own customers only
+```
+
+Manager:
+
+```txt
+team customers
+```
+
+Admin:
+
+```txt
+organization customers
+```
+
+CRM Admin:
+
+```txt
+all CRM customers
+```
+
+Server-side enforced.
+
+---
+
+# Scope L3.4 Contact Enforcement
+
+Apply same rules.
+
+Preserve:
+
+```txt
+Contact Sharing
+```
+
+Rules:
+
+Shared contacts remain visible.
+
+Ownership rules still respected.
+
+---
+
+# Scope L3.5 Lead Enforcement
+
+Apply:
+
+```txt
+Lead Scope
+```
+
+Marketing:
+
+```txt
+view monitoring surfaces
+assign leads
+view follow-ups
+```
+
+Sales:
+
+```txt
+assigned leads only
+```
+
+Manager:
+
+```txt
+team leads
+```
+
+Enforce:
+
+```txt
+branch scope
+product scope
+ownership
+```
+
+---
+
+# Scope L3.6 Enquiry Enforcement
+
+Apply:
+
+```txt
+lead -> enquiry pipeline rules
+```
+
+Sales:
+
+```txt
+assigned enquiries only
+```
+
+Manager:
+
+```txt
+team enquiries
+```
+
+Marketing:
+
+```txt
+monitor only
+```
+
+Must not edit sales-owned enquiries unless permission exists.
+
+---
+
+# Scope L3.7 Quotation Enforcement
+
+Highest priority.
+
+Rules:
+
+Sales:
+
+```txt
+own quotations
+```
+
+Manager:
+
+```txt
+team quotations
+```
+
+CRM Admin:
+
+```txt
+all quotations
+```
+
+Marketing:
+
+```txt
+cannot view pricing
+cannot edit quotations
+```
+
+Support:
+
+```txt
+can edit only if permission granted
+```
+
+---
+
+# Scope L3.8 Pricing Visibility Enforcement
+
+Add centralized helper:
+
+```txt
+canViewQuotationPricing()
+```
+
+Required for:
+
+```txt
+Quotation Detail
+Quotation List
+Dashboard Revenue
+Exports
+PDF Preview
+PDF Download
+Approved PDF
+```
+
+If denied:
+
+Hide:
+
+```txt
+subtotal
+discount
+tax
+total
+currency values
+```
+
+Server-side.
+
+Not UI-only.
+
+---
+
+# Scope L3.9 Approval Enforcement
+
+Verify:
+
+```txt
+approval authority
+```
+
+comes from:
+
+```txt
+resolved CRM access
+```
+
+not role string.
+
+Rules:
+
+Only users with matching authority level may:
+
+```txt
+approve
+reject
+request changes
+```
+
+---
+
+# Scope L3.10 Dashboard Enforcement
+
+Apply resolved scope to:
+
+```txt
+Lead KPI
+Enquiry KPI
+Revenue KPI
+Approval KPI
+Follow-up KPI
+Sales Ranking
+Exports
+```
+
+Rules:
+
+Revenue only visible with:
+
+```txt
+crm.quotation.price.read
+```
+
+Sales Ranking:
+
+```txt
+branch/product filtered
+```
+
+Exports:
+
+```txt
+same scope as dashboard
+```
+
+---
+
+# Scope L3.11 Report / Export Enforcement
+
+Audit:
+
+```txt
+CSV
+Excel
+Dashboard Export
+Revenue Export
+Sales Ranking Export
+```
+
+Rules:
+
+Export must never return records not visible in UI.
+
+Server-side filtering required.
+
+---
+
+# Scope L3.12 Document Artifact Enforcement
+
+Protect:
+
+```txt
+Approved PDF
+Artifacts
+Downloads
+```
+
+Rules:
+
+User may download only if:
+
+```txt
+can access quotation
+AND
+has artifact permission
+```
+
+No direct artifact bypass.
+
+---
+
+# Scope L3.13 CRM Settings Enforcement
+
+Protect:
+
+```txt
+Roles
+User Assignments
+Templates
+Approval Workflows
+Document Sequences
+Master Options
+```
+
+Permissions:
+
+```txt
+crm.role.*
+crm.role.assignment.*
+crm.document_template.*
+crm.approval.workflow.*
+crm.document_sequence.*
+crm.master_option.*
+```
+
+No implicit admin access.
+
+---
+
+# Scope L3.14 Security Regression Suite
+
+Add:
+
+```txt
+scripts/security/verify-crm-access.ts
+```
+
+Verify:
+
+### Marketing
+
+```txt
+cannot see quotation prices
+cannot export revenue
+cannot approve quotation
+```
+
+### Sales
+
+```txt
+cannot see other sales records
+```
+
+### Sales Manager
+
+```txt
+can see team records only
+```
+
+### CRM Admin
+
+```txt
+can manage settings
+```
+
+### Mixed Roles
+
+```txt
+permissions union correctly
+scope union correctly
+```
+
+---
+
+# Scope L3.15 Security Audit Logging
+
+Audit entity:
+
+```txt
+crm_security_access
+```
+
+Log:
+
+```txt
+access_denied
+scope_violation
+permission_violation
+pricing_hidden
+```
+
+Purpose:
+
+Security troubleshooting.
+
+---
+
+# Scope L3.16 Documentation
+
+Create:
+
+```txt
+docs/security/crm-authorization-boundaries.md
+docs/implementation/task-l3-full-crm-scope-enforcement.md
+```
+
+Document:
+
+```txt
+ownership model
+scope model
+pricing visibility model
+approval authority model
+dashboard visibility model
+artifact visibility model
+```
+
+---
+
+# Verification Matrix
+
+## Marketing
+
+Expected:
+
+```txt
+Lead Monitoring
+Follow-ups
+Assignments
+
+No Pricing
+No Revenue
+No Approval
+```
+
+---
+
+## Sales
+
+Expected:
+
+```txt
+Own Records
+Own Quotations
+Own Follow-ups
+```
+
+---
+
+## Sales Manager
+
+Expected:
+
+```txt
+Team Visibility
+Approval Access
+```
+
+---
+
+## CRM Admin
+
+Expected:
+
+```txt
+Settings
+Roles
+Templates
+Sequences
+```
+
+---
+
+## Sales + Manager
+
+Expected:
+
+```txt
+Union Permissions
+Union Scope
+```
+
+---
+
+## Marketing + Sales Support
+
+Expected:
+
+```txt
+Lead Access
+Quotation Support
+
+No Revenue
+```
+
+---
+
+# Deliverables
+
+1. Full CRM Scope Enforcement
+2. Pricing Visibility Layer
+3. Dashboard Security Layer
+4. Artifact Security Layer
+5. Approval Authority Enforcement
+6. Security Verification Suite
+7. Security Audit Logging
+8. Authorization Boundary Documentation
+
+---
+
+# Definition of Done
+
+Task L.3 is complete when:
+
+* all CRM routes use resolved CRM access
+* branch scope enforced
+* product scope enforced
+* ownership scope enforced
+* pricing visibility enforced
+* dashboard security enforced
+* artifact security enforced
+* approval authority enforced
+* exports respect visibility
+* regression suite passes
+* authorization boundaries documented
+
+Result:
+
+```txt
+Authorization Foundation = CLOSED
+CRM Security Boundary = PRODUCTION READY
+```