Authority Invalidation Architect

---
name: authority-invalidation-architect
description: 'Diagnose and design the fix for the "change didn''t take effect" access-bug class — a removed user still sees the data, a revoked role still works, logout doesn''t end the session, a plan change still shows the old tier, a deleted item stays visible: inventory every place the old authority survives (server session records, JWT/token claims until expiry, client-side stores and data caches, server/CDN caches, live realtime subscriptions, database session context, search indexes, signed URLs), locate which holds the stale copy, design the invalidation or forced refresh per surface against a stated revocation-latency bound (deny direction first: revoked access must actually revoke), and verify with before/after tests that access changed. Composes caching-strategy-designer, realtime-subscription-architect, plan-entitlement-architect, share-link-access-architect, rls-policy-auditor. Do NOT use to design a cache, author the permission matrix, or when access never worked — this owns changes that failed to propagate.'
---

# Authority Invalidation Architect

## Purpose

The bug class this skill owns is silent by construction: an authority change
— a member removed, a role revoked, a logout, a plan change, a deletion —
that did not take effect somewhere, so old authority keeps working. The
removed user experiences nothing broken and reports nothing; the owner
believes the change worked; the app keeps honoring a copy of authority that
no longer exists in the database. That is unauthorized access to tenant data
arriving through time instead of through a query, and its victims cannot
name the mechanism — which copy, of the many the platform minted for them,
is the one still alive. This skill owns the lifecycle CHANGE → PROPAGATE →
VERIFY: classify the change and its direction, inventory every place old
authority survives, locate the holder, design the invalidation or forced
refresh per surface against a stated revocation-latency bound (deny
direction first), and prove the change took effect with a cross-surface
verify battery. The per-surface mechanism owners are composed, never
restated; this skill contributes the surfaces nothing else owns —
token-claims staleness, server-session versioning, client-state purge — and
the differential and verify battery no single-surface skill can see whole.

## Use When

- Use when: a removed user or member can still see or reach data, a revoked
  role or permission still works, or an access change "didn't take effect"
  or "didn't propagate".
- Use when: logout doesn't end the session — still signed in on another tab
  or device, or a replayed old cookie/token still works.
- Use when: a plan change doesn't show — upgraded but still the old tier,
  downgraded but the old limits still apply (triage starts here; the
  plan-resolution mechanics route onward).
- Use when: a deleted or archived item stays visible — in the app, in
  search results, or through an old link or URL.
- Use when: a change takes effect only after refresh or re-login, or works
  for the person who made it but not for other users or devices —
  propagation happening by accident, not by design.
- Use when: designing revocation propagation deliberately — the mechanism
  by which removing a membership kills its effect in active sessions and
  issued tokens (the mechanism `authorization-matrix-designer` requires you
  to state), a stale-claims policy, or purge-access-state-on-change.
- Do NOT use when: access never behaved correctly — there is no
  before-state in which it worked. That is authorization correctness, not
  propagation: `authorization-matrix-designer` (the matrix) or
  `rls-policy-auditor` (the policy SQL). The discriminator question: did it
  behave correctly before the change?
- Do NOT use when: adding or designing a cache, choosing TTLs, keys, or
  layers — `caching-strategy-designer`; its output is one surface in this
  skill's inventory, not the other way around.
- Do NOT use when: a live channel delivers another tenant's data — that is
  a cross-tenant leak, not a stale change: `realtime-subscription-architect`.
- Do NOT use when: designing plans, limits, and metering —
  `plan-entitlement-architect`.
- Do NOT use when: a credential leaked and needs rotation or custody fixes
  — `secrets-identity-hardener` (manual-only).
- Do NOT use when: an unknown-cause failure has no authority-change shape —
  `systematic-debugger` is the generic method; this skill is the domain
  differential for this symptom family and composes that method's evidence
  discipline where the holder is ambiguous.

## Inputs to Inspect

1. The auth mechanism, before anything else: server-side sessions or
   stateless tokens (JWT)? If tokens — exactly which claims are minted at
   sign-in (role? tenant? plan?) and the access/refresh TTLs. This one fact
   usually names the staleness window.
2. Every authority-change path: member-removal and role-change UI, billing
   webhooks, admin and support tooling, background jobs, bulk imports —
   each is either a propagation trigger or a propagation hole.
3. The client data layer: state stores, query/data-cache libraries (e.g.
   React Query, SWR, Apollo), persisted storage — and what, if anything,
   clears each on logout or on an authority change.
4. Server and shared HTTP/CDN caches in play, with their keys and TTLs
   (the design from `caching-strategy-designer`, where one exists).
5. Live surfaces: realtime channels and presence — their subscribe-time
   authorization and whether anything re-checks mid-connection.
6. The database's authorization context source: the session settings or
   token claims that RLS policies read, and connection-pool context reset
   behavior.
7. Secondary copies: search indexes, signed URLs and file CDN, share
   links, exports.
8. The incident specifics: who changed what, when, which surface still
   shows old authority, and the tells — works in incognito? fixes itself
   after re-login or "overnight"? wrong on one device only?

## Workflow

1. **Classify the change, and take the deny direction first.** Which
   event: member removal, role/permission revoke, logout, plan change,
   deletion, share revoke — and which direction failed: deny (the removed
   must LOSE access — the security case) or grant (the added must GAIN —
   the UX case). Deny gets designed and verified first. Run the
   discriminator now: if access never behaved correctly, stop and route
   (Stop Conditions).
2. **Build the surface inventory.** From
   [references/stale-authority-surface-map.md](references/stale-authority-surface-map.md):
   server session records; JWT/token claims; client stores and data
   caches; shared HTTP/CDN caches; in-process/distributed server caches;
   database session context; live realtime subscriptions; share links;
   entitlement resolution; search indexes; signed URLs. Mark which exist
   in THIS app — a surface that exists and is never dispositioned is the
   next incident.
3. **Locate the holder — the differential.** Use the tells: works in an
   incognito window → a client-side copy; fixes itself after a consistent
   interval → token claims (the interval is the access TTL) or a cache
   TTL; stops after reconnect → a live subscription; wrong on one app
   instance only → an in-process cache; wrong only in search → the index.
   Where evidence is ambiguous, compose `systematic-debugger`'s
   prediction-testing; this map supplies the hypotheses it ranks.
4. **State the revocation-latency bound.** Per change type, in writing,
   with an owner-confirmed number: "removed from a workspace means
   unreachable on every surface within N seconds." The deny-direction
   bound is the tightest and is a security parameter, not a tuning knob.
   This is the sibling of `caching-strategy-designer`'s consistency
   envelope, applied to authority — without the number, "immediately"
   silently becomes "at token expiry".
5. **Design propagation per surface — own the unowned, compose the
   owned.** The three surfaces this skill owns outright:
   - **Token/claims staleness.** If authority (role/tenant/plan) is baked
     into a stateless token, revocation latency equals the access-token
     TTL unless a server-side check exists. The menu, chosen against step
     4's bound: (a) short access TTL + refresh rotation — simplest;
     latency floor = the TTL; authority re-resolved at refresh time;
     (b) session-version / epoch — bump a per-user (or per-tenant)
     version on every authority change and check it server-side on each
     request — near-immediate; costs one indexed read per request, and
     that read must not itself be cached into staleness; (c) denylist the
     affected principal's tokens until natural expiry — targeted; needs a
     fast shared store; doubles as the logout kill. State the chosen
     latency; never imply immediate revocation from a stateless token
     alone.
   - **Server session records.** Logout and revocation invalidate
     server-side — the session record is deleted or version-bumped so a
     replayed cookie or token fails. Clearing the client is presentation,
     not revocation. Custody implementation hands to
     `secrets-identity-hardener` (manual-only) with the control named.
   - **Client-state purge.** On logout AND on received authority-change
     events: purge the query/data caches, state stores, and persisted
     storage carrying the old view. The server cannot reach these copies
     — design the signal (an authority-change event on an existing
     realtime channel, an authority version stamped on responses, or
     re-check on focus/refetch) plus the purge it triggers. The
     acceptance test is the shared-device case: sign in as a different
     user and nothing of the previous user's data renders.
   The per-surface owners are composed, never restated: shared/server
   cache purge mechanics → `caching-strategy-designer` (its
   authorization-caching Safety Rule governs any proposal to cache authz
   — cite it, never re-approve it here); mid-connection re-auth and
   subscription teardown → `realtime-subscription-architect`; plan
   resolution, plan-change invalidation, and billing-webhook lag →
   `plan-entitlement-architect`; share-link revocation →
   `share-link-access-architect`; RLS policy correctness →
   `rls-policy-auditor` (this skill owns the FRESHNESS of the claims and
   context feeding those policies, plus pool context reset); search-index
   deletion → `search-architecture-designer`; signed URLs and file CDN →
   `file-upload-storage-architect`.
6. **Design the verify battery — per surface, changed principal, deny
   first.** For the actual changed principal (not a fresh test user):
   before/after probes per inventoried surface — the API read is denied;
   the pre-change token/cookie is rejected within the bound; live events
   stop arriving; the client renders nothing stale after the purge
   signal; the search hit is gone; the old signed URL no longer resolves.
   Then the positive control (an unaffected user is unaffected) and the
   grant direction (a newly added member gains access without re-login,
   or the designed latency is stated). `authorization-matrix-designer`'s
   revoked-membership negative tests are the design-time DB/API subset of
   this battery; this step extends them across every live surface.
7. **Hand off implementation.** Deliver named controls: session/token
   custody changes → `secrets-identity-hardener`; cache, channel, plan,
   link, and index changes → their owners' outputs; anything touching
   live production state follows the ops approval path. This skill
   designs and specifies verification — it executes nothing against live
   systems.

## Output Format

```
AUTHORITY INVALIDATION DESIGN — <incident / change type>
Change: <removal|revoke|logout|plan-change|deletion|share-revoke> —
  direction: <deny|grant|both>; never-worked check: <behaved correctly
  before the change? yes → proceed | no → routed>
Revocation-latency bound: "<change> means <effect> on every surface within
  <N seconds>" (owner-confirmed)
Surface inventory (every row dispositioned):
  <surface> — exists? <y/n> — holder? <yes: evidence/tell | ruled out: how>
    invalidation: <owned design here | composed → owning skill>
    latency: <fits the bound? actual window>
    verify: <the before/after probe, deny direction>
Token/claims policy: <short-TTL+refresh | session-version/epoch | denylist>
  → revocation latency = <value>; logout kill = <mechanism>
Server sessions: <invalidated on logout/revoke; replay rejected>
Client purge: <signal → what is purged>; shared-device test: <designed>
Verify battery: <per-surface probes for the changed principal, deny then
  grant, plus the positive control>
Handoffs: <secrets-identity-hardener (custody impl) |
  caching-strategy-designer (cache mechanics) | realtime / plan /
  share-link / rls / search / file owners as routed>
```

## Validation Checklist

- [ ] The deny-direction revocation-latency bound is stated as a number
      and owner-confirmed — not "immediately", not implied.
- [ ] Every surface in the inventory is dispositioned — holder, or ruled
      out with evidence; none skipped because "we probably don't cache
      that".
- [ ] The token policy is chosen with its tradeoff and resulting latency
      stated; a stateless token is never presented as immediately
      revocable.
- [ ] Logout invalidates the server session, not just client state;
      replay of the old cookie/token is tested as rejected.
- [ ] Client purge fires on both logout and authority-change; the
      shared-device (next-user) case is in the battery.
- [ ] The battery tests the CHANGED principal per surface, deny direction
      first, then grant direction, plus a positive control.
- [ ] Composed surfaces are routed with their owner named — no cache-TTL,
      RLS-SQL, plan-resolution, or link-token content restated here.
- [ ] The never-worked discriminator was actually asked and recorded.

## Security Rules

- The deny direction is this skill's priority ordering: revoked access
  must actually revoke. Old authority honored after a change is
  unauthorized access to tenant data — the tenant-isolation harm arriving
  through time.
- A propagation design without a stated latency bound is not a design; it
  is the current bug with better documentation.
- UI disappearance is never propagation. Hiding the button, the menu
  item, or the list row while the session, token, or API still honors the
  old authority is the illusion of revocation.
- A stateless token's revocation latency is its access TTL unless a
  server-side check (session-version, denylist) exists — state which, and
  the resulting number, every time.
- Logout is a revocation event held to the same standard: it ends the
  server session and purges client state; anything less leaves the
  account open on the next shared device.

## Gotchas

- JWT claims are stale by design, not by bug: role/tenant/plan claims
  minted at sign-in do not observe the database change; managed-auth
  platforms (e.g. Supabase, Firebase) default access TTLs around an hour
  — the removal "not working" often just IS that TTL, chosen by nobody.
- The open-tab problem: a removed user's already-loaded app keeps a
  working token and rendered state; with no per-request server check and
  no purge signal, they retain full access until the token expires — no
  refresh needed on their part.
- The next-user-on-a-shared-device leak: persisted client caches survive
  logout, so signing in as user B briefly (or fully) renders user A's
  data. Purge on logout is a privacy control, not a nicety.
- Pooled database connections reuse session context: authorization
  context set for one request can leak into the next if the pool doesn't
  reset on checkout — the RLS policy is correct; its input is stale.
- Authority-change events not emitted from every change path — the admin
  bulk tool, the billing webhook, the support script: the
  missed-mutation-path class `caching-strategy-designer` names for caches
  applies equally to authority signals, and one missed path is a
  permanent hole.
- "Works in incognito" is diagnostic gold: a fresh profile has no client
  state and no cookies, so if incognito behaves correctly the holder is a
  client-side copy; if incognito is also wrong, the holder is
  server-side.
- The grant direction embarrasses quietly: the newly invited member can't
  see the workspace until they sign out and back in, because their claims
  were minted before the invite — the same mechanism as the security
  case, opposite direction, and usually the first symptom anyone actually
  reports.

## Stop Conditions

- Access never behaved correctly — no before-state in which the
  permission worked → stop; that is `authorization-matrix-designer` /
  `rls-policy-auditor` territory. This skill owns changes that failed to
  propagate, not authority that was never wired.
- Asked to execute the purge NOW against live systems — flush a
  production cache, kill live sessions, force-expire real users' tokens →
  stop; the design is the deliverable, execution follows the ops approval
  path (`human-approval-boundary`). Killing every session is a
  mass-logout event a human must own.
- A proposed "fix" is to cache an authorization result →
  `caching-strategy-designer`'s Safety Rule governs (an explicit approved
  envelope with a revocation-propagation bound); never green-light it
  from here.
- No owner will confirm a revocation-latency number → present the
  per-change default menu with consequences and stop; do not invent a
  deny-direction tolerance on anyone's behalf.
- The evidence shows a live cross-tenant leak (not stale authority of a
  formerly entitled principal) → stop and route to the isolation path —
  `rls-policy-auditor` / `tenant-isolation-reviewer` — that is an active
  incident, not a propagation design task.

## Supporting Files

- [references/stale-authority-surface-map.md](references/stale-authority-surface-map.md)
  — the per-surface map: where the old copy lives, the diagnostic tell,
  the invalidation options, the verify probe, and the owning skill to
  compose.
- `evals/evals.json` — behavior cases: the removed-user-still-sees
  diagnosis, the logout/shared-device edge, the cache-design non-trigger,
  and the live-purge stop.
- `evals/trigger-evals.json` — discrimination against
  `caching-strategy-designer`, `authorization-matrix-designer`,
  `rls-policy-auditor`, `realtime-subscription-architect`,
  `plan-entitlement-architect`, `share-link-access-architect`,
  `secrets-identity-hardener`, and `systematic-debugger`.