docs: enrich thin KMS and netrunner pages with source content

2026-09-24 00:25:32 +00:00 · 2026-03-22 19:05:24 -07:00
parent 03e5669a68
commit bc28d8cbda
14 changed files with 987 additions and 82 deletions
@@ -4,12 +4,73 @@ description: Ephemeral database credentials
 icon: Timer
 ---

-Dynamic secrets are short-lived credentials generated on demand. They are automatically revoked after their TTL expires.
+Dynamic secrets are short-lived credentials generated on demand. They are automatically revoked after their TTL expires, eliminating the risk of credential sprawl.

 ## Supported Backends

-| Backend | Description |
-|---------|-------------|
-| PostgreSQL | Dynamic database users with configurable roles |
-| MySQL | Ephemeral credentials with automatic cleanup |
-| MongoDB | Scoped database access with TTL |
+| Backend | Description | Min TTL | Max TTL |
+|---------|-------------|---------|---------|
+| PostgreSQL | Dynamic database users with configurable roles | 1m | 24h |
+| MySQL | Ephemeral credentials with automatic cleanup | 1m | 24h |
+| MongoDB | Scoped database access with TTL | 1m | 24h |
+| RabbitMQ | Dynamic vhost permissions | 1m | 12h |
+
+## How It Works
+
+1. Application requests credentials from KMS
+2. KMS creates a temporary database user with scoped permissions
+3. Application uses the credentials for the TTL duration
+4. KMS automatically revokes the user when TTL expires
+
+## PostgreSQL Example
+
+### Configure the Backend
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/dynamic-secrets/postgres \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "name": "app-db",
+    "host": "db.internal",
+    "port": 5432,
+    "database": "myapp",
+    "adminUser": "kms_admin",
+    "adminPassword": "<from-kms>",
+    "defaultTTL": "1h",
+    "maxTTL": "24h",
+    "creationStatement": "CREATE ROLE \"{{username}}\" WITH LOGIN PASSWORD '\''{{password}}'\'' VALID UNTIL '\''{{expiration}}'\''; GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO \"{{username}}\";"
+  }'
+```
+
+### Request Credentials
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/dynamic-secrets/postgres/app-db/lease \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{"ttl": "2h"}'
+```
+
+Response:
+
+```json
+{
+  "leaseId": "lease-abc123",
+  "username": "kms_dyn_abc123",
+  "password": "randomSecurePassword",
+  "expiresAt": "2026-03-22T14:00:00Z"
+}
+```
+
+### Revoke Early
+
+```bash
+curl -X DELETE https://kms.lux.network/api/v1/dynamic-secrets/leases/lease-abc123 \
+  -H "Authorization: Bearer $KMS_TOKEN"
+```
+
+## Benefits
+
+- No long-lived database passwords
+- Automatic cleanup of unused credentials
+- Each application instance gets unique credentials
+- Full audit trail of credential usage
@@ -4,14 +4,84 @@ description: Encrypt and decrypt data without managing keys
 icon: Shield
 ---

-The transit encryption engine provides encryption-as-a-service. Data is encrypted/decrypted via API without exposing keys.
+The transit encryption engine provides encryption-as-a-service. Applications encrypt and decrypt data via API without ever seeing the underlying keys.

 ## Algorithms

 | Algorithm | Key Size | Use Case |
 |-----------|----------|----------|
-| AES-256-GCM | 256-bit | General purpose |
-| ChaCha20-Poly1305 | 256-bit | High-performance |
-| RSA-OAEP | 2048/4096 | Key wrapping |
-| ECDSA P-256 | 256-bit | Signing |
-| HMAC-SHA256 | 256-bit | Authentication |
+| AES-256-GCM | 256-bit | General purpose, authenticated encryption |
+| ChaCha20-Poly1305 | 256-bit | High-performance, mobile/embedded |
+| RSA-OAEP | 2048/4096 | Asymmetric encryption, key wrapping |
+| ECDSA P-256 | 256-bit | Digital signatures |
+| HMAC-SHA256 | 256-bit | Message authentication codes |
+
+## Encrypt Data
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/kms/keys/my-key/encrypt \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "plaintext": "aGVsbG8gd29ybGQ="
+  }'
+```
+
+Response:
+
+```json
+{
+  "ciphertext": "vault:v1:AbCdEf...",
+  "keyVersion": 3
+}
+```
+
+## Decrypt Data
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/kms/keys/my-key/decrypt \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "ciphertext": "vault:v1:AbCdEf..."
+  }'
+```
+
+## Sign Data
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/kms/keys/signing-key/sign \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "input": "aGVsbG8=",
+    "algorithm": "ecdsa-p256-sha256"
+  }'
+```
+
+## Key Rotation
+
+Transit keys support automatic versioning. When a key is rotated:
+
+- New data is encrypted with the latest version
+- Old ciphertext can still be decrypted
+- Rewrap API upgrades ciphertext to the latest key version without exposing plaintext
+
+```bash
+# Rotate key
+curl -X POST https://kms.lux.network/api/v1/kms/keys/my-key/rotate \
+  -H "Authorization: Bearer $KMS_TOKEN"
+
+# Rewrap old ciphertext with new key version
+curl -X POST https://kms.lux.network/api/v1/kms/keys/my-key/rewrap \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{"ciphertext": "vault:v1:AbCdEf..."}'
+```
+
+## Data Encryption Keys (DEK)
+
+Generate a data encryption key for client-side encryption:
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/kms/keys/my-key/generate-data-key \
+  -H "Authorization: Bearer $KMS_TOKEN"
+```
+
+Returns both plaintext and wrapped versions of the DEK. Store the wrapped version; use plaintext for encryption, then discard it.
@@ -4,11 +4,68 @@ description: Hardware security module backends
 icon: Cpu
 ---

+Lux KMS supports Hardware Security Modules (HSMs) for root key protection. The root key encrypts all organization and project KEKs, ensuring that key material is hardware-bound.
+
 ## Supported HSMs

-| HSM | Interface | Use Case |
-|-----|-----------|----------|
-| Zymbit SCM | PKCS#11 | Edge/IoT |
-| AWS CloudHSM | PKCS#11 | Cloud production |
-| Google Cloud HSM | Cloud KMS | Cloud production |
-| Azure Managed HSM | REST API | Cloud production |
+| HSM | Interface | Use Case | Status |
+|-----|-----------|----------|--------|
+| Zymbit SCM | PKCS#11 | Edge/IoT devices | Supported |
+| AWS CloudHSM | PKCS#11 | AWS cloud production | Supported |
+| Google Cloud HSM | Cloud KMS API | GCP production | Supported |
+| Azure Managed HSM | REST API | Azure production | Supported |
+| SoftHSM | PKCS#11 | Development/testing | Supported |
+
+## Architecture
+
+```
+Application
+  -> KMS API
+    -> Organization KEK (encrypted by Root Key)
+      -> Project KEK (encrypted by Org KEK)
+        -> Data Keys (encrypted by Project KEK)
+          -> Encrypted Secrets
+
+Root Key is stored in HSM -- never leaves hardware
+```
+
+## Configuration
+
+```bash
+# Environment variables for HSM
+HSM_ENABLED=true
+HSM_TYPE=pkcs11
+HSM_LIBRARY_PATH=/usr/lib/softhsm/libsofthsm2.so
+HSM_SLOT=0
+HSM_PIN=1234
+```
+
+## AWS CloudHSM Setup
+
+```bash
+# Configure AWS CloudHSM
+AWS_HSM_CLUSTER_ID=cluster-abc123
+AWS_HSM_IP=10.0.0.100
+AWS_HSM_USER=kms-user
+AWS_HSM_PASSWORD=<from-kms>
+```
+
+## PKCS#11 Operations
+
+KMS uses PKCS#11 for:
+
+| Operation | Description |
+|-----------|-------------|
+| Key wrapping | Wrap organization KEKs with root key |
+| Key unwrapping | Unwrap KEKs for secret access |
+| Signing | Sign audit log entries |
+| Random generation | Cryptographically secure random bytes |
+
+## Session Management
+
+HSM sessions are pooled for performance:
+
+- Connection pool size: configurable (default 5)
+- Session timeout: 30 minutes
+- Automatic reconnection on failure
+- Health checks every 60 seconds
@@ -4,11 +4,62 @@ description: Threshold key management for MPC nodes
 icon: Users
 ---

-KMS provides key share storage and backup for MPC nodes.
+KMS provides key share storage, backup, and password management for MPC nodes. Each MPC node's ZapDB encryption password is derived from KMS -- never stored in plaintext.

-## Key Share Backup
+## Key Share Backup Flow

-1. Key shares exported from ZapDB
-2. Encrypted with scrypt + AES-256-GCM using KMS-derived backup key
-3. Stored to S3 with org-prefixed paths
-4. Can be restored to a new node
+1. Key shares are exported from ZapDB (encrypted at rest with ChaCha20-Poly1305)
+2. Backup is encrypted with scrypt + AES-256-GCM using a KMS-derived backup key
+3. Encrypted backup is stored to S3 with org-prefixed paths
+4. Backup can be restored to a new node with the same KMS-derived key
+
+## ZapDB Password Management
+
+MPC nodes use `--hsm-provider` to resolve their ZapDB encryption password:
+
+| Provider | Source | Use Case |
+|----------|--------|----------|
+| `env` | `MPC_DB_PASSWORD` env var | Development, backward compat |
+| `file` | Password file on disk | Container deployments |
+| `aws` | AWS KMS decrypt | AWS production |
+| `gcp` | GCP KMS decrypt | GCP production |
+| `azure` | Azure Key Vault | Azure production |
+
+## Backup Configuration
+
+```yaml
+backup:
+  provider: s3
+  bucket: lux-mpc-backups
+  prefix: "org-123/"
+  encryption:
+    kms_key_id: "arn:aws:kms:us-east-1:..."
+  schedule: "0 */6 * * *"  # Every 6 hours
+```
+
+## Restore Process
+
+```bash
+# List available backups
+lux mpc backup list --org org-123
+
+# Restore to a new node
+lux mpc backup restore \
+  --backup-id backup-2026-03-01 \
+  --data-dir /data/mpc/node0 \
+  --kms-key-id arn:aws:kms:...
+```
+
+## Multi-Tenant Key Isolation
+
+Each organization's MPC key shares are encrypted with a unique KMS-derived key. Even if the S3 bucket is shared, cross-org access is cryptographically prevented.
+
+## Audit Trail
+
+All backup and restore operations are logged in KMS audit:
+
+| Event | Data Logged |
+|-------|------------|
+| `mpc.backup.create` | Node ID, backup size, timestamp |
+| `mpc.backup.restore` | Node ID, backup source, timestamp |
+| `mpc.password.access` | Node ID, provider type, timestamp |
@@ -1,16 +1,88 @@
 ---
 title: PKI / Certificates
-description: X.509 certificate authority
+description: X.509 certificate authority and management
 icon: FileCheck
 ---

+Lux KMS includes a full Public Key Infrastructure (PKI) for issuing, managing, and revoking X.509 certificates.
+
 ## Certificate Lifecycle

-1. **Create CA** — Root or intermediate certificate authority
-2. **Issue Certificates** — Sign CSRs with configurable profiles
-3. **Revoke** — CRL and OCSP support
-4. **Renew** — Automatic renewal before expiry
+1. **Create CA** -- Root or intermediate certificate authority
+2. **Configure Templates** -- Define certificate profiles for policy enforcement
+3. **Issue Certificates** -- Sign Certificate Signing Requests (CSRs)
+4. **Monitor** -- Track expiration with alerting
+5. **Revoke** -- CRL and OCSP support
+6. **Renew** -- Automatic renewal before expiry
+
+## Create a Certificate Authority
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/pki/ca \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "commonName": "Lux Internal CA",
+    "organization": "Lux Network",
+    "keyAlgorithm": "EC-P256",
+    "validityDays": 3650,
+    "type": "root"
+  }'
+```
+
+## Issue a Certificate
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/pki/certificates \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "caId": "ca-abc123",
+    "commonName": "api.internal.lux.network",
+    "sans": ["api.internal", "10.0.1.50"],
+    "validityDays": 365,
+    "template": "server-tls"
+  }'
+```
+
+## Certificate Templates
+
+| Template | Key Usage | Extended Key Usage |
+|----------|-----------|-------------------|
+| `server-tls` | Digital Signature, Key Encipherment | Server Auth |
+| `client-tls` | Digital Signature | Client Auth |
+| `code-signing` | Digital Signature | Code Signing |
+| `email` | Digital Signature, Key Encipherment | Email Protection |

 ## EST Protocol

-Full EST (RFC 7030) support for automated certificate enrollment.
+Full EST (RFC 7030) support for automated certificate enrollment:
+
+```bash
+# Simple enrollment
+curl https://kms.lux.network/.well-known/est/simpleenroll \
+  --cert client.pem --key client-key.pem \
+  -d @csr.pem -H "Content-Type: application/pkcs10"
+```
+
+## Kubernetes PKI Issuer
+
+The KMS PKI Issuer integrates with cert-manager for automatic TLS certificate provisioning:
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: lux-kms-issuer
+spec:
+  external:
+    endpoint: https://kms.lux.network/api/v1/pki
+```
+
+## Alerting
+
+Configure alerts for expiring certificates:
+
+| Alert | Trigger | Channel |
+|-------|---------|---------|
+| CA expiry warning | 90 days before | Email, Slack |
+| Certificate expiry | 30 days before | Email, Slack |
+| Certificate revoked | Immediately | Email, Slack, PagerDuty |
@@ -4,10 +4,79 @@ description: Store, version, and rotate secrets
 icon: Lock
 ---

+Lux KMS provides centralized secret management with automatic versioning, rotation, and audit logging. Secrets are encrypted at rest with organization-level Key Encryption Keys (KEKs).
+
 ## Features

- **Versioning** — Every secret change creates a new version
- **Rotation** — Automatic rotation with configurable intervals
- **Folders** — Organize secrets in a hierarchical structure
- **Tags** — Label and filter secrets
- **Audit** — Full audit log of all secret access
+- **Versioning** -- Every secret change creates a new version with rollback support
+- **Rotation** -- Automatic rotation with configurable intervals per secret
+- **Folders** -- Organize secrets in a hierarchical folder structure
+- **Tags** -- Label and filter secrets for access control
+- **Audit** -- Full audit log of all secret access and modifications
+- **Point-in-Time Recovery** -- Restore entire project state to any previous point
+
+## Create a Secret
+
+```bash
+curl -X POST https://kms.lux.network/api/v1/secrets \
+  -H "Authorization: Bearer $KMS_TOKEN" \
+  -d '{
+    "secretName": "db-password",
+    "secretValue": "s3cureP@ss",
+    "environment": "production",
+    "type": "shared"
+  }'
+```
+
+## Environment Scoping
+
+Secrets are scoped per environment. Each environment maintains its own values:
+
+| Environment | Description |
+|-------------|-------------|
+| `development` | Local development values |
+| `staging` | Pre-production testing |
+| `production` | Live production secrets |
+
+## Secret Rotation
+
+Configure automatic rotation for database credentials:
+
+```json
+{
+  "secretName": "postgres-password",
+  "rotationInterval": "30d",
+  "rotationProvider": "postgresql",
+  "rotationConfig": {
+    "host": "db.internal",
+    "port": 5432,
+    "database": "myapp"
+  }
+}
+```
+
+## Kubernetes Integration
+
+The KMS Kubernetes operator syncs secrets to K8s:
+
+```yaml
+apiVersion: secrets.lux.network/v1alpha1
+kind: KMSSecret
+metadata:
+  name: app-secrets
+spec:
+  secretsPath: /myproject/production
+  managedSecretReference:
+    secretName: app-secrets
+    secretNamespace: default
+```
+
+## Native Integrations
+
+| Platform | Sync Method |
+|----------|-------------|
+| Kubernetes | KMS Operator (CRD) |
+| GitHub Actions | Native integration |
+| Vercel | Automatic sync |
+| AWS | Secrets Manager sync |
+| Terraform | Provider plugin |
@@ -4,11 +4,71 @@ description: Security best practices and audit logging
 icon: ShieldAlert
 ---

+Security is the foundation of KMS. Every operation is authenticated, authorized, and audited.
+
 ## Rules

-1. **ALL passwords MUST come from KMS** — Never plaintext
-2. **Rotate keys regularly** via KMS key rotation
-3. **Audit all access** via KMS audit logs
-4. **Use the K8s operator** for automated secret sync
-5. **Enable MFA** for administrative access
-6. **IP allowlisting** for production environments
+1. **ALL passwords MUST come from KMS** -- Never store plaintext passwords anywhere
+2. **Rotate keys regularly** -- Use KMS automatic key rotation
+3. **Audit all access** -- KMS logs every read, write, and admin operation
+4. **Use the K8s operator** -- Automated secret sync to Kubernetes
+5. **Enable MFA** -- Required for administrative access
+6. **IP allowlisting** -- Restrict production access by source IP
+
+## Encryption Hierarchy
+
+| Layer | Algorithm | Protected By |
+|-------|-----------|-------------|
+| Root Key | AES-256-GCM | HSM (hardware-bound) |
+| Organization KEK | AES-256-GCM | Root Key |
+| Project KEK | AES-256-GCM | Organization KEK |
+| Data Keys | AES-256-GCM | Project KEK |
+| Secrets | AES-256-GCM | Data Keys |
+
+## Access Control
+
+KMS supports multiple access control models:
+
+| Model | Description |
+|-------|-------------|
+| RBAC | Role-based access: admin, member, viewer |
+| ABAC | Attribute-based policies for fine-grained control |
+| Machine Identity | Service account auth via OIDC, K8s, AWS IAM |
+| Temporary Access | Time-limited access grants with auto-revocation |
+| Approval Workflows | Require human approval for sensitive operations |
+
+## Audit Logging
+
+Every operation produces an audit log entry:
+
+```json
+{
+  "event": "secret.read",
+  "actor": "user:[email protected]",
+  "resource": "/production/database/password",
+  "timestamp": "2026-03-22T10:15:30Z",
+  "sourceIp": "10.0.1.50",
+  "result": "success"
+}
+```
+
+## Secret Scanning
+
+KMS includes a CLI scanner to prevent secrets from leaking to git:
+
+```bash
+# Scan current directory
+lux kms scan .
+
+# Pre-commit hook
+lux kms scan --hook
+```
+
+## Compliance
+
+| Standard | Support |
+|----------|---------|
+| SOC 2 Type II | Audit log export |
+| PCI-DSS | Key rotation, access control |
+| HIPAA | Encryption at rest and in transit |
+| GDPR | Data isolation, audit trail |
@@ -4,6 +4,8 @@ description: MPC daemon REST API
 icon: FileCode
 ---

+The MPC daemon exposes a REST API on port 8081 (configurable via `--api-listen`) for key management and signing operations.
+
 ## Endpoints

 | Method | Path | Description |
@@ -13,5 +15,87 @@ icon: FileCode
 | GET | `/v1/keys` | List available keys |
 | GET | `/v1/keys/:id` | Get key metadata |
 | DELETE | `/v1/keys/:id` | Delete a key |
+| POST | `/v1/reshare` | Reshare key with new committee |
 | GET | `/v1/health` | Health check |
 | GET | `/v1/metrics` | Prometheus metrics |
+
+## Key Generation
+
+```bash
+curl -X POST http://localhost:8081/v1/keygen \
+  -H "Authorization: Bearer $MPC_TOKEN" \
+  -d '{
+    "walletId": "wallet-001",
+    "protocol": "cggmp21",
+    "threshold": 2,
+    "parties": 3
+  }'
+```
+
+Response:
+
+```json
+{
+  "walletId": "wallet-001",
+  "ecdsaPublicKey": "04abc123...",
+  "eddsaPublicKey": "ed25519:def456...",
+  "address": "0x9011E888251AB053B7bD1cdB598Db4f9DEd94714"
+}
+```
+
+## Threshold Signing
+
+```bash
+curl -X POST http://localhost:8081/v1/sign \
+  -H "Authorization: Bearer $MPC_TOKEN" \
+  -d '{
+    "walletId": "wallet-001",
+    "message": "0xdeadbeef...",
+    "protocol": "cggmp21",
+    "encoding": "hex"
+  }'
+```
+
+Response:
+
+```json
+{
+  "signature": "0x...",
+  "r": "0x...",
+  "s": "0x...",
+  "v": 27
+}
+```
+
+## List Keys
+
+```bash
+curl http://localhost:8081/v1/keys \
+  -H "Authorization: Bearer $MPC_TOKEN"
+```
+
+## Health Check
+
+```bash
+curl http://localhost:8081/v1/health
+```
+
+Response:
+
+```json
+{
+  "status": "healthy",
+  "nodeId": "node0",
+  "peers": 2,
+  "threshold": 2,
+  "mode": "consensus"
+}
+```
+
+## Authentication
+
+All endpoints except `/v1/health` and `/v1/metrics` require a JWT bearer token. Configure the JWT secret with `--jwt-secret` or `MPC_JWT_SECRET`.
+
+## Dashboard API
+
+When `MPC_API_DB` is set, the dashboard API provides additional endpoints for ORM-based entity management on port 8081.
@@ -4,13 +4,69 @@ description: MPC signing for cross-chain bridge transfers
 icon: ArrowLeftRight
 ---

-The Lux Bridge uses MPC for threshold signing of cross-chain transfers. Each bridge transaction requires t-of-n MPC nodes to produce a valid signature.
+The Lux Bridge uses MPC for threshold signing of cross-chain transfers. Each bridge transaction requires t-of-n MPC nodes to produce a valid signature before assets are released on the destination chain.

-## Flow
+## Transfer Flow

-1. User initiates transfer via Bridge UI
-2. Bridge API validates and creates intent
-3. MPC nodes receive signing request via NATS
-4. Each node produces a threshold signature share
-5. Shares are aggregated into a valid signature
-6. Transaction is broadcast to the destination chain
+1. User initiates transfer via Bridge UI at [bridge.lux.network](https://bridge.lux.network)
+2. Bridge API validates the request and creates an intent document
+3. HSM co-signs the intent (if `--hsm-attest` is enabled)
+4. MPC nodes receive the signing request via the consensus transport
+5. Each participating node produces a threshold signature share
+6. Shares are aggregated into a valid ECDSA signature
+7. The bridge server broadcasts the signed transaction to the destination chain
+8. Bridge API updates the transfer status
+
+## Supported Protocols
+
+| Protocol | Curve | Chains |
+|----------|-------|--------|
+| CGGMP21 | secp256k1 | Ethereum, Lux, all EVM chains |
+| FROST | secp256k1 | Bitcoin (Taproot) |
+
+## Bridge Architecture
+
+```
+Bridge UI (Next.js)
+  -> Bridge API (Node.js, port 3000)
+    -> MPC Cluster (3 nodes, consensus mode)
+      -> node-0 (port 9651)
+      -> node-1 (port 9652)
+      -> node-2 (port 9653)
+    -> Destination chain RPC
+```
+
+## MPC Node Configuration for Bridge
+
+```bash
+mpcd start --mode consensus \
+  --node-id node0 \
+  --listen :9651 \
+  --api :9800 \
+  --data /data/mpc/node0 \
+  --threshold 2 \
+  --peer [email protected]:9652 \
+  --peer [email protected]:9653
+```
+
+## Security Properties
+
+| Property | Guarantee |
+|----------|-----------|
+| Key safety | Full private key never exists on any single node |
+| Fault tolerance | 1 node can be offline (2-of-3 threshold) |
+| Signing speed | Sub-second threshold signature generation |
+| Audit trail | Every signing request logged with intent hash |
+| HSM binding | Optional hardware attestation per signature share |
+
+## Kubernetes Deployment
+
+The bridge MPC nodes run in the `lux-bridge` namespace with separate PostgreSQL and Valkey instances from the main MPC cluster:
+
+```
+lux-bridge namespace:
+  mpc-node-0, mpc-node-1, mpc-node-2
+  bridge-postgres
+  bridge-api
+  bridge-ui
+```
@@ -4,25 +4,68 @@ description: CLI flags and environment variables
 icon: Settings
 ---

+The MPC daemon (`mpcd`) supports two operation modes: consensus (recommended) and legacy (NATS/Consul).
+
+## Operation Modes
+
+| Mode | Transport | Dependencies | Recommended |
+|------|-----------|-------------|-------------|
+| `consensus` | ZAP wire protocol | None | Yes |
+| `legacy` | NATS + Consul | NATS, Consul | No (deprecated) |
+
 ## CLI Flags

 | Flag | Env Var | Description | Default |
 |------|---------|-------------|---------|
-| `--name` | `MPC_NAME` | Node name | — |
-| `--mode` | `MPC_MODE` | Operation mode | — |
-| `--node-id` | `MPC_NODE_ID` | Node identifier | — |
-| `--listen` | `MPC_LISTEN` | P2P listen address | — |
+| `--mode` | `MPC_MODE` | Operation mode (consensus/legacy) | consensus |
+| `--node-id` | `MPC_NODE_ID` | Node identifier | -- |
+| `--listen` | `MPC_LISTEN` | P2P listen address | `:9651` |
 | `--api` | `MPC_API` | Consensus API address | `:9800` |
 | `--api-listen` | `MPC_API_LISTEN` | Dashboard API address | `:8081` |
-| `--data` | `MPC_DATA` | Data directory | — |
-| `--keys` | `MPC_KEYS` | Keys directory | — |
-| `--threshold` | `MPC_THRESHOLD` | Signing threshold | — |
-| `--peer` | `MPC_PEER` | Peer addresses | — |
+| `--data` | `MPC_DATA` | ZapDB data directory | `/data/mpc` |
+| `--threshold` | `MPC_THRESHOLD` | Signing threshold (t-of-n) | -- |
+| `--peer` | `MPC_PEER` | Peer address (repeatable) | -- |
 | `--log-level` | `MPC_LOG_LEVEL` | Log verbosity | `info` |
-| `--hsm-signer` | `MPC_HSM_SIGNER` | Signer provider (aws/gcp/zymbit/mldsa/local) | `local` |
-| `--hsm-signer-key-id` | `MPC_HSM_SIGNER_KEY_ID` | Key ID for signing | — |
+| `--hsm-signer` | `MPC_HSM_SIGNER` | Signer provider | `local` |
+| `--hsm-signer-key-id` | `MPC_HSM_SIGNER_KEY_ID` | HSM key ID for signing | -- |
 | `--hsm-provider` | `MPC_HSM_PROVIDER` | Password provider type | `env` |
-| `--hsm-key-id` | `MPC_HSM_KEY_ID` | Key ID for password decryption | — |
+| `--hsm-key-id` | `MPC_HSM_KEY_ID` | Key ID for password decryption | -- |
 | `--hsm-attest` | `MPC_HSM_ATTEST` | Enable threshold attestation | `false` |
-| `--jwt-secret` | `MPC_JWT_SECRET` | JWT secret for API auth | — |
-| `--debug` | `MPC_DEBUG` | Enable debug mode | `false` |
+| `--jwt-secret` | `MPC_JWT_SECRET` | JWT secret for API auth | -- |
+
+## Consensus Mode Example
+
+```bash
+mpcd start --mode consensus \
+  --node-id node0 \
+  --listen :9651 \
+  --api :9800 \
+  --data /data/mpc/node0 \
+  --threshold 2 \
+  --peer [email protected]:9652 \
+  --peer [email protected]:9653
+```
+
+## HSM Signer Providers
+
+| Provider | Description |
+|----------|-------------|
+| `local` | Software-based Ed25519 signing |
+| `aws` | AWS KMS for intent co-signing |
+| `gcp` | Google Cloud KMS |
+| `zymbit` | Zymbit hardware security module |
+| `mldsa` | Post-quantum ML-DSA signatures |
+
+## HSM Password Providers
+
+| Provider | Source | Use Case |
+|----------|--------|----------|
+| `env` | `MPC_DB_PASSWORD` env var | Development |
+| `file` | Password file on disk | Containers |
+| `aws` | AWS KMS decrypt | AWS production |
+| `gcp` | GCP KMS decrypt | GCP production |
+| `azure` | Azure Key Vault | Azure production |
+
+## Storage
+
+Key shares are stored in ZapDB (encrypted BadgerDB) at the `--data` path. The database is encrypted with ChaCha20-Poly1305 using the password from the HSM provider.
@@ -4,16 +4,82 @@ description: Hardware security module integration for MPC
 icon: ShieldCheck
 ---

-The MPC daemon uses HSM for intent co-signing, ZapDB password decryption, and threshold attestation. See the [HSM documentation](https://hsm.lux.network) for provider details.
+The MPC daemon uses HSM for three security functions: intent co-signing, ZapDB password management, and threshold attestation.

 ## Intent Co-signing

-Every approved transaction is co-signed by the HSM before threshold signing begins.
+Every approved transaction is co-signed by the HSM before threshold signing begins. This adds a hardware-bound authorization layer on top of the threshold scheme.

-## ZapDB Password
+```bash
+mpcd start --mode consensus \
+  --hsm-signer aws \
+  --hsm-signer-key-id arn:aws:kms:us-east-1:123:key/abc
+```

-The encryption password for the key share database is derived from cloud KMS — never stored in plaintext.
+The HSM signature is verified by all MPC nodes before they participate in the threshold signing round.
+
+## ZapDB Password Management
+
+The encryption password for the key share database is derived from cloud KMS -- never stored in plaintext.
+
+| Provider | Flag | Description |
+|----------|------|-------------|
+| `env` | `--hsm-provider=env` | Password from `MPC_DB_PASSWORD` env var |
+| `file` | `--hsm-provider=file` | Password from file at `--hsm-key-id` path |
+| `aws` | `--hsm-provider=aws` | Decrypt via AWS KMS |
+| `gcp` | `--hsm-provider=gcp` | Decrypt via Google Cloud KMS |
+| `azure` | `--hsm-provider=azure` | Decrypt via Azure Key Vault |
+
+Example with AWS KMS:
+
+```bash
+mpcd start --mode consensus \
+  --hsm-provider aws \
+  --hsm-key-id arn:aws:kms:us-east-1:123:key/db-key
+```

 ## Threshold Attestation

-When enabled (`--hsm-attest`), every signature share is co-signed by the HSM, binding it to specific hardware.
+When enabled with `--hsm-attest`, every signature share produced by a node is co-signed by the HSM. This binds each share to specific hardware, preventing share forgery.
+
+```bash
+mpcd start --mode consensus \
+  --hsm-attest \
+  --hsm-signer aws \
+  --hsm-signer-key-id arn:aws:kms:us-east-1:123:key/attest-key
+```
+
+## Security Properties
+
+| Feature | Without HSM | With HSM |
+|---------|------------|----------|
+| Key share storage | Software encryption | Hardware-derived password |
+| Intent authorization | Software signature | Hardware co-signature |
+| Share authenticity | Node identity only | Hardware attestation |
+| Key extraction risk | Software compromise | Physical access required |
+
+## Supported HSM Types
+
+| Type | Interface | Use Case |
+|------|-----------|----------|
+| AWS KMS | AWS SDK | Cloud production |
+| Google Cloud HSM | Cloud KMS API | GCP production |
+| Azure Managed HSM | REST API | Azure production |
+| Zymbit SCM | PKCS#11 | Edge/IoT deployments |
+
+## Kubernetes Configuration
+
+In Kubernetes, HSM credentials are mounted as secrets:
+
+```yaml
+env:
+  - name: AWS_REGION
+    value: us-east-1
+  - name: MPC_HSM_SIGNER
+    value: aws
+  - name: MPC_HSM_SIGNER_KEY_ID
+    valueFrom:
+      secretKeyRef:
+        name: mpc-hsm
+        key: signer-key-id
+```
@@ -1,18 +1,100 @@
 ---
 title: API Reference
-description: Programmatic usage
+description: gRPC and REST API for programmatic network control
 icon: FileCode
 ---

-## Go API
+Netrunner exposes a gRPC API (port 8080) with a REST gateway (port 8081) for programmatic network management.
+
+## Go Client

 ```go
-import "github.com/luxfi/netrunner"
+package main

-net, _ := netrunner.Start(netrunner.Config{
-    NumNodes: 5,
-    Duration: 60 * time.Second,
-})
-result := net.Benchmark()
-fmt.Println(result.TPS)
+import (
+    "context"
+    "fmt"
+    "time"
+
+    "github.com/luxfi/netrunner/client"
+)
+
+func main() {
+    cli, err := client.New(client.Config{
+        Endpoint:    "localhost:8080",
+        DialTimeout: 10 * time.Second,
+    })
+    if err != nil {
+        panic(err)
+    }
+    defer cli.Close()
+
+    ctx := context.Background()
+
+    // Start a network
+    resp, err := cli.Start(ctx, "/path/to/luxd",
+        client.WithNumNodes(5),
+    )
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println("Cluster info:", resp.ClusterInfo)
+
+    // Check health
+    health, _ := cli.Health(ctx)
+    fmt.Println("Healthy:", health.Healthy)
+
+    // Get status
+    status, _ := cli.Status(ctx)
+    for name, node := range status.ClusterInfo.NodeInfos {
+        fmt.Printf("  %s: %s\n", name, node.Uri)
+    }
+
+    // Save snapshot
+    cli.SaveSnapshot(ctx, "my-snapshot")
+
+    // Stop
+    cli.Stop(ctx)
+}
 ```
+
+## REST API
+
+The REST gateway mirrors the gRPC API:
+
+```bash
+# Start network
+curl -X POST http://localhost:8081/v1/control/start \
+  -d '{"numNodes": 5, "execPath": "/path/to/luxd"}'
+
+# Health check
+curl http://localhost:8081/v1/control/health
+
+# Status
+curl http://localhost:8081/v1/control/status
+
+# Save snapshot
+curl -X POST http://localhost:8081/v1/control/savesnapshot \
+  -d '{"snapshotName": "my-snapshot"}'
+
+# Load snapshot
+curl -X POST http://localhost:8081/v1/control/loadsnapshot \
+  -d '{"snapshotName": "my-snapshot"}'
+
+# Stop
+curl -X POST http://localhost:8081/v1/control/stop
+```
+
+## gRPC Methods
+
+| Method | Description |
+|--------|-------------|
+| `Start` | Start a new network |
+| `Stop` | Stop the running network |
+| `Health` | Check network health |
+| `Status` | Get network status and node info |
+| `SaveSnapshot` | Save network state |
+| `LoadSnapshot` | Restore from snapshot |
+| `SaveHotSnapshot` | Snapshot without stopping nodes |
+| `AddNode` | Add a node to the running network |
+| `RemoveNode` | Remove a node from the network |
@@ -1,17 +1,85 @@
 ---
 title: Consensus Testing
-description: Verify consensus correctness
+description: Verify consensus correctness under adversarial conditions
 icon: CheckCircle
 ---

-## Liveness
+Netrunner provides tools for verifying consensus liveness and safety properties under various failure modes.
+
+## Liveness Testing
+
+Verify that the network continues to produce blocks and finalize transactions:

 ```bash
+# Run liveness test for 2 minutes
 netrunner test --liveness --duration 120s
+
+# With a specific block production target
+netrunner test --liveness --min-blocks 100 --duration 120s
 ```

-## Safety
+The liveness test verifies:
+- All chains produce blocks within expected intervals
+- Transactions are confirmed within timeout
+- No chain falls behind
+
+## Safety Testing
+
+Verify that the network does not produce conflicting finalized blocks:

 ```bash
+# Safety test with 1 faulty node
 netrunner test --safety --faults 1
+
+# Safety with network partitions
+netrunner test --safety --partition-duration 30s
+```
+
+The safety test verifies:
+- No two nodes finalize conflicting blocks
+- Chain state is consistent across all honest nodes
+- Block hashes match at the same height
+
+## Consensus Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `consensus-sample-size` | 5 | Validators sampled per consensus round |
+| `consensus-quorum-size` | 4 | Required agreement for finality |
+| Maximum Byzantine faults | 1 | `floor((n-1)/3)` for n=5 |
+
+## Test Scenarios
+
+| Scenario | Command | Verifies |
+|----------|---------|----------|
+| Happy path | `test --liveness` | Normal block production |
+| Node crash | `test --safety --faults 1` | Consensus with minority failure |
+| Partition | `test --safety --partition-duration 30s` | Recovery after partition |
+| Slow node | `test --liveness --latency 500ms` | Tolerance for slow peers |
+| Full restart | `test --liveness --restart-all` | Bootstrap from saved state |
+
+## Chain-Specific Tests
+
+```bash
+# Test P-Chain consensus
+netrunner test --chain P --liveness
+
+# Test C-Chain consensus
+netrunner test --chain C --liveness --min-blocks 50
+
+# Test all chains
+netrunner test --all-chains --liveness
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Run consensus tests
+  run: |
+    netrunner server &
+    netrunner control start --number-of-nodes=5 --node-path=./luxd
+    netrunner test --liveness --duration 60s
+    netrunner test --safety --faults 1
+    netrunner control stop
 ```
@@ -1,18 +1,84 @@
 ---
 title: Custom Topology
-description: Configure network topology
+description: Configure network topology and connections
 icon: GitBranch
 ---

-## Topology File
+Netrunner supports custom network topologies to simulate different deployment configurations. Define the connectivity between nodes using a YAML topology file.
+
+## Topology File Format

 ```yaml
 nodes:
  - id: node-0
-    connections: [node-1, node-2]
+    role: bootstrap
+    connections: [node-1, node-2, node-3, node-4]
  - id: node-1
    connections: [node-0, node-2]
  - id: node-2
+    connections: [node-0, node-3]
+  - id: node-3
+    connections: [node-0, node-4]
+  - id: node-4
    connections: [node-0, node-1]
 latency: 10ms
+bandwidth: 100mbps
 ```
+
+## Built-in Topologies
+
+| Topology | Description | Use Case |
+|----------|-------------|----------|
+| `mesh` | Every node connects to every other | Default, best finality |
+| `star` | All nodes connect through a central hub | Test hub failure scenarios |
+| `ring` | Each node connects to two neighbors | Minimal connectivity |
+| `hierarchical` | Tree structure with bootstrap root | Realistic deployment sim |
+
+## Use a Custom Topology
+
+```bash
+netrunner control start \
+  --number-of-nodes=5 \
+  --node-path=/path/to/luxd \
+  --topology=my-topology.yaml
+```
+
+## Network Conditions
+
+Add realistic network conditions per link:
+
+```yaml
+nodes:
+  - id: node-0
+    connections:
+      - target: node-1
+        latency: 5ms
+      - target: node-2
+        latency: 50ms
+      - target: node-3
+        latency: 200ms
+
+defaults:
+  latency: 10ms
+  bandwidth: 100mbps
+  packet_loss: 0.1%
+```
+
+## Node Roles
+
+| Role | Description |
+|------|-------------|
+| `bootstrap` | First node started, other nodes connect to it |
+| `validator` | Normal validator node (default) |
+| `api` | API-only node, no validation |
+| `observer` | Read-only node, no consensus participation |
+
+## Topology Visualization
+
+After starting a network with a custom topology, view the actual connectivity:
+
+```bash
+netrunner control status --topology
+```
+
+This displays which nodes are connected and the measured latency between them.