kms

Hanzo Base KMS Plugin

Zero-knowledge encrypted secret management for Hanzo Base with FHE query support.

What It Does

The KMS plugin adds transparent field-level encryption to any Base collection. Configured fields are encrypted before database writes and decrypted after reads, making encryption invisible to the application layer. FHE-encrypted indexes allow equality queries on encrypted data without decryption.

The plugin connects to the TFHE-KMS MPC cluster — a distributed key management system using Shamir secret sharing, HPKE key wrapping, and AES-256-GCM encryption. No single node ever holds the complete encryption key.

Quick Start

package main

import (
    "github.com/hanzoai/base"
    "github.com/hanzoai/base/plugins/kms"
)

func main() {
    app := base.New()

    kms.MustRegister(app, kms.Config{
        Nodes:     []string{"https://kms-mpc-0:9651", "https://kms-mpc-1:9651", "https://kms-mpc-2:9651"},
        OrgSlug:   "my-org",
        Threshold: 2,
        EncryptedCollections: map[string][]string{
            "credentials": {"api_key", "api_secret"},
            "tokens":      {"access_token", "refresh_token"},
        },
        FHESearchable: map[string][]string{
            "credentials": {"name"},
        },
    })

    app.Start()
}

Configuration

Encrypted Collections

Fields listed in EncryptedCollections are transparently encrypted with AES-256-GCM before storage. Each encrypted value is stored with the prefix enc:v1: followed by base64-encoded ciphertext.

Encryption uses Additional Authenticated Data (AAD) scoped to org:collection:record_id, preventing ciphertext from being transplanted between records.

EncryptedCollections: map[string][]string{
    "credentials": {"api_key", "api_secret"},
    "wallets":     {"private_key", "mnemonic"},
}

FHE Search

Fields listed in FHESearchable maintain a deterministic HMAC-SHA256 index in a synthetic _fhe_{field} column. This allows equality queries without decrypting the underlying data.

Index derivation:

field_key = HMAC-SHA256(CEK, org_slug + ":" + collection + ":" + field)
index     = HMAC-SHA256(field_key, plaintext_value)

FHE fields must also appear in EncryptedCollections.

// Query encrypted data by name without decrypting:
p := app.Store().Get("kms").(*kms.Plugin)
token, _ := p.ComputeSearchToken("credentials", "name", "my-api-key")
records, _ := app.FindAll("credentials", "_fhe_name = ?", token)

Compliance Modes

The MPC cluster supports regulatory compliance enforcement. When enabled, all secret access is logged to a WORM (Write Once Read Many) hash-chained audit trail.

Compliance is configured on the MPC node, not the Base plugin. The plugin inherits the compliance posture of its connected cluster.

API Endpoints

All endpoints require superuser authentication.

Enterprise Features

Enterprise features are configured on the MPC node (EnterpriseConfig):

• Multi-region replication — Configure primary/replica regions for geographic redundancy
• Key rotation policy — Automatic CEK rotation with configurable interval and advance notification
• IP allow-lists — Restrict access by CIDR range
• MFA enforcement — Require MFA for secret access
• Session timeout — Auto-lock CEK after inactivity
• Audit sinks — Fan-out WORM audit entries to GCP Cloud Logging, AWS CloudWatch, Azure Monitor, S3, GCS, or custom webhooks
• HSM integration — AWS CloudHSM, PKCS#11, YubiHSM for root key protection
• KMIP — Key Management Interoperability Protocol for enterprise key lifecycle

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Application (Hanzo Base)                                     │
│  ┌─────────────────────┐                                      │
│  │  KMS Plugin          │                                     │
│  │  • encrypt/decrypt   │  REST API (/api/kms/*)              │
│  │  • FHE index         │                                     │
│  │  • record hooks      │                                     │
│  └────────┬────────────┘                                      │
└───────────┼──────────────────────────────────────────────────┘
            │ gRPC (TLS + HPKE)
            ▼
┌───────────────────────────────────────────────────────────────┐
│  TFHE-KMS MPC Cluster (t-of-n Shamir)                           │
│                                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                    │
│  │ MPC Node │  │ MPC Node │  │ MPC Node │  ...               │
│  │  ZapDB   │  │  ZapDB   │  │  ZapDB   │                    │
│  │  Shard   │  │  Shard   │  │  Shard   │                    │
│  └──────────┘  └──────────┘  └──────────┘                    │
│       │              │              │                          │
│       └──────────────┼──────────────┘                         │
│              FHE CRDT Sync                                    │
│                                                               │
│  Compliance: WORM Audit │ Escrow │ Break-Glass │ Retention    │
│  Enterprise: HSM │ KMIP │ Audit Sinks │ Multi-Region          │
└───────────────────────────────────────────────────────────────┘

Chain-Agnostic Design

The KMS is chain-agnostic. Any application — Lux L1/L2, exchange platforms, or standard web services — connects via the standard gRPC/REST API. There is no chain-specific configuration.

Use cases across different deployments:

• Blockchain nodes: validator keys, staking credentials
• Exchange platforms: wallet keys, API keys, trading credentials, compliance records
• Web applications: API secrets, database credentials, encryption keys
• Compliance-regulated services: ATS/BD/TA records, PHI, financial controls