Docs/Calcifer.UserMatrix

🔐

Access Control

Calcifer.UserMatrix

Universal access and identity control. Roles, permissions, feature-level access, audit logs, and SSO — designed to work across multiple systems from a single source of truth.

# Overview

UserMatrix solves a problem that every multi-system business eventually hits: fragmented identity management. Users exist in multiple databases, permissions are inconsistent, and audit trails are nonexistent.

UserMatrix provides a centralized identity and access control layer that works across all your Calcifer products — and can extend to third-party systems via federation. One user, one identity, consistent permissions everywhere.

💡 Core Principle

Access control should be invisible when it's working correctly — and impossible to bypass when it's not. UserMatrix enforces this at the infrastructure level, not the application level.

# Role & Permission Architecture

UserMatrix uses a hierarchical RBAC (Role-Based Access Control) model with support for fine-grained permissions at the resource level. Roles are composable — a user can hold multiple roles, and permissions are resolved through a merge strategy.

Permission Hierarchy

SuperAdmin
  └── Admin
       ├── Manager
       │    ├── Editor       → Can create & modify content
       │    └── Reviewer     → Can approve & reject content
       └── Operator
            ├── Support      → Can view & respond to tickets
            └── ReadOnly     → Can view dashboards & reports

Each role inherits permissions from its parent.
Custom roles can be created at any level.

🏗️ Hierarchical Roles

Roles inherit from parent roles. Create custom roles at any level of the hierarchy with granular permission overrides.

🧩 Composable Permissions

Users can hold multiple roles. Permissions are merged using a union strategy — the most permissive applicable role wins.

🔒 Resource-Level Guards

Permissions operate at the resource level — not just the endpoint level. Control who can access specific records, not just endpoints.

⚡ Dynamic Resolution

Permission checks happen in real-time against cached role definitions. No stale permissions. Changes propagate instantly.

# Feature-Level Access Control

Beyond roles, UserMatrix supports feature-level access — controlling which specific features a user can access based on their license tier, subscription, or explicit grants. This integrates directly with Forge's licensing engine.

Access Resolution Flow

Request → Authenticate (JWT)
       → Resolve User Identity
       → Load Role Permissions    → Merge
       → Load Feature Grants      → Merge
       → Load License Features    → Merge
       → Final Access Decision
       → Allow / Deny (403)
       → Log to Audit Trail

Integration with Forge

When used alongside Calcifer.Forge, UserMatrix automatically syncs license tier features into the permission resolution pipeline. A user's effective permissions become the union of their role permissions and their license-granted features.

# Audit Logging System

Every access decision, every permission change, every login attempt — logged. The audit system creates an immutable, queryable trail of everything that happens in the identity layer.

📝

Complete Activity Log

Every login, logout, permission change, role assignment, and access decision is recorded with timestamps, actors, and context.

🔍

Queryable & Filterable

Search audit logs by user, action type, resource, date range, or result. Export to JSON or CSV for compliance reporting.

🔐

Immutable Records

Audit logs cannot be modified or deleted. They're stored in an append-only format to ensure compliance integrity.

🚨

Alert Rules

Configure alerts for suspicious patterns — multiple failed logins, privilege escalation attempts, or unauthorized access attempts.

GET /api/audit/logs?userId=usr_123EXAMPLE

{
  "logs": [
    {
      "timestamp": "2026-04-07T14:23:11Z",
      "action": "permission.granted",
      "actor": "admin@company.com",
      "target": "user@company.com",
      "details": {
        "permission": "reports.export",
        "method": "role_assignment",
        "role": "Manager"
      }
    },
    {
      "timestamp": "2026-04-07T14:25:03Z",
      "action": "resource.accessed",
      "actor": "user@company.com",
      "target": "/api/reports/revenue",
      "details": {
        "result": "allowed",
        "resolved_via": "role:Manager → reports.export"
      }
    }
  ]
}

# SSO & Identity Federation

UserMatrix supports Single Sign-On (SSO) through industry-standard protocols, allowing your users to authenticate once and access all connected systems seamlessly.

🔑

OAuth 2.0 / OIDC

live

Full OAuth 2.0 and OpenID Connect support. Works with Azure AD, Google Workspace, Okta, and any OIDC-compliant provider.

🏛️

SAML 2.0

live

Enterprise-grade SAML support for organizations that require it. Compatible with ADFS and enterprise identity providers.

🔗

API Key Authentication

live

For service-to-service communication. Scoped API keys with configurable permissions and expiration.

🌐

LDAP / Active Directory

planned

Direct LDAP integration for organizations that manage identities through Active Directory or compatible directory services.

# API Security Patterns

UserMatrix enforces security at the API gateway level. Every request is validated for authentication, authorization, and rate limiting before reaching your business logic.

🛡️

JWT Validation Pipeline

Every request passes through a multi-stage JWT validation — signature verification, expiry check, issuer validation, and claim extraction.

⏱️

Rate Limiting

Configurable rate limits per endpoint, per user, and per IP. Prevents abuse and ensures fair resource distribution.

🔄

Token Refresh & Rotation

Short-lived access tokens with refresh token rotation. Compromised tokens expire quickly and can't be reused.

📋

CORS & CSP Policies

Strict CORS configuration and Content Security Policies to prevent cross-origin attacks and injection vulnerabilities.

# Permission Matrix Example

Below is a real‑world permission matrix for an e‑commerce system built with UserMatrix:

Role \ Resource	View orders	Edit orders	View reports	Manage users
Customer	✅ (own)	❌	❌	❌
Support	✅ (all)	❌	❌	❌
Manager	✅ (all)	✅ (all)	✅	❌
Admin	✅ (all)	✅ (all)	✅	✅

# Audit API Reference

GET /api/audit/logs?userId=usr_123&action=permission.granted&from=2026-03-01

{
  "logs": [
    { "timestamp": "2026-04-07T14:23:11Z", "action": "permission.granted", "actor": "admin@co.com", "target": "user@co.com", "details": { "permission": "reports.export" } }
  ],
  "pagination": { "next": "/api/audit/logs?cursor=abc123" }
}

Query parameters: userId, action, resource, from, to, limit (max 1000).

Control access. Everywhere.

One identity system that works across your entire product ecosystem.