Developer Guides: Direct Permissions & Temporal Roles

[kevalyq]

Objective

Create detailed developer guides for Direct Permissions and Temporal Roles concepts to supplement the central architecture documentation.

Scope

Files to Create:

1. docs/guides/direct-permissions.md
2. docs/guides/temporal-roles.md

Both in api repository under new docs/guides/ directory.

Guide 1: Direct Permissions

Content Structure

What Are Direct Permissions?

• Definition: Permissions assigned directly to users, bypassing roles
• Independence from role system
• Permission inheritance formula with examples

When to Use Direct Permissions?

Use Cases Table:

Scenario	Solution	Why Direct Permission?
Guard needs temporary export access	Assign employees.export for 1 week	Avoid modifying Guard role or creating new role
Manager should NOT delete employees	Revoke employees.delete	Override role permission
Client needs report generation	Assign reports.generate	Special exception for one client
Auditor needs read access	Assign multiple read permissions	Time-limited access without creating role

Minimum 6-8 real-world scenarios documented.

When NOT to Use Direct Permissions?

• Standard access patterns (use roles)
• Organization-wide permissions (create role)
• Multiple users need same access (create role)
• Long-term access needs (assign role)

Decision Tree

Visual flowchart helping developers choose between:

• Create new role?
• Modify existing role?
• Assign direct permission?

How to Use (API Examples)

Assign Direct Permission (Permanent):

POST /api/v1/users/123/permissions
{"permissions": ["employees.export", "reports.generate"]}

Assign Direct Permission (Temporal):

POST /api/v1/users/123/permissions
{
  "permissions": ["reports.generate"],
  "valid_from": "2025-11-01T00:00:00Z",
  "valid_until": "2025-11-30T23:59:59Z"
}

View All Permissions (Role + Direct):

GET /api/v1/users/123/permissions
# Response shows via_roles, direct, and all combined

Revoke Direct Permission:

DELETE /api/v1/users/123/permissions/employees.export
# Note: Role permissions remain unchanged

Permission Hierarchy Explained

Detailed examples showing:

1. User with only role permissions
2. User with only direct permissions
3. User with both (union)
4. User loses role but keeps direct permissions

Best Practices

• Use sparingly (roles should be primary)
• Document reason for direct assignment
• Review direct permissions periodically
• Prefer temporal for exceptional access
• Audit trail tracking

Common Mistakes

• Assigning too many direct permissions (should create role)
• Using direct permissions for standard patterns
• Not documenting rationale
• Forgetting temporal constraints for temporary access

Guide 2: Temporal Roles

Content Structure

What Are Temporal Assignments?

• Definition: Time-limited role/permission assignments
• Optional nature (permanent is default)
• Automatic expiration handling

Permanent vs Temporal: The Default

Critical Clarification:

• Default: Assignments are PERMANENT (no expiration)
• Temporal is OPTIONAL, used for specific scenarios
• Do NOT make everything temporal by default

When to Use Temporal Assignments?

Decision Matrix:

Access Type	Duration	Recommended Approach	Example
Permanent employee	Indefinite	Permanent role	Standard Manager assignment
Vacation coverage	1-2 weeks	Temporal role	Acting manager during absence
Project access	Weeks to months	Temporal role/permission	External consultant access
Event coverage	Hours to days	Temporal role	Security lead during event
Compliance test	Minutes to hours	Temporal permission	Developer debugging production

Minimum 10 scenarios with recommendations.

Use Cases Deep Dive

1. Vacation Coverage:

Manager A on vacation (2025-12-01 to 2025-12-14)
→ Assign Manager role to Manager B temporarily
→ valid_from: 2025-12-01T00:00:00Z
→ valid_until: 2025-12-14T23:59:59Z
→ Auto-revoke: true
→ Automatic expiration without manual intervention

2. Project-Based Access:
[Detailed example with code]

3. Event-Based Elevation:
[Detailed example with code]

4. Compliance Testing:
[Detailed example with code]

Minimum 5 detailed use case walkthroughs.

How to Implement (API Examples)

Assign Temporal Role:

POST /api/v1/users/123/roles
{
  "role": "manager",
  "valid_from": "2025-12-01T00:00:00Z",
  "valid_until": "2025-12-14T23:59:59Z",
  "auto_revoke": true,
  "reason": "Vacation coverage for Manager A"
}

Extend Temporal Role:

PATCH /api/v1/users/123/roles/manager/extend
{
  "valid_until": "2025-12-21T23:59:59Z",
  "reason": "Extended vacation period"
}

Revoke Before Expiration:

DELETE /api/v1/users/123/roles/manager
# Manual revocation before auto-expiry

Expiration Handling

• Scheduled command runs every minute
• Audit trail logs all expirations
• Notifications (7 days, 24 hours, on expiration)
• What happens during active session when role expires?

Best Practices

Do:

• Use temporal for truly time-limited access
• Set realistic expiration dates
• Document reason for assignment
• Enable auto_revoke for security
• Plan for notification timing

Don't:

• Make everything temporal by default
• Use temporal for permanent staff
• Set excessively long durations (use permanent instead)
• Forget to test expiration edge cases
• Ignore timezone handling

Timezone Considerations

• All timestamps stored in UTC
• API accepts/returns ISO 8601
• Expiration checking in UTC
• Edge case: Role expires during active session

Testing Temporal Logic

Code examples for:

• Mocking time in tests
• Testing expiration
• Testing extension
• Testing audit trail

Implementation Checklist

Direct Permissions Guide

• What/When/How/Best Practices structure
• Minimum 6 use case scenarios
• Decision tree for role vs direct permission
• 4+ API examples with full requests/responses
• Permission hierarchy explained with examples
• Common mistakes section

Temporal Roles Guide

• Clear statement: "Permanent is default, temporal is optional"
• Decision matrix with 10+ scenarios
• 5 detailed use case walkthroughs
• API examples for assign/extend/revoke
• Expiration handling explained
• Timezone considerations documented
• Testing strategies included

Quality Gates

• REUSE 3.3 compliant (both files)
• Markdownlint clean
• Code examples tested
• Links to architecture doc work
• API examples match implementation

Acceptance Criteria

• Both guide files created in docs/guides/
• Direct Permissions guide covers 6+ use cases
• Temporal Roles guide covers 10+ scenarios
• Decision matrices help choose correct approach
• Minimum 8 code examples across both guides
• "Permanent is default" clearly stated in temporal guide
• Best practices and common mistakes documented
• Links to central architecture doc (Central RBAC Architecture Documentation #143)
• Links to API documentation (RBAC API Documentation (Phase 4) #140)
• Markdownlint passes for both files
• REUSE compliant

Related Issues

Part of: #141 - Complete RBAC Documentation Epic
Depends on: #143 - Architecture doc should exist to reference
Related to:

• User Direct Permission Assignment API (RBAC Phase 4) #138 - Direct Permission API implementation
• RBAC Phase 4: Documentation & Final Testing #108 - Contains use cases to document
• 🔐 Implement RBAC System (Role-Based Access Control) #5 - Parent RBAC issue with temporal use cases

Effort Estimate

Time: 2-2.5 hours total
Breakdown:

• Direct Permissions guide: 1 hour
  • Structure and what/when: 20 min
  • Use cases and examples: 25 min
  • Best practices: 15 min
• Temporal Roles guide: 1.5 hours
  • Structure and permanent vs temporal: 20 min
  • Decision matrix and use cases: 30 min
  • API examples: 20 min
  • Best practices and testing: 20 min

Complexity: Medium (requires synthesizing information from multiple issues)

Review Checklist

Before creating PR:

• Both guides comprehensive and actionable
• Use cases realistic and varied
• Code examples accurate and complete
• "Optional" nature of temporal clear
• Decision matrices help developers choose
• Links between guides and architecture doc work
• No redundancy with architecture doc (complementary)

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.