# Security & Authentication Matrix

The **Asterisk 2** platform implements a defense-in-depth security model built natively on ASP.NET Core security services. It enforces granular access controls across public users, tenant organizations, background logic engines, and distributed machine-to-machine API integrations.

---

## Global Layered Access Boundary Map

The system topology below illustrates how security layers validate traffic before allowing access to internal data arrays:

```mermaid
graph TD
    %% Ingress Sources
    subgraph IngressTier["Access Ingress Sources"]
        U_Public["Unauthenticated Browsers"]
        U_Tenant["Authenticated Customers"]
        U_M2M["External MCP / API Tools"]
    end

    %% Security & Auth Filters
    subgraph SecurityTier["Security Verification Matrix"]
        CookieFilter["Identity Cookie Validation<br/>(ASP.NET Core Cookie Engine)"]
        ApiFilter["ApiKeyFilter Pipeline<br/>(X-API-KEY Header Scan)"]
        RoleResolver["Claims Authorization Logic<br/>(RBAC Evaluation Maps)"]
    end

    %% Execution Controllers
    subgraph CoreControllers["Target Controller Scopes"]
        Ctrl_Admin["AdminController Modules<br/>(Full Administrative Access)"]
        Ctrl_Tenant["Project / RAG Controllers<br/>(Scoped Workspace Modifiers)"]
        Ctrl_Api["Documentation Api / MCP Endpoints<br/>(Tool-Driven Synchronizers)"]
    end

    %% Data isolation Tier
    subgraph StorageTier["Secure Database Ledger"]
        DB_Ledger[("Application Master Store<br/>(EF Context Maps)")]
    end

    %% Paths
    U_Public -->|"Session Access"| CookieFilter
    U_Tenant -->|"Session Access"| CookieFilter
    U_M2M ==>|"API Invocation"| ApiFilter
    
    CookieFilter -->|"Valid Session Cookie"| RoleResolver
    ApiFilter ==>|"Verified Hash Payload"| RoleResolver
    
    RoleResolver -->|"Role == Admin"| Ctrl_Admin
    RoleResolver -->|"Role == Customer"| Ctrl_Tenant
    RoleResolver ==>|"Role Validated"| Ctrl_Api
    
    Ctrl_Admin ==>|"Unrestricted Write"| DB_Ledger
    Ctrl_Tenant -->|"Tenant-Scoped Write"| DB_Ledger
    Ctrl_Api ==>|"Scoped Pipeline Write"| DB_Ledger

    %% Professional Design Tokens
    classDef srcToken fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef filterToken fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef ctrlToken fill:#312e81,stroke:#ec4899,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef dbToken fill:#065f46,stroke:#10b981,stroke-width:2px,color:#fff,rx:6px,ry:6px;

    class IngressTier,U_Public,U_Tenant,U_M2M srcToken;
    class SecurityTier,CookieFilter,ApiFilter,RoleResolver filterToken;
    class CoreControllers,Ctrl_Admin,Ctrl_Tenant,Ctrl_Api ctrlToken;
    class StorageTier,DB_Ledger dbToken;
```

---

## Strategic Authentication Core

### 1. Unified Interface Security
Interactive authentication operates securely using ASP.NET Core Identity authentication cookies. User password hashes use modern PBKDF2 iterations, preventing brute-force database attacks.

### 2. Strict Access Control Directives
To prevent privilege escalation, endpoint controllers enforce access bounds using clear declarative authorization roles:
- **`Admin` Role**: Full access to global tool arrays, RAG search indices, multi-tenant workspace provisioning, and server environment variables.
- **`Customer` Role**: Access restricted strictly to customer-specific documentation hierarchies and organization slug spaces.

### 3. Decoupled Machine Identity
External MCP agent frameworks authenticate securely via persistent `X-API-KEY` strings. This isolates machine background loops from interactive human interfaces.