guava-suite

适用于 AI 代理的高级安全套件。 在防护扫描器之上添加 $GUAVA 令牌门控严格模式保护。 特点：2层防御（静态+运行时）、灵魂锁、内存卫士、 通过 SoulRegistry V2 进行链上身份验证。 在 Polygon 主网上需要 $GUAVA 代币。

# GuavaSuite 🍈

Premium 2-layer security for AI agents — powered by **$GUAVA** token gating.

## What It Does

GuavaSuite upgrades your guard-scanner from `enforce` (CRITICAL-only) to `strict` mode
(HIGH + CRITICAL blocking), plus adds these exclusive features:

| Feature | Free (guard-scanner) | Suite ($GUAVA) |
|---------|---------------------|----------------|
| Static Scan (129 patterns, 21 categories) | ✅ | ✅ |
| Runtime Guard (enforce) | ✅ | ✅ |
| **Runtime Guard (strict)** | ❌ | ✅ |
| **Soul Lock** (SOUL.md integrity + auto-rollback) | ❌ | ✅ |
| **Memory Guard** (L1-L5 記憶システム保護) | ❌ | ✅ |
| **Zettel Memory** (原子的ノート+リンク+検索) | ❌ | ✅ |
| **On-chain Identity** (SoulRegistry V2) | ❌ | ✅ |
| Audit Log (JSONL) | ✅ | ✅ |

## Prerequisites

1. **guard-scanner** installed (`clawhub install guard-scanner`)
2. **$GUAVA tokens** on Polygon Mainnet (minimum 1M $GUAVA)
   - Token: `0x25cBD481901990bF0ed2ff9c5F3C0d4f743AC7B8`
   - Buy on [QuickSwap V2](https://quickswap.exchange/#/swap)

### How to Get $GUAVA

| Method | How |
|--------|-----|
| **超越者プラン** (note.com membership) | 手動送金 — MetaMaskでウォレットに直接送付 |
| **自分で購入** | QuickSwap V2 で MATIC → $GUAVA swap |

> **セキュリティ方針**: $GUAVAの配布はすべてMetaMaskからの手動送金で行います。秘密鍵をスクリプトに渡すことは一切しません。

## Quick Start

### 1. Install

```bash
# Via clawhub (coming soon)
clawhub install guava-suite

# Or: git clone + setup
git clone https://github.com/koatora20/guava-suite.git
cd guava-suite && bash setup.sh
```

### 2. Activate

```bash
node services/license-api/src/activate.js --wallet 0xYOUR_WALLET_ADDRESS
```

This single command will:
1. Request a challenge nonce
2. Prompt you to sign with your wallet (EIP-712)
3. Verify your signature & check $GUAVA balance on Polygon
4. Save JWT locally & switch guard-scanner to `strict` mode

### 3. Check Status

```bash
node services/license-api/src/activate.js --status
```

### Deactivate

```bash
node services/license-api/src/activate.js --deactivate
```

## How Token Gating Works

```
   You hold $GUAVA on Polygon
           │
           ▼
   Sign EIP-712 challenge
           │
           ▼
   LicenseService checks:
   ├─ Signature valid?
   ├─ $GUAVA balance ≥ 1M?
   │
   ▼
   JWT issued → SuiteGate activated
           │
           ▼
   guard-scanner mode: strict
   (HIGH + CRITICAL blocked)
```

## Architecture

- **SuiteGate** — JWT-based fail-closed gate (grace period for network issues)
- **LicenseService** — Nonce + EIP-712 signature + $GUAVA balance check + JWT issuance
- **TokenBalanceChecker** — Polygon RPC ERC-20 balance verification (zero dependencies)
- **SuiteBridge** — Connects SuiteGate status to guard-scanner runtime mode
- **SoulRegistry V2** — On-chain identity verification (Polygon)

## External Endpoints

| URL | Data Sent | Purpose |
|-----|-----------|---------|
| `polygon-rpc.com` | Wallet address | $GUAVA balance check (read-only `eth_call`) |

## Security & Privacy

- **Read-only on-chain**: Only calls `balanceOf` — no transactions, no approvals
- **Local JWT**: Tokens stored locally, never sent to external servers
- **Fail-closed**: If balance check fails, Suite features are disabled (not bypassed)
- **No telemetry**: Zero analytics or tracking

## License

Proprietary — © 2026 Guava 🍈 & Dee

---

## 中文说明

# GuavaSuite 🍈

为 AI 代理提供的高级双层安全方案 —— 由 **$GUAVA** 代币门控驱动。

## 功能简介

GuavaSuite 将你的 guard-scanner 从 `enforce` 模式（仅拦截 CRITICAL）升级为 `strict` 模式
（拦截 HIGH + CRITICAL），并额外提供以下专属特性：

| 特性 | 免费版 (guard-scanner) | 套件版 ($GUAVA) |
|---------|---------------------|----------------|
| 静态扫描（129 个模式，21 个类别） | ✅ | ✅ |
| 运行时防护 (enforce) | ✅ | ✅ |
| **运行时防护 (strict)** | ❌ | ✅ |
| **灵魂锁**（SOUL.md 完整性校验 + 自动回滚） | ❌ | ✅ |
| **内存卫士**（L1-L5 记忆系统保护） | ❌ | ✅ |
| **Zettel 记忆**（原子化笔记 + 链接 + 检索） | ❌ | ✅ |
| **链上身份**（SoulRegistry V2） | ❌ | ✅ |
| 审计日志 (JSONL) | ✅ | ✅ |

## 前置条件

1. 已安装 **guard-scanner**（`clawhub install guard-scanner`）
2. 在 Polygon 主网上持有 **$GUAVA 代币**（至少 1M $GUAVA）
   - 代币：`0x25cBD481901990bF0ed2ff9c5F3C0d4f743AC7B8`
   - 在 [QuickSwap V2](https://quickswap.exchange/#/swap) 购买

### 如何获取 $GUAVA

| 方式 | 说明 |
|--------|-----|
| **超越者计划**（note.com 会员） | 手动转账 —— 通过 MetaMask 直接发送至钱包 |
| **自行购买** | 在 QuickSwap V2 上将 MATIC → $GUAVA 兑换 |

> **安全方针**：$GUAVA 的分发全部通过 MetaMask 手动转账完成。绝不会将私钥传递给任何脚本。

## 快速开始

### 1. 安装

```bash
# Via clawhub (coming soon)
clawhub install guava-suite

# Or: git clone + setup
git clone https://github.com/koatora20/guava-suite.git
cd guava-suite && bash setup.sh
```

### 2. 激活

```bash
node services/license-api/src/activate.js --wallet 0xYOUR_WALLET_ADDRESS
```

这一条命令将会：
1. 请求一个挑战 nonce
2. 提示你用钱包签名（EIP-712）
3. 验证你的签名并在 Polygon 上检查 $GUAVA 余额
4. 在本地保存 JWT 并将 guard-scanner 切换为 `strict` 模式

### 3. 查看状态

```bash
node services/license-api/src/activate.js --status
```

### 停用

```bash
node services/license-api/src/activate.js --deactivate
```

## 代币门控的工作原理

```
   You hold $GUAVA on Polygon
           │
           ▼
   Sign EIP-712 challenge
           │
           ▼
   LicenseService checks:
   ├─ Signature valid?
   ├─ $GUAVA balance ≥ 1M?
   │
   ▼
   JWT issued → SuiteGate activated
           │
           ▼
   guard-scanner mode: strict
   (HIGH + CRITICAL blocked)
```

## 架构

- **SuiteGate** —— 基于 JWT 的故障关闭门控（网络问题时有宽限期）
- **LicenseService** —— Nonce + EIP-712 签名 + $GUAVA 余额检查 + JWT 签发
- **TokenBalanceChecker** —— Polygon RPC ERC-20 余额验证（零依赖）
- **SuiteBridge** —— 将 SuiteGate 状态连接到 guard-scanner 运行时模式
- **SoulRegistry V2** —— 链上身份验证（Polygon）

## 外部端点

| URL | 发送的数据 | 用途 |
|-----|-----------|---------|
| `polygon-rpc.com` | 钱包地址 | $GUAVA 余额检查（只读 `eth_call`） |

## 安全与隐私

- **链上只读**：仅调用 `balanceOf` —— 无交易、无授权
- **本地 JWT**：令牌存储在本地，绝不发送到外部服务器
- **故障关闭**：若余额检查失败，套件功能将被禁用（而非被绕过）
- **无遥测**：零分析、零追踪

## 许可证

专有 —— © 2026 Guava 🍈 & Dee