@trustroot/guard

TrustRoot Guard is a security framework designed to hash directories and files, ensuring data integrity and detecting unauthorized changes.

Overview

TrustRoot Guard is a security and verification toolkit designed to protect users and developers in the TrustRoot ecosystem. It provides tools and browser integrations for verifying file and directory integrity, monitoring registry attestations, and ensuring tamper-proof execution of Web3 automations. TrustRoot Guard is composed of a CLI, browser extension, service worker, and utility modules, all working together to deliver verifiable trust for Web3 interactions.

Components

• CLI: Command-line interface for hashing, manifest generation, and developer tools.
• Extension: Browser extension for real-time verification and UI integration.
• Service Worker: Background verification and message handling for browser and dApp security.
• Utils: Shared utility functions for hashing, validation, and cryptographic operations.
• Tests: Test suite for validating Guard functionality and security.

Features

• CLI: Hashes files and directories, generates and updates .troot.json manifests, normalizes and hashes HTML for reproducible integrity, and bundles web projects for TrustRoot integrity protection.
• Service Worker: Enforces subresource integrity for all file requests using .troot.json manifests, blocks or allows external resources based on a cryptographically managed whitelist, and caches/validates file hashes for secure resource loading.
• Chrome Extension: Verifies the root hash of index.html and provides real-time UI feedback for trust status.

Setup

Prerequisites

• Node.js and npm installed on your system.

Installation

1. Clone the repository:

   git clone https://github.com/trustRootOrg/guard.git
   cd guard

2. Install dependencies:

   npm install

Usage

CLI

Use the CLI to hash a directory or file, or to bundle a directory for deployment:

npx @trustroot/guard hash <directory-or-file>
npx @trustroot/guard bundle <directory>

Options:

• <directory or file path>: Path to the directory or file you want to hash.
• --refreshHash: Recalculates hash values for the specified directory or file (default: false).
• --skipGenerateHash: Skips writing the .troot.json file (default: false).

Examples:

1. Hash a directory:

   npx @trustroot/guard hash ./my-directory

2. Hash a file:

   npx @trustroot/guard hash ./my-file.txt

3. Bundle a directory for deployment:

   npx @trustroot/guard bundle ./my-directory

4. Refresh hash values in .troot.json:

   npx @trustroot/guard hash ./my-directory --refreshHash

5. Skip writing .troot.json:

   npx @trustroot/guard hash ./my-directory --skipGenerateHash

Chrome Extension

The Chrome extension provides real-time verification of the root hash and trust status for your web project. To install it in developer mode:

1. Build the extension assets (if not already built):

   npm run build

2. Open Chrome and navigate to chrome://extensions/.
3. Enable Developer mode (toggle in the top right).
4. Click Load unpacked and select the cli/extension directory inside your project.
5. After loading, open your web project and click the TrustRoot extension icon to view verification status.

Development

Build

To build the project, run:

npm run build

Test

Run tests using Mocha:

npm test

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix:

   git checkout -b feature/your-feature-name

3. Commit your changes:

   git commit -m "Add your descriptive commit message here"

4. Push your branch:

   git push origin feature/your-feature-name

5. Submit a pull request.

License

This project is licensed under the MIT License.

Support

If you encounter any issues or have questions, feel free to open an issue on the GitHub repository.

Acknowledgments

Special thanks to all contributors and the open-source community for their support and inspiration.