Multi-Tenant Scope Types and Data Isolation in Zippi

global
 └── country
      └── city
           ├── zippi_branch        (Zippi-owned branch)
           └── business_group      (multi-brand group)
                └── business        (individual brand/business)
                     └── business_branch  (physical branch of a business)
self  (a single user: delivery_driver or customer)

SCOPE_ALIASES = {
    "pais": "country",
    "país": "country",
    "ciudad": "city",
    "sucursal_zippi": "zippi_branch",
    "zippi branch": "zippi_branch",
    "negocio": "business",
    "marca": "business",
    "sucursal": "business_branch",
    "business branch": "business_branch",
    "sucursal_negocio": "business_branch",
    "propio": "self",
    "zona": "city",
}

# WRONG — fetches all rows across all tenants, then filters in Python
all_orders = session.query(Pedido).all()
return [o for o in all_orders if o.id_negocio == scope.business_id]

# CORRECT — scope filter is part of the SQL query
def list_orders(self, scope: BusinessScope, **filters):
    q = session.query(Pedido)
    q = apply_scope(q, scope)          # ALWAYS; applied first
    if filters.get("status"):
        q = q.filter(Pedido.estado == filters["status"])
    return q.order_by(Pedido.id.desc()).all()

@dataclass(frozen=True)
class BusinessScope:
    role: str
    scope_type: str
    scope_id: str | None
    business_id: int | None
    branch_id: int | None
    email: str

# backend/app/modules/business/security/business_scope.py

BUSINESS_ROLES = {
    "business_owner", "business_admin", "business_branch_admin",
    "kitchen_staff", "cashier", "waiter",
    "super_admin", "platform_admin",
}

def business_scope_from_user(user: dict | None) -> BusinessScope:
    if not user:
        raise HttpError("Sesion requerida", status_code=401)
    role = str(_first_value(user, "role", "rol") or "")
    if role not in BUSINESS_ROLES:
        raise HttpError("Este modulo es solo para usuarios de negocio", status_code=403)
    # ... resolves business_id and branch_id from JWT claims

def apply_scope(q, scope: BusinessScope):
    if scope.role in {"super_admin", "platform_admin"}:
        return q                              # global — no filter
    if scope.branch_id is not None:
        q = q.filter(Pedido.id_sucursal == scope.branch_id)
    elif scope.business_id is not None:
        q = q.filter(Pedido.id_negocio == scope.business_id)
    if scope.scope_type == "self":
        q = q.filter(Pedido.id_usuario == scope.user_id)
    return q

# backend/app/modules/business/security/business_scope.py

def row_in_business_scope(row: dict[str, Any], scope: BusinessScope) -> bool:
    if scope.role in {"super_admin", "platform_admin"}:
        return True
    if scope.branch_id is not None:
        return _to_int(
            row.get("businessBranchId") or row.get("branch_id")
        ) == scope.branch_id
    if scope.business_id is not None:
        return _to_int(
            row.get("businessId") or row.get("business_id")
        ) == scope.business_id
    return False

# WRONG — IDOR vulnerability
order = repo.get_by_id(oid)         # whose order is this?
return serialize(order)             # leaks data from another tenant

# CORRECT — scope validated inside the repository call
order = repo.get_order(scope, oid)  # filters by scope in SQL
if order is None:
    raise HttpError("No encontrado", status_code=404)   # 404, not 403
return serialize(order)

# 1. Build scope from JWT
scope = business_scope_from_user(current_user)
# → BusinessScope(role="business_admin", scope_type="business",
#                 business_id=42, branch_id=None, ...)

# 2. Query with scope filter
q = session.query(Producto)
# apply_scope adds: WHERE id_negocio = 42
q = apply_scope(q, scope)

# 3. Additional filters come after scope
q = q.filter(Producto.activo == True)
products = q.all()
# → Only products belonging to business 42 are returned

product = repo.get_product(scope, product_id=99)
# apply_scope makes the query: WHERE id = 99 AND id_negocio = 42
# → returns None (no match)
# → controller raises HttpError("No encontrado", 404)

# WRONG — allows mass assignment of tenant (user sends id_negocio in body)
product = Producto(id_negocio=data.id_negocio, ...)

# CORRECT — tenant comes from the authenticated scope, never from the request body
product = Producto(
    id_negocio=scope.business_id,   # from scope, not from body
    nombre=data.nombre,
    precio=data.precio,
)

-- WRONG
UPDATE productos SET precio = :precio WHERE id = :id;

-- CORRECT
UPDATE productos SET precio = :precio
WHERE id = :id AND id_negocio = :business_id;

- [ ] Every new query passes through apply_scope / filters by tenant in SQL
- [ ] Access by ID validates membership (not just format or existence)
- [ ] Create operations take the tenant from scope, never from the request body
- [ ] Update / delete operations include the tenant discriminator in the WHERE clause
- [ ] Resources from another tenant respond with 404 (not 403)
- [ ] Tenant isolation is covered by automated tests