v0.0.2

HieraChain v0.0.2 - Security Hardening, Observability & Stability Improvements

What's New

This release focuses on enhanced security, system observability, and stability improvements for hierachain/. Key highlights include unified SecretManager, Prometheus metrics, JSON logging, Redis rate limiting, brute force protection, GraphQL security, deadlock detection, chain rehydration fixes, and hierarchical chain resilience.

Security & Policy

• Brute Force Protection: Added persistent storage backends (file/Redis) to BruteForceProtector for lockout tracking across restarts. Extracted storage and tracking logic into _LockoutStorage and _FailureTracker classes (03c9958, 53266c2).
• GraphQL Security: Added GraphQLSecurity module with per-IP rate limiting, introspection blocking, query depth analysis, and complexity estimation (e5cb679). Integrated security checks into the GraphQL endpoint handler (c4ced4a).
• Input Validation: Actively reject dangerous input patterns in is_safe_input. Enforced full regex matching in PolicyEngine to prevent bypass via partial matches. Added validation to ChannelLedger.add_event for malformed events (7a64bc6, fbe72f9, b3ce2a5).
• Master Key: Prevented auto-generation of master key in production; raised MasterKeyError in _load_auto. Path traversal prevention for SubChain SQLite database directory creation and validation (c5bcb9e, 69aaf65, 7240690).
• Key Backups: Used consistent base directory for key backups (f479331).
• Secret Manager: Introduced SecretManager for unified secret retrieval (env/Vault/AWS backends). Masked secret keys and backend identifiers in logs to prevent sensitive data exposure. Refactored to use generic log messages (a74d2c4, cfa4200, 0baf029, de16b59).
• Cluster Secrets: Refactored ClusterLockdownManager to use SecretManager for cluster secret retrieval (7f75bd5).

Observability & Monitoring

• Prometheus Metrics: Added PrometheusMetrics singleton with global metrics instance for tracking API latency, block throughput, consensus health. Integrated optional /metrics endpoint (a842639, d2daa69).
• JSON Logging: Added _JsonFormatter and _JSON_LOGGING_CONFIG for structured JSON log output, configurable via HRC_LOG_FORMAT (b30b47f, 68a6cd0).
• Rate Limiting: Introduced RedisRateLimiter for distributed multi-node rate limiting with standard X-RateLimit-* headers. Added request logging middleware with unique X-Request-ID. Enhanced API rate limiting via d2daa696 (d2daa69).
• Alert Manager: Added send_alert convenience method and global alert_manager singleton for proactive event notification (217a32b).
• Proxy Support: Added TRUSTED_PROXIES setting and enabled proxy headers for accurate client IP detection behind reverse proxies (9bd3c31, 001f36f).

Stability & Deadlock Prevention

• Deadlock Detection: Implemented DeadlockDetector singleton with background monitoring thread to track lock wait times and trigger recovery callbacks via timeout-based safe_lock/safe_unlock methods in Blockchain (f8cbeae, 9b54505).
• Consensus/Ordering Fixes:
  • Resolved race condition in commit_block by introducing _block_index_lock (dd06ae7).
  • Made lockdown and resume operations atomic in OrderingMaintenance (e56dfbe, ee1de83). Later removed lock for direct state transitions (a0e8251).
  • Prevented silent data loss during journal recovery by re-raising exceptions (c6aa38d5).
  • Improved state recovery with journal replay and config validation (9e36f0f, 803bd09).
  • Prevented duplicate processing threads and fixed pending event status on recovery (19cfa3e).

Hierarchical Chain

• Graceful Shutdown: Added shutdown() method to SubChain with _shutdown_event for graceful consumer thread termination. Set consumer thread as daemon to prevent blocking on exit (d980066, c6d5fd5, 482920d).
• Rehydration: Improved state validation with block hash comparison during rehydration (d8ede52).
• Proof Submission: Made proof recording atomic with thread lock. Added validation to ensure blocks are finalized before proof submission. Improved proof submission and shutdown robustness (35394c6, ed8521a).
• ZK Proofs: Escalated missing ZK proof severity to critical with automatic alert triggering (4eeff59).
• Stability: Enhanced SubChain stability with retry-backoff for ZK proof generation, isolated SQLite databases per SubChain, synchronized event state across OrderingService and BlockChain (35b77f3).
• DomainChain: Added metadata support to DomainChain constructor. Fixed create_sub_chain to correctly pass metadata (1f27730, 482920d).

Core Improvements

• Thread Safety: Improved thread safety and deterministic event hashing with sort_keys=True in JSON serialization. Enhanced deadlock prevention mechanisms (8ed692c, 9b54505).
• Error Handling: Improved error handling in ParallelProcessingEngine and Blockchain (922b1ab).
• Cache & TTL: Added cache invalidation method to CrossChainValidator. Reduced EntityTracer cache TTL from 5min to 1min (1c8a71e, d034f29).

API

• Block Retrieval: Added endpoint to fetch specific blocks by index or hash with CID resolution for IPFS off-chain details (5e4530b).
• System Endpoints: Bypassed authentication and rate limiting for health/metrics/doc endpoints (6ff900e).
• GraphQL Security: Implemented GraphQL security module and endpoint integration (e5cb679, c4ced4a).
• Rate Limiter Thread Safety: Made in-memory RateLimiter thread-safe with lock (c4ced4a).
• IPFS Error Logging: Fixed bytes copy in encryption_key property and improved error logging in IPFS availability checks (fda8109).

SDK & CLI

• Multi-Chain SDK: Updated SDK client for multi-chain API v3 support with NodeStatus, ChainStats, EntityTrace dataclasses. Added get_chain_stats, submit_proof, trace_entity methods (9cae7a8).
• Key Management CLI: Added hrc key generate, hrc key show, hrc key verify commands for Ed25519 validator key pairs (cc7be51).
• Block Schema Alignment: Aligned block schema with event schema for consistent data structure (fbbb276).

Refactoring

• Modularized Recovery: Extracted state recovery from transaction journal into focused methods (803bd09).
• Helper Extraction: Extracted helper functions in API server and v1 endpoints to reduce complexity (b9625fc).
• Code Quality: Used lazy string interpolation, chained comparisons, corrected type hints across network, security, integration modules (da3e09e, 258412e, 6864b7d, bb07dd0).

Changes Since v0.0.1

Area	Improvements	Key Commits
Security	Brute force persistence, GraphQL security, input validation, secret masking, master key safeguards	03c9958, e5cb679, cfa4200
Observability	Prometheus metrics, JSON logging, Redis rate limiting, alert manager, proxy support	a842639, b30b47f, d2daa69
Consensus/Ordering	Race condition fixes, atomic lockdown, journal recovery, duplicate thread prevention	dd06ae7, e56dfbe, c6aa38d5
Hierarchical	Graceful shutdown, rehydration fixes, proof atomicity, ZK escalation, isolated SQLite	d980066, 35b77f3, 4eeff59
API	Block retrieval by index/hash, system endpoint bypass, GraphQL security	5e4530b, 6ff900e, c4ced4a
SDK/CLI	Multi-chain v3 support, key management CLI	9cae7a8, cc7be51

Architecture Audit Summary

Tool	Result
Security	✅ PASS - Brute force, GraphQL, input validation, secret management
Observability	✅ PASS - Prometheus, JSON logging, Redis rate limiting
Consensus	✅ PASS - Atomic operations, race condition fixes, journal recovery
Hierarchical	✅ PASS - Graceful shutdown, proof atomicity, rehydration fixes
API	✅ PASS - Block retrieval, GraphQL security, rate limiting

Known Limitations

• Not production-ready; targeted for evaluation and testing.

Links

Documentation

• README (English)
• README (Tiếng Việt)
• AGENTS.md
• HieraChain Documentation

What's Changed

• build(deps): bump requests from 2.32.5 to 2.33.0 by @dependabot[bot] in #5
• build(deps): bump cryptography from 46.0.5 to 46.0.6 by @dependabot[bot] in #6
• build(deps): bump aiohttp from 3.13.3 to 3.13.4 by @dependabot[bot] in #7

Full Changelog: v0.0.1...v0.0.2