MESA Core · v0.9.3

Security & scope

v0.9.3 source: docs/security-and-privacy.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

Tenant is the authorization boundary#

Authenticated keys bind a principal; tenant/workspace/dataset OWNER, WRITER and READER roles inherit downward. Agent IDs describe context, not credentials. Sessions freeze dataset membership. Purge and rollback need explicit dataset permissions in addition to roles. Scope is checked before retrieval ranking.

Deployment responsibilities remain#

Core does not encrypt SQLite/LanceDB/Kùzu at rest. Protect volumes, OS permissions, backups and networks. Versioned memory, health and metrics need an API key, but readiness, OpenAPI, Swagger and Redoc have public boundaries. Provide TLS and access policy at the deployment edge.

Evidence is untrusted input#

Source-linked context is not independently verified truth. UNTRUSTED_MEMORY_EVIDENCE must remain data in downstream prompts and tools. Avoid logging content, credentials, model output or claim tokens. Model consensus does not guarantee legal correctness or eliminate hallucinations.

v0.9.3 operation#

Purge erases the document’s owned source and extracted text while retaining audit IDs and hashes. Shared assertion/entity text remains while another document owns it. Protect local credentials and generated MCP configuration.

Bounded request work in v0.9.3#

Legal rule extraction, citation resolution, scope construction and heavy token scoring bound caller-text work and yield thread execution so health requests can run during measured heavy repros. In v0.9.3, per-minute and daily rate limits are not enforced for /v4/* and /control/*. Kùzu 0.11.3 raw graph files may contain process memory fragments; protect the graph directory like SQLite. See current limitations. Legal names, identities and exact-match promotion are resolved within the authorized tenant/dataset/agent/time scope.

Diagrams

UML · Class diagramWho may read what, and where every fact comes from
Principal+ principal_id+ key (scrypt hash) Tenant+ tenant_id Workspace+ workspace_id Dataset+ dataset_id+ purge, rollback grants «enumeration»RoleOWNERWRITERREADER Session+ session_id+ dataset_ids {frozen} Agent+ agent_idpersona, not a boundary Document+ document_id+ title «immutable»Revision+ revision_id SourceChunk+ chunk_id+ exact content «snapshot»LegalItem+ version, type+ start, end+ source quote 0..* Assertion+ subject+ predicate+ object+ state 1..* 1..* 0..* 1..* 1..* **role 10..*starts *1acts as «scope» 1..* datasets 1..*0..*evidence Roles inherit downward.Request metadata nevergrants authority (ADR 0011).

Filled diamonds mean ownership (composition): deleting a dataset removes its documents. Role is an association class on the Principal–Tenant link and inherits down to workspaces and datasets. A session is created by the server and freezes its dataset set. LegalItem snapshots belong to source chunks, remain separate from SPO assertions and are hidden from returned copies when legal rules are off.

All diagrams with their design rationale: Architecture →

Source reference for this page

The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.

Threat model and deployment boundary#

Core enforces authenticated principals, scoped catalog/session access and

ownership-aware storage operations. An operator with filesystem access or

control over the process/credentials is outside that application boundary.

Embedded SQLite/LanceDB/Kùzu data is not encrypted at rest by Core; use reviewed

volume encryption and restrict OS permissions, backups and network access.

V4 keys are key_id.secret; the registry stores salted scrypt hashes, supports

rotation/revocation and binds principal identity server-side. Provision tenant

roles, agent permission and dataset purge/rollback permission explicitly.

Revalidate roles for each request; user metadata grants no authority.

Tenant → workspace → dataset roles inherit downwards. Sessions bind immutable

dataset membership and agent context. Negative isolation contracts cover SQL,

vectors, graph and historical mutation management; passing tests is not an

absolute guarantee against every possible leak. V3 agent/session checks are a

separate compatibility contract.

Network and authentication#

Versioned memory routes, /health and /metrics require an API

key. /health/init is a public readiness probe. OpenAPI, Swagger and Redoc are

not protected by the memory-router authentication dependency. Configure an

authenticated reverse proxy, TLS and access policy for nonlocal deployments.

Compose publishes loopback only; the normal runtime launcher binds 0.0.0.0

inside the process/container. Do not expose its port without a network boundary.

Control-plane routes require an active principal with ADMIN; MCP gateway

credentials additionally bind a client/workspace. Gateway encrypted approvals

and bridge spools are separate from canonical memory storage. Protect the

Fernet key and local XDG environment files; do not reuse a shared gateway token.

Approvals and the control-plane audit belong to the HTTP MCP gateway. Direct

mesa-mcp stdio creates no local database and relies on the MCP client's tool

approval and the MESA API key's grants for access to Core.

Untrusted data and logs#

Exact source content remains data. Context uses UNTRUSTED_MEMORY_EVIDENCE

JSON records; prompt injection detection/rendering is not proof that a downstream

model will ignore malicious instructions. Review consumers, tool authority and

output handling. API bounds and source-file containment checks reduce abuse;

they do not establish document truth or a legal opinion.

Document purge erases its source and extracted text while retaining identifiers and hashes; shared assertion/entity text remains while another document still owns it.

Kùzu keeps graph structure and entity names; assertion evidence, literal values

and source references stay in SQLite. Graph ranking reads evidence from the

authorized SQLite assertion map. Existing stores need one offline projection

rebuild to create a fresh active graph with those text fields empty (see the

rebuild runbook). Retained generations and rebuild backups still

contain historical bytes; retire those copies under your retention policy

after verifying the new generation. Purge cannot erase independent backups.

Known v0.9 limitation: Kùzu may write leftover process memory into unused

parts of its file. The offline rebuild reads every assertion from SQLite, so a

new graph file can contain fragments of live documents' text in such unused

bytes (seen in 2 of 6 test rebuilds; not seen in normal projection). Kùzu never

overwrites them, so text of a document purged after that rebuild can stay

recoverable from the graph file. If a purge must leave no copy at all, run

another offline rebuild after the purge and retire the older generation.

Strict erasure setups can set MESA_GRAPH_ENABLED=false to keep Kùzu closed and prevent new graph files; retire any existing graph files and retained copies under the retention policy.

Avoid query/source content, credentials, raw model output and claim tokens in

logs. IDs and aggregate diagnostics still reveal operational metadata and need

access/retention policy. Historical reports may contain deployment details;

they are not public defaults or evidence that those endpoints are safe to use.

MESA_EXTERNAL_PROVIDER_ENABLED=false fences canonical external model/provider

calls; local model provisioning/download and browser fonts are separate network

concerns. MESA_ZERO_COST_MODE is provider selection, not a complete air-gap or

exfiltration guarantee. Preserve validation assurance when selecting local models.

With the external switch off, ollama and openai_compatible (LLM and

embedding) can use only HTTP(S) URLs whose host is localhost, 127.0.0.1,

::1 or host.docker.internal. The last name means the Docker host, allowing

a container to reach its host's model server. Other hosts, including private

LAN addresses, are blocked. The same rule checks the effective embedding URL,

including MESA_EMBEDDING_BASE_URL overrides and MESA_LLM_BASE_URL fallback.

Local openai_compatible endpoints need no API key; clients send local when

none is configured. openai, claude, anthropic and hosted remain blocked

regardless of URL. Enabling external providers permits remote model endpoints;

remote OpenAI-compatible endpoints still require a configured provider key.

Responsible reporting and supply chain#

Follow SECURITY.md for private reporting. CI checks secrets,

dependency/image vulnerabilities and SBOMs; release requires same-commit evidence

and artifact attestation verification. A local string scan does not replace those

checks. Store real keys in a secret manager and keep .env out of Git.