tenancy

name	tenancy
description	Use when creating, updating, reviewing, or debugging multi-tenancy, tenant isolation, tenantId scoping, organization data access, row-level security, tenant-aware cache keys, or cross-tenant security.

Tenancy

Use this skill for safe multi-tenant data isolation.

Rules

• Follow the project’s existing tenancy model.
• Do not introduce a new tenancy architecture unless explicitly requested.
• Never trust tenant, organization, workspace, or account IDs from client input alone.
• Derive tenant scope from verified auth/session/context.
• Every tenant-owned query must be scoped.
• Prevent cross-tenant reads, writes, updates, deletes, joins, exports, and background jobs.
• Include tenant scope in cache keys for tenant-owned data.
• Include tenant scope in queue/job payloads when needed.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing tenancy-related code, check existing patterns for:

• tenant identification
• auth/session tenant context
• organization/workspace membership
• database scoping
• repository filters
• joins and relations
• cache keys
• background jobs
• admin/super-admin behavior
• tests for cross-tenant access

Implementation Checklist

• Identify the trusted tenant source.
• Pass tenant context explicitly through layers.
• Scope all tenant-owned reads and writes.
• Verify related records belong to the same tenant.
• Protect joins and nested queries.
• Scope cache keys by tenant.
• Scope background jobs by tenant.
• Add permission checks for tenant switching or admin access.
• Add or update cross-tenant tests.

Query Rules

• All tenant-owned tables/entities must be queried with tenant scope.
• Updates and deletes must include tenant scope, not only record ID.
• List queries must be tenant-scoped.
• Detail queries must be tenant-scoped.
• Joins must not pull related records from another tenant.
• Search, filters, exports, reports, and counts must be tenant-scoped.
• Unscoped admin queries must be explicit, privileged, and reviewed.

Security Rules

• Do not accept tenant scope from request body as trusted.
• Do not let users choose arbitrary tenant IDs.
• Verify user membership before allowing tenant access.
• Verify role/permission for tenant admin actions.
• Return safe errors that do not leak another tenant’s data.
• Avoid logging sensitive tenant data.
• Treat missing tenant scope as a security risk unless the route is truly global.

Cache Rules

• Tenant-owned cached data must include tenant scope in the cache key.
• User-specific cached data should include both tenant and user scope when needed.
• Do not share cached results across tenants.
• Invalidate tenant-scoped cache on tenant-owned mutations.

Job Rules

• Background jobs touching tenant data must include trusted tenant scope.
• Workers must re-check tenant scope before acting.
• Jobs must not rely on stale or client-provided tenant data.
• Duplicate/retried jobs must not cross tenant boundaries.

Tests

Cover relevant paths:

• tenant user can access own tenant data
• tenant user cannot access another tenant’s data
• update/delete cannot cross tenant boundary
• joins remain tenant-scoped
• cache key includes tenant scope
• background job uses tenant scope
• admin access requires explicit permission