ComensIA · Bloque 0 — Cimiento de aislamiento multi-tenant

Resumen ejecutivo

tests, 100% verdes

en el test de fuga

errores mypy (strict)

políticas RLS (FORCE)

tablas + 2 índices parciales

~2.2k

LOC Python tipado

Resultado: el cimiento está completo y verificado de punta a punta: docker compose up levanta Postgres+pgvector y Redis sanos, alembic upgrade head reconstruye todo desde cero (rol de app, tablas, índices únicos parciales y políticas RLS), mypy estricto pasa sin errores y la suite completa —incluido el test de fuga con concurrencia sobre el pool— está verde. El backend responde GET /health con HTTP 200.

Qué se construyó

Configuración tipada (pydantic-settings) + .env.example, cero secretos en código.
Logging estructurado JSON con request_id y tenant_id por línea.
TenantContext inmutable en contextvar; falla ruidosamente si falta.
Capa de datos con el puente RLS: set_config(..., true) local a transacción.
Mixins base (UUID / Timestamp / SoftDelete / Audit) y las 4 entidades del bloque.
Auth: argon2 + JWT RS256 (access 15 min + refresh rotativo + revocación en Redis).
Migración Alembic async que crea el rol comensia_app (sin superuser / sin BYPASSRLS).
Tests pytest async, incluido el test de fuga (aislamiento, negativo, concurrencia, no-residuo).
Observabilidad: middleware request_id + GET /health (Postgres + Redis).

Decisiones de arquitectura del cimiento

Decisión	Por qué
Aislamiento en DB (RLS) además de en la app	Defensa en profundidad: la app filtra (1ª línea), RLS atrapa cualquier bug (última línea).
Owner cross-tenant vía `app.level='owner'` en las políticas	Auditable y sin atajos: el Owner NO es un superusuario de Postgres que se saltaría el aislamiento.
Rol de runtime sin superuser ni BYPASSRLS	Un superusuario ignoraría RLS por completo; el rol restringido garantiza que FORCE RLS aplique.
GUC `set_config(..., true)` local a transacción	Evita la fuga de scope entre tenants al reutilizarse conexiones del pool.
Índices únicos parciales `WHERE deleted_at IS NULL`	El soft delete rompe los `UNIQUE` ingenuos; el parcial permite reusar slug/email de borrados.
JWT RS256 con llaves PEM por entorno	Estándar global DM-IA (regla transversal). No se usa HS256 (no es MVP de cliente único).

Arquitectura del cimiento

Stack: FastAPI · SQLAlchemy async · PostgreSQL 16 + pgvector · Redis 7 · Alembic async · pytest async.

Dos roles de base de datos

Rol	privilegios	Uso
comensia_admin	SUPERUSER (bootstrap del contenedor)	Solo migraciones (CREATE ROLE / EXTENSION / políticas). Bypassa RLS.
comensia_app	NOSUPERUSER · NOBYPASSRLS · LOGIN	La aplicación en runtime. Sujeto a RLS siempre.

Verificado en vivo: SELECT rolname, rolsuper, rolbypassrls FROM pg_roles → comensia_app | f | f (sin superusuario, sin bypass).

Caminos de acceso a datos

get_session (dependencia HTTP): depende de get_current_principal → abre transacción → aplica GUC del TenantContext del request.
tenant_session(ctx) (context manager): mismo patrón, para workers / scripts / tests fuera de HTTP.
anon_session (sin GUC): flujos pre-autenticación (login) y health. Las tablas con RLS quedan invisibles; solo users (sin RLS) es consultable.

Mapa del repositorio

# app/ — backend tipado (mypy strict)
core/      config · logging(JSON) · context(TenantContext) · security(argon2/JWT RS256)
db/        base(engine/sessionmaker) · mixins · session(puente RLS)
models/    chain · restaurant · user · audit_log · enums
api/       deps(principal + get_session) · auth · health · schemas
services/  auth_service · token_revocation(Redis)
middleware request_id   ·   main  app factory + lifespan
# alembic/ — migración 0001 (rol, extensiones, tablas, RLS, grants)
# tests/ — conftest(seed) · test_leak(fuga) · test_auth

Observabilidad base

Middleware asigna request_id (header X-Request-ID o generado) y lo propaga al logging.
Cada línea de log JSON lleva request_id y tenant_id.
GET /health verifica conectividad real a Postgres y Redis (503 si degradado).
Puntos de enganche para OpenTelemetry y Sentry dejados como TODO en main.py (sin cablear proveedor en este bloque).

Esquema creado

Todas las entidades de negocio con soft delete + audit + timestamps. audit_logs es append-only.

chains RLS + FORCE

columna	tipo
id	uuid PK · gen_random_uuid()
name	varchar(200)
brand_config	jsonb · default '{}'
created_at / updated_at	timestamptz (trigger updated_at)
deleted_at	timestamptz NULL (soft delete)
created_by / updated_by / deleted_by	uuid → users(id)

restaurants RLS + FORCE

columna	tipo
id	uuid PK
chain_id	uuid NULL → chains(id) — afiliado directo al Owner
name	varchar(200)
slug	varchar(120) · único parcial
brand_config	jsonb · default '{}'
order_confirmation_mode	enum · default requires_authorization
timestamps · soft delete · audit	igual que chains

users sin RLS (login pre-contexto)

columna	tipo
id	uuid PK
email	varchar(320) · único parcial
hashed_password	varchar(255) · argon2
level	enum tenant_level (owner\|chain\|restaurant)
scope_id	uuid NULL (NULL owner · chain_id · restaurant_id)
is_active	boolean · default true
timestamps · soft delete · audit	incluidos

audit_logs RLS + FORCE append-only

columna	tipo
id	uuid PK
actor_id	uuid → users(id)
scope_level	enum tenant_level
scope_id	uuid NULL
action / entity_type	varchar(120)
entity_id	uuid NULL
metadata	jsonb · default '{}'
created_at	timestamptz (sin soft delete, sin updated)

Índices únicos parciales (gotcha de soft delete)

índice	definición
uq_restaurants_slug_active	UNIQUE (slug) WHERE deleted_at IS NULL
uq_users_email_active	UNIQUE (email) WHERE deleted_at IS NULL

Apoyo: ix_restaurants_chain_id, ix_audit_logs_scope(scope_level, scope_id).

Verificación en vivo del esquema

-- pg_tables     audit_logs · chains · restaurants · users · alembic_version
-- pg_extension  pgcrypto · vector · plpgsql
-- RLS (relrowsecurity | relforcerowsecurity)
audit_logs t | t   chains t | t   restaurants t | t   users f | f
-- pg_policy    audit_logs_isolation · chains_isolation · restaurants_isolation

Políticas RLS aplicadas

Las tres tablas tienen ENABLE + FORCE ROW LEVEL SECURITY (FORCE para que el aislamiento aplique incluso al dueño de la tabla). Políticas FOR ALL con USING = WITH CHECK (salvo audit_logs) para impedir tanto leer como escribir filas de otro tenant.

Ajuste de implementación respecto al SQL del enunciado: el cast del scope se envuelve en NULLIF(current_setting('app.scope_id', true), '')::uuid. current_setting es STABLE, así que Postgres pliega el cast antes del corto-circuito del OR y la cadena vacía del owner reventaba con invalid input syntax for type uuid: "". El NULLIF neutraliza la cadena vacía a NULL — exactamente el intent declarado ("la cadena vacía nunca se castea a uuid"). Detectado y corregido por el test de fuga (caso owner).

chains_isolation

CREATE POLICY chains_isolation ON chains FOR ALL
USING (
  current_setting('app.level', true) = 'owner'
  OR (current_setting('app.level', true) = 'chain'
      AND id = NULLIF(current_setting('app.scope_id', true), '')::uuid)
)
WITH CHECK ( /* misma expresión */ );

restaurants_isolation

USING (
  current_setting('app.level', true) = 'owner'
  OR (level = 'chain'      AND chain_id = NULLIF(scope,'')::uuid)
  OR (level = 'restaurant' AND id       = NULLIF(scope,'')::uuid)
)  -- WITH CHECK idéntico

audit_logs_isolation

USING (
  level = 'owner'
  OR (level = 'chain' AND (
        (scope_level='chain'      AND scope_id = NULLIF(scope,'')::uuid)
        OR (scope_level='restaurant' AND scope_id IN (
              SELECT id FROM restaurants
              WHERE chain_id = NULLIF(scope,'')::uuid))))
  OR (level = 'restaurant' AND scope_level='restaurant'
      AND scope_id = NULLIF(scope,'')::uuid)
)
WITH CHECK (true);  -- cualquier nivel inserta su propia traza; la LECTURA queda restringida por USING

El Owner corta por OR primero (rama 'owner'). La subconsulta de audit_logs sobre restaurants hereda el mismo contexto RLS, así que para una cadena devuelve exactamente sus restaurantes.

El puente `set_config` local a transacción

Es el punto más crítico del bloque: por qué no hay fuga de tenant bajo pooling.

El footgun

Con SQLAlchemy async + pool de conexiones, las conexiones se reutilizan entre requests. Si se setea la variable de sesión de forma global (SET app.scope_id = ...), ese valor persiste cuando la conexión vuelve al pool y la toma el siguiente request — que podría ser de otro tenant. Eso es una fuga de aislamiento.

La solución

Toda unidad de trabajo corre dentro de una transacción explícita y aplica el contexto a la GUC antes de cualquier query de negocio, con set_config parametrizado (binds, nunca interpolación de strings) y local a la transacción (tercer argumento true):

# app/db/session.py
_APPLY_GUC = text(
    "SELECT set_config('app.level', :level, true), "
    "set_config('app.scope_id', :scope_id, true)"
)

async def apply_tenant_guc(session, ctx):
    await session.execute(_APPLY_GUC,
        {"level": ctx.level.value, "scope_id": ctx.guc_scope_value})
        # owner → scope_id = ''  ·  chain/restaurant → uuid en texto

Al ser local, el valor desaparece en el COMMIT/ROLLBACK y no persiste cuando la conexión vuelve al pool. Eso es lo que previene la fuga. El test test_no_guc_residue_after_tenant_transaction lo prueba: tras una transacción de Cadena A, una transacción nueva sin GUC observa app.scope_id vacío.

Garantía probada: 40 operaciones concurrentes de 4 tenants distintos intercaladas con asyncio.gather sobre el mismo pool — cada una ve exactamente sus filas, ninguna ve las de otro.

Tests & mypy

tests verdes

test de fuga

tests de auth

archivos · mypy OK

mypy estricto

$ mypy
Success: no issues found in 31 source files

Test de fuga — `tests/test_leak.py`

# pytest -v tests/test_leak.py
test_chain_a_sees_its_restaurants_not_b PASSED
test_restaurant_a1_sees_only_itself PASSED
test_owner_sees_all_restaurants PASSED
test_audit_isolation_restaurant_a1 PASSED
test_audit_isolation_chain_a PASSED
test_audit_isolation_owner PASSED
test_restaurant_a1_cannot_read_b1_by_id PASSED
test_chain_a_cannot_insert_restaurant_for_chain_b PASSED
test_chain_a_cannot_move_own_restaurant_to_chain_b PASSED
test_concurrent_tenants_do_not_leak PASSED
test_no_guc_residue_after_tenant_transaction PASSED
============================== 11 passed in 2.21s ==============================

Escenario del enunciado	Cubierto por	Estado
Aislamiento por nivel (restaurants)	chain_a / restaurant_a1 / owner	✓
Aislamiento por nivel (audit_logs)	audit_isolation_*	✓
Negativo: lectura cross-tenant vacía	cannot_read_b1_by_id	✓
Negativo: INSERT/UPDATE cross-tenant rechazado (WITH CHECK)	cannot_insert_* / cannot_move_*	✓
Estrés de concurrencia sobre el pool	concurrent_tenants_do_not_leak	✓
No-residuo de pool (GUC local)	no_guc_residue_*	✓

Tests de auth — `tests/test_auth.py`

# pytest -v tests/test_auth.py
test_login_ok PASSED
test_login_wrong_password PASSED
test_login_unknown_email PASSED
test_me_reflects_token_context PASSED
test_me_requires_auth PASSED
test_refresh_rotates_and_revokes_old PASSED
test_logout_revokes_access PASSED
test_token_context_for_chain_user PASSED
============================== 8 passed in 3.14s ===============================

Hashes de archivos críticos (sha256)

archivo	sha256 (12)
app/db/session.py	7f64f45621d9
alembic/versions/0001_initial.py	050521327b50
app/api/deps.py	79fe04d92542
app/core/context.py	29ea4a97a276

Entorno & arranque

Variables de entorno (ver `.env.example`, sin valores reales)

variable	descripción
DATABASE_URL	DSN async del rol restringido `comensia_app`
DATABASE_ADMIN_URL	DSN admin — solo Alembic
APP_DB_PASSWORD	password del rol que crea la migración 0001
REDIS_URL	lista de revocación de tokens
JWT_PRIVATE_KEY / JWT_PUBLIC_KEY	llaves PEM RS256 (una línea con `\n` escapados)
ACCESS_TOKEN_TTL_SECONDS	900 (15 min)
REFRESH_TOKEN_TTL_SECONDS	604800 (7 días)
DB_POOL_SIZE / DB_MAX_OVERFLOW	pool del engine async

Servicios (Docker Compose)

servicio	imagen	host	healthcheck
postgres	pgvector/pgvector:pg16	:55432	pg_isready
redis	redis:7	:56379	redis-cli ping
backend	build .	:8085	/health → 200

Arranque

$ docker compose up -d postgres redis          # sanos por healthcheck
$ docker compose run --rm backend alembic upgrade head
$ docker compose up -d backend
$ curl http://localhost:8085/health
  {"status":"ok","postgres":true,"redis":true}   HTTP 200

# Tests + mypy (host con venv y .env apuntando a :55432 / :56379)
$ alembic upgrade head
$ mypy        # estricto, sin errores
$ pytest      # 19 passed

Transparencia total

Lo que NO se tocó (a propósito)

Módulos de negocio (menú, IA, órdenes, pagos): pertenecen a bloques posteriores. No se construyó nada de eso.
Otros proyectos del servidor: cero contacto. ComensIA usa puertos altos (55432/56379/8085) para no chocar con CTT/SIBO/Galia/etc.
El rol y las extensiones no se eliminan en el downgrade de la migración (pueden estar en uso por otros objetos del cluster). Decisión explícita y comentada.

Desviaciones del enunciado (reportadas proactivamente)

Punto	Qué se hizo y por qué	Severidad
Cast del scope en RLS	Se envolvió en `NULLIF(..., '')::uuid`. El SQL literal del enunciado revienta para el owner (cadena vacía → `::uuid`) porque `current_setting` es STABLE y Postgres pliega el cast antes del `OR`. El `NULLIF` implementa exactamente el intent declarado. Detectado por el test de fuga.	Media
Algoritmo JWT	Se usó RS256 con llaves PEM (el enunciado no fijó algoritmo; el CLAUDE.md global lo manda como regla transversal). Access 15 min, refresh 7 días rotativo, revocación en Redis — todo según el enunciado.	Baja
Endpoint extra `GET /auth/me`	Introspección de auth (devuelve level/scope_id del principal). Se agregó para poder testear que el TenantContext se construye correctamente desde los claims. Es auth-scope, no un módulo de negocio.	Baja
Emails de seed	Se usa el dominio `@comensia.com` en los tests: `email-validator` rechaza el TLD reservado `.test`. Solo afecta datos de prueba.	Baja

Relacionado que se vio pero no se modificó

El enunciado pide grants para la app; se otorgó SELECT, INSERT, UPDATE en chains/restaurants/users y SELECT, INSERT en audit_logs — sin DELETE, reforzando "nunca DELETE físico desde la app".

Próximas acciones

Activación operativa final (la hace Diego)

Apuntar DNS comensia.dm-ia.com → 2.24.194.226 y correr certbot para SSL. El nginx en terciario ya sirve este reporte por HTTP; con DNS+SSL queda en https://comensia.dm-ia.com.
Definir las credenciales productivas reales (rol comensia_app, llaves RS256) en el .env del entorno productivo — los valores del repo son solo de desarrollo.

Hooks para bloques posteriores (ya cableados como TODO)

Inicializar OpenTelemetry y Sentry en app/main.py (puntos de enganche dejados, sin proveedor).
Los módulos de negocio (menú, IA, órdenes, pagos) se apoyan en este cimiento: todo acceso a datos debe pasar por get_session / tenant_session para heredar el aislamiento.

El cimiento queda listo para que el resto de la plataforma se construya encima sin volver a tocar el aislamiento. La regla de oro para todo bloque futuro: nunca acceder a datos de tenant fuera de un tenant_session/get_session.