Caching decisions

A mobile UI re-checks the same permissions constantly — every re-render, every list row, every navigation. The opt-in decision cache makes the repeats free, without ever letting a stale or synthetic verdict turn a deny into an allow.

Motivation

usePermission already skips a refetch when the query is unchanged (it keys its effect on a stable serialisation). But across components — ten rows each asking doc.read, a header and a screen both asking panel.view — the same query still hits the network once per caller. A short-lived cache on the client collapses those into one round-trip while a TTL keeps verdicts fresh.

Turn it on

The cache is off by default. Enable it on the client:

const iam = new IamClient({
  baseUrl: 'https://iam.example.com/api/iam/v1',
  token: process.env.IAM_SERVICE_TOKEN,
  cache: { ttlMs: 5000, maxEntries: 1000 }, // 5s TTL, ≤1000 entries (default cap 1000)
});

How the key works (RN-safe)

The Node SDK hashes the query with node:crypto SHA-256. Hermes has no node:crypto, so this SDK keys on a canonical JSON string of the full payload instead — keys sorted, recursive, order-independent.

// cacheKey({ permission: 'p', subject: { id: 'u', type: 'user' } })
// → '{"permission":"p","subject":{"id":"u","type":"user"}}'   (stable regardless of input order)

Functionally identical to the hashed key for an in-memory Map: the same query always maps to the same entry. See RN-safe: no node:crypto.

What is — and isn’t — cached

Three rules keep the cache safe:

• Transport-error denies are never stored. A deny born of an outage must not outlive it. Only real server verdicts enter the cache.
• explain queries bypass the cache entirely — both on read and write — so a diagnostic call always reflects the live policy.
• A newer policyVersion flushes everything. When the server returns a higher policy generation than the cache has seen, the whole cache is cleared before the new entry is stored — a policy change can’t be shadowed by stale entries.

The policy-version flush, formally

Let $p_c$ be the highest policyVersion the cache has observed and $p_d$ the version on an incoming decision. On set:

So the maximum staleness of any allow is bounded by $\min(\texttt{ttlMs},\ \text{time to the next policy bump})$ — and a revocation that bumps the policy version is reflected on the very next decision.

Worked example: a list that checks once, not per row

// client has cache: { ttlMs: 5000 }
function DocRow({ doc }: { doc: Document }) {
  const { allowed } = usePermission('doc.read', { type: 'document', id: doc.id });
  return allowed ? <Text>{doc.title}</Text> : null;
}

Distinct doc.ids still produce distinct keys (one check each), but a re-render, a scroll that remounts rows, or two components asking the same {permission, resource, subject} now serve from cache for 5 seconds — no extra network calls, same fail-closed verdicts.

ADR: a cache that can only shorten the life of an allow

Gotchas

Next steps

• Caching safely — choosing TTLs and the revocation story.
• The decision model — what policyVersion is and why it flushes.
• RN-safe: no node:crypto — the canonical-JSON key.