Software Design Specification: Security Architecture

Document Type: System-Level (Tier 1) Status: Draft Last Updated: 2026-01-25

---

1. Purpose

This document describes the security architecture of the PCR Analysis System, covering authentication, authorization, session management, audit logging, and data protection mechanisms.

This is a Tier 1 document that provides cross-cutting security constraints and patterns. It does not satisfy individual requirements directly. Domain-specific security details (e.g., user account management, role assignment workflows) belong to the USERMGMT domain document.

---

2. Authentication Architecture

2.1 Overview

The system uses a hybrid authentication architecture combining:

• AWS Cognito for identity management and credential verification
• Laravel Sessions for web request authentication
• Laravel Passport for API token authentication

2.2 Authentication Flow

2.3 Authentication Error Handling

The following error paths are handled during authentication:

Error Condition	Cognito Exception	HTTP Response	User Message
Invalid credentials (< 5 attempts)	NotAuthorizedException	401	Invalid credentials
Account lockout (5 failed attempts)	TooManyRequestsException	429	Account locked (~15 min timeout)
Account disabled	UserNotFoundException	401	Account not found

2.4 Authentication Methods

Method	Flow	Provider
Native	Username/password via Cognito	AWS Cognito
Federated (SAML)	SAML 2.0 via Cognito identity broker	External IdP + Cognito

2.5 SAML/SSO Authentication Flow

For federated authentication via corporate identity providers:

SAML Flow Notes:

• The Cognito Hosted UI handles the SAML protocol exchange
• Authorization codes are exchanged server-side to prevent token exposure
• GlobalSignOut ensures single-device enforcement applies to federated users
• The DynamoDB session record is created identically to native login

2.6 Token Architecture

Token	Source	Storage	Lifetime	Purpose
Cognito AccessToken	AWS Cognito	Ephemeral (not stored)	Login only	Initial authentication
Laravel Session	Laravel	DynamoDB (prod)	Configurable	Web request auth
Passport Token	Laravel Passport	arctichare_token HTTP-only cookie	Configurable	API request auth

Design Decision: Cognito tokens are not persisted. They are used only at login time to verify identity and fetch user attributes. This reduces token management complexity and attack surface.

---

3. Authorization Architecture

3.1 Authorization Model

The system implements role-based access control (RBAC) with:

• User Types (roles) stored in local database
• Middleware-based enforcement at route level
• Gate-based enforcement for specific actions

3.2 Role Hierarchy

3.3 Role Matrix Overview

Role	Run Files	Reports	Audits	Upload	Westgard	User Mgmt	Multi-Site
Junior	Yes	Yes	Yes	Yes	No	No	No
Senior	Yes	Yes	Yes	Yes	Yes	No	No
Client-Admin	No	No	Yes	No	No	Yes*	No
Manager	Read	Read	Read	No	No	No	Yes
Super Admin	Yes	Yes	Yes	Yes	Yes	Yes	Yes

*Client-Admin cannot modify Super Admin accounts.

3.4 Enforcement Mechanisms

Mechanism	Implementation	Purpose
UserType Middleware	app/Http/Middleware/UserType.php	Route-level role restriction
Authenticate Middleware	app/Http/Middleware/Authenticate.php	Authentication enforcement
Gate: uploadFiles	AuthServiceProvider	Prevents Client-Admin upload
CheckIPMiddleware	app/Http/Middleware/CheckIPMiddleware.php	IP whitelist enforcement

Reference: For detailed role definitions and assignment workflows, see SDS: USERMGMT Domain.

---

4. Session Management

4.1 Session Configuration

Feature	Implementation	Purpose
Single-device enforcement	logoutOtherDevices('') on login	Prevents concurrent sessions
Session storage	DynamoDB (production)	Scalable, serverless
Session invalidation	$request->session()->invalidate()	Clean logout
Cognito logout	Redirect to /logout endpoint	Federated session termination

4.2 Inactivity Timeout

Sessions expire after a configurable inactivity period. See Configuration Reference for session timeout settings.

4.3 Account Disable Flow

When an account is disabled:

1. UserAccountDisabled event is fired
2. Cognito global sign-out is triggered
3. Event is broadcast on private channel for real-time logout

---

5. Security Headers and Hardening

5.1 HTTP Security Headers

All responses include security headers via SetSecurityHeaders middleware:

Header	Value	Purpose
X-Frame-Options	DENY	Clickjacking prevention
Strict-Transport-Security	max-age=15724800; includeSubDomains	HTTPS enforcement
X-Content-Type-Options	nosniff	MIME sniffing prevention
Content-Security-Policy	Strict directive	XSS prevention

5.2 CSRF Protection

• VerifyCsrfToken middleware validates tokens on state-changing requests
• Tokens regenerated on authentication

5.3 Rate Limiting

• Key: Request URL + Client IP
• Enforcement: RateLimit middleware
• Exclusions: Specific high-frequency polling endpoints

---

6. AI Security (LLM Endpoints)

6.1 Overview

AI/LLM endpoints have additional security layers to prevent prompt injection attacks.

6.2 Defense Layers

6.3 Security Controls

Control	Implementation	Action
Suspicious header detection	AiSecurityMiddleware	Log + continue
Request size limit	1MB maximum	HTTP 413
Rate limiting	10 req/min/IP	HTTP 429
Prompt injection detection	PrismCustomInstructions	Sanitize to [REDACTED]
Secure system instructions	Explicit override warnings	Inject into prompt

---

7. Audit Logging Architecture

7.1 Audited Events

Security-relevant events are captured via Laravel events:

Event	Trigger	Data Captured
UserLoggedIn	Successful authentication	User ID, timestamp
UserLoggedOut	Logout action	User ID, timestamp
UserAccountCreated	New account creation	User ID, creator
UserAccountDeleted	Account deletion	User ID, deleter
UserAccountDisabled	Account disable	User ID, modifier
UserAccountEnabled	Account enable	User ID, modifier
UserAssociatedWithRole	Role change	User ID, old/new role
PasswordChanged	Password modification	User ID, timestamp

7.2 Audit Storage

Audit events are persisted to the audit log. See SDS: AUDIT Domain for storage and query details.

---

8. Data Protection

8.1 Encryption

Layer	Mechanism
In Transit	TLS 1.2+ (HTTPS enforced via HSTS)
At Rest	AWS encryption (S3, RDS, DynamoDB)
Cookies	Laravel cookie encryption (EncryptCookies)
Passwords	Cognito-managed (not stored locally)

8.2 Sensitive Data Handling

• Passport tokens stored in HTTP-only cookies (prevents XSS theft)
• Session tokens regenerated on login (prevents fixation)
• Password fields excluded from request trimming

---

9. Access Control Policies

9.1 Site-Based Access

When configured, users can only access data from sites they have been granted access to. Multi-site access is limited to Manager and Super Admin roles.

9.2 IP-Based Access

When block_unauthorized_ip is enabled:

1. CheckIPMiddleware validates client IP against whitelist
2. Requests from non-whitelisted IPs receive AuthorizationException
3. /unauthorized path is exempt for error display

9.3 Cognito Group Enforcement

Sites can optionally require Cognito group membership for access. This adds IdP-level access control on top of application-level RBAC.

---

10. Implementation Mapping

Security Concern	Code Location
Authentication flow	app/Http/Controllers/Auth/HandleAuthenticated.php
Cognito integration	app/Support/CognitoAuthenticator.php
User management	app/CognitoUserManager.php
Role enforcement	app/Http/Middleware/UserType.php
Auth middleware	app/Http/Middleware/Authenticate.php
IP whitelist	app/Http/Middleware/CheckIPMiddleware.php
Security headers	app/Http/Middleware/SetSecurityHeaders.php
AI security	app/Http/Middleware/AiSecurityMiddleware.php
Prompt sanitization	app/Support/PrismCustomInstructions.php
Auth guards config	config/auth.php
Kernel middleware	app/Http/Kernel.php
Auth service provider	app/Providers/AuthServiceProvider.php

---

11. Related Documents

Document	Relevance
SRS: User Management	Requirements this architecture implements
SDS: USERMGMT Domain	Domain-specific user management design
SDS: AUDIT Domain	Audit logging design
SDS: Configuration Reference	Security-related configuration options
SDD: Security (Legacy)	Predecessor document