db/_archive/acldb

ACLDB - Access Control Database

ACLDB is a secure, permission-based database system that provides fine-grained access control for data storage and retrieval. It's designed to work with the HeroDB ecosystem, offering a robust solution for managing data with complex access control requirements.

Overview

ACLDB organizes data into "circles" and "topics" with comprehensive access control lists (ACLs) that govern who can read, write, delete, or administer different pieces of data. It's built on top of OurDB and TST (Ternary Search Tree) for efficient storage and retrieval.

Key Features

• Fine-grained Access Control: Define who can access what data with a hierarchical permission system
• Circle-based Organization: Group data by circles (e.g., organizations, teams, projects)
• Topic-based Categorization: Organize data within circles by topics
• Permission Levels: Supports Read, Write, Delete, Execute, and Admin permission levels
• RPC API: Access all functionality through a well-defined RPC interface
• REST API Server: Includes a built-in HTTP server with Swagger/OpenAPI documentation
• Async/Await Support: Built with Rust's async/await for efficient concurrency

Architecture

ACLDB consists of several key components:

1. ACLDB: The main database instance for a specific circle
2. ACLDBTopic: A database instance for a specific topic within a circle
3. ACL: Access Control List for managing permissions
4. Server: HTTP server for exposing the RPC API
5. RpcInterface: Interface for handling RPC requests

Data is stored using:

• OurDB: For efficient data storage and retrieval
• TST: For key-to-id mapping and prefix searches

Permission System

ACLDB implements a hierarchical permission system with the following levels:

• Read: Allows reading data
• Write: Includes Read permission and allows writing data
• Delete: Includes Write permission and allows deleting data
• Execute: Includes Delete permission and allows executing operations
• Admin: Includes all permissions and allows managing ACLs

API Methods

The RPC API provides the following methods:

ACL Management

• aclupdate: Update or create an ACL with specified permissions
• aclremove: Remove specific public keys from an existing ACL
• acldel: Delete an entire ACL

Data Operations

• set: Store data with optional ACL protection
• get: Retrieve data with ACL verification
• del: Delete data with ACL verification
• prefix: Search for keys with a specific prefix

Usage Examples

Starting the Server

# Start the server on localhost:8080
cargo run

# Start the server on a specific host and port
cargo run -- 0.0.0.0 9000

API Documentation

Once the server is running, you can access the API documentation at:

http://localhost:8080/redoc

Using the API

Creating an ACL

{
  "method": "aclupdate",
  "params": {
    "caller_pubkey": "user_public_key",
    "circle_id": "my_circle",
    "name": "project_data",
    "pubkeys": ["user1_pubkey", "user2_pubkey"],
    "right": "write"
  },
  "signature": "signature_here"
}

Storing Data with ACL Protection

{
  "method": "set",
  "params": {
    "caller_pubkey": "user_public_key",
    "circle_id": "my_circle",
    "topic": "documents",
    "key": "doc1",
    "value": "base64_encoded_data",
    "acl_id": 1
  },
  "signature": "signature_here"
}

Retrieving Data

{
  "method": "get",
  "params": {
    "caller_pubkey": "user_public_key",
    "circle_id": "my_circle",
    "topic": "documents",
    "key": "doc1"
  },
  "signature": "signature_here"
}

Integration with Other Systems

ACLDB is designed to work seamlessly with other components of the HeroDB ecosystem. It can be used as:

1. A standalone database with access control
2. A backend for applications requiring fine-grained permissions
3. A component in a larger distributed system

Development

Prerequisites

• Rust 1.56 or later
• Cargo

Building

cargo build

Running Tests

cargo test