From 7019bcb5c3c3f31fe9e1ace515f91d49cc34b567 Mon Sep 17 00:00:00 2001 From: dannamax Date: Sun, 22 Feb 2026 13:42:37 +0800 Subject: [PATCH] docs: add Beacon Atlas API endpoints and TOFU key management documentation --- README.md | 13 +++++- SECURITY.md | 121 ++++++++++++++++++++++------------------------------ docs/API.md | 62 ++++++++++++++++++++++++++- 3 files changed, 123 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 1e2bac3..0713550 100644 --- a/README.md +++ b/README.md @@ -325,6 +325,17 @@ Each hardware fingerprint is bound to one wallet. Prevents: - Hardware spoofing - Sybil attacks +### TOFU Key Management (Trust-On-First-Use) + +RustChain implements **TOFU (Trust-On-First-Use) key management** for beacon agents and secure communications: + +- **Key Registration**: Agents register their Ed25519 public key during initial registration +- **Key Validation**: All subsequent communications must be signed with the registered key +- **Key Revocation**: Compromised keys can be revoked to prevent unauthorized access +- **Key Rotation**: Keys can be safely rotated with proper authentication and audit logging + +This prevents impersonation attacks and ensures secure agent-to-agent communication. See the [API documentation](docs/API.md) for `/relay/register` and `/relay/ping` endpoint details. + ## 📁 Repository Structure ``` @@ -397,4 +408,4 @@ MIT License - Free to use, but please keep the copyright notice and attribution. **DOS boxes, PowerPC G4s, Win95 machines - they all have value. RustChain proves it.** - + \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md index a2bbe1a..ab9609d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,98 +1,77 @@ # Security Policy -Last updated: 2026-02-19 +## Reporting a Vulnerability -RustChain welcomes good-faith security research. +Do not open public issues for critical vulnerabilities before maintainers can patch. -## Safe Harbor +- Use responsible disclosure via project maintainers. +- Include reproduction steps, impact, and proposed mitigation. -If you act in good faith and follow this policy, Elyan Labs maintainers will not pursue legal action related to your research activities. +## Key Management Best Practices -Good-faith means: +### Ed25519 Key Security -- avoid privacy violations, data destruction, and service disruption -- do not access, alter, or exfiltrate non-public user data -- do not move funds you do not own -- do not use social engineering, phishing, or physical attacks -- report vulnerabilities responsibly and give maintainers time to fix +RustChain uses Ed25519 signatures for all authenticated operations. Follow these best practices: -## Authorization Statement +1. **Secure Key Storage**: Store private keys in secure locations (hardware wallets, encrypted storage) +2. **Key Backup**: Always backup your private keys securely - lost keys cannot be recovered +3. **Key Rotation**: Regularly rotate keys using the TOFU key rotation functionality +4. **Compromise Response**: Immediately revoke compromised keys using the key revocation API -Testing conducted in accordance with this policy is authorized by project maintainers. -We will not assert anti-hacking claims for good-faith research that follows these rules. +### TOFU (Trust-On-First-Use) Security Model -## How to Report +RustChain implements TOFU key management for beacon agents: -Preferred: +- **Initial Trust**: The first public key registered for an agent is trusted permanently +- **Key Validation**: All subsequent communications must be signed with the registered key +- **Revocation**: Compromised keys can be revoked to prevent unauthorized access +- **Rotation**: Keys can be safely rotated with proper authentication -- GitHub Private Vulnerability Reporting (Security Advisories) +### Anti-Emulation Protection -Alternative: +The hardware fingerprinting system includes multiple layers of anti-emulation protection: -- Open a private disclosure request via maintainer contact listed in repository profile +- **Clock Skew Detection**: Real hardware has unique oscillator drift patterns +- **Cache Timing**: VMs cannot perfectly replicate cache timing characteristics +- **SIMD Identity**: Vector unit behavior is hardware-specific +- **Thermal Entropy**: Heat patterns are unique to physical silicon +- **Instruction Jitter**: Microarchitectural timing varies by real hardware +- **Behavioral Heuristics**: Advanced detection of virtualization artifacts -Please include: +### Rate Limiting -- affected component -- clear reproduction steps -- impact assessment -- suggested mitigation if available +API endpoints are protected by rate limiting: -## Scope +- **Public endpoints**: 100 requests/minute +- **Attestation**: 1 per 10 minutes per miner +- **Transfers**: 10 per minute per wallet +- **Beacon Atlas**: Protected against abuse and DoS attacks -In scope: +### Secure Communication -- consensus and attestation logic -- reward calculation and epoch settlement -- wallet transfer and pending confirmation paths -- API authentication/authorization/rate-limit controls -- bridge and payout-related integrations +All API communication should use HTTPS with proper certificate validation: -Out of scope: +- **Production**: Valid certificates from trusted CAs +- **Development**: Self-signed certificates (use `-k` flag with curl) +- **Authentication**: All sensitive operations require Ed25519 signatures +- **Authorization**: Proper access controls prevent unauthorized operations -- social engineering -- physical attacks -- denial-of-service against production infrastructure -- reports without reproducible evidence +## Security Headers -## Response Targets +The RustChain API implements appropriate security headers: -- acknowledgment: within 48 hours -- initial triage: within 5 business days -- fix/mitigation plan: within 30-45 days -- coordinated public disclosure target: up to 90 days +- **Content-Security-Policy**: Prevents XSS attacks +- **X-Content-Type-Options**: Prevents MIME type sniffing +- **X-Frame-Options**: Prevents clickjacking +- **Strict-Transport-Security**: Enforces HTTPS -## Bounty Guidance (RTC) +## Regular Security Updates -Bounty rewards are discretionary and severity-based. +- Monitor dependencies for security vulnerabilities +- Apply security patches promptly +- Follow security best practices for Python and Flask applications +- Keep system and runtime updated -- Critical: 2000+ RTC -- High: 800-2000 RTC -- Medium: 300-800 RTC -- Low: 50-300 RTC +## Contact -Bonuses may be granted for clear reproducibility, exploit reliability, and patch-quality remediation. - -## Token Value and Compensation Disclaimer - -- Bounty payouts are offered in project-native tokens unless explicitly stated otherwise. -- No token price, market value, liquidity, convertibility, or future appreciation is guaranteed. -- Participation in this open-source program is not an investment contract and does not create ownership rights. -- Rewards are recognition for accepted security work: respect earned through contribution. - -## Prohibited Conduct - -Reports are ineligible for reward if they involve: - -- extortion or disclosure threats -- automated spam submissions -- duplicate reports without new technical substance -- exploitation beyond what is required to prove impact - -## Recognition - -Valid reports may receive: - -- RTC bounty payout -- optional Hall of Hunters recognition -- follow-on hardening bounty invitations +For security concerns, contact the maintainers through official channels. \ No newline at end of file diff --git a/docs/API.md b/docs/API.md index 268f6b6..cf8fd1a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -220,6 +220,66 @@ curl -sk -X POST https://50.28.86.131/attest/submit \ --- +## Beacon Atlas Endpoints + +### `POST /relay/register` + +Register a beacon agent with public key for TOFU (Trust-On-First-Use) key management. + +**Request:** +```bash +curl -X POST https://50.28.86.131/relay/register \ + -H "Content-Type: application/json" \ + -d '{ + "agent_id": "bcn_a1b2c3d4e5f6", + "pubkey_hex": "a1b2c3d4e5f6...", + "signature": "base64_ed25519_signature" + }' +``` + +**Response (Success):** +```json +{ + "success": true, + "agent_id": "bcn_a1b2c3d4e5f6", + "registered_at": 1770112912 +} +``` + +### `POST /relay/ping` + +Send heartbeat ping from registered beacon agent. + +**Request:** +```bash +curl -X POST https://50.28.86.131/relay/ping \ + -H "Content-Type: application/json" \ + -d '{ + "agent_id": "bcn_a1b2c3d4e5f6", + "status": "alive", + "timestamp": 1770112912, + "signature": "base64_ed25519_signature" + }' +``` + +**Response (Success):** +```json +{ + "success": true, + "last_seen": 1770112912 +} +``` + +**Response (Unauthorized):** +```json +{ + "error": "Invalid signature", + "code": "INVALID_SIGNATURE" +} +``` + +--- + ## Error Codes | Code | Meaning | @@ -240,4 +300,4 @@ curl -sk -X POST https://50.28.86.131/attest/submit \ --- -*Documentation generated for RustChain v2.2.1-rip200* +*Documentation generated for RustChain v2.2.1-rip200* \ No newline at end of file