Run it

Security model

Strangers get no map. Not even a wrong one.

In short

  • What fyrr trusts and what a deployment must protect itself: provider code, the embeddings and reranker services, the bucket and the reader mirror.
  • How reader tokens, subjects, permission modes and freshness deadlines decide who may read what, and when a revocation reaches readers.
  • How secrets, stored credentials and provider workers are handled.

To report a vulnerability, see SECURITY.md. Serving many users over HTTP is in HTTP login and users.

Trust boundaries

Principals and reader tokens

Reader tokens and principals are checked at the authorization gates.

A subject is the caller of a request:

A subject with more than identity.max_tokens_per_user reader tokens (5000 by default) is refused with authorization_unavailable; other subjects are unaffected.

Permission modes

Each source is either:

Restricted parts of a document, such as a comment with its own audience, are separate records with their own readers. Public and link-only sharing, unknown identities and unsupported holder types grant nobody.

Freshness and revocation

The authorization gates themselves are described in How fyrr works. What a deployment has to plan for:

Source polling

Connectors reuse permission and membership snapshots read during a sync run, so a rights change at the source during that run may still leave old grants in its publication. Revocation takes effect after the next successful sync of that source that reads the changed rights and a commit publishes them; Keycloak membership changes similarly need a successful directory pull and commit. Sync intervals alone provide no end-to-end wall-clock bound.

Canonical directory

identity.directory.provider selects where canonical users and groups come from: none, a snapshot file, a keycloak realm, or scim pushes to the writer's SCIM 2.0 endpoint. Source users link to canonical users through explicit account links in the directory snapshot, or through an e-mail address that the source reports as verified and organization-managed in an approved domain (verified_domains). Personal or unverified addresses never link. An inactive canonical user is denied everywhere. The keys are in identity.

Secrets and stored credentials

Worker isolation

All Python runs in fyrr writer __worker child processes, one per source (provider discovery uses its own worker), with a timeout that also kills descendants, a memory limit (writer.worker_memory_max_bytes), no core dumps and provider stdout and stderr discarded. Results return over a size-capped socket with fixed diagnostic codes, never Python exception text. A crash or hang fails only that source.

The deployment guide covers reader hosts; the reader settings specify mirror ownership and modes.

HTTP boundary

See HTTP boundary for host and origin checks, request limits, readiness and administration, and tokens for access-token validation.

A caller can still infer shared query-embedding cache membership by choosing a deadline_ms shorter than provider latency and observing whether dense retrieval degrades.

Opt-in object-store diagnostics write only method names, hashed keys, numeric transport facts and fixed error codes to an operator-owned private file. They never format backend errors or record bodies, headers or credentials. Treat key hashes and operational timing as restricted operator metadata and configure log retention accordingly.

Edit this page on GitHub ↗