Permission changes and audit trails

Policy Audit & Cache Invalidation

When to Use

Use when implementing permission caching, JWT/session claim validation, policy decision logging, or compliance audit trails for authorization and approval systems.

1. Permission Cache Hygiene & Immediate Invalidation

Caching authorization decisions or embedding roles inside long-lived stateless JWTs introduces a dangerous revocation lag where a fired employee, downgraded member, or revoked API key retains access until TTL expiry:

• Never Cache Permission Decisions Indefinitely: Every cached role/permission lookup must have a short, bounded TTL and deterministic event-driven invalidation.
• Include Subject & Resource Version Stamps in Cache Keys:
  • Maintain a permissions_version (or updated_at epoch) on workspace_memberships and users.
  • When a user's role changes, a membership is revoked, a delegation is cancelled, or an organization's plan changes, increment permissions_version and purge tenant:${tenantId}:authz:${userId}:*.
• Resource-State Decisions Must Not Be Stale-Cached:
  • Decisions that depend on mutable resource state (quote.status === 'pending_approval', quote.amount, account.owner_id) must evaluate against the current database row (or transaction-locked row for mutations), never a stale cached boolean.

2. Structured Authorization & Approval Audit Trail

Sensitive access checks, policy mutations, and approval decisions must be traceable and tamper-evident:

What Must Always Be Logged

1. Policy & Role Mutations: Role assignments, permission matrix edits, delegation grants/revocations, and approval threshold configuration changes (with before and after diffs).
2. Approval Lifecycle Events: approval.requested, approval.approved, approval.rejected, approval.superseded (when edits invalidate a prior approval), and approval.expired—recording subject_type, subject_id, subject_version, payload_sha256, requester_id, decider_id, and reason.
3. Sensitive Reads & Authorization Denials:
   • Access to restricted/PII fields or bulk data exports (export.executed).
   • High-severity authorization denials (authz.denied on privilege escalation attempts, cross-tenant probes, or self-approval attempts), including which policy rule denied the action (rule: 'sod.no_self_approval').

Safe Error Responses (Zero Data Leakage on Denial)

• Record the detailed denial reason (missing_role, wrong_department, status_locked, cross_tenant_mismatch) in the server-side audit log.
• Return only a safe, minimal error to the caller (404 when the caller has no read visibility on the resource; 403 with a domain reason code like self_approval_forbidden or insufficient_role only when the caller is already authorized to view the resource).