Skip to main content

Security Implementation

The HCS-12 security system provides comprehensive protection for HashLinks applications through multi-layered security controls, permission management, and content integrity verification.

What It Does​

  • Implements capability-based security with fine-grained permissions
  • Provides content integrity verification through hash validation chains
  • Manages digital signature verification for trusted operations
  • Enforces WASM sandboxing with resource limits and import restrictions
  • Enables audit logging with compliance reporting

Security Architecture​

The security system operates on multiple layers to provide defense in depth:

interface SecurityContext {
  permissions: PermissionSystem;        // Capability-based permissions
  contentVerifier: HashVerifier;        // Content integrity verification  
  signatureVerifier: SignatureVerifier; // Digital signature validation
  wasmValidator: WasmValidator;         // WASM security validation
  auditLogger: AuditLogger;            // Security event logging
}

enum SecurityLevel {
  LOW = 'low',           // Basic access operations
  MEDIUM = 'medium',     // Data modification operations
  HIGH = 'high',         // Token/crypto operations  
  CRITICAL = 'critical'  // Administrative functions
}

Permission System Implementation​

Capability-Based Security​

Implement fine-grained access control with capabilities:

import { PermissionSystem, Capability, SecurityLevel } from '@hashgraphonline/standards-sdk';

// Initialize permission system
const permissionSystem = new PermissionSystem({
  defaultPolicy: 'deny',           // Deny by default
  auditLog: true,                  // Log all permission checks
  complianceMode: 'strict',        // Strict compliance checking
  rateLimiting: true,              // Enable rate limiting
  sessionTimeout: 3600000,         // 1 hour session timeout
  maxSessions: 5                   // Max concurrent sessions per user
});

// Define custom capabilities
const swapCapability: Capability = {
  type: 'action_execution',
  scope: 'token_operations',
  actions: ['swap', 'quote'],
  constraints: {
    maxValue: 10000,               // Max $10,000 per operation
    rateLimit: {
      requests: 100,               // 100 requests
      window: 3600000              // Per hour
    },
    networks: ['mainnet', 'testnet'],
    requiredApprovals: 1,          // Single approval required
    securityLevel: SecurityLevel.HIGH
  },
  metadata: {
    description: 'Execute token swaps',
    riskLevel: 'high',
    complianceRequired: true
  }
};

// Register capability
await permissionSystem.registerCapability('token:swap', swapCapability);

// Define user roles with capability inheritance
await permissionSystem.defineRole('trader', {
  capabilities: [
    'block:render:*',              // Render any block
    'action:execute:quote',        // Execute quote actions
    'action:execute:swap',         // Execute swap actions
    'assembly:load:*',             // Load any assembly
    'registry:read:*'              // Read from any registry
  ],
  constraints: {
    'action:execute:swap': {
      maxValue: 5000,              // Lower limit for traders
      requiredApprovals: 1
    }
  },
  inheritance: ['basic_user'],     // Inherits basic capabilities
  sessionDuration: 7200000,       // 2 hour sessions
  mfaRequired: false
});

await permissionSystem.defineRole('admin', {
  capabilities: [
    'system:*',                    // Full system access
    'registry:write:*',            // Write to registries
    'user:manage:*',               // User management
    'audit:read:*'                 // Access audit logs
  ],
  constraints: {
    'system:*': {
      securityLevel: SecurityLevel.CRITICAL,
      requiredApprovals: 2,        // Dual approval
      mfaRequired: true,           // MFA mandatory
      auditLevel: 'detailed'
    }
  },
  sessionDuration: 1800000,       // 30 minute sessions
  mfaRequired: true
});

// Assign roles to users
await permissionSystem.assignRole('0.0.user123', 'trader', {
  expiresAt: new Date(Date.now() + 86400000 * 30), // 30 days
  assignedBy: '0.0.admin456',
  reason: 'Regular trading access',
  conditions: {
    ipWhitelist: ['192.168.1.0/24'],
    timeRestrictions: {
      allowedHours: '09:00-17:00',
      timezone: 'UTC',
      weekdaysOnly: true
    }
  }
});

Permission Checking and Enforcement​

Implement comprehensive permission checking:

// Check permissions before action execution
async function executeAction(
  userId: string, 
  actionId: string, 
  operation: string, 
  params: any,
  context: SecurityContext
): Promise<ActionResult> {
  
  // Multi-layered permission check
  const permissionCheck = await permissionSystem.checkPermission(userId, {
    capability: `action:execute:${operation}`,
    resource: actionId,
    context: {
      value: params.amount || 0,
      network: context.network,
      timestamp: Date.now(),
      source: context.source || 'direct'
    }
  });

  if (!permissionCheck.granted) {
    // Log security denial
    await permissionSystem.auditLog({
      userId,
      action: 'permission_denied',
      resource: actionId,
      reason: permissionCheck.reason,
      severity: 'warning',
      details: permissionCheck.details
    });
    
    throw new SecurityError(`Permission denied: ${permissionCheck.reason}`, {
      code: 'PERMISSION_DENIED',
      userId,
      capability: `action:execute:${operation}`,
      reason: permissionCheck.reason
    });
  }

  // Rate limiting check
  const rateLimitCheck = await permissionSystem.checkRateLimit(userId, {
    capability: `action:execute:${operation}`,
    window: 3600000 // 1 hour
  });

  if (rateLimitCheck.exceeded) {
    await permissionSystem.auditLog({
      userId,
      action: 'rate_limit_exceeded',
      resource: actionId,
      severity: 'warning',
      details: {
        limit: rateLimitCheck.limit,
        current: rateLimitCheck.current,
        resetTime: rateLimitCheck.resetTime
      }
    });
    
    throw new SecurityError('Rate limit exceeded', {
      code: 'RATE_LIMIT_EXCEEDED',
      resetTime: rateLimitCheck.resetTime,
      limit: rateLimitCheck.limit
    });
  }

  // Approval requirements check
  if (permissionCheck.requiresApproval) {
    const approvalRequest = await permissionSystem.createApprovalRequest({
      userId,
      action: `action:execute:${operation}`,
      resource: actionId,
      params,
      requiredApprovers: permissionCheck.requiredApprovals,
      expiration: Date.now() + 3600000 // 1 hour to approve
    });

    return {
      pending: true,
      approvalId: approvalRequest.id,
      message: 'Operation requires approval',
      requiredApprovals: permissionCheck.requiredApprovals
    };
  }

  // Execute with security context
  try {
    const result = await executeWithSecurity(actionId, operation, params, context);
    
    // Log successful execution
    await permissionSystem.auditLog({
      userId,
      action: 'action_executed',
      resource: actionId,
      severity: 'info',
      details: {
        operation,
        success: true,
        duration: result.executionTime
      }
    });

    return result;
  } catch (error) {
    // Log execution failure
    await permissionSystem.auditLog({
      userId,
      action: 'action_failed',
      resource: actionId,
      severity: 'error',
      details: {
        operation,
        error: error.message,
        stack: error.stack
      }
    });
    
    throw error;
  }
}

// Permission delegation
async function delegatePermission(
  delegator: string,
  delegatee: string, 
  capability: string,
  constraints?: PermissionConstraints
): Promise<void> {
  
  // Verify delegator has permission to delegate
  const canDelegate = await permissionSystem.checkPermission(delegator, {
    capability: `delegate:${capability}`,
    context: { delegatee, constraints }
  });

  if (!canDelegate.granted) {
    throw new SecurityError('Cannot delegate permission', {
      code: 'DELEGATION_DENIED',
      delegator,
      capability
    });
  }

  // Create delegation
  await permissionSystem.createDelegation({
    delegator,
    delegatee,
    capability,
    constraints: {
      ...constraints,
      expiresAt: Date.now() + (constraints?.duration || 86400000), // 24h default
      maxUses: constraints?.maxUses || 10,
      canSubdelegate: false
    }
  });

  await permissionSystem.auditLog({
    userId: delegator,
    action: 'permission_delegated',
    details: { delegatee, capability, constraints },
    severity: 'info'
  });
}

Content Integrity Verification​

Hash-Based Integrity Checking​

Implement comprehensive content verification:

import { HashVerifier, ContentIntegrityError } from '@hashgraphonline/standards-sdk';

const hashVerifier = new HashVerifier({
  algorithm: 'sha256',           // Hash algorithm
  encoding: 'hex',              // Hash encoding
  blockSize: 8192,              // Block size for streaming
  parallelism: 4,               // Parallel verification
  cacheResults: true,           // Cache verification results
  strictMode: true              // Strict verification mode
});

// Verify single content integrity
async function verifyContentIntegrity(
  content: Buffer | Uint8Array | string,
  expectedHash: string,
  context?: VerificationContext
): Promise<VerificationResult> {
  
  const verification = await hashVerifier.verify({
    content,
    expectedHash,
    context: {
      sourceId: context?.sourceId || 'unknown',
      contentType: context?.contentType || 'binary',
      network: context?.network || 'testnet',
      timestamp: Date.now()
    }
  });

  if (!verification.valid) {
    await hashVerifier.auditLog({
      action: 'content_integrity_failed',
      contentId: context?.sourceId,
      expectedHash,
      actualHash: verification.actualHash,
      severity: 'error'
    });
    
    throw new ContentIntegrityError('Content integrity verification failed', {
      code: 'HASH_MISMATCH',
      expected: expectedHash,
      actual: verification.actualHash,
      contentId: context?.sourceId
    });
  }

  return verification;
}

// Verify complete trust chain
async function verifyTrustChain(
  contentChain: ContentChainItem[],
  rootTrustAnchor?: TrustAnchor
): Promise<ChainVerificationResult> {
  
  const chainResult: ChainVerificationResult = {
    valid: true,
    verifiedItems: [],
    failedItems: [],
    trustLevel: 'unknown',
    warnings: []
  };

  // Verify each item in the chain
  for (let i = 0; i < contentChain.length; i++) {
    const item = contentChain[i];
    const previousItem = i > 0 ? contentChain[i - 1] : null;

    try {
      // Verify content hash
      const contentVerification = await verifyContentIntegrity(
        item.content,
        item.expectedHash,
        { sourceId: item.id, contentType: item.type }
      );

      // Verify chain linkage
      if (previousItem && item.previousHash !== previousItem.hash) {
        chainResult.warnings.push({
          type: 'chain_gap',
          message: `Chain gap detected at item ${i}`,
          itemId: item.id
        });
      }

      // Verify timestamp ordering
      if (previousItem && item.timestamp < previousItem.timestamp) {
        chainResult.warnings.push({
          type: 'timestamp_ordering',
          message: `Timestamp out of order at item ${i}`,
          itemId: item.id
        });
      }

      chainResult.verifiedItems.push({
        id: item.id,
        hash: item.hash,
        verified: true,
        timestamp: item.timestamp
      });

    } catch (error) {
      chainResult.valid = false;
      chainResult.failedItems.push({
        id: item.id,
        error: error.message,
        code: error.code
      });
    }
  }

  // Verify against root trust anchor
  if (rootTrustAnchor && chainResult.valid) {
    const rootVerification = await verifyRootTrustAnchor(
      contentChain[0],
      rootTrustAnchor
    );
    
    if (rootVerification.trusted) {
      chainResult.trustLevel = rootVerification.trustLevel;
    } else {
      chainResult.warnings.push({
        type: 'untrusted_root',
        message: 'Root of chain is not trusted',
        details: rootVerification.reason
      });
    }
  }

  return chainResult;
}

// Verify WASM module integrity with source verification
async function verifyWasmModule(
  wasmModule: Buffer,
  jsWrapper: Buffer,
  moduleInfo: ModuleInfo,
  sourceVerification?: SourceVerification
): Promise<WasmVerificationResult> {
  
  const verification: WasmVerificationResult = {
    wasmValid: false,
    jsValid: false,
    infoValid: false,
    sourceVerified: false,
    securityChecks: []
  };

  // Verify WASM binary hash
  try {
    await verifyContentIntegrity(wasmModule, moduleInfo.wasmHash, {
      sourceId: moduleInfo.name,
      contentType: 'application/wasm'
    });
    verification.wasmValid = true;
  } catch (error) {
    verification.securityChecks.push({
      check: 'wasm_hash_verification',
      passed: false,
      error: error.message
    });
  }

  // Verify JavaScript wrapper hash
  if (moduleInfo.jsHash) {
    try {
      await verifyContentIntegrity(jsWrapper, moduleInfo.jsHash, {
        sourceId: moduleInfo.name,
        contentType: 'application/javascript'
      });
      verification.jsValid = true;
    } catch (error) {
      verification.securityChecks.push({
        check: 'js_hash_verification', 
        passed: false,
        error: error.message
      });
    }
  } else {
    verification.jsValid = true; // No JS wrapper required
  }

  // Verify INFO consistency
  const infoJson = JSON.stringify(moduleInfo, Object.keys(moduleInfo).sort());
  const infoHash = await hashVerifier.hash(infoJson);
  verification.infoValid = infoHash === moduleInfo.hash;

  if (!verification.infoValid) {
    verification.securityChecks.push({
      check: 'info_hash_verification',
      passed: false,
      error: 'INFO hash mismatch'
    });
  }

  // Verify source if provided
  if (sourceVerification) {
    try {
      const sourceContent = await fetchContent(sourceVerification.sourceTopicId);
      await verifyContentIntegrity(
        sourceContent,
        sourceVerification.sourceHash,
        { sourceId: sourceVerification.sourceTopicId }
      );

      // Verify compilation target
      if (sourceVerification.target === 'wasm32-unknown-unknown') {
        verification.sourceVerified = true;
        verification.securityChecks.push({
          check: 'source_verification',
          passed: true,
          message: 'Source code verified'
        });
      }
    } catch (error) {
      verification.securityChecks.push({
        check: 'source_verification',
        passed: false,
        error: error.message
      });
    }
  }

  return verification;
}

Digital Signature Verification​

Signature-Based Authentication​

Implement digital signature verification for high-security operations:

import { SignatureVerifier, SignatureScheme } from '@hashgraphonline/standards-sdk';

const signatureVerifier = new SignatureVerifier({
  supportedSchemes: [
    SignatureScheme.ED25519,
    SignatureScheme.ECDSA_SECP256K1,
    SignatureScheme.RSA_PSS
  ],
  requireTimestamp: true,
  maxAge: 300000,              // 5 minute signature validity
  nonceTracking: true,         // Prevent replay attacks
  chainVerification: true      // Verify certificate chains
});

// Verify transaction signature
async function verifyTransactionSignature(
  transaction: Transaction,
  signature: Signature,
  publicKey: PublicKey,
  context: SignatureContext
): Promise<SignatureVerificationResult> {
  
  const verification = await signatureVerifier.verify({
    message: transaction.serialize(),
    signature: signature.bytes,
    publicKey: publicKey.bytes,
    scheme: signature.scheme,
    context: {
      timestamp: signature.timestamp,
      nonce: signature.nonce,
      purpose: 'transaction_authorization',
      network: context.network
    }
  });

  if (!verification.valid) {
    await signatureVerifier.auditLog({
      action: 'signature_verification_failed',
      transactionId: transaction.id,
      publicKey: publicKey.toString(),
      reason: verification.reason,
      severity: 'error'
    });

    throw new SecurityError('Transaction signature verification failed', {
      code: 'INVALID_SIGNATURE',
      transactionId: transaction.id,
      reason: verification.reason
    });
  }

  // Additional security checks
  const securityChecks = await performAdditionalSignatureChecks(
    transaction,
    signature,
    publicKey,
    context
  );

  return {
    ...verification,
    additionalChecks: securityChecks
  };
}

// Multi-signature verification for high-value operations
async function verifyMultiSignature(
  message: Buffer,
  signatures: MultiSignature,
  publicKeys: PublicKey[],
  threshold: number
): Promise<MultiSignatureResult> {
  
  const verificationResults: SignatureVerificationResult[] = [];
  let validSignatures = 0;

  // Verify each signature
  for (let i = 0; i < signatures.signatures.length; i++) {
    const sig = signatures.signatures[i];
    const pubKey = publicKeys[sig.signerIndex];

    try {
      const result = await signatureVerifier.verify({
        message,
        signature: sig.bytes,
        publicKey: pubKey.bytes,
        scheme: sig.scheme,
        context: {
          timestamp: sig.timestamp,
          signerIndex: sig.signerIndex,
          purpose: 'multi_signature_authorization'
        }
      });

      verificationResults.push(result);
      if (result.valid) {
        validSignatures++;
      }
    } catch (error) {
      verificationResults.push({
        valid: false,
        reason: error.message,
        signerIndex: sig.signerIndex
      });
    }
  }

  const thresholdMet = validSignatures >= threshold;

  if (!thresholdMet) {
    throw new SecurityError('Multi-signature threshold not met', {
      code: 'MULTISIG_THRESHOLD_NOT_MET',
      required: threshold,
      valid: validSignatures,
      total: signatures.signatures.length
    });
  }

  return {
    valid: thresholdMet,
    validSignatures,
    totalSignatures: signatures.signatures.length,
    threshold,
    verificationResults
  };
}

// Certificate chain verification
async function verifyCertificateChain(
  certificate: X509Certificate,
  trustedRoots: TrustedRoot[]
): Promise<ChainVerificationResult> {
  
  const chainVerification = await signatureVerifier.verifyChain({
    certificate,
    trustedRoots,
    checkRevocation: true,
    maxChainLength: 5,
    allowSelfSigned: false
  });

  if (!chainVerification.valid) {
    throw new SecurityError('Certificate chain verification failed', {
      code: 'INVALID_CERTIFICATE_CHAIN',
      reason: chainVerification.reason,
      certificate: certificate.subject
    });
  }

  return chainVerification;
}

WASM Security Validation​

Comprehensive WASM Module Security​

Implement strict WASM security validation:

import { WasmValidator, SecurityViolation } from '@hashgraphonline/standards-sdk';

const wasmValidator = new WasmValidator({
  maxMemoryPages: 256,              // 16MB memory limit
  maxTableSize: 1024,               // Max table entries
  maxModuleSize: 10 * 1024 * 1024,  // 10MB module size limit
  maxFunctions: 1000,               // Max function count
  maxExecutionTime: 5000,           // 5 second timeout
  allowedImports: [
    'wasi_snapshot_preview1',       // WASI imports
    'env.memory',                   // Memory imports
    'env.abort'                     // Abort function
  ],
  forbiddenOpcodes: [
    'memory.grow',                  // Prevent memory growth
    'unreachable'                   // Prevent unreachable code
  ],
  validateExports: true,            // Validate required exports
  sandboxed: true                   // Run in sandbox mode
});

// Validate WASM module security
async function validateWasmSecurity(
  wasmModule: Buffer,
  moduleInfo: ModuleInfo
): Promise<WasmSecurityResult> {
  
  const securityResult: WasmSecurityResult = {
    safe: true,
    violations: [],
    warnings: [],
    metrics: {}
  };

  try {
    // Parse WASM module
    const parsedModule = await wasmValidator.parse(wasmModule);
    securityResult.metrics.moduleSize = wasmModule.length;
    securityResult.metrics.functionCount = parsedModule.functions.length;

    // Validate module structure
    const structureValidation = await wasmValidator.validateStructure(parsedModule);
    if (!structureValidation.valid) {
      securityResult.safe = false;
      securityResult.violations.push({
        type: 'structure',
        severity: 'critical',
        description: 'Invalid module structure',
        details: structureValidation.errors
      });
    }

    // Validate imports
    const importValidation = await wasmValidator.validateImports(parsedModule);
    for (const violation of importValidation.violations) {
      if (violation.severity === 'critical') {
        securityResult.safe = false;
      }
      securityResult.violations.push(violation);
    }

    // Validate memory usage
    const memoryValidation = await wasmValidator.validateMemory(parsedModule);
    if (memoryValidation.memoryPages > wasmValidator.maxMemoryPages) {
      securityResult.safe = false;
      securityResult.violations.push({
        type: 'memory',
        severity: 'critical',
        description: 'Memory limit exceeded',
        details: {
          requested: memoryValidation.memoryPages,
          maximum: wasmValidator.maxMemoryPages
        }
      });
    }

    // Validate exports (required interface)
    const expectedExports = ['INFO', 'GET', 'POST'];
    const moduleExports = parsedModule.exports.map(e => e.name);
    
    for (const requiredExport of expectedExports) {
      if (!moduleExports.includes(requiredExport)) {
        securityResult.violations.push({
          type: 'interface',
          severity: 'critical',
          description: `Missing required export: ${requiredExport}`,
          details: { required: expectedExports, found: moduleExports }
        });
        securityResult.safe = false;
      }
    }

    // Validate opcodes
    const opcodeValidation = await wasmValidator.validateOpcodes(parsedModule);
    for (const forbiddenOpcode of opcodeValidation.forbiddenFound) {
      securityResult.violations.push({
        type: 'opcode',
        severity: 'high',
        description: `Forbidden opcode: ${forbiddenOpcode.opcode}`,
        details: {
          location: forbiddenOpcode.location,
          function: forbiddenOpcode.functionIndex
        }
      });
      
      // Some opcodes are critical security violations
      if (['memory.grow', 'call_indirect'].includes(forbiddenOpcode.opcode)) {
        securityResult.safe = false;
      }
    }

    // Validate against module info
    const infoValidation = await validateModuleInfo(parsedModule, moduleInfo);
    if (!infoValidation.valid) {
      securityResult.warnings.push({
        type: 'info_mismatch',
        severity: 'medium',
        description: 'Module info inconsistency',
        details: infoValidation.mismatches
      });
    }

    // Performance and resource validation
    const resourceValidation = await wasmValidator.validateResources(parsedModule);
    securityResult.metrics = {
      ...securityResult.metrics,
      ...resourceValidation.metrics
    };

  } catch (error) {
    securityResult.safe = false;
    securityResult.violations.push({
      type: 'parsing',
      severity: 'critical',
      description: 'Failed to parse WASM module',
      details: { error: error.message }
    });
  }

  return securityResult;
}

// Runtime security monitoring
class WasmRuntimeMonitor {
  private executionMetrics = new Map<string, ExecutionMetrics>();

  async monitorExecution(
    moduleId: string,
    execution: WasmExecution
  ): Promise<SecurityMonitoringResult> {
    
    const startTime = Date.now();
    const startMemory = process.memoryUsage();

    try {
      // Execute with monitoring
      const result = await this.executeWithLimits(execution);
      
      const endTime = Date.now();
      const endMemory = process.memoryUsage();
      
      const metrics: ExecutionMetrics = {
        executionTime: endTime - startTime,
        memoryUsed: endMemory.heapUsed - startMemory.heapUsed,
        cpuTime: result.cpuTime,
        callsCount: result.callsCount
      };

      // Update tracking
      this.executionMetrics.set(moduleId, metrics);

      // Check for anomalies
      const anomalies = await this.detectAnomalies(moduleId, metrics);

      return {
        success: true,
        metrics,
        anomalies,
        securityEvents: []
      };

    } catch (error) {
      // Log security incident
      const securityEvent: SecurityEvent = {
        type: 'wasm_execution_failure',
        moduleId,
        timestamp: Date.now(),
        severity: 'high',
        details: {
          error: error.message,
          executionTime: Date.now() - startTime
        }
      };

      return {
        success: false,
        error: error.message,
        securityEvents: [securityEvent]
      };
    }
  }

  private async detectAnomalies(
    moduleId: string,
    currentMetrics: ExecutionMetrics
  ): Promise<SecurityAnomaly[]> {
    
    const anomalies: SecurityAnomaly[] = [];
    const historicalMetrics = this.getHistoricalMetrics(moduleId);

    // Detect execution time anomalies
    if (historicalMetrics.length > 10) {
      const avgExecutionTime = historicalMetrics
        .reduce((sum, m) => sum + m.executionTime, 0) / historicalMetrics.length;
      
      if (currentMetrics.executionTime > avgExecutionTime * 3) {
        anomalies.push({
          type: 'execution_time_anomaly',
          severity: 'medium',
          description: 'Execution time significantly higher than normal',
          details: {
            current: currentMetrics.executionTime,
            average: avgExecutionTime
          }
        });
      }
    }

    // Detect memory usage anomalies
    if (currentMetrics.memoryUsed > 50 * 1024 * 1024) { // 50MB
      anomalies.push({
        type: 'high_memory_usage',
        severity: 'high', 
        description: 'Unusually high memory usage',
        details: {
          memoryUsed: currentMetrics.memoryUsed
        }
      });
    }

    return anomalies;
  }
}

Audit Logging and Compliance​

Comprehensive Security Auditing​

Implement detailed audit logging for compliance and security monitoring:

import { AuditLogger, ComplianceReporter } from '@hashgraphonline/standards-sdk';

const auditLogger = new AuditLogger({
  storage: 'secure',            // Secure storage backend
  encryption: true,             // Encrypt audit logs
  integrity: true,              // Tamper-proof logging
  retention: 2555000000,        // 30 days retention
  realtime: true,               // Real-time log processing
  compliance: ['SOX', 'GDPR'],  // Compliance standards
  alerting: {
    enabled: true,
    thresholds: {
      'security_violation': 1,   // Alert on any violation
      'failed_login': 5,         // Alert after 5 failed logins
      'permission_denied': 10    // Alert after 10 denials
    }
  }
});

// Security event logging
async function logSecurityEvent(
  event: SecurityEvent,
  context: AuditContext
): Promise<void> {
  
  const auditEntry: AuditEntry = {
    timestamp: Date.now(),
    eventId: generateEventId(),
    type: event.type,
    severity: event.severity,
    userId: context.userId,
    sessionId: context.sessionId,
    sourceIp: context.sourceIp,
    userAgent: context.userAgent,
    resource: event.resource,
    action: event.action,
    result: event.result,
    details: event.details,
    
    // Additional security context
    riskScore: await calculateRiskScore(event, context),
    threatIndicators: await detectThreatIndicators(event, context),
    complianceFlags: await checkComplianceFlags(event),
    
    // Integrity protection
    hash: '', // Calculated after entry creation
    previousHash: await getLastEntryHash()
  };

  // Calculate entry hash for integrity
  auditEntry.hash = await calculateAuditEntryHash(auditEntry);

  // Store with encryption and integrity protection
  await auditLogger.logEntry(auditEntry);

  // Real-time alerting
  if (auditEntry.severity === 'critical' || auditEntry.riskScore > 8) {
    await triggerSecurityAlert(auditEntry);
  }

  // Compliance notifications
  if (auditEntry.complianceFlags.length > 0) {
    await notifyComplianceTeam(auditEntry);
  }
}

// Generate comprehensive compliance reports
async function generateComplianceReport(
  startDate: Date,
  endDate: Date,
  standards: ComplianceStandard[]
): Promise<ComplianceReport> {
  
  const complianceReporter = new ComplianceReporter(auditLogger);
  
  const report = await complianceReporter.generateReport({
    startDate,
    endDate,
    standards,
    includeMetrics: true,
    includeRecommendations: true,
    format: 'comprehensive'
  });

  // SOX compliance checks
  if (standards.includes('SOX')) {
    report.sections.push(await generateSoxSection({
      accessControls: await analyzeAccessControls(startDate, endDate),
      changeManagement: await analyzeChangeManagement(startDate, endDate),
      dataIntegrity: await analyzeDataIntegrity(startDate, endDate)
    }));
  }

  // GDPR compliance checks
  if (standards.includes('GDPR')) {
    report.sections.push(await generateGdprSection({
      dataProcessing: await analyzeDataProcessing(startDate, endDate),
      consentManagement: await analyzeConsentManagement(startDate, endDate),
      dataBreaches: await analyzeDataBreaches(startDate, endDate)
    }));
  }

  return report;
}

// Security monitoring dashboard data
async function getSecurityMetrics(
  timeRange: TimeRange
): Promise<SecurityMetrics> {
  
  const metrics = await auditLogger.analyzeMetrics(timeRange);

  return {
    // Authentication metrics
    authentication: {
      totalLogins: metrics.totalLogins,
      failedLogins: metrics.failedLogins,
      successRate: metrics.loginSuccessRate,
      unusualLoginPatterns: metrics.unusualLoginPatterns
    },

    // Authorization metrics  
    authorization: {
      permissionChecks: metrics.permissionChecks,
      permissionDenials: metrics.permissionDenials,
      elevatedAccess: metrics.elevatedAccessEvents,
      roleChanges: metrics.roleChanges
    },

    // Security incidents
    incidents: {
      total: metrics.totalIncidents,
      bySeverity: metrics.incidentsBySeverity,
      byType: metrics.incidentsByType,
      resolved: metrics.resolvedIncidents,
      averageResolutionTime: metrics.averageResolutionTime
    },

    // Compliance status
    compliance: {
      overallScore: metrics.complianceScore,
      violations: metrics.complianceViolations,
      remediation: metrics.remediationItems,
      reportingStatus: metrics.reportingStatus
    },

    // Risk assessment
    risk: {
      overallRiskScore: metrics.overallRiskScore,
      highRiskEvents: metrics.highRiskEvents,
      riskTrends: metrics.riskTrends,
      mitigationActions: metrics.mitigationActions
    }
  };
}

Common Security Issues and Solutions​

1. Permission Bypass Attempts​

Problem: Users attempting to bypass permission checks

Warning: Multiple permission denials for user 0.0.user123

Solution: Implement behavioral analysis and automatic response

// Behavioral security monitoring
class SecurityBehaviorMonitor {
  private userBehavior = new Map<string, UserBehaviorProfile>();

  async analyzeUserBehavior(userId: string, event: SecurityEvent): Promise<BehaviorAnalysis> {
    const profile = this.getUserProfile(userId);
    
    // Update behavior pattern
    profile.events.push({
      type: event.type,
      timestamp: Date.now(),
      severity: event.severity,
      resource: event.resource
    });

    // Analyze for suspicious patterns
    const analysis = await this.detectSuspiciousBehavior(profile);
    
    if (analysis.suspiciousScore > 7) {
      // Automatic response to suspicious behavior
      await this.triggerSecurityResponse(userId, analysis);
    }

    return analysis;
  }

  private async triggerSecurityResponse(
    userId: string, 
    analysis: BehaviorAnalysis
  ): Promise<void> {
    
    const response: SecurityResponse = {
      userId,
      timestamp: Date.now(),
      reason: analysis.suspiciousIndicators,
      actions: []
    };

    // Progressive response based on risk
    if (analysis.suspiciousScore > 8) {
      // High risk - immediate account lock
      await permissionSystem.lockUser(userId, {
        reason: 'Suspicious behavior detected',
        duration: 3600000, // 1 hour
        requiresAdminUnlock: true
      });
      response.actions.push('account_locked');
    } else if (analysis.suspiciousScore > 6) {
      // Medium risk - require MFA for sensitive operations
      await permissionSystem.requireMfa(userId, {
        duration: 1800000, // 30 minutes
        operations: ['high', 'critical']
      });
      response.actions.push('mfa_required');
    }

    // Log security response
    await auditLogger.logSecurityResponse(response);
  }
}

2. Content Integrity Violations​

Problem: Content hash mismatches indicating tampering

Error: Content hash verification failed - potential tampering detected

Solution: Implement content integrity monitoring and recovery

// Content integrity monitoring
class ContentIntegrityMonitor {
  async monitorContentIntegrity(
    contentId: string,
    expectedHash: string,
    checkInterval: number = 300000 // 5 minutes
  ): Promise<void> {
    
    setInterval(async () => {
      try {
        const currentContent = await fetchContent(contentId);
        const currentHash = await hashVerifier.hash(currentContent);
        
        if (currentHash !== expectedHash) {
          // Content integrity violation detected
          await this.handleIntegrityViolation({
            contentId,
            expectedHash,
            actualHash: currentHash,
            timestamp: Date.now()
          });
        }
      } catch (error) {
        // Content retrieval failed
        await this.handleContentUnavailable(contentId, error);
      }
    }, checkInterval);
  }

  private async handleIntegrityViolation(
    violation: IntegrityViolation
  ): Promise<void> {
    
    // Log critical security event
    await auditLogger.logEntry({
      type: 'content_integrity_violation',
      severity: 'critical',
      contentId: violation.contentId,
      details: violation,
      timestamp: violation.timestamp
    });

    // Quarantine content
    await this.quarantineContent(violation.contentId);
    
    // Notify security team
    await this.notifySecurityTeam(violation);
    
    // Attempt content recovery
    await this.attemptContentRecovery(violation.contentId);
  }
}

This comprehensive security documentation provides developers with all the tools needed to implement robust security measures in HCS-12 applications, ensuring protection against common threats while maintaining compliance with industry standards.