Access control at retrieval

The leak

Filter after, and it leaks

Same question, same corpus, one switch. Watch what rides into the answer when the filter runs after retrieval instead of inside it.

• Filter at retrieval (ON). The query itself excludes anything the caller can’t see. The model only ever receives passages it’s allowed to read.
• Filter after (OFF). The model retrieves everything, then is told to hide the restricted parts. It doesn’t reliably obey — and the restricted text is already in its context.
• Two ways to leak. A role leak (the underwriting memo reaching a broker) and a cross-tenant leak (another insurer’s claim reaching you).
• The point. “The model saw it but chose not to say it” is not access control. Not-retrieved is the only safe state.

With the filter off, the broker’s answer quotes an underwriting risk memo and a claim from another insurer — because the model saw both, and “please hide them” is not a security control. With the filter on, those documents are never retrieved, so they can’t leak. The safe answer and the leaky answer differ by one thing: where the check runs.

Provenance

The filter is built from the token, never the prompt

The permission check is compiled from the caller’s signed identity — tenant, environment and roles — resolved from a verified token (a JWT in production). The question the user typed can never widen access.

• Signed token, not text. Tenant, env and roles come from verified claims. The question is data to answer, never a source of permissions.
• Identity → RetrievalFilter. The token resolves to an Identity, and build_filter turns it into the exact RetrievalFilter pushed into the search.
• Three conditions, all required. Scope match (tenant and env), role overlap (chunk.acl_roles ∩ roles ≠ ∅), and an optional doc-type narrowing.
• Fail closed. No roles → the filter matches nothing. The default is deny, never allow — an empty role list must not become an open door.

build_filter fails closed on empty roles; is_visible is the one definition of “allowed” both stores share — the local store calls it directly, and the production store encodes the same scope + role test as a boolean filter query:

def build_filter(identity: Identity, *, doc_types: set[str] | None = None) -> RetrievalFilter:
    if not identity.roles:
        # No roles => can retrieve nothing. Fail closed, never open.
        return RetrievalFilter(scope=identity.scope, roles=frozenset(), doc_types=frozenset())
    return RetrievalFilter(
        scope=identity.scope,
        roles=frozenset(identity.roles),
        doc_types=frozenset(doc_types) if doc_types else None,
    )


def is_visible(chunk_scope, chunk_roles: frozenset[str], flt: RetrievalFilter) -> bool:
    if chunk_scope != flt.scope:       # 1. tenant + env must match
        return False
    if not (chunk_roles & flt.roles):  # 2. at least one role must overlap
        return False
    return True

And the retrieve node uses it in exactly one place — the filter is derived from the identity, then pushed into the search call, not applied to the results afterward:

def run(state: QueryState, settings, *, embedder: Embedder, store: VectorStore) -> dict:
    identity = state["identity"]
    # The filter is derived only from the signed identity. Fail-closed logic
    # (no roles => no results) lives in build_filter / the store.
    flt = build_filter(identity)

    queries = state.get("sub_queries") or [state.get("question", "")]
    best: dict[str, Retrieved] = {}
    for q in (q for q in queries if q and q.strip()):
        vec = embedder.embed_query(q)
        for hit in store.search(vec, flt, k=settings.retrieve_k):  # filter pushed into the query
            best[hit.chunk.chunk_id] = hit
    return {"retrieved": list(best.values())}

Isolation

Tenant and env are partition keys, not afterthoughts

The same scope check that stops role leaks stops one insurer from ever seeing another — and dev from ever leaking into prod. Every document, chunk and query carries a TenantScope (tenant + env), and the vector index is namespaced tenant__env.

• Namespace = tenant__env. The index is partitioned by it, so acme__prod and fjord__prod don’t share storage — a query for one can’t reach the other.
• Scope is a mandatory filter. Retrieval always filters on scope — no scope, no results. There is no “search across everything” path to get wrong.
• Envs are isolated too. dev, qa and prod are separate scopes. A test document in dev can never surface in a prod answer.
• Deletes really delete. When the data lake sends a delete tombstone, the document leaves the index for that scope — a redacted claim stops being retrievable, the governance story that matters in insurance.

@dataclass(frozen=True, slots=True)
class TenantScope:
    tenant_id: str
    env: str  # e.g. "dev", "qa", "prod"

    def namespace(self) -> str:
        """Vector-store namespace / index suffix for this scope."""
        return f"{self.tenant_id}__{self.env}"

git clone https://github.com/xaviramirezcom/open-ai-overview
cd open-ai-overview
git checkout v4-access-control
pip install -e ".[local]"

# Broker: policy only — the underwriting risk memo is never retrieved
own-overview query "Why did POL-55012's premium rise?" \
  --tenant acme --env prod --role broker

# Underwriter: same question, now the risk memo is in scope
own-overview query "Why did POL-55012's premium rise?" \
  --tenant acme --env prod --role underwriter

{"timestamp":"2026-08-13T18:04:11Z","user_id":"u_88","tenant":"acme","env":"prod",
 "question":"Why did POL-55012's premium rise?","retrieved_chunk_ids":["POL-55012#0"],
 "groundedness":0.94,"abstained":false}

Explain it back

A teammate says: “We already tell the model, in the system prompt, to never reveal anything the user isn’t cleared for. Isn’t that access control?” What’s wrong with that, in one breath?