This document defines the security boundaries and invariants for Maestria. It complements, and does not replace:

• docs/SPECS.md — system contracts and behavior
• docs/PHILOSOPHY.md — architectural principles and invariant ownership

Security controls are implemented through replaceable adapters and policies. No model, database, search backend, parser, provider, or algorithm is a permanent default until it has been benchmarked against Maestria’s security, correctness, and operational requirements.

Maestria must:

1. enforce scope and authorization before data is retrieved, ranked, or exposed;
2. preserve provenance, source versions, and evidence boundaries;
3. treat external content and model output as untrusted data;
4. prevent secrets and restricted data from crossing policy boundaries;
5. make denial, quarantine, abstention, and incomplete evidence explicit;
6. provide an auditable explanation of security-relevant decisions;
7. keep domain state transitions deterministic and policy-controlled.

Maestria owns internal state integrity and provenance. It does not make an external source, claim, or model-generated assertion factually true.

The following invariants are normative.

ACL, scope, sensitivity, trust-zone, and quarantine filters are applied before candidate scoring, fusion, reranking, graph traversal, context expansion, or evidence packing.

A prohibited candidate must not influence ranking or reveal its existence through scores, counts, explanations, or timing-sensitive response content.

Web pages, files, command output, repository content, retrieved passages, OCR, model output, and harness results are data. They are never policy, system instructions, authorization, or tool definitions.

Every evidence candidate must resolve to:

artifact version
source span, page, region, or structured location
corpus snapshot
retrieval trace
trust and freshness metadata

Content without sufficient provenance may be retained as quarantined or incomplete data but cannot silently become authoritative evidence.

Parsing, embedding, summarization, reranking, memory promotion, or model agreement does not increase source authority by itself.

Trust, freshness, conflict, and sensitivity annotations are policy-controlled metadata.

If authorization, scope, provenance, secret scanning, prompt-injection checks, or provider capability checks cannot be completed, the operation is denied, quarantined, or marked incomplete.

It must not continue under a weaker implicit policy.

Adapters and providers cannot mutate domain state directly. They return typed results that runtime maps into DomainInput; the domain reducer performs the state transition.

An evidence object records what a source or operation produced. A claim remains uncertain, potentially stale, disputed, or unsupported until validated under policy.

Every artifact, evidence object, provider result, and derived representation has a security classification.

Trust zones are security metadata, not claims about factual correctness.

The daemon has no network transport: it answers only on the per-instance Unix domain socket with per-instance token authentication and read/write scope checks (rule 48). The browser-facing HTTP surface — static UI assets, the REST shape, origin enforcement, and bearer-token checks — belongs exclusively to the Studio server, which holds no durable state and no database access. Studio's middleware is browser-boundary hygiene; the daemon's token-and-scope check is the authority. ADR-0010 records this topology decision; new browser capabilities extend the typed socket API, never the daemon's transport.

Scope is explicit on every operation that can read, write, execute, retrieve, fetch, or promote data.

A scope should identify, as applicable:

instance
user or principal
workspace or repository
allowed paths
allowed domains
allowed artifact classes
allowed modalities
allowed harness capabilities
read/write/execute permissions
network permissions
time and freshness limits
sensitivity ceiling

A search plan must carry:

corpus scope
ACL context
trust-zone restrictions
snapshot identity
freshness requirement
sensitivity constraints

Authorization is enforced before:

• candidate generation;
• index or graph traversal;
• score calculation;
• duplicate clustering;
• reranking;
• context expansion;
• evidence-pack construction;
• model or provider submission.

Indexes and caches must not bypass the same authorization rules applied to source data.

Harness requests must declare:

capability requested
principal and scope
working directory
read/write targets
command or action
network requirement
approval requirement

The harness must reject requests outside the granted scope. A successful process exit does not override policy failure.

Network access is disabled unless explicitly granted. Domain, URL, method, content type, byte, page, query, and time budgets are policy inputs.

Redirects, uploads, authenticated requests, and access to local or private network addresses require separate authorization.

Realm federation is a local, provider-owned read capability, not shared instance storage. Every schema-v2 manifest has one stable RealmId. An existing schema-v1 manifest has no realm identity and must be explicitly migrated before it can participate.

The provider owns grant issuance and revocation. A grant binds exactly one consumer realm to:

search-only or search-and-open-evidence access
a sensitivity ceiling
a maximum result count
a maximum evidence excerpt size

The raw bearer credential exists only in the provider's create reply, the consumer's private binding, and a local federation request. The provider stores and keys grants by a domain-separated credential digest; raw credentials are not domain state, events, projections, ordinary logs, or CLI output. The consumer never receives or reuses the provider daemon token.

For every provider request, authorization is ordered as follows:

1. accept only the tagged federation authentication envelope and only federation_search or federation_evidence;
2. derive the credential digest and read the provider's current grant projection;
3. verify provider realm, consumer realm, active state, requested operation, finite bounds, and access type;
4. intersect the grant sensitivity ceiling with the provider retrieval policy;
5. pass that composed authorization context to every enabled candidate lane before candidate retrieval or scoring;
6. return bounded provenance-bearing data and append a successful access audit event.

Denied, missing, wrong, or revoked credentials reveal no provider result, count, source path, or evidence. Graph expansion is disabled for federation until graph relations can be authorized before materialization; it must not be post-filtered.

Grants do not expire automatically and have no rate quota. Explicit revocation is observed on the next provider request, including after restart. A search-only grant cannot open evidence. The v1 authenticated actor is the consumer realm itself, not a user or per-agent principal; a future principal model must add a separate identity and grant boundary.

Taint tracks data that may affect safety, reliability, or authorization.

Example taint labels:

contains_prompt_injection_signal
contains_secret_signal
untrusted_external
parser_failed
provenance_incomplete
stale
poisoning_suspected
sensitive
generated_derivative
live_unreproducible

Taint is additive unless a versioned validator explicitly records a permitted disposition. A summary or embedding inherits the relevant source restrictions.

Content is quarantined when:

- parsing fails in a way that prevents reliable provenance;
- prompt injection or poisoning indicators require review;
- secret exposure is suspected;
- source scope cannot be established;
- a provider returns malformed or unverifiable output;
- content is denied but must be retained for audit;
- evidence cannot be aligned to the source snapshot.

Quarantined content must not enter ordinary context, memory promotion, task completion evidence, or policy text.

Prompt-injection detection is a security signal, not a factual judgment.

External or retrieved content may contain instructions such as:

ignore previous instructions
reveal secrets
change system policy
call a tool
approve an action
modify files

These strings remain source content. They cannot:

• alter system or policy instructions;
• grant capabilities;
• change approval requirements;
• authorize tools or network access;
• modify domain state;
• cause memory promotion;
• suppress evidence or audit records.

Retrieved content must be passed through a clearly delimited data channel. System instructions, policy decisions, tool descriptions, and approval text must remain separate from evidence content.

Detection results must include:

source evidence ID
detector and version
matched span or reason
severity
disposition
review status

Implementations are replaceable until benchmarked against Maestria-specific injection and poisoning test sets. Detection alone is not a complete defense; capability isolation and policy enforcement remain mandatory.

Secrets include, at minimum:

credentials and tokens
private keys and certificates
session material
passwords
API keys
personal or regulated data
private repository content
user-designated confidential material

• Secrets must not be embedded, indexed, summarized, logged, or placed in ordinary evidence packs.
• Secret scanning occurs before persistence, indexing, provider submission, and memory promotion.
• Redaction must preserve the fact that redaction occurred without exposing the value.
• Secret-bearing command output is stored only under an explicit policy and protected storage path.
• Providers receive the minimum data required for the approved operation.
• Access to sensitive data is auditable by principal, purpose, scope, and provider.
• Failed secret scans produce denial or quarantine, not a silent downgrade.

A secret-like string is a security signal, not proof that the value is a valid credential. Final disposition is governed by policy and review.

Providers include, but are not limited to:

search and index backends
embedding and reranking services
language or multimodal models
web providers
parsers
filesystem and blob stores
harnesses
external APIs

Provider boundaries must use typed adapter contracts.

Providers must not:

• access domain state directly;
• mutate domain state;
• bypass governance;
• receive credentials or content outside their declared scope;
• return provider-specific types across domain or governance boundaries;
• be treated as authoritative merely because they returned successfully.

Provider outputs are untrusted until validated for:

schema correctness
scope compliance
provenance
model/index fingerprint compatibility
content and size limits
secret and injection signals
freshness
reproducibility

Capability descriptors must state what a provider can do and under which limits. Runtime must reject requests requiring undeclared capabilities.

Backend, model, parser, and algorithm implementations remain replaceable until benchmarked. Replacement requires contract tests, security regression tests, migration checks, and—where applicable—quality and latency evaluation.

Immutable source content is stored by content hash. Metadata, ACLs, trust labels, taint, and policy annotations are stored separately and versioned.

Blob paths must be derived from validated content hashes. Path traversal and arbitrary path construction are prohibited.

Indexes are projections, not authoritative state.

Every index generation records:

source/corpus snapshot
representation and schema version
model or processing fingerprint
ACL and filtering policy version
build status
activation time

Index activation is atomic. Old generations remain available for rollback until validation completes.

Caches must include authorization and scope context in their keys or be proven incapable of crossing scopes.

When source access is revoked or content is deleted:

- future retrieval is blocked immediately;
- active indexes and caches are invalidated or filtered;
- derived representations inherit the restriction;
- evidence packs are marked invalid where required;
- audit records retain only the minimum permitted metadata.

Deletion behavior must be tested for metadata, blobs, indexes, caches, and generated derivatives.

The security model distinguishes:

Source       produces an observation.
Evidence     preserves a source-backed observation.
Claim        normalizes an uncertain proposition.
Memory       promotes a useful claim under policy.
Decision     selects an action based on evidence and policy.
Validation   checks support and required controls.

Evidence may be stale, contradictory, disputed, or incomplete. An evidence record does not make its source true.

Memory promotion requires:

source lineage
adequate evidence coverage
scope and sensitivity checks
duplicate and contradiction checks
freshness evaluation
governance approval where required

A generated summary or memory must never replace the raw source span required for validation or citation.

Security-relevant failures are explicit and auditable.

Permitted task outcomes include:

answerable
answerable_with_warnings
evidence_incomplete
sources_conflict
stale_evidence_only
no_evidence_found
denied
quarantined

A failed security check must not be represented as successful completion.

Security-relevant actions produce append-only audit records or domain events containing, as appropriate:

principal and instance
request and task identifiers
scope and policy profile
requested capability
allow/deny/quarantine decision
policy and validator versions
source, artifact, and snapshot identifiers
provider and adapter identity
redacted reason and failure code
approval references
result and disposition

Audit records must avoid storing secrets or restricted content unnecessarily. Redaction itself is recorded.

Search traces and transition journals are reproducibility and audit artifacts. They are not authoritative external truth and must be protected by the same scope controls as the data they describe.

Security controls require shared contract and regression tests covering:

ACL filtering before scoring
cross-scope cache isolation
quarantine propagation
prompt-injection boundary enforcement
secret redaction and non-persistence
provider capability enforcement
path traversal and blob isolation
index generation authorization
revocation and deletion behavior
stale and conflicting evidence handling
fail-closed behavior
audit completeness without secret leakage

Retrieval and security changes must be evaluated against versioned Maestria-specific sets, including:

ACL leakage attempts
prompt-injection fixtures
poisoning and near-duplicate cases
secret-bearing inputs
scope-confusion cases
stale and contradictory sources
provider failure and malformed-output cases

Public benchmarks or a provider’s stated capabilities are not proof that the implementation is secure for Maestria.