Security at a glance
Foundation4 is designed for sensitive content. This page summarizes how Foundation4 protects that content and where the protection ends, so that security reviewers and operators can plan the controls that surround a deployment. The Data protection and Access control pages describe each mechanism in detail.
Data residency
Foundation4 runs entirely inside the customer's environment. Content, vectors, keys and logs remain in the deployment's PostgreSQL database, cache and cluster. No Foundation4 cloud service participates in any request, and Foundation4 sends no telemetry to the vendor.
Outbound connections are those that the administrator configures: the registered LLM endpoints and, if configured, a remote embedding endpoint. Some embedding models and text splitters also download files from the internet when first used: the built-in FastEmbed models that are not in the API server image and the token text splitter. The GPT4All and Hugging Face Sentence Transformers libraries can also contact their services while loading a model. When the configured endpoints are inside the customer's network and the pipelines use only the models and splitters that work without internet access, Foundation4 makes no connection outside the network. This property is what makes air-gapped deployment practical.
API authentication
Every request carries an API key identifier and secret in the x-api-key and x-api-key-secret headers.
- Secrets are hashed. Foundation4 stores key secrets as Argon2 hashes and returns a new secret exactly once, when the key is created.
- Keys can be retired. A key can be deactivated, deleted or given an expiry date. Deactivation and deletion take effect on the next request.
- Permissions are explicit. A key holds read, write and execute permissions on each object type or on individual objects. A key that can search a pipeline cannot change or delete the pipeline unless the key also holds write permission.
- Keys cannot escalate. A key can grant only permissions that the key already holds.
- One master key bootstraps the deployment. The master key is created at installation and is used to create the scoped keys that client applications use. The master key does not belong in application configuration.
Each integration should have a dedicated key with the minimum permissions that the integration requires. Dedicated keys limit the effect of a leaked key and keep the audit trail attributable.
Result scoping
Foundation4 provides two mechanisms for returning only the content that a given end user is permitted to see.
- Classifications. Every document carries one classification, an attribute that a reader must hold to see the document. Every search request names the classifications that the caller holds, and search returns only documents that carry one of those classifications or, with hierarchical matching, a classification beneath one of those classifications.
- Metadata filters. Every search request can filter on document metadata, such as the identifiers of the rooms, projects or accounts to which the end user belongs.
The client application selects the classifications and filters for each end user, because the client application holds the identity and entitlements of that user. Foundation4 applies both mechanisms identically in every search mode. For content with strict access rules, the recommended pattern is the one that the Rocket.Chat integration uses: scope every search with both mechanisms, then confirm the end user's access to each result in the client application before displaying the result.
Encryption
| Data | Protection |
|---|---|
| Fragment text | Encrypted with ChaCha20-Poly1305, using a separate key for each classification |
| LLM API keys | Encrypted with the application secret; never returned by the API |
| API key verification cache and agent traces | Encrypted with the application secret |
| API key secrets | Hashed with Argon2 |
| Connections to PostgreSQL | TLS supported, including a custom certificate authority; certificate verification needs sslmode=verify-ca or verify-full |
Some data is stored unencrypted because search reads that data directly:
- Vectors. Nearest-neighbor search compares vectors inside the database.
- Full-text index entries. The normalized words of each fragment, which PostgreSQL matches against queries.
- Metadata. Filters compare metadata values inside the database.
Embedding model settings, including any credentials for a remote embedding endpoint, are stored as plain configuration and are readable by any key with read permission on embedding models.
The per-classification keys are stored in the same database as the content. Encryption therefore protects fragment text only in copies of the fragment tables that exclude the classifications tables. A backup of the whole database contains the keys. Encryption does not protect against a party with full access to the running database, so database access controls must be planned accordingly. The application secret is a root credential: if the secret is lost, stored LLM API keys cannot be decrypted.
Intra-cluster traffic
By default, traffic between Foundation4 components (PostgreSQL, the cache, NATS JetStream and the gRPC service) is unencrypted, and the API server accepts cross-origin requests from any origin. Most deployments terminate TLS at the ingress and rely on cluster network controls for internal traffic. Security hardening describes TLS for client and database connections and the network policies that restrict internal traffic.
Retention
- Raw document text. Held in the NATS object store only until a worker has processed the document, and for at most 24 hours.
- Agent execution traces. Held for 60 minutes, then discarded. A trace records the prompt and the fragments used to produce a response.
- Documents and fragments. Retained until deleted. Expiring a document removes the document from search results but keeps the version history readable. Deleting a document removes the document and the fragments of the document.