@kido/tenant-guardCopy Anchor Link

Architecture Paradigm: Ambient AsyncLocalStorage Context Propagation + Zero-Downtime Prisma ORM Query Rewrite + Tenant Cache Namespace Guard + Cryptographic Surgical Snapshot + Public Demo Sandbox Masking.

💥 The Real-World BottleneckCopy Anchor Link

In multi-tenant SaaS, retail franchises, and POS ecosystems, tenant data leakage is the single most catastrophic vulnerability:

1. The "Forgotten WHERE Clause" Catastrophe:

   Copy Text

   -- The Naive Disaster: Developer forgets tenant_id in a complex JOIN
   SELECT o.id, o.total, c.credit_card 
   FROM orders o 
   JOIN customers c ON o.customer_id = c.id 
   WHERE o.status = 'PENDING'; -- Leaks Tenant B's financial data to Tenant A!

   A single junior developer query without tenant_id compromises the entire database, violating GDPR, SOC2, and PCI-DSS compliance.
2. Cache Key Collisions & Dirty Reads: When caching queries in Redis (cache.set("order:1001", data)), two independent tenants sharing identical order sequence IDs overwrite each other's cache entries, serving customer private PII across tenant boundaries.
3. The Unsafe Public Demo Dilemma: Prospects demand realistic interactive demos. Running a demo on production data leaks actual payroll, revenue, and customer contact information, while mock databases drift from schema reality and cost double to maintain.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

@kido/tenant-guard is decomposed into self-contained slices with zero circular dependencies:

1. Context & RLS Filters (src/tenant-context.ts, src/rls-query-filter.ts)Copy Anchor Link

• TenantContextStore: Zero-overhead ambient context provider wrapping Node.js AsyncLocalStorage.
• runWithTenantContext(ctx, fn): Executes an asynchronous block within an active tenant scope.
• runWithTenantAndUserContext(tenantCtx, userCtx, fn): Binds both tenant hierarchy and user roles.
• buildTenantWhereClause(ctx, options): Generates parameterized SQL WHERE clauses with positional parameters (\\$1, \\$2).
• buildTenantOrmFilter(ctx, options): Creates typed filter objects for Prisma, Drizzle, or TypeORM.

2. ORM & Cache Interceptor (src/orm-cache-interceptor.ts)Copy Anchor Link

• createPrismaTenantExtensionConfig(getTenantContext): Returns a Prisma $extends query client extension that intercepts all operations (findMany, create, update, delete) and guarantees tenant injection.
• prefixTenantCacheKey(tenantId, key): Formats cache keys into strict namespaces (tenant:{tenantId}:{key}).
• buildTenantCachePattern(tenantId, prefix): Produces wildcard patterns for safe single-tenant cache eviction.

3. Team RBAC & ABAC Engine (src/team-rbac/)Copy Anchor Link

• AuthorizationGuard: Attribute-based access control engine evaluating complex permission matrices.
• evaluateAbacPolicy(user, resource, action): Dynamic evaluator supporting shift hours, maximum approval amounts, and branch restrictions.
• TeamRbacEngine: Workspace membership and role hierarchy engine.

4. Surgical Snapshot & Sandbox Masking (src/snapshot/, src/sandbox/)Copy Anchor Link

• SurgicalSnapshotEngine: Reverse-FK database snapshot engine producing cryptographic SHA-256 state manifests.
• ModuleStudioManager: Live public sandbox router routing anonymous users to isolated demo personas.
• sanitizeStaffProfile(profile) & recomputePayslipJson(payslip): Deterministic PII masking engine.

💻 Production Implementation & Code SnippetCopy Anchor Link

Complete End-to-End Multi-Tenant SetupCopy Anchor Link

import { PrismaClient } from '@prisma/client';
import { 
  TenantContextStore, 
  createPrismaTenantExtensionConfig, 
  prefixTenantCacheKey,
  AuthorizationGuard,
  type TenantContext,
  type UserContext
} from '@kido/tenant-guard';

// 1. Initialize Prisma with Tenant Guard Interceptor
const basePrisma = new PrismaClient();
export const db = basePrisma.$extends(
  createPrismaTenantExtensionConfig(() => {
    const ctx = TenantContextStore.getTenantContext();
    if (!ctx) throw new Error('Cannot execute query without active TenantContext');
    return ctx;
  })
);

// 2. HTTP Request Context Middleware (Hono / Express / Next.js)
export async function tenantMiddleware(req: Request, next: () => Promise<Response>) {
  const tenantId = req.headers.get('x-tenant-id');
  const userId = req.headers.get('x-user-id');
  const userRole = (req.headers.get('x-user-role') || 'CASHIER') as any;

  if (!tenantId) {
    return new Response(JSON.stringify({ error: 'Missing X-Tenant-Id header' }), { status: 401 });
  }

  const tenantCtx: TenantContext = {
    tenantId,
    tenantName: `Tenant-${tenantId}`,
    plan: 'ENTERPRISE',
    hierarchyLevel: 'BRANCH',
  };

  const userCtx: UserContext = {
    userId: userId || 'anon',
    role: userRole,
    tenantId,
  };

  return TenantContextStore.runWithTenantAndUserContext(tenantCtx, userCtx, async () => {
    return await next();
  });
}

// 3. Service Layer Example (Guaranteed 0 Data Leakage)
export async function listActiveOrders() {
  // Developer does NOT write { where: { tenantId } } - It is injected automatically!
  const orders = await db.order.findMany({
    where: { status: 'PENDING' },
  });

  // Isolated Cache Lookup
  const tenantId = TenantContextStore.getTenantId()!;
  const cacheKey = prefixTenantCacheKey(tenantId, 'active_orders_count');
  
  return { orders, cacheKey };
}

⚡ Benchmark & Verified k6 PerformanceCopy Anchor Link

Stress-tested under simulated 10,000 virtual users across 500 concurrent tenants:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

# Install directly into your project via Kido CLI
npx @kido/cli add @kido/tenant-guard