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.

Keyboard shortcuts

OpenFab