prove-tenant-isolation-read-paths

Adds cross-tenant isolation test cases for every API route and R2/D1 key builder.

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/shuddl/shuddl-os --skill prove-tenant-isolation-read-paths-shuddl
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: prove-tenant-isolation-read-paths
Source: https://github.com/shuddl/shuddl-os/tree/main/.claude/skills/prove-tenant-isolation-read-paths
Command: npx skills add https://github.com/shuddl/shuddl-os --skill prove-tenant-isolation-read-paths-shuddl

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Multi-tenant systems can silently leak one tenant's data to another when a read path or storage key builder drops the tenant prefix, and such regressions can ship green if no test covers them. This Skill enforces REQ-025 by requiring a proven isolation test case for every route and R2/D1 key builder that touches tenant-scoped storage. ## Core Features & Use Cases - Read-path registry: Maintains a registry of every tenant-scoped read path (routes, key builders, D1 loaders) with its required test cases, updated in the same PR as the code. - Attack-shape matrix: Defines the adversarial cases every route must pass — client tenant header, query param injection, forged tokens, unsigned tokens, and cross-tenant IDs under a valid session. - Key-builder unit assertions: Adds literal string assertions that R2 key builders embed the tenant prefix, catching regressions route tests cannot see. - Use Case: When adding a new API route that reads session.tenant or a new R2 key template like evidence/${tenant}/..., use this Skill to add the matching isolation tests and registry row before merging. ## Quick Start Ask the AI to prove tenant isolation for the new route you just added by generating the attack-shape test cases and updating the read-path registry.

Frequently Asked Questions about prove-tenant-isolation-read-paths

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test tenant isolation for a new API route?▼

Add a route case covering all attack shapes: X-Tenant-Id header, ?tenant= query param, forged token with wrong secret, unsigned token, and a cross-tenant ID in the path under a valid session. Each client-supplied tenant must be rejected with 403 or ignored, never used to re-key the store.

Why do route tests alone not catch a dropped tenant prefix in R2 keys?▼

If both tenants' stores are empty, both return 404 and the test passes even with a dropped ${tenant} segment. A key-builder unit test asserting the literal key string, and that two tenants never produce the same key, is the only net that catches this.

What attack shapes must every tenant isolation test cover?▼

Four shapes: client tenant header (X-Tenant-Id), client tenant query param, forged token signed with the wrong secret, and unsigned garbage token. Tenant identity must come only from the verified JWT claim via session.tenant or tenantDb.

When should the read-path registry be updated?▼

In the same PR that adds the read path, since REQ-025 is a per-merge gate. At work-package exit, grep every route for session.tenant and every key builder with a ${tenant} segment; each must have a registry row and test case.

Can a stale registry claim a test gap that does not exist?▼

Yes. Before treating a missing-case row as a work item, mutate the key builder and run the suite — incidental nets like hardcoded test literals may already catch the regression. The registry should record the mechanism of each catch, not just its polarity.