ChainGuard Security Framework

Version: 1.0.0
Last Updated: 18-11-2025
Status: Production Ready

Overview
Security Architecture Philosophy
Security Boundaries & Network Zones
Authentication & Authorization
Cryptographic Operations
Operational Security
Vault Security
Compliance & Auditing
ISO 27001 Alignment
Security Advantages
Related Documentation

Overview

ChainGuard's security framework is built on the principles of defense in depth, zero trust architecture, user sovereignty preservation, and non-custodial design. This document outlines the comprehensive security controls, authentication mechanisms, authorization systems, and operational security measures that protect the ChainGuard ecosystem.

Security Architecture Philosophy

Core Principles

Defense in Depth:

Multiple layers of security controls at network, application, and data levels
No single point of failure
Redundant security measures across all system components

Zero Trust Architecture:

Never trust, always verify
Continuous authentication and authorization
Least privilege access principles
Network segmentation and micro-perimeters

User Sovereignty Preservation:

Users maintain full control of their private keys
Non-custodial design - ChainGuard never holds user assets
Decentralized verification where possible
User-controlled data sharing and consent management

Non-Custodial Design:

Users control their own keys and assets
ChainGuard infrastructure facilitates but never controls transactions
Smart contract-based verification provides trustless security
Backend compromise cannot result in asset loss

Security Boundaries & Network Zones

Network Security Zones Diagram

Network Security Zones

Public Zone:

ChainGuard DApp (Public Website)
Internet-facing load balancers and CDN
Security Controls: DDoS protection, WAF, rate limiting, SSL/TLS termination

DMZ / Edge Zone:

OAuth Portal (module.chain-fi.io) - Authenticated user workspace
Security Controls: Authentication required, no-index robots, session validation

Internal Services Zone:

Backend Server
Forwarder Server (Payment Service)
Blockchain Listener
Security Controls: Internal network only, service-to-service authentication, encrypted communication

Data Zone:

PostgreSQL Database
Redis Cache
MinIO Object Storage
Hashicorp Vault
Security Controls: No direct internet access, encrypted at rest, access logging, network segmentation

External Integration Zone:

Stripe API
Sumsub API
Blockchain RPC endpoints
Security Controls: Outbound-only connections, API key management, TLS 1.3+, certificate pinning

Perimeter Controls

Perimeter	Control Type	Implementation	ISO 27001 Mapping
Internet → Public Zone	DDoS Protection	Cloud provider DDoS mitigation	A.12.4.2
Internet → Public Zone	WAF	Web Application Firewall	A.14.1.2
Internet → Public Zone	SSL/TLS	TLS 1.3+ with certificate validation	A.14.1.3
Public Zone → DMZ	Authentication	JWT validation, session management	A.9.4.2
DMZ → Internal Zone	Service Auth	API keys, mutual TLS	A.9.4.4
Internal Zone → Data Zone	Network Segmentation	Private subnets, firewall rules	A.13.1.1
Data Zone	Encryption at Rest	AES-256, key rotation	A.10.1.1

Authentication & Authorization

Multi-Layer Authentication Diagram

Multi-Layer Authentication

Layer 1: User Authentication

Method: Email/password with bcrypt hashing (12 rounds)
Storage: PostgreSQL (password_hash)
Session: JWT tokens in HttpOnly cookies
Components: Backend Server
Security: Password never stored in plain text, secure session management

Layer 2: Two-Factor Authentication (2FA)

Method: Wallet-based cryptographic signatures using EIP-712
Storage: Mobile device (private keys never leave device)
Session: Separate 2FA JWT token
Components: Mobile App, Backend Server, OAuth Portal
Security: Hardware-level security, offline-capable signing, QR code-based session establishment

Layer 3: OAuth 2.0 Authorization

Method: Authorization code flow with PKCE support
Storage: PostgreSQL (tokens, codes)
Session: Access tokens (short-lived), refresh tokens (long-lived, server-side only)
Components: Backend Server, OAuth Portal, Client Applications
Security: Tokens never exposed to frontend, server-to-server exchanges only

Authorization Mechanisms

Role-Based Access Control (RBAC)

Service: Backend Server, OAuth Portal
Storage: PostgreSQL (roles, permissions, assignments)
Enforcement: Middleware in services
Principle: Least privilege access
Components: All authenticated services

Scope-Based Access (OAuth)

Service: OAuth Service
Storage: PostgreSQL (scopes per client)
Enforcement: Token validation
User Control: Consent screens, scope approval, revocation
Components: Backend Server, Client Applications

Wallet Ownership Validation

Service: Wallet Validation Service
Method: Signature verification (EIP-712)
Storage: PostgreSQL (linked wallets)
Security: Cryptographic proof of ownership
Components: Forwarder Server, Backend Server

Vault Access Control

Service: Vault Stack (On-Chain)
Method: Dual-signature enforcement (owner + auth addresses)
Guardian Role: Forwarder Server acts as guardian, verifies signatures, submits meta-transactions
Whitelist Enforcement: WhitelistRegistry gates all external contract interactions
Emergency Fallback: Users can bypass guardian by paying gas directly
Components: ChainFiVault, ChainFiVaultFactory, WhitelistRegistry, Forwarder Server

Cryptographic Operations

Signature Verification

Standard: EIP-712 typed data signing
Library: Ethers.js (off-chain), Solidity ECDSA (on-chain)

Use Cases:

Vault creation (owner + auth + guardian signatures)
Vault transactions (owner + auth signatures)
2FA verification (wallet-based signatures)
Marketplace operations (owner + auth signatures)

Security Features:

Nonce-based replay protection
Deterministic vault addresses
Guardian verification
On-chain signature validation

Components: Forwarder Server, Backend Server, Mobile App, Vault Contracts

Encryption

Key Management: Hashicorp Vault
Encryption at Rest: AES-256 for databases, file storage
Encryption in Transit: TLS 1.3+ for all communications
Key Rotation: Automated key rotation policies
Storage: Encrypted storage for sensitive data

Components: Hashicorp Vault, PostgreSQL, MinIO

Password Hashing

Algorithm: bcrypt (12 rounds)
Storage: PostgreSQL
Security: Salted hashes, never stored in plain text
Components: Backend Server

Operational Security

Secure Token Handling

Token Responsibility Matrix:

Token Type	Holder	Storage	Exposure Risk
Main JWT	ChainGuard Portal only	HttpOnly cookie	None (server-side only)
2FA JWT	ChainGuard Portal only	HttpOnly cookie	None (server-side only)
OAuth Access Token	Client Backend only	Server-side storage	None (never sent to frontend)
OAuth Refresh Token	Client Backend only	Server-side storage	None (never sent to frontend)
client_id + client_secret	Client Backend only	Server-side storage	None (never sent to frontend)
Client Session Cookie	Client Backend → Frontend	HttpOnly cookie	Minimal (client-controlled)

Key Principles:

Tokens never exposed to frontend environments
Server-to-server exchanges only
HttpOnly cookies prevent XSS attacks
Refresh tokens stored server-side only
No token storage in browser localStorage or sessionStorage

Secure 2FA Implementation

Mobile App Security:

Private keys stored in device secure storage (Keychain/Keystore)
Keys never leave the device
Offline-capable signing
QR code-based session establishment
Biometric protection (optional)

Backend Security:

WebSocket-based secure communication
Session ID validation
Signature verification on backend
Nonce-based replay protection
Time-limited sessions

Components: Mobile App, Backend Server, OAuth Portal

Server-Side Token Handling

OAuth Flow Security:

Authorization codes exchanged server-to-server
Access tokens issued to client backend only
Refresh tokens never exposed to frontend
Token revocation capabilities
Scope-based access enforcement

Session Management:

JWT tokens in HttpOnly cookies
Secure cookie flags (Secure, SameSite)
Token expiration and refresh
Session invalidation on logout

Components: Backend Server, Client Applications

Secure WebSocket Communication

WebSocket Security:

TLS-encrypted WebSocket connections (WSS)
Authentication required for connection
Session-based message routing
Rate limiting and abuse prevention
Connection validation

Use Cases:

2FA session establishment
Real-time transaction updates
Blockchain event notifications
System status updates

Components: Backend Server, Blockchain Listener, Mobile App

Vault Security

Transaction-Level 2FA

Per-Transaction Authorization:

Each transaction requires a separate signature from the ChainGuard 2FA app
Not just session-based authentication, but explicit approval for each financial action
User must approve each transaction individually
No batch transaction approval

Security Benefits:

Prevents unauthorized bulk transactions
User awareness of each action
Explicit consent for financial operations
Audit trail of individual approvals

On-Chain Signature Verification

Cryptographic Proof:

Transaction signatures verified directly on the smart contract level
Provides cryptographic proof of authorization
Trustless security independent of ChainGuard infrastructure
Decentralized verification

Smart Contract Security:

EIP-712 typed data signing
Nonce-based replay protection
Dual-signature enforcement (owner + auth)
Guardian verification for gasless transactions

Components: ChainFiVault, ChainFiVaultFactory, Forwarder Server

Backend Compromise Protection

Hardware-Level Security:

Even if ChainGuard's backend is compromised, attackers cannot simulate transactions
Requires physical access to user's mobile device containing the specific wallet
Private keys never leave the device
On-chain verification provides additional protection

Multi-Layer Defense:

Backend compromise cannot result in asset loss
Transaction signatures required from user's device
Smart contract validation independent of backend
Emergency fallback paths (direct gas payment)

Portal-Mediated Transactions

Transaction Flow Security:

All transaction requests flow through the ChainGuard Portal
Must originate from authorized applications
User approval required in portal
2FA signature from mobile device
Guardian verification and execution

Audit Trail:

Complete logging of transaction requests
User approval records
Signature verification logs
Execution results
Application tracking

Components: OAuth Portal, Mobile App, Forwarder Server, Vault Contracts

Compliance & Auditing

Comprehensive Logging

Log Categories:

Authentication events (login, logout, registration)
OAuth events (authorization grants, token issuance)
Transaction events (requests, signatures, execution)
Security events (failed logins, suspicious activity)
2FA events (setup, verification, resets)
Access control events (permission changes, role assignments)

Log Storage:

PostgreSQL compliance_events table
Immutable log storage
7-year retention (legal requirement)
Access controls on log data

Components: Compliance Logger, Backend Server, Forwarder Server

Audit Trail Capabilities

Transaction Audit Trail:

Connection events
Logout events
Transaction requests
Signatures
Execution results
Application tracking

User Activity Tracking:

Complete audit trail of who performed what action and when
IP address logging
Device fingerprinting (hashed)
Session tracking
Consent history

Compliance-Ready:

Extensive logging supports regulatory auditing requirements
ISO 27001 monitoring controls
GDPR Article 30 compliance
AML/CTF audit requirements

Components: All system components

ISO 27001 Alignment

Security Control Mapping

ChainGuard's security framework aligns with ISO 27001 Annex A controls:

A.8.5 (Authentication): Wallet-based 2FA, server-side refresh tokens, no frontend token exposure
A.8.24 (Cryptographic Operations): Signature-based authentication, JWTs, OAuth tokens, EIP-712 signing
A.5.15 (Access Control): Scope-based permissions, client ID authentication, API key tracking
A.5.18 (Access Rights): Frontend/backend separation, role-based access control
A.9.4.2 (User Authentication): Multi-factor authentication, secure session management
A.9.4.4 (Password Management): bcrypt hashing, secure password storage
A.10.1.1 (Cryptographic Controls): Encryption at rest (AES-256), encryption in transit (TLS 1.3+)
A.12.4.2 (Logging): Comprehensive event logging, audit trails
A.13.1.1 (Network Controls): Network segmentation, firewall rules
A.14.1.2 (Application Security): WAF, secure coding practices
A.14.1.3 (Secure Communications): TLS 1.3+, certificate validation

Security Advantages

Per-Transaction Authorization

Not just session-based authentication, but explicit approval for each financial action. Users must approve each transaction individually, preventing unauthorized bulk operations.

Hardware-Level Security

Wallet keys remain on the user's mobile device and never leave it. Even backend compromise cannot result in asset loss without physical device access.

Decentralized Verification

Smart contract validation provides trustless security independent of ChainGuard's infrastructure. On-chain signature verification ensures cryptographic proof of authorization.

Financial Transaction Safety

Specifically designed for high-stakes operations involving monetary transfers. Multi-layer security ensures protection against various attack vectors.

Non-Custodial Protection

Users maintain full control of their assets. ChainGuard infrastructure facilitates but never controls transactions, ensuring user sovereignty.