docs: improvements

Author: evansims

README.md

@@ -1,6 +1,6 @@
 # InferaDB Control
 
-**Policy Administration Endpoint** — multi-tenant orchestration with headless APIs, Kubernetes-native deployment, and WebAuthn authentication.
+Multi-tenant control plane with headless APIs, Kubernetes-native deployment, and WebAuthn authentication.
 
 > [!IMPORTANT]
 > Under active development. Not production-ready.
@@ -11,29 +11,30 @@
 git clone https://github.com/inferadb/control && cd control
 docker-compose up -d
 export INFERADB_CTRL__AUTH__KEY_ENCRYPTION_SECRET=$(openssl rand -base64 32)
-cargo run --bin inferadb-control
+make setup && make dev
 ```
 
 Register and login:
 
 ```bash
 # Register
-curl -X POST http://localhost:3000/v1/auth/register \
+curl -X POST http://localhost:9090/v1/auth/register \
   -H "Content-Type: application/json" \
   -d '{"email": "alice@example.com", "password": "securepass123", "name": "Alice"}'
 
 # Login
-curl -X POST http://localhost:3000/v1/auth/login/password \
+curl -X POST http://localhost:9090/v1/auth/login/password \
   -H "Content-Type: application/json" \
   -d '{"email": "alice@example.com", "password": "securepass123"}'
 ```
 
 | Endpoint | URL                             |
 | -------- | ------------------------------- |
-| REST API | `http://localhost:3000`         |
-| gRPC API | `http://localhost:3001`         |
-| Health   | `http://localhost:3000/health`  |
-| Metrics  | `http://localhost:3000/metrics` |
+| REST API | `http://localhost:9090`         |
+| gRPC API | `http://localhost:9091`         |
+| Mesh API | `http://localhost:9092`         |
+| Health   | `http://localhost:9090/healthz` |
+| Metrics  | `http://localhost:9090/metrics` |
 
 ## Features
 
@@ -43,7 +44,7 @@ curl -X POST http://localhost:3000/v1/auth/login/password \
 | **Multi-Tenancy**    | Organization-based isolation with RBAC       |
 | **Vault Management** | Policy containers with access grants         |
 | **Client Auth**      | Ed25519 certificates, JWT assertions         |
-| **Token Issuance**   | Vault-scoped JWTs for Server API             |
+| **Token Issuance**   | Vault-scoped JWTs for Engine API             |
 
 ## Key Concepts
 
@@ -55,49 +56,61 @@ curl -X POST http://localhost:3000/v1/auth/login/password \
 | Client       | Service identity with Ed25519 certs           |
 | Team         | Group-based vault access                      |
 
-**Auth Flow:** User → Session → Vault access → JWT → Server API
+**Auth Flow:** User → Session → Vault access → JWT → Engine API
 
 ## Architecture
 
 ```mermaid
 graph TD
-    API[inferadb-control-api] --> Core[inferadb-control-core]
+    Bin[inferadb-control] --> API[inferadb-control-api]
+    API --> Core[inferadb-control-core]
     Core --> Storage[inferadb-control-storage]
     Storage --> FDB[(FoundationDB)]
-    API --> GRPC[inferadb-control-engine-client]
+    Core --> Engine[inferadb-control-engine-client]
 ```
 
 | Crate                          | Purpose                  |
 | ------------------------------ | ------------------------ |
+| inferadb-control               | Binary entrypoint        |
 | inferadb-control-api           | REST/gRPC handlers       |
 | inferadb-control-core          | Business logic, entities |
 | inferadb-control-storage       | Memory or FoundationDB   |
+| inferadb-control-types         | Shared type definitions  |
 | inferadb-control-engine-client | Engine API client        |
 
 ## Configuration
 
-```bash
-INFERADB_CTRL__STORAGE__BACKEND=foundationdb
-INFERADB_CTRL__STORAGE__FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster
-INFERADB_CTRL__SERVER__HTTP_PORT=3000
-INFERADB_CTRL__AUTH__KEY_ENCRYPTION_SECRET=<base64>
+```yaml
+control:
+  listen:
+    http: "0.0.0.0:9090"
+    grpc: "0.0.0.0:9091"
+    mesh: "0.0.0.0:9092"
+
+  webauthn:
+    party: "localhost"
+    origin: "http://localhost:9090"
 ```
 
+Environment variables use `INFERADB_CTRL__` prefix (e.g., `INFERADB_CTRL__LISTEN__HTTP`).
+
 See [config.yaml](config.yaml) for all options.
 
 ## Development
 
 ```bash
-cargo test                    # All tests
-cargo clippy -- -D warnings   # Lint
-cargo fmt                     # Format
+make setup                    # One-time setup
+make dev                      # Dev server with auto-reload
+make test                     # Run tests
+make check                    # Format, lint, audit
+cargo build --release         # Release build
 ```
 
 ## Deployment
 
 ```bash
-cargo build --release
-./target/release/inferadb-control --config /etc/inferadb/config.yaml
+docker run -p 9090:9090 inferadb/control:latest
+kubectl apply -k k8s/
 ```
 
 See [docs/deployment.md](docs/deployment.md) for Kubernetes.

config.integration.yaml

@@ -1,33 +1,24 @@
 # InferaDB Control Configuration - Integration Tests
-# This config is optimized for Docker container E2E testing
-#
-# This file uses the unified configuration format. Both engine and control
-# can share the same config file by reading their respective sections.
 
 control:
-  threads: 2  # Reduced for test environment
-  logging: "debug"  # Verbose logging for tests
-
   frontend:
     url: "http://localhost:9090"
 
   listen:
-    # Client-facing HTTP/REST API server
     http: "0.0.0.0:9090"
-
-    # Client-facing gRPC API server
     grpc: "0.0.0.0:9091"
-
-    # Service mesh / inter-service communication
     mesh: "0.0.0.0:9092"
 
-  storage: "memory"  # In-memory for fast tests
+  storage: "foundationdb"
+
+  foundationdb:
+    cluster_file: "/var/fdb/fdb.cluster"
 
   webauthn:
     party: "localhost"
     origin: "http://localhost:9090"
 
-  secret: "test-integration-secret-key-32bytes-long!"
+  key_file: "/tmp/integration-master.key"
 
   email:
     host: "localhost"
@@ -36,13 +27,11 @@ control:
     name: "InferaDB Test"
 
   limits:
-    login_attempts_per_ip_per_hour: 1000  # Relaxed for tests
+    login_attempts_per_ip_per_hour: 1000
     registrations_per_ip_per_day: 100
     email_verification_tokens_per_hour: 100
     password_reset_tokens_per_hour: 100
 
-  # Mesh configuration for engine communication
-  # Discovery mode discovers all engine pod IPs
   mesh:
     url: "http://inferadb-engine.inferadb"
     grpc: 8081
@@ -52,7 +41,6 @@ control:
     timeout: 5000
     retries: 0
 
-  # Kubernetes discovery for pod-level cache invalidation
   discovery:
     mode:
       type: kubernetes

config.production.yaml

@@ -1,90 +1,42 @@
 # InferaDB Control Configuration - Production Template
-#
-# This is a template for production deployment. Replace all placeholder values
-# (marked with <...>) with your actual production values.
-#
-# SECURITY: Do not commit this file with real credentials to version control.
-# Use environment variables or a secrets management system in production.
-#
-# This file uses the unified configuration format. Both engine and control
-# can share the same config file by reading their respective sections.
 
 control:
-  # Worker threads (recommended: number of CPU cores)
-  threads: 8
-  logging: "info"
-
   listen:
-    # Client-facing HTTP/REST API server (web, CLI, SDK)
     http: "0.0.0.0:9090"
-
-    # Client-facing gRPC API server
     grpc: "0.0.0.0:9091"
-
-    # Service mesh / inter-service communication
     mesh: "0.0.0.0:9092"
 
-  # Storage backend: "memory" or "foundationdb"
   storage: "foundationdb"
 
-  # FoundationDB configuration (only used when storage = "foundationdb")
   foundationdb:
-    # FoundationDB cluster file path
-    # This file contains the connection string for your FDB cluster
     cluster_file: "/etc/foundationdb/fdb.cluster"
 
-  # WebAuthn configuration (for passkey authentication)
   webauthn:
-    # Relying party ID (your domain)
     party: "example.com"
-
-    # Origin URL (must match browser origin)
     origin: "https://example.com"
 
-  # Master secret for encrypting private keys (REQUIRED: 32+ bytes for AES-256)
-  # SECURITY: Use environment variable in production!
-  # Set via: INFERADB__CONTROL__SECRET
-  secret: "<REPLACE-WITH-32+-BYTE-SECRET>"
+  key_file: "/var/lib/inferadb/master.key"
 
-  # Email configuration (SMTP)
   email:
-    # SMTP server settings
     host: "<SMTP-HOST>"
     port: 587
-
-    # SMTP authentication (optional, uncomment if needed)
     # username: "<SMTP-USERNAME>"
     # password: "<SMTP-PASSWORD>"
-
-    # From address
     address: "noreply@example.com"
     name: "InferaDB"
 
-  # Rate limits configuration
   limits:
-    # Login attempts per IP per hour
     login_attempts_per_ip_per_hour: 100
-
-    # Registration attempts per IP per day
     registrations_per_ip_per_day: 5
-
-    # Email verification tokens per email per hour
     email_verification_tokens_per_hour: 5
-
-    # Password reset tokens per user per hour
     password_reset_tokens_per_hour: 3
 
-  # Mesh configuration for engine communication
-  # All engine instances are discovered from this base URL + ports
-  # In production with Kubernetes/Tailscale discovery, set discovery.mode appropriately
   mesh:
-    # Base service URL (without port)
-    # For Kubernetes: use the k8s service name (e.g., "http://inferadb-engine.inferadb")
-    # For direct connection: use the host (e.g., "http://localhost")
     url: "http://inferadb-engine.inferadb"
-
-    # gRPC port for engine communication
     grpc: 8081
-
-    # Mesh port for webhooks and JWKS
     port: 8082
+
+  discovery:
+    mode:
+      type: kubernetes
+    cache_ttl: 30

config.yaml

@@ -2,9 +2,6 @@
 # Good defaults for local development and testing
 
 control:
-  threads: 4
-  logging: "info"
-
   frontend:
     url: "http://localhost:9090"
 
@@ -13,19 +10,13 @@ control:
     grpc: "127.0.0.1:9091"
     mesh: "0.0.0.0:9092"
 
-  storage: "memory"
-
   webauthn:
     party: "localhost"
     origin: "http://localhost:9090"
 
-  # secret: "" # Set via INFERADB__CONTROL__SECRET
-
   email:
     host: "localhost"
-    port: 1025  # MailHog default port for development
-    # username: ""
-    # password: "" # Set via INFERADB__CONTROL__EMAIL__PASSWORD
+    port: 1025 # MailHog default port for development
     address: "noreply@inferadb.local"
     name: "InferaDB"
 

crates/inferadb-control-api/src/handlers/auth.rs

@@ -144,12 +144,14 @@ impl AppState {
 
     /// Create AppState for testing with default configuration
     /// This is used by both unit tests and integration tests
+    #[allow(clippy::field_reassign_with_default)]
     pub fn new_test(storage: Arc<Backend>) -> Self {
         use inferadb_control_core::ManagementConfig;
 
         // Create a minimal test config using default and overriding necessary fields
         let mut config = ManagementConfig::default();
-        config.secret = Some("test-secret-key-at-least-32-bytes-long!".to_string());
+        // Use a temporary key file for tests - MasterKey will auto-generate it
+        config.key_file = Some("/tmp/test-master.key".to_string());
         config.webauthn.party = "localhost".to_string();
         config.webauthn.origin = "http://localhost:3000".to_string();
         let server_client = ServerApiClient::new("http://localhost".to_string(), 8080).unwrap();

crates/inferadb-control-api/src/handlers/clients.rs

@@ -5,7 +5,7 @@ use axum::{
 };
 use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
 use inferadb_control_core::{
-    Error as CoreError, IdGenerator, PrivateKeyEncryptor, RepositoryContext, keypair,
+    Error as CoreError, IdGenerator, MasterKey, PrivateKeyEncryptor, RepositoryContext, keypair,
 };
 use inferadb_control_types::{
     dto::{
@@ -293,16 +293,9 @@ pub async fn create_certificate(
     let (public_key_base64, private_key_bytes) = keypair::generate();
 
     // Encrypt private key for storage
-    tracing::debug!("Retrieving secret from config");
-    let master_secret = state
-        .config
-        .secret
-        .as_ref()
-        .ok_or_else(|| CoreError::Internal("secret not configured".to_string()))?
-        .as_bytes();
-
-    tracing::debug!(secret_len = master_secret.len(), "Creating encryptor");
-    let encryptor = PrivateKeyEncryptor::new(master_secret)?;
+    tracing::debug!("Loading master key for encryption");
+    let master_key = MasterKey::load_or_generate(state.config.key_file.as_deref())?;
+    let encryptor = PrivateKeyEncryptor::from_master_key(&master_key)?;
 
     tracing::debug!("Encrypting private key");
     let private_key_encrypted = encryptor.encrypt(&private_key_bytes)?;