Openshart

Name: Openshart
Rating: 3.5 (1 reviews)
Author: bcharleson

By bcharleson ⭐ 10 stars 👁 23 views ▲ 0 votes

OpenShart — encrypted AI agent memory with OpenClaw plugin support for secure memory_search/get/store/forget workflows.

Homepage GitHub

Install

npm install openshart

README

<p align="center">
  <h1 align="center">💩 OpenShart</h1>
  <p align="center"><strong>Enterprise-Grade Encrypted Memory for AI Agents</strong></p>
  <p align="center"><em>If your agent memory leaks, you're going to OpenShart yourself.</em></p>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.x-blue" alt="TypeScript"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-20%2B-green" alt="Node.js"></a>
  <a href="https://csrc.nist.gov/publications/detail/fips/140/2/final"><img src="https://img.shields.io/badge/FIPS_140--2-Algorithms_Used-yellowgreen" alt="FIPS Algorithms"></a>
  <a href="https://www.aicpa-cima.com/topic/audit-assurance/audit-and-assurance-greater-than-soc-2"><img src="https://img.shields.io/badge/SOC2-Designed_For-blue" alt="SOC2"></a>
  <a href="https://www.hhs.gov/hipaa"><img src="https://img.shields.io/badge/HIPAA-Designed_For-blue" alt="HIPAA"></a>
  <img src="https://img.shields.io/badge/Bell--LaPadula-Implemented-red" alt="Bell-LaPadula">
  <img src="https://img.shields.io/badge/64_Tests-Passing-brightgreen" alt="Tests Passing">
  <img src="https://img.shields.io/badge/💩-Enterprise_Grade-gold" alt="Enterprise Grade">
</p>

---

## What is OpenShart?

**OpenShart** is a zero-dependency encrypted memory framework for AI agents. It fragments, encrypts, and distributes agent context using Shamir's Secret Sharing, AES-256-GCM, and HMAC-based searchable encryption — with enterprise hierarchical access control, government classification levels, and **ChainLock** temporal sequence locks.

No single storage location holds a complete memory. No database breach reveals usable data. No admin can read agent context without the agent's key.

The name is intentional. The security is not a joke.

## Key Features

- 🔐 **AES-256-GCM** authenticated encryption with per-fragment derived keys
- 🧩 **Shamir's Secret Sharing** — K-of-N threshold reconstruction
- 🔍 **Searchable encryption** — HMAC-SHA256 tokens, zero content exposure during search
- 🏛️ **Government classification** — UNCLASSIFIED → CUI → CONFIDENTIAL → SECRET → TOP SECRET → TS/SCI
- ⛓️ **ChainLock** — temporal sequence locks with breach detection
- 🛡️ **Bell-LaPadula MAC** — mandatory access control (no read up, no write down)
- 🏢 **Enterprise RBAC** — role hierarchy, department isolation, delegated keys
- 📋 **Tamper-evident audit** — SHA-256 hash chain, compliance export
- 🗑️ **GDPR Article 17** — DoD 5220.22-M 3-pass cryptographic erasure
- 🔑 **FIPS-ready** — approved algorithms, key entropy validation, self-tests
- 🏥 **HIPAA PHI detection** — Safe Harbor patterns, minimum necessary enforcement
- 📦 **Zero runtime dependencies** — Node.js `crypto` only

## Security Presets

| Preset | What You Get |
|--------|-------------|
| **`standard`** | AES-256-GCM, Shamir fragmentation, PII detection, audit log |
| **`enterprise`** | + RBAC, department isolation, key rotation, SOC2 controls |
| **`government`** | + ChainLock, FIPS mode, classification levels, Bell-LaPadula, compartments |
| **`classified`** | + TS/SCI compartments, increased fragmentation (5-of-8), Bell-LaPadula strict enforcement |

## Quick Start

```bash
npm install openshart
```

```typescript
import { OpenShart, MemoryBackend, Classification } from 'openshart';
import { randomBytes } from 'node:crypto';

const shart = await OpenShart.init({
  storage: new MemoryBackend(),
  encryptionKey: randomBytes(32),
  securityLevel: 'government',
});

// Store — PII auto-detected, fragmented, encrypted, ChainLock-secured
const { id } = await shart.store(
  "Patient John Doe, SSN 123-45-6789, diagnosed with hypertension",
  {
    classification: Classification.SECRET,
    compartments: ['MEDICAL'],
    tags: ['patient', 'diagnosis'],
  }
);

// Search — HMAC tokens only, content never decrypted
const results = await shart.search('patient diagnosis');

// Recall — ChainLock sequence enforced, access control verified
const memory = await shart.recall(id);
console.log(memory.content);

// Forget — DoD 5220.22-M 3-pass overwrite + cryptographic erasure
await shart.forget(id);

await shart.close();
```

## ⛓️ ChainLock — Temporal Sequence Lock

ChainLock is OpenShart's composite security layer for high-security recall operations. Fragments must be decrypted in a cryptographically random sequence, within strict time windows, with HMAC chain tokens linking each step. It combines known techniques (hash chains, temporal windows, breach detection) into a defense-in-depth layer over the core Shamir + AES-GCM pipeline.

```
Recall Request
     │
     ▼
┌──────────────────────────────┐
│  1. Generate session nonce    │
│  2. Decrypt sequence order    │
│  3. Start temporal clock      │
└──────────────┬───────────────┘
               │
     ┌─────────▼─────────┐
     │  Step 1 (≤2000ms)  │──→ chain_token_1
     └─────────┬─────────┘
               │
     ┌─────────▼─────────┐
     │  Step 2 (≤2000ms)  │──→ chain_token_2
     └─────────┬─────────┘
               │
     ┌─────────▼─────────┐
     │  Step N (≤2000ms)  │──→ chain_token_N
     └─────────┬─────────┘
               │
     ┌─────────▼─────────┐
     │  ✅ Reconstruct     │
     │  🔄 Rotate sequence │
     │  🧹 Wipe ephemeral  │
     └───────────────────┘
```

**Why it matters:**
- Stolen fragments are already **useless** without the master key (AES-256-GCM). ChainLock adds **API-level friction** against automated extraction by anyone with key access
- Automated attacks **detected** via timing analysis (uniform step durations = bot)
- Replay attacks **prevented** — sequence rotates after every successful recall
- Breach lockdown — configurable failure threshold triggers account lockdown

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     AGENT APPLICATION                        │
│           (OpenClaw, LangChain, CrewAI, custom)              │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                      OPENSHART SDK                           │
│                                                              │
│  ┌─────────┐ ┌────────┐ ┌────────┐ ┌────────┐              │
│  │  STORE  │ │ SEARCH │ │ RECALL │ │ FORGET │              │
│  └────┬────┘ └───┬────┘ └───┬────┘ └───┬────┘              │
│       │          │          │          │                     │
│  ┌────▼──────────▼──────────▼──────────▼──────────────────┐ │
│  │  ACCESS CONTROL · BELL-LAPADULA · CLASSIFICATION       │ │
│  │  FIPS Crypto · Key Rotation · Need-to-Know             │ │
│  └──────────────────────────┬─────────────────────────────┘ │
│                             │                                │
│  ┌──────────────────────────▼─────────────────────────────┐ │
│  │          PII DETECTION + AUTO-CLASSIFICATION            │ │
│  └──────────────────────────┬─────────────────────────────┘ │
│                             │                                │
│  ┌──────────────────────────▼─────────────────────────────┐ │
│  │          FRAGMENT ENGINE (Shamir SSS) + CHAINLOCK       │ │
│  │       K-of-N shares → AES-256-GCM → Temporal Lock      │ │
│  └──────────────────────────┬─────────────────────────────┘ │
│                             │                                │
│  ┌──────────────┐ ┌────────▼──────┐ ┌──────────────────┐   │
│  │ SEARCH INDEX │ │  AUDIT LOG    │ │ KEY MANAGEMENT   │   │
│  │(HMAC-SHA256) │ │ (hash chain)  │ │(HSM · rotation)  │   │
│  └──────┬───────┘ └──────┬────────┘ └──────┬───────────┘   │
└─────────┼────────────────┼─────────────────┼────────────────┘
          ▼                ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                    STORAGE BACKEND                           │
│  ┌──────────┐  ┌────────────┐  ┌──────────┐                │
│  │  SQLite  │  │ PostgreSQL │  │  Memory  │                │
│  └──────────┘  └────────────┘  └──────────┘                │
└─────────────────────────────────────────────────────────────┘
```

## Government Classification

OpenShart supports the full US government classification hierarchy with policy-level enforcement (Bell-LaPadula MAC). Note: this provides application-level access control, not cryptographically-bound compartmentalization. Formal government certification (FedRAMP, Common Criteria) requires third-party assessment beyond this library.

```typescript
import { Classification, checkClassifiedAccess } from 'openshart';

// Classification levels:
// UNCLASSIFIED → CUI → CONFIDENTIAL → SECRET → TOP_SECRET → TS_SCI

// SCI Compartments: GAMMA, HCS, SI, TK
// Dissemination controls: NOFORN, ORCON, REL TO

// Bell-LaPadula enforced at the cryptographic level:
// - No Read Up: agents cannot read above their clearance
// - No Write Down: agents cannot write below their clearance
```

| Classification | Clearance Required | Fragmentation | ChainLock |
|---------------|-------------------|---------------|-----------|
| UNCLASSIFIED | None | 2-of-3 | Off |
| CUI | CONTRIBUTOR+ | 3-of-5 | Off |
| CONFIDENTIAL | MANAGER+ | 3-of-5 | Off |
| SECRET | DIRECTOR+ | 5-of-8 | ✅ |
| TOP SECRET | EXECUTIVE | 5-of-8 | ✅ |
| TS/SCI | EXECUTIVE + compartment | 5-of-8 | ✅ + TPI |

## Enterprise Hierarchy

```typescript
import { OpenShart, ContextFlowManager, DepartmentManager, Role } from 'openshart';

const departments = new DepartmentManager();
departments.registerDepartment({
  id: 'engineering',
  name: 'Engineering',
  encryptionNamespace: 'eng-ns-2026',
});

const flow = new ContextFlowManager(departments);

// Context flows DOWN with automatic PII redaction
const pushed = flow.pushDown(
  'Q3 target: $2M ARR. Contact [email protected] for details.',
  Role.EXE

... (truncated)

tools