Server Configuration & Security Guide

This document details the configuration topology, cryptographic secret references, mandatory TLS setup, and operational parameters for the OpenFAB Rocket backend service.

Configuration Overview

OpenFAB uses a structured, type-safe configuration model backed by serde. Configuration can be supplied via an OpenFab.toml file or overridden using environment variables prefixed with OPENFAB_.

Mandatory Security Defaults

Strict TLS Enforcement: Plain HTTP execution is disabled. The server requires valid X.509 certificate and private key paths before initializing routes.
Deterministic HMAC Token Protection: All API keys, activation codes, and session tokens are hashed using HMAC-SHA256 with a dedicated server-side secret key before entering PostgreSQL.
Secret Isolation (SecretRef): Sensitive credentials (database passwords, object store keys, cryptographic seeds) must be loaded via file references (file:///path/to/secret) or environment variables, keeping secrets out of repository tracking.

Standardized `OpenFab.toml` Prototype

Below is the complete, canonical configuration file with sane defaults:

[server]
address = "127.0.0.1"
port = 7777
max_upload_limit_mb = 100
static_dir = "static"

[tls]
cert_path = "/etc/openfab/certs/server.crt"
key_path = "/etc/openfab/secrets/server.key"

[database]
url = "file:///etc/openfab/secrets/db_url.txt"
max_connections = 16
min_connections = 2

[storage]
endpoint = "localhost:3900"
bucket = "openfab"
access_key = "OPENFAB_STORAGE_ACCESS_KEY"
secret_key = "file:///etc/openfab/secrets/store.key"
secure = true
primary_hash_alg = "blake3"

[auth]
allow_registration = true
hmac_secret = "file:///etc/openfab/secrets/hmac.key"

[auth.oidc]
name = "LaunchSpace Keycloak"
client_id = "openfab"
client_secret = "file:///etc/openfab/secrets/keycloak.txt"
issuer_url = "[https://sso.example.com/realms/master](https://sso.example.com/realms/master)"
redirect_url = "[https://openfab.example.com:7777](https://openfab.example.com:7777)"
jwt_privkey_path = "/etc/openfab/secrets/backend.key.pem"
post_login_redirect = "/accounts/dashboard"

Cryptographic Secrets Inventory

The OpenFAB server requires several cryptographic secrets to be provisioned on disk prior to launch. File permissions must be set to 0600 (chmod 600), owned by the service user.

Secret Key File	Required	Purpose	Format / Algorithm
`hmac.key`	Yes	HMAC-SHA256 seed for deterministic hashing of API keys & activation codes.	Random high-entropy byte sequence (minimum 32 bytes).
`server.key`	Yes	Private key for web server TLS termination.	PEM-encoded PKCS#8 or RSA private key.
`server.crt`	Yes	Server certificate chain.	PEM-encoded X.509 certificate.
`store.key`	Yes	Authentication secret for object storage (S3/MinIO/Garage).	UTF-8 secret string.
`backend.key.pem`	Yes	RSA private key used by `OidcSigner` to sign local session tokens and JWTs.	PEM-encoded RSA Private Key (`-----BEGIN RSA PRIVATE KEY-----`).
`keycloak.txt`	Optional	OIDC Client Secret (if OIDC auto-registration is enabled).	Standard string secret from IdP.

Environment Variable Overrides

(this will be the standard after figment configuration is implemented) For containerized deployment environments (e.g., Docker, Podman, Kubernetes), any configuration option can be set or overridden using OPENFAB_ environment variables:

Environment Variable	Equivalent TOML Field	Description
`OPENFAB_SERVER_ADDRESS`	`server.addr`	Network interface IP binding.
`OPENFAB_SERVER_PORT`	`server.port`	HTTP/TLS listener port.
`OPENFAB_TLS_CERT_PATH`	`tls.cert_path`	Path to TLS certificate.
`OPENFAB_TLS_KEY_PATH`	`tls.key_path`	Path to TLS private key.
`OPENFAB_DATABASE_URL`	`database.url`	PostgreSQL connection string or `file://` ref.
`OPENFAB_AUTH_HMAC_SECRET`	`auth.hmac_secret`	Secret key or `file://` reference for HMAC operations.
`OPENFAB_STORAGE_SECRET_KEY`	`storage.secret_key`	Storage secret or `file://` reference.

Limits & Runtime Tuning

Upload Limits: The default max_upload_limit_mb is set to 100MB for data-form and file inputs to accommodate large parametric models, multi-layer 3MF files, and dense binary G-code payloads.
Database Pool: The PostgreSQL connection pool defaults to 16 maximum concurrent connections with 2 idle connections maintained for low-latency dispatching.

API Integration & Third-Party Tooling

This guide provides an overview for developers looking to build integrations, CLI utilities, or third-party client applications for the platform.

1. Interactive API Documentation (Swagger UI)

For an interactive, real-time reference of all available REST endpoints, request schemas, and response types, consult the built-in Swagger UI.

Local Development: http://localhost:7777/swagger-ui/
Production / Remote: https://<your-domain>/api/swagger-ui/

The Swagger UI allows you to inspect model schemas, test queries directly against a running server instance, and inspect expected status codes (e.g., 401 Unauthorized, 412 Precondition Failed, 422 Unprocessable Entity).

2. Official Rust SDK Crate

If you are developing third-party tools or microservices in Rust, you can use the official SDK crate rather than implementing raw HTTP logic.

Installation

Add the SDK dependency to your Cargo.toml:

[dependencies]
openfab-sdk = "0.1" # Adjust crate name/version as appropriate
tokio = { version = "1", features = ["full"] }

Quick Example

use openfab_sdk::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client with base URL and Bearer Access Token
    let client = Client::new("https://api.yourdomain.com", "your_bearer_token_here")?;

    // Perform operations via the client SDK
    let user = client.users().me().await?;
    println!("Authenticated as: {}", user.email);

    Ok(())
}

3. Authentication & Bearer Tokens

All protected API endpoints require authentication using standard HTTP Bearer Tokens in the Authorization header.

Header Format

Authorization: Bearer <your_access_token>

Obtaining an Access Token (web UI only)

OIDC / SSO Authorization Flow: Complete the OpenID Connect web flow to acquire an ID/Access token pair.
Account Activation / Local Login: Submit user credentials or complete account activation via the /accounts/activate endpoint to acquire a session token.

Security Guidelines

Token Storage: Store tokens securely (e.g., using OS keyring services for CLI tools, or secure, HTTP-only cookies for web applications).
Transit Security: All production API endpoints strictly enforce HTTPS/TLS. Non-TLS requests will be rejected.

4. API Architecture & Key Components

The platform API is structured around clear domain boundaries to simplify building custom tools:

Primary Domain Modules

Identity & Accounts (/accounts, /auth)
- Handles user registration, OIDC account linking, account activation, and credential management.
- Enforces strict identity collision checks (returns 409 Conflict on email collision rather than silent linking). (For security reasons this will be excluded from the standard REST API until further notice.)

Error Handling & Status Code Taxonomy

The API adheres to a strict error taxonomy to simplify programmatic client logic:

Status Code	Meaning	Common Cause
`401 Unauthorized`	Authentication Failure	Missing, invalid, or expired Bearer token.
`403 Forbidden`	Permission Denied	Authenticated user lacks specific DB/RBAC permissions.
`409 Conflict`	Identity Collision	Email already exists under another account provider.
`412 Precondition Failed`	State Requirement	Account activation required (`is_active == false`).
`422 Unprocessable Entity`	Validation Failure	Invalid request parameters or form fields.

5. Building Third-Party Tooling

When creating custom integrations (such as CLI tools, desktop wrappers using Slint/Tauri, or web widgets):

Use the OpenAPI Spec: You can download the raw OpenAPI JSON/YAML definition directly from /api/openapi.json to auto-generate client bindings for other languages (Python, Go, TypeScript).
Handle Precondition Errors: Always check for 412 Precondition Failed responses to gracefully prompt users to complete email activation or administrator setup.
Respect Rate Limits: Ensure long-running scripts handle exponential backoff on retries.

Keyboard shortcuts

OpenFab