> ## Documentation Index
> Fetch the complete documentation index at: https://edocs.iamnaime.info.bd/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Control Specification Skill: RBAC and Audit

> Define who can do what: RBAC role inventory, zero-blank permission matrix, ABAC rules, audit logging, separation of duties, and break-glass procedures.

The **admin-access-control-specification** skill produces the specification that defines who inside an organization can do what, how that is enforced, how every privileged action is logged, and what happens when access is needed outside the normal process. Nearly every real system ends up with more than one privilege level — and nearly every serious insider security incident traces back to a permission that was never explicitly decided, just implemented ad hoc as `if user.is_admin`. This skill applies RBAC design, the principle of least privilege, separation of duties, and break-glass emergency procedures to define the complete admin surface before it is built.

<Info>
  | Property           | Value                                                                            |
  | :----------------- | :------------------------------------------------------------------------------- |
  | **Type**           | Workflow                                                                         |
  | **Estimated time** | 2–4 hours                                                                        |
  | **Conditional?**   | Include whenever more than one privilege level exists — which is nearly always   |
  | **Output file**    | `.engineering-docs/11-admin-access-control-specification.md`                     |
  | **Compliance**     | Supports SOC 2, PCI-DSS, ISO 27001 audit logging and access control requirements |
</Info>

<Note>
  **This skill is conditional.** If the entire system has exactly one user type with identical permissions and no internal staff access of any kind, it can be skipped. In practice, any system with an admin panel, support tooling, or internal operations team should invoke it.
</Note>

## Best for

* Designing the admin panel and permission system for any multi-role application
* Formalizing who can do what before building authorization logic, rather than deciding it ad hoc in code
* Satisfying compliance requirements for access control and audit logging (SOC 2, PCI-DSS, ISO 27001)
* Defining emergency access procedures for when normal access is unavailable or compromised

## What it produces

The generated document covers:

1. **Overview** — what system this governs, how many distinct privilege levels it has
2. **Role inventory** — every role with description and assignment criteria, including implicit roles (system service accounts, support staff, platform-level super-admins)
3. **Permission matrix** — complete role × action table with explicit `Allow` or `Deny` in every cell — no blanks
4. **Role assignment rules** — inheritance model, mutual exclusivity rules, maximum roles, auto-assignment, revocation rules
5. **Conditional permissions (ABAC)** — context-dependent rules by ownership, temporal, environmental, user state, and resource state attributes
6. **Permission implementation map** — per permission: API layer enforcement, UI layer enforcement, database row-level enforcement, cache strategy, invalidation triggers, maximum propagation delay
7. **Sensitive actions and separation of duties** — actions requiring dual approval, risk if misused, approval workflow
8. **Audit logging specification** — fields logged (actor, action, target, timestamp, before/after state, service identity), retention period, who can read the log, and who explicitly cannot alter it
9. **Break-glass / emergency access procedure** — trigger conditions, invocation steps (request → approval → grant → alert → auto-expiry → post-use review), what is logged during emergency sessions, failure mode fallback
10. **Permission testing strategy** — positive tests, negative tests, privilege escalation tests, boundary tests, matrix completeness tests, cross-tenant isolation tests; coverage target: 100% of matrix cells
11. **Access review cadence** — quarterly review schedule, document owner, off-cycle review triggers

## How to invoke it

<CodeGroup>
  ```bash Claude Code theme={null}
  claude "Define the admin roles and permission matrix for our multi-tenant SaaS product" --skill admin-access-control-specification
  ```

  ```bash Gemini CLI theme={null}
  gemini "Design the access control specification for our internal tool, including a super-admin break-glass procedure" --skill admin-access-control-specification
  ```

  ```bash Generic (npx) theme={null}
  npx engineering-docs admin-access-control-specification "What should be logged every time an admin acts on a user's behalf, and what should require a second approver?"
  ```
</CodeGroup>

<Tip>
  Provide the anticipated roles (even informally — "there's regular users and then there's us") and any sensitive actions you already know about (refunds, data export, user impersonation, deletion). Compliance requirements (SOC 2, PCI-DSS) should be mentioned so the skill applies appropriate audit log retention.
</Tip>

## Example scenarios

<CardGroup cols={2}>
  <Card title="Multi-tenant SaaS roles" icon="users">
    "Define the admin roles and permission matrix for our multi-tenant SaaS — workspace owner, admin, member, and an internal support role that can view customer data."
  </Card>

  <Card title="Internal tool with break-glass" icon="shield-halved">
    "Design the access control specification for our internal operations tool, including a super-admin break-glass procedure for 3 AM production incidents."
  </Card>

  <Card title="Audit logging design" icon="file-lines">
    "What should be logged every time an admin acts on a user's behalf? What actions should require a second approver?"
  </Card>

  <Card title="Compliance preparation" icon="clipboard-check">
    "Produce an access control spec suitable for a SOC 2 Type II audit — covering RBAC, least privilege, audit logging, and access review cadence."
  </Card>
</CardGroup>

## Key concepts

<Accordion title="RBAC — roles, not direct user permissions">
  Define roles as named bundles of permissions and assign roles to users — never assign individual permissions directly to a user. This keeps the system auditable: "what can an Admin do" has exactly one answer, not one answer per admin.

  The permission matrix is the core artifact: a table of every role against every protected action/resource, with an explicit `Allow` or `Deny` in every cell. No cell should be left undecided — an undecided permission becomes a bug (either a silent block or a silent hole) the first time someone hits it.
</Accordion>

<Accordion title="Principle of least privilege">
  Every role gets the minimum permissions required for its purpose, not the maximum that seems convenient. A support role that needs to view account data to help with tickets does not also need permission to change billing — even if the same person happens to hold a billing-capable role in a different context.

  The skill justifies any broad permission grant explicitly. "Admin can do everything" is not a design; it is a liability.
</Accordion>

<Accordion title="Separation of duties — dual approval for destructive actions">
  For sufficiently sensitive actions, require two different people — one to propose, one to approve — so a single compromised or malicious account cannot act alone.

  | Action                    | Risk if Misused         | Requires Dual Approval?                       |
  | :------------------------ | :---------------------- | :-------------------------------------------- |
  | Refund > \$X              | Financial loss          | Yes — requester ≠ approver                    |
  | Delete organization       | Irrecoverable data loss | Yes — second Owner or platform admin confirms |
  | User impersonation        | Privacy violation       | No, but time-boxed + logged + user notified   |
  | Export all workspace data | Data breach             | Yes — must log justification                  |
</Accordion>

<Accordion title="ABAC — context-dependent permission rules">
  RBAC covers coarse-grained role assignments. ABAC handles fine-grained, context-dependent rules:

  | Condition Type     | Example Rule                                                           |
  | :----------------- | :--------------------------------------------------------------------- |
  | **Ownership**      | Members can edit only their own reports, not others'                   |
  | **Temporal**       | Finance role can approve invoices only during business hours (9AM–5PM) |
  | **Environment**    | Admin panel accessible only from the office VPN IP range               |
  | **User state**     | Verified email required before a user can initiate payouts             |
  | **Resource state** | Approve action allowed only when resource status is "Pending"          |
</Accordion>

<Accordion title="Audit logging — every privileged action, immutably">
  Every privileged action is logged with:

  * **Who** — user ID and role at time of action
  * **What** — specific action taken
  * **Target** — affected resource or user
  * **When** — UTC timestamp
  * **Before/after state** — for change operations, where feasible
  * **Service identity** — for machine-to-machine calls: service ID and permission scope

  Critically: **no role, including the actor, can modify or delete audit log entries**. The log is only as useful as its immutability.
</Accordion>

<Accordion title="Break-glass emergency access — documented, logged, and time-limited">
  Undocumented emergency access is indistinguishable from a compromise after the fact. The break-glass procedure specifies:

  1. Trigger conditions (e.g., production incident requiring elevated DB access)
  2. Invocation method (e.g., `/emergency-access` Slack command)
  3. Approval requirement (auto-approved for P1 incidents, manual otherwise)
  4. Automatic alerting on grant (`#security` Slack, PagerDuty, email to security team)
  5. Auto-expiry after a defined maximum window (e.g., 4 hours)
  6. Post-use review — required, performed by someone who did not use the access

  Every action taken during an elevated session is logged along with the start/end time and the invoker's written justification.
</Accordion>

<Accordion title="Multi-tenant isolation — platform admin vs. tenant admin">
  In multi-tenant systems, the skill enforces a strict boundary:

  * A **tenant admin** can see and manage only their own tenant's users and data — never another tenant's
  * A **platform admin** can see across tenants, but every cross-tenant action is logged and requires justification
  * Every data query is scoped to `tenant_id` — no query should return data across tenant boundaries
  * Testing requirement: an automated test case must attempt cross-tenant data access and verify it is blocked
</Accordion>

<Accordion title="Permission caching — staleness is a security window">
  | Concern               | Recommendation                                                                        |
  | :-------------------- | :------------------------------------------------------------------------------------ |
  | Cache location        | Redis or in-memory per request (avoid JWT claims for frequently-changing permissions) |
  | TTL                   | 5 minutes maximum for most roles                                                      |
  | Invalidation triggers | Role change, permission update, organization membership change                        |
  | Propagation delay     | Document the maximum — this is a known security window                                |
  | Emergency revocation  | Define a cache-bypass mechanism for high-severity compromises                         |
</Accordion>

## Interview process

<Steps>
  <Step title="Phase 1: Socratic clarification (mandatory)">
    Reads all prior `.engineering-docs/` files. Up to 3 questions: which actions would cause the most damage if misused (data export, refunds, impersonation, deletion, permission changes), and whether the system serves multiple separate organizations who must never see each other's data.
  </Step>

  <Step title="Phase 2: Role inventory (40–60 min)">
    Enumerate every role, including implicit ones — system service accounts, support staff, internal operations team, platform-level super-admins.
  </Step>

  <Step title="Phase 3: Resource and action inventory (60–90 min)">
    List every protected resource and action the system exposes that access control must govern.
  </Step>

  <Step title="Phase 4: Permission matrix (1.5–2 hrs)">
    Build the complete role × action matrix. Leave no cell undecided. Apply least privilege and justify any broad grant in writing.
  </Step>

  <Step title="Phase 5: Separation of duties and sensitive actions (40–60 min)">
    Identify actions requiring dual approval or additional verification. Define the approval flow for each.
  </Step>

  <Step title="Phase 6: Audit logging specification (40–60 min)">
    Define exactly what gets logged for privileged actions, retention period, who can read the log, and who explicitly cannot alter it.
  </Step>

  <Step title="Phase 7: Break-glass procedure (30–45 min)">
    Define the emergency access process — trigger conditions, invocation authority, automatic alerting, auto-expiry, and mandatory post-use review.
  </Step>

  <Step title="Phase 8: Revision (after user review)">
    Apply changes — cascading through the permission matrix, audit logging spec, and break-glass procedure. Re-verify zero blank matrix cells and all sensitive actions still have dual-approval requirements. Update `last_updated`.
  </Step>
</Steps>

## Output structure

The generated `.engineering-docs/11-admin-access-control-specification.md` follows this structure:

```
1.  Overview (system governed + privilege level count)
2.  Role Inventory (description + who holds each role)
3.  Permission Matrix (role × action, all cells explicit Allow/Deny)
4.  Role Assignment Rules (inheritance, exclusivity, auto-assignment, revocation)
5.  Conditional Permissions — ABAC (ownership, temporal, environmental, state rules)
6.  Permission Implementation Map (API / UI / DB / cache per permission)
7.  Sensitive Actions and Separation of Duties
8.  Audit Logging Specification (fields, retention, read access, immutability)
9.  Break-Glass / Emergency Access Procedure
10. Permission Testing Strategy (positive, negative, escalation, boundary, matrix completeness)
11. Access Review Cadence
```

**Target length:** 5–8 pages excluding appendices.

## Handoff

<CardGroup cols={2}>
  <Card title="Reads from" icon="arrow-down">
    * `4-technical-specification.md` — functional requirements, user roles
    * `7-system-architecture.md` — system components, services, trust zones
    * `8-database-design-document.md` — data entities that permissions govern
    * `9-api-design-document.md` — API actions that require access control
  </Card>

  <Card title="Feeds into" icon="arrow-up">
    * `12-security-threat-model.md` — privilege model and trust boundaries for threat analysis
    * `14-technical-blueprint.md` — access control requirements for feature designs
    * `15-implementation-plan.md` — auth/permissions as a foundation build phase
  </Card>
</CardGroup>

## Quality gate

* [ ] Every role in the inventory has a clear description and defined assignment criteria
* [ ] The permission matrix has zero blank cells — every role/action intersection is explicitly `Allow` or `Deny`
* [ ] Every sensitive action (data export, impersonation, deletion, financial operations) is listed in the Separation of Duties table
* [ ] Audit logging specification covers who, what, when, and target for every privileged action, and specifies who cannot alter logs
* [ ] Break-glass procedure includes trigger conditions, invocation authority, auto-expiry, alerting, and mandatory post-use review

<Warning>
  **Common gotchas:**

  * Leaving permission matrix cells blank or implicit — an undecided permission is not "deny by default," it is a bug that surfaces as either a silent block or a silent security hole
  * Assigning permissions directly to individual users instead of roles — defeats the purpose of RBAC and makes the system unauditable
  * Skipping audit logging for "read-only" admin actions — accessing sensitive data (viewing PII, exporting records, user impersonation) is a privileged action even if it does not mutate data
  * Defining break-glass access without automatic alerting or expiry — emergency access that doesn't auto-revoke and doesn't alert is just a backdoor
  * Omitting separation of duties for destructive actions — a single compromised admin account that can delete an organization or issue large refunds without a second approver is a critical single point of failure
</Warning>