Roles & Permissions Matrix

Defines every actor in the Sindh IT Portal — Facilitation Desk (SITP), the nested organizational model, role templates, granular permission overrides, and the full capability matrix that governs access.

1. Overview

SITP uses a hybrid authorization model that combines Role-Based Access Control (RBAC) for coarse duties with Attribute-Based Access Control (ABAC) for fine-grained, context-sensitive visibility (especially on confidential and VIP tickets), plus per-user granular overrides on top of role templates.

• RBAC layer. Every account is bound to a role template (Government side, Company side, Oversight, or Other) that grants a baseline set of capabilities. Templates are the starting point, never the final word.
• ABAC layer. For tickets carrying the Confidential or VIP attribute, visibility is resolved dynamically from ticket attributes (department, sensitivity flag, assigned unit, watcher list) rather than from role alone. A DG who would normally see all department tickets is still excluded from a confidential ticket unless explicitly added.
• Granular overrides. Every individual capability in the matrix is independently overridable per user by a Super Admin or Department Admin (within their scope). An override can grant a capability the template denies, or revoke one the template grants. See §7.
• Role-scoped UX. The role determines the user's landing dashboard, navigation, and default filters (see §16 and /specs/en/10-ux-sitemap-flows/). A Viewer never sees configuration screens; a Filer never sees staff-management screens.
• Nested government organization. Departments are tree-structured (Department → Section → Sub-section → Staff) and admins may add sub-departments freely. The same chain is mirrored inside the owning department, S&ITD.
• Company-side roles. Each registered company may hold multiple representatives with differentiated powers: exactly one mandatory Primary Authorized Representative, plus Admin Reps, Filers, Viewers, and Notifications-only contacts.
• Oversight roles. DG/Director, Department Secretary, and Minister/SACM sit above the resolving staff. Whether they are notify-only or hold action powers (reassign, override SLA, force-resolve, send directives) is configurable per department by Super Admin (see §9).
• Configurable powers everywhere. Because role templates are starting points and feature flags (Q) toggle every capability, almost nothing in the matrix is hard-wired. The cells marked ◐ mean "conditional / configurable".

Symbol legend (used throughout all matrices)

2. Organizational Hierarchy (Government Side)

The Government of Sindh side of SITP is a tree. The owning department, S&ITD, holds platform-wide administration (Super Admin, facilitation staff) and also runs its own internal ticketing chain identical in shape to every other department. All other departments (40+, e.g. Labour, Investment, Finance, Excise, Revenue, IT-specific bodies) follow the same five-tier chain: Secretary (top oversight) → DG/Director (middle oversight) → Section/Sub-department → Officer/Staff/POC (resolve).

Written description. The diagram shows two parallel subtrees under the Government of Sindh. On the left, S&ITD owns the platform and runs Super Admin plus an internal five-tier chain (Secretary S&ITD → DG S&ITD → Facilitation Section → Facilitation Officer). On the right, every other department (40+) follows the identical five-tier chain: Department Secretary → DG/Director → Section/Sub-department → Officer/Staff/POC. The arrows read top-down as reporting/oversight; tickets flow bottom-up for resolution and top-down only when escalated.

Nesting rules.

• Free nesting. A Super Admin (and, where delegated, a Department Admin) can add sub-departments at any depth without code changes. Sections, wings, field offices, and directorates are all the same "department node" with a parent_id. The Labour Department, for example, may contain a Shop Inspectorate section, a Minimum Wage wing, and a Field Office Sukkur sub-node — each independently assignable.
• Department ≠ Section. A Department is a top-level node reporting directly to the Government of Sindh (e.g. Labour Department). A Section/Sub-department is any node below it (e.g. Shop Inspectorate). The matrix treats "Department Admin" as administrator of a top-level department and its whole subtree; "Officer/Staff" belongs to a leaf or mid-level node.
• Cross-department isolation. By default a Department Admin, Officer, or DG sees only tickets routed to their own department subtree. Only Super Admin and (optionally, by toggle) the Minister see across all departments.
• Mirror inside S&ITD. S&ITD is simultaneously the platform owner and a working department that receives facilitation requests. The same Secretary → DG → Section → Staff chain resolves tickets routed to S&ITD, and the same escalation ladder applies internally (see _context.md §5).

3. Government-Side Roles

The eight government-side role templates are described below. For each: scope (what data/org unit they touch), primary responsibilities, and typical actions.

3.1 Super Admin (S&ITD)

3.2 S&ITD Facilitation Officer / Staff

3.3 Department Admin

3.4 Department Officer / Staff / POC

3.5 DG / Director (oversight)

3.6 Department Secretary (oversight)

3.7 Minister / SACM (oversight)

3.8 Read-only Auditor

4. Company-Side Roles

A registered company (or other entity — see §4.2) may hold multiple representatives, each with one role. The role set is fixed at five templates. Permissions are role template + per-user overrides (see §7). Authorization relies on domain-email + CNIC verification; explicit authorization proof is optional (see _context.md §5).

4.1 Representative role templates

4.1.1 Primary Authorized Representative (exactly one, mandatory, transferable)

4.1.2 Admin Representative

4.1.3 Filer

4.1.4 Viewer

4.1.5 Notifications-only (e.g. Finance POC)

4.2 Entity types

Registration uses a conditional/dynamic form driven by the entity type. Five types are supported (see _context.md §5):

All types follow the same file-first, verify-in-parallel model: register → instant Provisional account → file immediately → background checks run → Verified badge or hold+appeal if fail.

4.3 Multiple representatives per company

• A company may invite any number of Admin Reps, Filers, Viewers, and Notifications-only contacts.
• Exactly one Primary Authorized Representative is always required; if the Primary leaves, the role must be transferred (or Super Admin can assist in a break-glass handover) before the departing Primary is revoked.
• Each rep has their own OIDC/Keycloak identity, 2FA, and notification preferences.
• Rep invitations, acceptances, role changes, and revocations are all audit-logged (see §11).

5. Other Actors

6. Permission Model — Roles + Granular Overrides

SITP's authorization is role templates + per-user granular overrides + ABAC attribute gates, evaluated in a strict order, defaulting to deny.

6.1 Evaluation order

For any (user, capability, resource) request, the authorization engine resolves in this order:

1. ABAC attribute gate (first, for confidential/VIP tickets): if the resource carries the Confidential or VIP attribute, evaluate ticket-specific visibility rules (assigned unit, watcher list, break-glass grant). If the ABAC gate denies, stop — deny.
2. User-level override: an explicit per-user grant or revocation on this exact capability for this user. A grant here overrides the template; a revocation here overrides a template grant.
3. Role template: the baseline capability set for the user's role (the matrix in §8).
4. Scope check: even when a capability is allowed, data scope restricts which rows the user can act on (own tickets vs. department vs. all — see §15).
5. Deny default: if none of the above explicitly allows, deny.

6.2 Why per-user overrides

Government practice is irregular: a junior officer may temporarily act as section lead; a Secretary may delegate directive power to an Additional Secretary; a company may want one Filer to also export data. Hard role templates cannot capture this. SITP therefore treats every matrix cell as independently overridable, with full audit (see §11.5).

6.3 ABAC layer for confidential/VIP visibility

The ABAC layer applies only to tickets carrying the Confidential or VIP attribute (see §13). For normal tickets, RBAC + scope is sufficient. ABAC prevents the "I can see all department tickets, therefore I can see the confidential one" escalation.

7. Permission Model

(See §6 above for the model; this section restates the contract for implementers and is referenced by the capability matrix.)

Role templates are starting points; every permission is individually overridable per user. The decision function:

authorize(user, capability, resource):
    if resource is Confidential or VIP:
        if not ABAC_allows(user, resource): return DENY
    if user has explicit override for capability:
        return override_value              # grant or revoke
    if role_template(user) allows capability:
        return ALLOW
    return DENY                            # default-deny

Override management is restricted: Super Admin can override any user platform-wide; Department Admin can override users within their department subtree; Primary/Admin Rep can override (narrowly) within their company's reps. Every override creation, change, and removal is audit-logged.

8. Capability / Permission Matrix

The matrix is split into five tables by capability group to keep it readable. Symbols: ✓ allow · ✗ deny · ◐ conditional/configurable · — not applicable (see §1 legend).

Column key (used in all five tables):

8.1 Ticketing capabilities

8.2 Oversight & escalation capabilities

8.3 Administration & configuration capabilities

8.4 Company self-service capabilities

8.5 Analytics, content & comms capabilities

Matrix totals: 67 capability rows across 5 groups (26 ticketing + 11 oversight/escalation + 11 admin/config + 8 company self-service + 11 analytics/content/comms).

9. Oversight Powers (configurable)

A core design decision (see _context.md §5): whether DG/Director, Department Secretary, and Minister/SACM are notify-only observers or hold action powers is not fixed globally — it is configurable per department by the Super Admin (and, where delegated, by the Department Secretary). This lets each department calibrate oversight to its own administrative culture while keeping a sensible default.

The powers below are toggleable per department, per oversight role. The default is shown; all can be flipped.

| # | Oversight power | DG default | Secretary default | Minister default | Effect when ON | |---|---||---|---|---| | O1 | Receive escalation notifications | ✓ | ✓ | ✓ | Auto-notified at the role's escalation tier (DG = 2d, Sec = 7d, Min = 17d). | | O2 | View department tickets | ✓ | ✓ | ✓ | Read access to all department tickets (subject to ABAC on confidential). | | O3 | Comment / add internal note | ◐ | ◐ | ◐ | Can participate in ticket threads. | | O4 | Reassign within department | ◐ (off) | ◐ (off) | ✗ | Can move tickets between sections/staff. | | O5 | Override / change SLA | ◐ (off) | ◐ (off) | ✗ | Can extend or compress SLA deadlines. | | O6 | Force-resolve (skip proof) | ◐ (off) | ◐ (off) | ◐ (off) | Can resolve without the evidence gate. | | O7 | Send directive to staff | ◐ (off) | ◐ (off) | ✓ (on) | Issues a formal directive logged on the ticket. | | O8 | Approve sensitive closure | ◐ (off) | ◐ (off) | ◐ (off) | Required sign-off before sensitive tickets close. | | O9 | Approve VIP closure | ✓ (on) | ◐ (off) | ◐ (off) | Required sign-off before VIP tickets close. | | O10 | Approve MoM (sensitive/VIP) | ✓ (on) | ◐ (off) | ◐ (off) | Required before sensitive MoM is shared. | | O11 | e-Sign official letters | ✓ (on) | ✓ (on) | ◐ (off) | PKI signing authority. |

Powers O1–O3 are effectively always-on (observation baseline). Powers O4–O11 are the ones departments actually toggle. Changing any toggle is itself an audited configuration event.

10. Escalation & Role Involvement

SITP's default escalation ladder (configurable per department/category; see _context.md §5 and /specs/en/06-ticket-workflow/) is a 2/5/10-day chain. At each tier a new oversight role is pulled in, and the powers available at that tier depend on the §9 toggles.

Written description. The sequence shows the company filing a ticket that is assigned to the resolving Section Staff at Day 0. The auto-escalation engine monitors SLA. If unresolved at Day 2, the DG/Director is notified and added as a watcher; the DG may then act (directive, reassign, SLA override) only if the department has those oversight powers enabled. If still unresolved at Day 7 (2 + 5 more), the Department Secretary is notified and added. If still unresolved at Day 17 (2 + 5 + 10 more), the final tier notifies the Minister/SACM and the S&ITD Secretary. The Minister's directive power is on by default; all other oversight powers are per-department toggles.

What each role can do at each tier (defaults):

The same ladder applies inside S&ITD for tickets routed to the owning department.

11. Account Lifecycle

11.1 Staff deactivation on transfer

When a government officer is transferred out of a department (a frequent event in the Sindh government), their SITP account must be deactivated for that department scope. The Department Admin (or Super Admin) marks the account inactive; active ticket assignments are flagged for reassignment; the account retains read-only historical access to tickets it worked (for audit continuity) but loses all write powers. Reactivation in a new department requires a fresh role assignment and certification check.

11.2 Rep revocation and change

Company representatives can be revoked by the Primary Rep (or Admin Rep for reps they invited). When the Primary leaves, the role must be transferred to another verified rep before the departing account is revoked; if no eligible rep exists, Super Admin can perform a break-glass handover (audit-logged). All revocations and transfers are audit-logged with reason codes.

11.3 Company suspension

A company account moves to Suspended (cannot file or be filed-against; existing tickets frozen) when:

• background verification fails and the appeal window lapses, or
• the SECP registry sync reports strike-off / dissolution, or
• the periodic re-attestation is missed, or
• a Super Admin applies a manual suspension (e.g. on confirmed abuse).

Suspended companies can appeal; on successful appeal or re-registration, the account is restored.

11.4 Re-attestation periodicity

Each company must periodically re-attest its profile and rep list (default cadence: annually, configurable). The Primary Rep triggers re-attestation; the system re-runs verification (SECP/FBR/SRB/PSEB/NADRA + domain email). Missed re-attestation leads to a Verified→Provisional downgrade, then to suspension after a grace period.

11.5 Audit of access changes

Every access-relevant event is written to an immutable audit log: account creation, role assignment, role change, per-user permission override (create/change/remove), activation, deactivation, suspension, restoration, rep invitation/acceptance/revocation, Primary transfer, break-glass access, step-up-auth events, and exports. The Read-only Auditor role (and Super Admin) can review these logs (capability #59). See /specs/en/11-security-compliance/.

12. Step-up Authentication

Certain high-impact actions require step-up authentication — a fresh 2FA challenge (or re-authentication) at the moment of action, regardless of the session being already authenticated. This is distinct from baseline 2FA at login. Step-up is required for:

All step-up events are audit-logged with timestamp, actor, action, and outcome.

13. Confidential / VIP Handling

Some tickets must not be visible to everyone who would otherwise see department tickets. SITP handles this through the ABAC layer (§6.3) and a dedicated Confidential flag (and a VIP flag for politically sensitive tickets).

• Restricted visibility. A confidential/VIP ticket is visible only to: the assigned Section Staff, the S&ITD Facilitation Officer on the case, watchers explicitly added, and oversight roles for whom the relevant confidential-visibility toggle is on. A DG who would normally see all department tickets does not see a confidential ticket unless explicitly added.
• Who can set confidentiality. The filing company rep, the receiving Department Admin, the S&ITD Facilitation Officer, and Super Admin can flag a ticket Confidential or VIP at filing or later. Changes are audit-logged.
• Break-glass access. When an authorized role genuinely needs access to a confidential ticket they cannot see (e.g. a DG who must intervene, or a Super Admin performing support), they use a break-glass flow: step-up authentication + stated reason → temporary access grant → every read and action on that ticket is flagged in the audit log for review by the Read-only Auditor. Break-glass grants expire automatically.
• VIP closure gate. VIP tickets require DG (Chair) approval before closure (capability #31, power O9). Sensitive tickets require Chair/DG approval before MoM share (capability #33, power O10). See /specs/en/21-mom-meetings/.
• Whistleblower channel. The anonymous/whistleblower intake (§5) feeds the confidential pipeline by default; identity is not stored in cleartext.

14. Onboarding & Certification Gate

Before any government-side account (Super Admin, Facilitation Officer, Department Admin, Officer/Staff, DG, Secretary) is activated to handle live tickets, the named user must pass the training certification exam delivered through Module O (Training & Certification). This is an exam-gated certification: an account may exist and complete internal training, but the handle-live-tickets capability is withheld until the exam is passed. See /specs/en/20-training-certification/.

• Recurring re-certification is required on role change and on a periodic basis (default annual, configurable).
• Failed exams block activation; the account remains in a "training" state with no ticket access.
• Certification status is shown on the staff record and is audit-logged.
• This gate applies to the government side; company reps are gated by verification (SECP/FBR/etc.), not by the training exam.

15. Data-Scope Rules

The capability matrix says what a role may do; data scope says which rows they may do it to. Two roles with the same capability see different datasets.

Multi-tenancy across departments. Departments are strict tenants: by default, Department Admins, Officers, DGs, and Secretaries see only their own department subtree. Cross-department visibility is reserved for Super Admin and (configurably) the Minister. A ticket can be routed across departments only by Super Admin (capability #13) or via the S&ITD Facilitation triage flow.

16. Permission / UI Mapping Note

A user's role determines their landing dashboard and navigation. This keeps the interface scoped to relevant capabilities and reduces error. The mapping is detailed in /specs/en/10-ux-sitemap-flows/; the summary:

Role-to-UI is declarative: the navigation is generated from the capabilities the user actually holds after overrides and ABAC, so a per-user override that grants a new capability immediately surfaces the corresponding nav entry.