Audit Trail & Healthcare Compliance

The Audit & Compliance bounded context provides cryptographic audit logging, automated tamper-evidence verification, and compliance controls tailored for the HIPAA Security Rule (45 CFR § 164.312(b)) and the European Union General Data Protection Regulation (GDPR Article 32).

Cryptographic SHA-256 Hash Chaining

Standard database logs can be manipulated or pruned by anyone with database administrator access. To guarantee unalterable legal provenance, Obelawium Dental chains every audit log entry to its predecessor using a cryptographic SHA-256 hash chain:

+----------------------------------------------------------------------------------------------------+
|                                             Log Entry #1                                           |
| previous_hash: NULL                                                                                |
| current_hash: 9f83c12c... = SHA256(NULL + "DR-MARTINEZ" + "CREATE" + "patient" + "482" + "T1")     |
+----------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+----------------------------------------------------------------------------------------------------+
|                                             Log Entry #2                                           |
| previous_hash: 9f83c12c...                                                                         |
| current_hash: d4e102aa... = SHA256("9f83c12c..." + "DR-MARTINEZ" + "UPDATE" + "chart" + "1" + "T2")|
+----------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+----------------------------------------------------------------------------------------------------+
|                                             Log Entry #3                                           |
| previous_hash: d4e102aa...                                                                         |
| current_hash: 3b94a8f1... = SHA256("d4e102aa..." + "ASST-JONES" + "AUTOCLAVE" + "cycle" + "1"...) |
+----------------------------------------------------------------------------------------------------+

The Hash Computation Algorithm

public static function computeHash(
    ?string $previousHash,
    ?string $actorId,
    string $action,
    ?string $resourceType,
    ?string $resourceId,
    string $timestamp
): string {
    $payload = implode('|', [
        $previousHash ?? 'GENESIS',
        $actorId ?? 'SYSTEM',
        $action,
        $resourceType ?? 'NONE',
        $resourceId ?? 'NONE',
        $timestamp,
    ]);

    return hash('sha256', $payload);
}

Algorithmic Tamper-Evidence Verification

The integrity of the entire historical audit log can be verified algorithmically at any time. If any record has been modified, deleted, or inserted out of order, verifyTamperEvidence() detects the anomaly and returns false:

flowchart TD
    START["Query all AuditLog records ordered by ID"] --> LOOP["Iterate each Record"]
    
    LOOP --> CHECK_PREV{"Does previous_hash match expected?"}
    CHECK_PREV -->|No| TAMPER_DETECTED["Chain Broken - Return FALSE"]
    
    CHECK_PREV -->|Yes| RECALC["Recalculate SHA-256 Hash<br/>from Record Fields"]
    RECALC --> CHECK_HASH{"Does current_hash match recalculated?"}
    
    CHECK_HASH -->|No| TAMPER_DETECTED
    CHECK_HASH -->|Yes| NEXT["Advance Expected Hash to current_hash"]
    
    NEXT --> LOOP
    LOOP -->|End of Records| VERIFIED["Verification Succeeded - Return TRUE"]

// Run integrity verification test
$isAuditChainIntact = ium()->dental()->audit()->verifyTamperEvidence();

if (! $isAuditChainIntact) {
    // ALERT: Database record alteration or unauthorized tampering detected!
}

Zero-PHI Logging Invariant

To ensure that the audit system itself does not become a target for unauthorized protected health data harvesting, Obelawium Dental enforces the Zero-PHI Logging Invariant:

• Allowed in Audit Details: Primary record IDs, actor user IDs, IP addresses, user agent strings, and non-PHI operational metadata (e.g. severity => critical, cdt_code => D2740).
• Strictly Excluded: Patient names, Social Security Numbers, addresses, phone numbers, health alert descriptions, and clinical progress notes.

Audited Actions

use Obelaw\Ium\Dental\Enums\AuditAction;

enum AuditAction: string
{
    case CREATE = 'create';
    case READ = 'read';
    case UPDATE = 'update';
    case DELETE = 'delete';
    case AUTOCLAVE_VALIDATED = 'autoclave_validated';
    case QUICKBOOKS_SYNC = 'quickbooks_sync';
}

Fluent Service Operations

All audit capabilities are accessible through ium()->dental()->audit():

1. Recording an Audit Event

While domain services automatically record audit logs during mutations, custom application events can also be logged directly:

use Obelaw\Ium\Dental\Enums\AuditAction;

$logEntry = ium()->dental()->audit()->log(
    action: AuditAction::READ,
    patientId: (string) $patient->id,
    resourceType: 'treatment_plan',
    resourceId: (string) $plan->id,
    actorId: 'DR-MARTINEZ',
    details: [
        'actor_role' => 'Attending Dentist',
        'terminal' => 'iPad Operatory 1',
    ]
);

echo $logEntry->current_hash; // e.g. "9f83c12c7813a...4b0f"

2. Performing Chain Integrity Checks

Automated background jobs or health-check endpoints can periodically verify the chain:

$passed = ium()->dental()->audit()->verifyTamperEvidence();

Compliance Reference Checklist