🔑 PIEZA · GRANTS — la retícula de privilegios

1 · Qué es

⛔ Y qué NO es, que ahorra más que la definición

2 · Su naturaleza

   IDENTIDAD                  LA CADENA (Index)                      EL OBJETO
   ─────────                  ─────────────────                      ─────────
   Clerk    ──┐
   Keycloak ──┼─▶ principal ──▶ principal role ──▶ catalog role ──▶ grant ──▶ securable
   (agentes)──┘   (kind,id)      «el equipo»       «el paquete»    (privilegio)   │
                                                                                   ▼
                                                          workspace › catalog › schema › dataset
                                                                    (la HERENCIA baja por aquí)

Las dos relaciones son N:M, y el nivel de en medio es lo que resuelve «este equipo lee el esquema entero salvo dos tablas». Con un solo nivel habría que repetir el paquete de permisos por cada equipo.

Las seis propiedades de su autoridad

El vocabulario: 40 privilegios en 6 familias

WORKSPACE_* (4) · CATALOG_* (7) · SCHEMA_* (8) · TABLE_* (10) · VIEW_* (6) · POLICY_* (6)

⭐ El invariante que más se equivoca al copiarlo: *_FULL_METADATA no abre el dato. Leer la metadata de una tabla y leer sus filas son permisos distintos (TABLE_READ_DATA va aparte, deliberadamente), y fundirlos es cómo se filtran datos por accidente.

3 · Dónde vive

⚠️ Por qué el vocabulario vive en TypeScript y no en SQL: el CHECK de la migración es sólo un patrón. Los 40 nombres, dónde se concede cada uno y qué implica viven en un solo sitio — repetirlos en SQL sería el mismo conocimiento en dos lenguajes, que es la clase de bug que ya costó una fase.

4 · Quién la ejerce — dos puertas, dos sujetos distintos

   ┌─ LA PUERTA (Junction) ────────────────────────────────────────┐
   │  pregunta: «¿puede esta PERSONA?»                             │
   │  lib/compute/junction.ts → user-authz.ts                      │
   │  en lectura, escritura y CREATE · interruptor USER_AUTHZ      │
   └───────────────────────────────────────────────────────────────┘
   ┌─ LA CARA (/api/iceberg) ──────────────────────────────────────┐
   │  pregunta: «¿puede este MOTOR?»                               │
   │  lib/governance/catalog-authz.ts · fail-closed · deja asiento │
   └───────────────────────────────────────────────────────────────┘

⭐ La decisión más importante de la cara: loadTable sin delegación pide TABLE_READ_PROPERTIES; con X-Iceberg-Access-Delegation pide además TABLE_READ_DATA. Porque son dos cosas: la primera dice dónde está la tabla; la segunda entrega la llave para leer sus bytes.

⚠️ Y lo que ninguna de las dos puertas hace: cerrar la red. Si un motor puede apuntar al catálogo directamente, esto no aplica nada. Es infraestructura, no código — y la parte más barata y más olvidable del trabajo.

5 · Lo medido (2026-08-12)

Los sujetos

principal_grants ....... 368 filas de SERVICIO  (8 sujetos, 8 inquilinos)
                   +  12 sujetos HUMANOS, derivados        ← F·2·0
privilege_grants ....... 248 · principal_roles 96 · catalog_roles 56 · bindings 120

⭐⭐ owner y admin NO reciben lo mismo, y ahí está la separación de deberes: sólo owner lleva WORKSPACE_MANAGE_ACCESS. Conceder es un oficio distinto de crear, y Clerk ya distinguía los dos nombres — implementarlo no costó diseño, sólo verlo.

Los gates

npx dotenv -e .env.local -- npx tsx scripts/governance/g0-censo-de-sujetos.ts
npx dotenv -e .env.local -- npx tsx scripts/governance/g1-derivar-grants-de-usuario.ts --apply  # 24/24
npx dotenv -e .env.local -- npx tsx scripts/governance/g2-aplicador-de-usuario.ts               # 22/22
npx dotenv -e .env.local -- npx tsx scripts/governance/g3-future-grants.ts                      #  5/5
npx vitest run lib/governance/membership-grants.test.ts                                         # 20/20
curl -H "x-diag-key: $SPARK_BRIDGE_JWT_SECRET" https://app.paladio.io/api/diag/motor            # userAuthz

Lo que cada uno prueba, que no es lo mismo que «pasa»:

6 · El estándar

⭐ Las dos divergencias deliberadas, dichas enteras

1. Un grant de workspace alcanza al DATO. En UC los grants de metastore no se heredan al dato. Pero nuestro workspace juega el papel del CATÁLOGO de UC —que sí hereda—, no el del metastore. La divergencia es de nombre, no de modelo. ⚠️ El cabo real: WORKSPACE_MANAGE_ACCESS (la retícula) y WORKSPACE_MANAGE_CONTENT (el dato) conviven en un nivel donde uno debe heredar y el otro no.
2. Los humanos se DERIVAN y los servicios se DECLARAN. No es incoherencia: un servicio no está escrito en ninguna otra parte; una persona sí. La regla no es «derivar siempre», es «derivar cuando hay de qué».

7 · Lo que falta — con su gate

8 · Historial