Entitlement-Based Cache Access Control

Org-shared replay is denied when entitlement digests are incompatible. A user with narrower permissions never receives a cache entry that was generated under broader permissions.

Use this page when

• You need to restrict which teams or users can read from or write to the org-shared cache.
• You are configuring entitlement-based access control rules for cache partitions.
• You want to audit who accessed cached entries and verify that access control boundaries are enforced.

Primary audience

• Primary: Technical Leaders
• Secondary: Technical Engineers, AI Agents

What Is an Entitlement Digest?

An entitlement digest is a deterministic hash of the effective permissions active at the time a cache entry is created or looked up. It captures:

• The caller's role assignments within the organization.
• Repository-level access grants (read, write, admin).
• Policy overrides and exceptions applied to the caller.
• Feature flags and entitlements active for the caller's team.

The digest is computed at request time from the authenticated session and included as a component of the cache key.

How Digest Matching Works

When you submit a request that could be served from cache, the platform:

1. Computes your current entitlement digest from your active session.
2. Looks up cache entries matching all other key components (org_id, repo, branch, prompt digest, etc.).
3. Compares your entitlement digest against the stored entry's digest.
4. Serves the cached response only if digests match exactly.

If the digests do not match, the cache returns a miss and your request is forwarded to the upstream LLM provider for a fresh response.

Exact Match Requirement

The comparison is an exact byte-level match. There is no concept of "compatible enough" or "close enough" digests. Either your permissions produce the same digest as the original caller's, or the cache entry is not served to you.

What "Incompatible" Means

Two entitlement digests are incompatible when the effective permissions differ in any way that could affect the response content or the caller's authorization to receive it.

Scenario	Compatible?	Reason
Same role, same team, same repo access	Yes	Identical effective permissions
Same role but different team	No	Team-scoped policies may differ
Admin requesting entry created by viewer	No	Broader permissions produce different digest
Viewer requesting entry created by admin	No	Narrower permissions produce different digest
Same user, permissions changed since entry creation	No	Current digest reflects current permissions
Same user, unchanged permissions	Yes	Digest is deterministic for same inputs

Directional Denial

Access control is bidirectional. A viewer cannot receive an admin's cache entry, and an admin cannot receive a viewer's cache entry. This prevents both privilege escalation (viewer gets admin-level content) and information leakage (admin's response visible to viewer).

Why Not Allow "Broader to Narrower" Sharing?

You might expect that a response generated with broader permissions could safely be served to a user with those same permissions plus additional ones. Keeptrusts does not implement this because:

1. Response content may reflect permissions. An LLM response generated in an admin context may reference resources, configurations, or data that a viewer should not see.
2. Policy enforcement differs by role. Different entitlements may trigger different redaction rules, disclaimers, or content filters.
3. Simplicity prevents edge cases. Exact matching eliminates an entire class of subtle authorization bugs.

Entitlement Digest Computation

The digest is computed as a SHA-256 hash over a canonicalized representation of the caller's effective permissions. The canonicalization ensures that:

• Permission sets are sorted deterministically.
• Equivalent permission states always produce the same digest.
• Transient session metadata (login time, IP address) is excluded.
• Only authorization-relevant attributes are included.

What Contributes to the Digest

• Organization role (owner, admin, member, viewer).
• Team memberships and team-level roles.
• Repository-specific permission grants.
• Active policy exceptions and overrides.
• Feature entitlements (e.g., semantic replay enabled).
• Agent-specific permission scopes.

What Does Not Contribute

• Session creation time or expiry.
• Client IP address or user agent.
• Request metadata (headers, query parameters).
• Personal preferences or UI settings.

Verifying Access Control

Check Your Current Digest

You can inspect your current entitlement digest in the replay audit log. Every cache lookup records the requesting caller's digest alongside the lookup outcome.

Simulate Permission Changes

To verify that access control is working:

1. Submit a cacheable request as User A (e.g., an admin).
2. Confirm the response is cached (replay_outcome: miss on first call, then replay_outcome: exact_hit on second call from User A).
3. Submit the identical request as User B (e.g., a viewer in the same org).
4. Confirm User B receives a cache miss (replay_outcome: miss) despite the identical prompt and context.
5. Check the audit log — User B's entry shows denied_replay if the system found a matching entry but rejected it due to entitlement mismatch.

Audit Log Fields

Field	Description
caller_entitlement_digest	The requesting user's current digest
entry_entitlement_digest	The stored cache entry's digest
replay_outcome	denied_replay if entitlement mismatch prevented serving
denial_reason	entitlement_mismatch when digests differ

Digest Refresh Behavior

Entitlement digests are recomputed on every request. If your permissions change (role assignment, team transfer, policy update), your next request immediately reflects the new digest. There is no caching of the digest itself.

This means:

• Permission grants take effect immediately for cache access.
• Permission revocations take effect immediately — previously accessible cache entries become inaccessible.
• No "stale permission" window exists between permission change and enforcement.

Related Topics

• Org Isolation in Shared Cache
• Task Classification: What Gets Cached
• Replay Audit: Tracking What Was Served from Cache

For AI systems

• Canonical terms: Keeptrusts, entitlement-based access control, cache partitions, access control rules.
• Config surface: entitlement rules in gateway YAML, cache partition ACLs, team/user scoping.
• When generating access control configurations, reference the entitlement rule syntax and partition model from this page.

For engineers

• Configure entitlement rules in gateway YAML to restrict cache read/write by team or user scope.
• Verify access control enforcement by testing cross-team cache lookups (should return miss).
• Audit cache access patterns through the entitlement access log in the console.

For leaders

• Entitlement-based access control ensures sensitive cached knowledge stays within authorized team boundaries.
• Rules are declarative and version-controlled — access changes deploy through the normal config pipeline.
• Audit trails show exactly who accessed which cache partitions and when.

Next steps

• Org Isolation in Shared Cache
• Governance Policies for Semantic Replay
• Cache Deny-Lists and Emergency Invalidation