diff --git a/AGENTS.md b/AGENTS.md index 1f0f825..c47b10e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,3 +35,14 @@ Every Pull Request to `main` is verified by [.github/workflows/pr-check.yml](.gi - **Test**: `pnpm client:test` (vitest unit + dependency-cruiser `test:arch`), `pnpm server:test` (jest), `pnpm blockchain:test` (hardhat), `pnpm ml:test` (pytest + ONNX parity), & `pnpm notifier:test` (unittest). - **API Contracts**: `pnpm test:contracts` (validates client Zod schemas against NestJS controllers and client-side envelope parsing). - **Build**: `pnpm client:build`, `pnpm server:build`, `pnpm blockchain:compile`. + +--- + +## πŸ”’ Security & Safe Coding Policy + +All agents and contributors MUST adhere to the security principles documented in [SECURITY.md](SECURITY.md): + +1. **Zero Secret Leaks**: NEVER commit private keys, Besu keystores, mnemonic phrases, database passwords, or JWT secrets to code. Always use environment variables validated via configuration schemas (`@nestjs/config` / Pydantic). +2. **Access Control & Role Guarding**: All backend endpoints MUST be explicitly protected by `JwtAuthGuard` and `RolesGuard` matching one of the 4 defined portals (`KTH`, `EMITTER`, `AUDITOR`, `REGULATOR`). +3. **Smart Contract Invariants**: Adhere to checks-effects-interactions, use OpenZeppelin contracts, prevent reentrancy, and verify role-based permissions (`onlyRole(DEFAULT_ADMIN_ROLE)`). +4. **Input Sanitization & Cryptographic Integrity**: Validate all incoming payload structures with `class-validator`/`zod` and preserve deterministic SHA-256 hash formatting. diff --git a/CITATION.cff b/CITATION.cff index 2ab2ebe..7171f81 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -18,7 +18,7 @@ title: "RekaKarbon: Digital MRV & Carbon Exchange Ecosystem with AI Anomaly Dete version: "1.0.0-pilot" date-released: "2026-10-07" url: "https://rekakarbon.farrelad.com" -repository-code: "https://github.com/KMIPN-2026/RekaKarbon" +repository-code: "https://github.com/SYNETRATECH2026/RekaKarbon" license: "Apache-2.0" keywords: - "carbon-accounting" diff --git a/NOTICE b/NOTICE index 569f34c..ce2ff0f 100644 --- a/NOTICE +++ b/NOTICE @@ -32,5 +32,5 @@ Recommended citation format: Pramudhita, A. N., Rosario, P. T. A., Fadlilurrahman, E. M. H., & Dinata, F. A. (2026). RekaKarbon: Digital MRV & Carbon Exchange Ecosystem with AI Anomaly Detection and Consortium Blockchain. Politeknik Negeri Malang. -Repository: https://github.com/KMIPN-2026/RekaKarbon +Repository: https://github.com/SYNETRATECH/RekaKarbon Live Demonstration: https://rekakarbon.farrelad.com diff --git a/README.md b/README.md index 2177964..e519a75 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,9 @@ Live Platform + + Security Policy + License @@ -331,7 +334,7 @@ If you reference, adapt, or build upon this project in academic research, compet title = {RekaKarbon: Digital MRV & Carbon Exchange Ecosystem with AI Anomaly Detection and Consortium Blockchain}, year = {2026}, url = {https://rekakarbon.farrelad.com}, - note = {Politeknik Negeri Malang (KMIPN 2026). Available at: https://github.com/KMIPN-2026/RekaKarbon} + note = {Politeknik Negeri Malang (KMIPN 2026). Available at: https://github.com/SYNETRATECH/RekaKarbon} } ``` @@ -339,4 +342,4 @@ If you reference, adapt, or build upon this project in academic research, compet > Pramudhita, A. N., Rosario, P. T. A., Fadlilurrahman, E. M. H., & Dinata, F. A. (2026). _RekaKarbon: Digital MRV & Carbon Exchange Ecosystem with AI Anomaly Detection and Consortium Blockchain_ [Computer software]. Politeknik Negeri Malang. https://rekakarbon.farrelad.com -For machine-readable citation metadata, see **[`CITATION.cff`](CITATION.cff)**. +For machine-readable citation metadata, see **[`CITATION.cff`](CITATION.cff)**. For responsible vulnerability disclosure and reporting guidelines, see **[`SECURITY.md`](SECURITY.md)**. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..0a71dcf --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,127 @@ +# Security Policy - RekaKarbon + +The RekaKarbon engineering team takes the security, reliability, and cryptographic integrity of our digital MRV (dMRV) and carbon exchange ecosystem seriously. Because RekaKarbon facilitates sovereign carbon certificate issuance, fiscal tax synchronization, machine learning telemetry, and smart contract settlement, we maintain proactive defenses to safeguard against tampering, fraud, and unauthorized access. + +This document outlines our vulnerability disclosure process, supported versions, domain-specific security scope, and response timelines. + +--- + +## πŸ›‘οΈ Supported Versions + +We provide active security patches and updates for the following versions: + +| Version | Supported | Status | Security Patch Policy | +| :---------------- | :-------: | :----------------------- | :---------------------------------------------------------------------- | +| **`1.0.x-pilot`** | βœ… | **Current Active Pilot** | Actively receiving vulnerability patches and critical security updates. | +| `< 1.0.0` | ❌ | Deprecated / Development | No longer supported. Please upgrade to the latest pilot release. | + +--- + +## 🚨 Reporting a Vulnerability + +If you discover a security vulnerability, flaw, or potential exploit in RekaKarbon, **do NOT open a public GitHub issue, pull request, or discussion**. Public disclosure before a fix is available puts users, institutions, and carbon market participants at risk. + +Please report vulnerabilities using one of the following confidential channels: + +### 1. GitHub Private Security Advisory (Preferred) + +The most secure and encrypted reporting mechanism is GitHub's built-in private vulnerability advisory: + +1. Navigate to the repository's **[Security Tab](https://github.com/SYNETRATECH/RekaKarbon/security)**. +2. Under "Security", click on **"Report a vulnerability"** (or **"Advisories"**). +3. Fill out the report form with full reproduction steps and click **Submit report**. +4. Our security response team will review and collaborate with you directly inside the private advisory workspace. + +### 2. Direct Security Contact (Fallback Email) + +If you cannot submit via GitHub Security Advisories, send an encrypted or direct email to our security point of contact: + +- **Email**: `farrel.apeiron@gmail.com` +- **Subject Line**: `[SECURITY] Vulnerability Report: RekaKarbon - ` + +### What to Include in Your Report + +To accelerate triage and verification, please include: + +- **Component Affected**: Specify whether the vulnerability affects the frontend (`client/`), NestJS API (`server/`), Besu smart contracts (`blockchain/`), or ML pipeline (`ml/`). +- **Severity & Impact**: Your estimate of the severity (Critical, High, Medium, Low) and potential real-world consequences (e.g., unauthorized token minting, authentication bypass, sensor spoofing). +- **Steps to Reproduce**: Detailed, step-by-step instructions or scripts to reliably replicate the vulnerability. +- **Proof of Concept (PoC)**: Minimal reproducible code snippet, transaction payload, or request trace. +- **Suggested Mitigation**: Any recommendations or pull request patches you believe resolve the vulnerability (optional). + +--- + +## ⏱️ Response Timelines & SLA + +Our core engineering team commits to the following Service Level Agreements for reported security issues: + +| Milestone | Target Response Time | Action | +| :------------------------------- | :-------------------- | :------------------------------------------------------------------------------- | +| **Initial Acknowledgment** | **< 48 hours** | Confirm receipt of the report and assign a primary security reviewer. | +| **Triage & Severity Assessment** | **< 5 business days** | Verify reproducibility, evaluate systemic impact, and determine CVSS score. | +| **Hotfix & Private Patching** | **14 – 30 days** | Develop, test, and audit the remediation patch in an isolated environment. | +| **Coordinated Disclosure** | **Upon Release** | Deploy the patch, release a security advisory, and publicly credit the reporter. | + +--- + +## πŸ” In-Scope Security Domains + +RekaKarbon’s architecture encompasses four distinct technology layers, each with specific threat surfaces: + +### 1. ⛓️ Consortium Blockchain & Smart Contracts (`blockchain/`) + +- **ERC-1155 Token Integrity**: Vulnerabilities allowing unauthorized minting, transfer, burning, or balance manipulation of `PTBAE-PU` (allowance tokens) or `SPE-GRK` (offset certificates). +- **Buffer Reserve Invariants**: Flaws that bypass the mandatory 5% global buffer pool contribution on forestry carbon issuance. +- **Access Control & Reentrancy**: Violations of OpenZeppelin `AccessControl` roles (`DEFAULT_ADMIN_ROLE`, `MINTER_ROLE`, `ORACLE_ROLE`) or reentrancy bugs in treasury settlement. +- **QBFT Consensus Fault Tolerance**: Exploits affecting validator node communication or transaction mempool manipulation in the Hyperledger Besu cluster. + +### 2. βš™οΈ Backend API & Database (`server/`) + +- **Authentication & RBAC Bypass**: Vulnerabilities circumventing `JwtAuthGuard` or `RolesGuard` enabling unauthorized access across the four isolated portals (`KTH`, `EMITTER`, `AUDITOR`, `REGULATOR`). +- **Cryptographic Envelope Integrity**: Tampering with standardized API response envelopes or forgery of SHA-256 verification hashes. +- **Database & Query Injection**: SQL injection or improper relation traversal via Prisma ORM / PostgreSQL. +- **Fiscal & Tax Data Tampering**: Forgery of DJP e-Faktur validation proofs or unverified emission calculation submissions. + +### 3. 🌿 Machine Learning & dMRV Engine (`ml/`) + +- **ONNX Model Deserialization**: Arbitrary code execution or heap corruption via manipulated ONNX runtime model files. +- **Adversarial Telemetry Spoofing**: Crafted inputs designed to systematically evade the Isolation Forest anomaly detector while reporting fraudulent emissions. +- **Stoichiometric Calculation Subversion**: Exploiting numerical instability or physical unit boundary checks in combustion thermodynamics calculations. + +### 4. 🎨 Frontend Application (`client/`) + +- **Cross-Site Scripting (XSS)**: Malicious script execution through user-supplied project descriptions, audit remarks, or telemetry graphs. +- **Client-Side Key Leakage**: Exposure of administrative credentials, private signing keys, or unredacted internal tokens in client bundles. + +--- + +## 🚫 Out-of-Scope Vulnerabilities + +The following types of activities and non-impact reports are strictly **out of scope**: + +- **Denial of Service (DoS/DDoS)**: Volumetric flooding attacks against local development ports (`localhost:3000`, `localhost:5173`, `localhost:8545`) or public staging endpoints. +- **Social Engineering & Phishing**: Attacks targeting project contributors, students, or institutional staff. +- **Theoretical Vulnerabilities**: Flaws reported without a working Proof of Concept (PoC) demonstrating practical impact. +- **Third-Party Dependency Scanner Dumps**: Automated reports from vulnerability scanners without evidence that the vulnerable dependency path is reachable and exploitable in RekaKarbon. +- **Local Attacks Requiring Physical Root Access**: Exploits that require physical possession of an unlocked developer workstation. + +--- + +## 🀝 Responsible Disclosure & Safe Harbor + +We fully support security researchers who conduct their testing ethically: + +- If you make a good-faith effort to avoid privacy violations, data destruction, and service interruption during your research, **we will not pursue legal action against you**. +- We request that you give us a reasonable opportunity to investigate and remediate the vulnerability before publicly discussing or publishing any details. +- Once a fix is verified and deployed, researchers will be permanently acknowledged in our **Security Hall of Fame** and the official GitHub release notes. + +--- + +## πŸ” Contributor Security Guidelines + +All engineers contributing code to RekaKarbon MUST follow these essential security standards: + +1. **Zero Secret Leaks**: Never commit `.env` files, private keys, Besu keystores, or database credentials. Use `.gitignore` and run pre-commit hooks (`husky` + `lint-staged`). +2. **Deterministic Typing & Validation**: Validate all incoming DTOs using `class-validator` (server) and `zod` (client). Never rely solely on client-side validation for critical actions. +3. **Smart Contract Auditing**: Run static analysis (`slither`) and Hardhat unit tests covering revert conditions and permission boundaries prior to opening pull requests. +4. **Dependency Auditing**: Regularly run `pnpm audit` and `poetry run pip-audit` to detect known vulnerabilities in third-party libraries.