@jantstack/adonis-authz 2.0.0-alpha.1 → 2.4.0-alpha.10

package/build/src/relations/define_relations_config.js

@@ -0,0 +1,211 @@
+/**
+ * `defineRelationsConfig` — la API declarativa de ReBAC (Fase 4, lote 4-2).
+ *
+ * Valida la config de relaciones del consumidor y devuelve un objeto
+ * CONGELADO que el manager de relaciones consulta para F-05 (`isDeclared`).
+ * Es la puerta de entrada, AGNÓSTICA de driver: rige igual en `database` y en
+ * `openfga` (paridad ⚪4). El generador del modelo fusionado
+ * (`src/drivers/openfga_facts.ts`, lote 4-1) hace la MISMA comprobación de
+ * reservados por defensa en profundidad al emitir el modelo —y además la de
+ * F-04 (colisión con un permiso del catálogo), que necesita las tuplas del
+ * catálogo y por eso vive en la capa del modelo—; las dos comparten la fuente
+ * única de tipos reservados (`RESERVED_FACTS_TYPES` en `src/identity.ts`).
+ *
+ * Pureza (regla 2 de `check_purity.mjs`): este módulo solo depende del puerto
+ * (`../types.js`), de los errores y de la gramática compartida
+ * (`../identity.js`); JAMÁS de `../manager` ni de `../drivers/*`. Es lo que
+ * mantiene `relations/` desacoplado de `roles/`.
+ */
+import { RelationConfigError, RelationTypeUnknownError, RelationUnknownError } from '../errors.js';
+import { RESERVED_FACTS_TYPES, RESERVED_SLUGS, RESERVED_SLUG_PREFIXES } from '../identity.js';
+/** La cota de FGA para el nombre de una relación (50). Un tipo de objeto llega a 254. */
+const RELATION_NAME_MAX = 50;
+const OBJECT_TYPE_MAX = 254;
+/** Nombres FGA: minúsculas, dígitos y `._-`; sin `:`/`#`/`@`/espacios ni `|`. */
+const FGA_NAME_FORMAT = /^[a-z0-9][a-z0-9._-]*$/;
+function reject(message) {
+    throw new RelationConfigError(message);
+}
+/**
+ * **F-05, la función ÚNICA** (L-0): rechaza un `object.type` no declarado
+ * (422 `E_AUTHZ_RELATION_TYPE_UNKNOWN`) o una `relation` no declarada para ese
+ * tipo (422 `E_AUTHZ_RELATION_UNKNOWN`). La aplican el `RelationsManager`
+ * (corta primero) Y los dos drivers de relaciones, ANTES de tocar el backend
+ * — la misma función, así que la misma clase, el mismo `code` y el mismo
+ * mensaje por cualquier puerta. Hacía falta en el driver (panel `{trx}`, 🔴 2
+ * del auditor): `manager.driver()` y `reconcileRelations` (que escribe con
+ * `to.relate`) entran por él, y sin la guarda
+ * `relate(evil, 'assignee', {type:'role_binding', id:<roleUuid>}, S)` componía
+ * en el store COMPARTIDO el id exacto de un binding de roles y
+ * `roles.authorize` pasaba de `false` a `true` (medido contra el `:8101`).
+ * La gramática de identidad no basta: `role_binding`/`assignee` son
+ * gramaticalmente válidos.
+ *
+ * **Cubre las OCHO operaciones del puerto** (`2.4.0-alpha.3`, cierre del
+ * 🔴 1 / 🟠 2 del auditor y cierre-2): hasta alpha.3 solo `relate`/`unrelate`
+ * la llamaban, y por `purgeObject({ type: 'role_binding', id: R }, S)` el
+ * puerto de relaciones BORRABA el binding real del store compartido
+ * (`authorize` pasaba de `true` a `false`, 0 tuplas, evento de auditoría
+ * limpio), y `listSubjects('assignee', role_binding)` enumeraba sus asignados
+ * sin catálogo ni `within`. **Son DOS funciones, no un opcional** (cierre-2,
+ * 🟠 1 del re-ataque): el primer cierre hizo `relation` opcional con un
+ * `if (relation === undefined) return` compartido por todas las llamadas, y
+ * eso APAGÓ F-05 en `relate`/`unrelate` sin relación (`request.input('relation')`
+ * ausente): antes `isDeclared('document', undefined)` era `false` ⇒ 422 con
+ * cero llamadas; con el opcional los dobles escribían la tupla, `openfga`
+ * devolvía 503 del servidor y `database` lo salvaba su driver (paridad rota),
+ * y `listSubjects(undefined)` devolvía la UNIÓN de relaciones del objeto.
+ * Esta función es ESTRICTA: la relación es obligatoria (ausente, `undefined`,
+ * vacía o no-string ⇒ 422 `E_AUTHZ_RELATION_UNKNOWN`) y la usan `relate`/
+ * `unrelate`/`check`/`listSubjects`/`membersOf` (+ `listObjects`, que también
+ * nombra una relación) y el userset de un sujeto (`{ object, relation }`).
+ * Quien NO nombra relación —`purgeObject`— usa `assertObjectTypeDeclared`.
+ */
+export function assertRelationDeclared(config, object, relation) {
+    assertObjectTypeDeclared(config, object);
+    if (typeof relation !== 'string' || relation.length === 0) {
+        throw new RelationUnknownError(`La relación de '${object.type}' es obligatoria y llegó ${relation === undefined ? 'undefined' : JSON.stringify(relation)} ` +
+            `(F-05): relate/unrelate/check/listObjects/listSubjects/membersOf exigen una relación declarada; ` +
+            `sin ella no hay tupla que escribir ni pregunta que responder.`);
+    }
+    if (!config.isDeclared(object.type, relation)) {
+        throw new RelationUnknownError(`La relación '${String(relation)}' no está declarada para el tipo '${object.type}' en ` +
+            `defineRelationsConfig (F-05).`);
+    }
+}
+/**
+ * **F-05 sobre el TIPO solo** (cierre-2 de alpha.3): la mitad de F-05 que
+ * aplican las operaciones que NO nombran relación —`purgeObject`— y la primera
+ * comprobación de `assertRelationDeclared`. Un tipo no declarado (o un objeto
+ * que no es `{ type }`) ⇒ 422 `E_AUTHZ_RELATION_TYPE_UNKNOWN`. Separada de la
+ * estricta a propósito: deducir «solo el tipo» de un `relation === undefined`
+ * era lo que apagaba F-05 en `relate`/`unrelate` sin relación (🟠 1 del
+ * re-ataque del auditor).
+ */
+export function assertObjectTypeDeclared(config, object) {
+    if (!object || typeof object !== 'object' || typeof object.type !== 'string') {
+        throw new RelationTypeUnknownError(`Objeto de relación inválido: se esperaba { type, id } y llegó ${JSON.stringify(object)}.`);
+    }
+    if (!config.hasType(object.type)) {
+        throw new RelationTypeUnknownError(`El tipo de objeto '${object.type}' no está declarado en defineRelationsConfig (F-05): ` +
+            `relate/unrelate/purgeObject/purgeSubject/check/listObjects/listSubjects/membersOf solo aceptan ` +
+            `tipos declarados. En el store compartido un tipo no declarado podría componer el id de un ` +
+            `'role_binding' real y escalar a roles.authorize, purgarlo o enumerar sus asignados.`);
+    }
+}
+/**
+ * Valida y congela la config de relaciones. Config inválida ⇒ 422
+ * `E_AUTHZ_RELATION_CONFIG` (misma clase que el gate del modelo del lote 4-1).
+ */
+export function defineRelationsConfig(spec) {
+    if (!spec || typeof spec !== 'object') {
+        reject(`Config de relaciones inválida: se esperaba un objeto y llegó ${JSON.stringify(spec)}.`);
+    }
+    // `membersOf` SOLO puede vivir en las opciones de `database` (⚪ del tester):
+    // ponerlo en la raíz o en un futuro bloque `openfga` es un error de
+    // configuración —`openfga` no puede resolver la transitiva sin truncar—.
+    if ('membersOf' in spec) {
+        reject(`Config de relaciones inválida: 'membersOf' es una opción del driver 'database' ` +
+            `(membresía transitiva por CTE recursiva) y va en 'database.membersOf', no en la raíz. ` +
+            `En 'openfga' la transitiva sería 'ListUsers', que trunca al tope del servidor.`);
+    }
+    if (!Array.isArray(spec.objectTypes) || spec.objectTypes.length === 0) {
+        reject(`Config de relaciones inválida: 'objectTypes' tiene que ser un array no vacío.`);
+    }
+    const holderTypes = spec.holderTypes ?? [];
+    for (const holder of holderTypes) {
+        if (typeof holder !== 'string') {
+            reject(`Config de relaciones inválida: un holder type no es una cadena (${JSON.stringify(holder)}).`);
+        }
+    }
+    const reservedTypes = new Set([...RESERVED_FACTS_TYPES, ...holderTypes]);
+    const seenTypes = new Set();
+    for (const objectType of spec.objectTypes) {
+        const type = objectType?.type;
+        if (typeof type !== 'string' || !FGA_NAME_FORMAT.test(type) || type.length > OBJECT_TYPE_MAX) {
+            reject(`Config de relaciones inválida: tipo de objeto ${JSON.stringify(type)} no es un tipo FGA válido ` +
+                `(minúsculas, dígitos y '._-'; sin ':'/'#'/'@'/'|'/espacios; 1-${OBJECT_TYPE_MAX} caracteres).`);
+        }
+        if (reservedTypes.has(type)) {
+            reject(`Config de relaciones inválida: el tipo de objeto '${type}' colisiona con un tipo reservado del ` +
+                `modelo compartido (${[...RESERVED_FACTS_TYPES].join(', ')}` +
+                `${holderTypes.length ? ', y los holder types ' + holderTypes.join(', ') : ''}). ` +
+                `En el store compartido un tipo de relaciones no puede duplicar uno de 'facts' (⚪4): ` +
+                `si pudiera declarar 'role_binding', 'relate' compondría el id de un binding real y escalaría a ` +
+                `roles.authorize. Renómbralo.`);
+        }
+        if (seenTypes.has(type)) {
+            reject(`Config de relaciones inválida: el tipo de objeto '${type}' está declarado dos veces.`);
+        }
+        seenTypes.add(type);
+        if (!Array.isArray(objectType.relations) || objectType.relations.length === 0) {
+            reject(`Config de relaciones inválida: el tipo '${type}' no declara ninguna relación.`);
+        }
+        const own = new Set();
+        for (const relation of objectType.relations) {
+            const name = relation?.name;
+            if (typeof name !== 'string' || !FGA_NAME_FORMAT.test(name)) {
+                reject(`Config de relaciones inválida: relación ${JSON.stringify(name)} del tipo '${type}' no es un ` +
+                    `nombre de relación válido (minúsculas, dígitos y '._-').`);
+            }
+            if (name.length > RELATION_NAME_MAX) {
+                reject(`Config de relaciones inválida: la relación '${name}' del tipo '${type}' tiene ${name.length} ` +
+                    `caracteres y FGA admite ${RELATION_NAME_MAX}.`);
+            }
+            if (RESERVED_SLUGS.has(name)) {
+                reject(`Config de relaciones inválida: la relación '${type}#${name}' usa un nombre reservado del modelo ` +
+                    `facts (${[...RESERVED_SLUGS].join(', ')}): elegiría una relación propia de 'facts' (⚪4).`);
+            }
+            const family = RESERVED_SLUG_PREFIXES.find((prefix) => name.startsWith(prefix));
+            if (family) {
+                reject(`Config de relaciones inválida: la relación '${type}#${name}' empieza por '${family}', prefijo ` +
+                    `reservado de las relaciones derivadas del modelo facts (${RESERVED_SLUG_PREFIXES.join(', ')}): ` +
+                    `pisaría el nombre de un permiso proyectado (⚪4).`);
+            }
+            if (own.has(name)) {
+                reject(`Config de relaciones inválida: la relación '${type}#${name}' está declarada dos veces.`);
+            }
+            own.add(name);
+        }
+        // Los `includes` refieren relaciones del MISMO tipo (un nivel, SIN `from`).
+        for (const relation of objectType.relations) {
+            for (const included of relation.includes ?? []) {
+                if (typeof included !== 'string') {
+                    reject(`Config de relaciones inválida: un 'includes' de '${type}#${relation.name}' no es una cadena.`);
+                }
+                // Un `from` (`viewer from parent`) se escribe con un separador; v1 no lo soporta.
+                if (/[:#@|. ]/.test(included) && !own.has(included)) {
+                    reject(`Config de relaciones inválida: '${type}#${relation.name}' incluye '${included}', que parece una ` +
+                        `herencia cross-objeto ('from'). v1 solo soporta includes de un nivel y del MISMO tipo.`);
+                }
+                if (!own.has(included)) {
+                    reject(`Config de relaciones inválida: '${type}#${relation.name}' incluye '${included}', que no es una ` +
+                        `relación de '${type}'. Los includes son de un nivel y del mismo tipo (v1 no soporta 'from').`);
+                }
+                if (included === relation.name) {
+                    reject(`Config de relaciones inválida: '${type}#${relation.name}' se incluye a sí misma.`);
+                }
+            }
+        }
+    }
+    const declared = new Map();
+    // `group` es el tipo BUILT-IN de las relaciones (el portador de los
+    // usersets, `group:g#member`): lo emite SIEMPRE el generador del modelo, no
+    // el consumidor —por eso NO se declara en `objectTypes` (arriba se rechaza)
+    // pero SÍ es un tipo válido para F-05: `relate(group:g#member, viewer, doc)`
+    // y `relate(u, member, group:g)` son legales. `role_binding`/`scope`/`role`
+    // siguen fuera: la frontera del 🔴 se mantiene.
+    declared.set('group', new Set(['member']));
+    const frozenTypes = spec.objectTypes.map((objectType) => {
+        const relations = objectType.relations.map((relation) => Object.freeze({ name: relation.name, includes: relation.includes ? Object.freeze([...relation.includes]) : undefined }));
+        declared.set(objectType.type, new Set(relations.map((r) => r.name)));
+        return Object.freeze({ type: objectType.type, relations: Object.freeze(relations) });
+    });
+    return Object.freeze({
+        objectTypes: Object.freeze(frozenTypes),
+        membersOf: spec.database?.membersOf === true,
+        hasType: (objectType) => declared.has(objectType),
+        isDeclared: (objectType, relation) => declared.get(objectType)?.has(relation) ?? false,
+    });
+}
+//# sourceMappingURL=define_relations_config.js.map

package/build/src/relations/define_relations_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_relations_config.js","sourceRoot":"","sources":["../../../src/relations/define_relations_config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAClG,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAG7F,yFAAyF;AACzF,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAC5B,MAAM,eAAe,GAAG,GAAG,CAAA;AAC3B,iFAAiF;AACjF,MAAM,eAAe,GAAG,wBAAwB,CAAA;AA2DhD,SAAS,MAAM,CAAC,OAAe;IAC7B,MAAM,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAuB,EACvB,MAAoC,EACpC,QAAgB;IAEhB,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,oBAAoB,CAC5B,mBAAmB,MAAM,CAAC,IAAI,4BAA4B,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG;YAC1H,kGAAkG;YAClG,+DAA+D,CAClE,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,MAAM,CAAC,QAAQ,CAAC,qCAAqC,MAAM,CAAC,IAAI,OAAO;YACrF,+BAA+B,CAClC,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAuB,EAAE,MAAoC;IACpG,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7E,MAAM,IAAI,wBAAwB,CAChC,iEAAiE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAC3F,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,wBAAwB,CAChC,sBAAsB,MAAM,CAAC,IAAI,uDAAuD;YACtF,iGAAiG;YACjG,4FAA4F;YAC5F,qFAAqF,CACxF,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAyB;IAC7D,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,CAAC,gEAAgE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjG,CAAC;IACD,6EAA6E;IAC7E,oEAAoE;IACpE,yEAAyE;IACzE,IAAI,WAAW,IAAK,IAA2C,EAAE,CAAC;QAChE,MAAM,CACJ,iFAAiF;YAC/E,wFAAwF;YACxF,gFAAgF,CACnF,CAAA;IACH,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,CAAC,+EAA+E,CAAC,CAAA;IACzF,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAA;IAC1C,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,mEAAmE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACvG,CAAC;IACH,CAAC;IACD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,oBAAoB,EAAE,GAAG,WAAW,CAAC,CAAC,CAAA;IAEhF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,UAAU,EAAE,IAAI,CAAA;QAC7B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;YAC7F,MAAM,CACJ,iDAAiD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,4BAA4B;gBAC/F,iEAAiE,eAAe,eAAe,CAClG,CAAA;QACH,CAAC;QACD,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,CACJ,qDAAqD,IAAI,wCAAwC;gBAC/F,sBAAsB,CAAC,GAAG,oBAAoB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC5D,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK;gBAClF,sFAAsF;gBACtF,iGAAiG;gBACjG,8BAA8B,CACjC,CAAA;QACH,CAAC;QACD,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,qDAAqD,IAAI,6BAA6B,CAAC,CAAA;QAChG,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEnB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9E,MAAM,CAAC,2CAA2C,IAAI,gCAAgC,CAAC,CAAA;QACzF,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;QAC7B,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,QAAQ,EAAE,IAAI,CAAA;YAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5D,MAAM,CACJ,2CAA2C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,IAAI,aAAa;oBAC5F,0DAA0D,CAC7D,CAAA;YACH,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;gBACpC,MAAM,CACJ,+CAA+C,IAAI,eAAe,IAAI,WAAW,IAAI,CAAC,MAAM,GAAG;oBAC7F,2BAA2B,iBAAiB,GAAG,CAClD,CAAA;YACH,CAAC;YACD,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,MAAM,CACJ,+CAA+C,IAAI,IAAI,IAAI,uCAAuC;oBAChG,UAAU,CAAC,GAAG,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,kDAAkD,CAC7F,CAAA;YACH,CAAC;YACD,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;YAC/E,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CACJ,+CAA+C,IAAI,IAAI,IAAI,kBAAkB,MAAM,aAAa;oBAC9F,2DAA2D,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBACjG,kDAAkD,CACrD,CAAA;YACH,CAAC;YACD,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClB,MAAM,CAAC,+CAA+C,IAAI,IAAI,IAAI,6BAA6B,CAAC,CAAA;YAClG,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACf,CAAC;QAED,4EAA4E;QAC5E,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YAC5C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC/C,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACjC,MAAM,CAAC,oDAAoD,IAAI,IAAI,QAAQ,CAAC,IAAI,qBAAqB,CAAC,CAAA;gBACxG,CAAC;gBACD,kFAAkF;gBAClF,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACpD,MAAM,CACJ,mCAAmC,IAAI,IAAI,QAAQ,CAAC,IAAI,cAAc,QAAQ,oBAAoB;wBAChG,wFAAwF,CAC3F,CAAA;gBACH,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACvB,MAAM,CACJ,mCAAmC,IAAI,IAAI,QAAQ,CAAC,IAAI,cAAc,QAAQ,mBAAmB;wBAC/F,gBAAgB,IAAI,0EAA0E,CACjG,CAAA;gBACH,CAAC;gBACD,IAAI,QAAQ,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;oBAC/B,MAAM,CAAC,mCAAmC,IAAI,IAAI,QAAQ,CAAC,IAAI,0BAA0B,CAAC,CAAA;gBAC5F,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC/C,oEAAoE;IACpE,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QACtD,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAoC,EAAE,EAAE,CAClF,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CACxH,CAAA;QACD,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAA6B,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAChG,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;IACtF,CAAC,CAAC,CAAA;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC;QACvC,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI;QAC5C,OAAO,EAAE,CAAC,UAAkB,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;QACzD,UAAU,EAAE,CAAC,UAAkB,EAAE,QAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK;KACvG,CAAoB,CAAA;AACvB,CAAC"}

package/build/src/relations/manager.d.ts

@@ -0,0 +1,138 @@
+import type { RelObject, RelSubject, RelationRef, RelationWriteEvent, RelationWriteOptions, RelationsDriver, RelationsDriverCapabilities, RelationObjectsPage, RelationSubjectsPage, RelationPage, RelationTuplePage, RelationPurgeOptions, ScopeRef } from '../types.js';
+import type { RelationsConfig } from './define_relations_config.js';
+export interface RelationsManagerOptions {
+    /**
+     * Comprobación PURA de escritura (R-13): recibe la referencia completa de la
+     * tupla (sujeto, relación, objeto, partición, operación) y LANZA para
+     * rechazarla. Corre DESPUÉS de F-05 y ANTES de tocar el driver. **No
+     * devuelve veredictos**: todo retorno distinto de `undefined` —una promesa,
+     * un `false`, un `true`, una función con `.then`— es 500 `E_AUTHZ_CONFIG`
+     * antes del driver (2.4.0-alpha.3 y su cierre: un `false` devuelto no
+     * denegaba nada y la escritura entraba).
+     */
+    assertWrite?(ref: RelationRef): void;
+    /**
+     * Auditoría: se notifica DESPUÉS de que el driver vuelva, con el `actor`
+     * (validado), `transactional: true` con `{ transaction }` e
+     * `indeterminate: true` al vencer el deadline (invariante 13). Puede ser
+     * `async` (la promesa devuelta SE ESPERA); si lanza o rechaza, se registra y
+     * NO tumba la escritura ya aplicada (2.4.0-alpha.3, paridad con
+     * `hooks.onWrite`). Se tipa `void` (y no `void | Promise<void>`) para no
+     * romper a quien ya lo construye a mano con `(e) => events.push(e)`: un
+     * retorno cualquiera solo es asignable a `void` a secas.
+     */
+    onRelationWrite?(event: RelationWriteEvent): void;
+    /** `true` exige `actor` en toda escritura (paridad con `requireActor` de roles). */
+    requireActor?: boolean;
+    /**
+     * Reloj de pared (R-15, paridad con `config.clock` de roles, 2.5 · J1): se
+     * aplica al driver con `withClock` al construir; un driver sin `withClock`
+     * con `clock` declarado es 500 `E_AUTHZ_CONFIG` (el reloj mentiría).
+     */
+    clock?: () => Date;
+    /**
+     * Deadline TOTAL (ms, default 5000) de la lectura de la barrera del freeze
+     * (paridad con `freezeTimeoutMs` del config de roles; el provider pasa el
+     * mismo valor).
+     */
+    freezeTimeoutMs?: number;
+    /**
+     * **Puerta 2 de `{ transaction }`** (L-2, opt-in): con `true`, el driver
+     * tiene que declarar `capabilities.transactionalWrites: true` o el manager
+     * falla AL CONSTRUIRSE (500 `E_AUTHZ_CONFIG`) — que para este puerto es el
+     * momento de resolver el driver (`buildRelationsManager`). El provider pasa
+     * `relations.requireTransactionalWrites ?? config.requireTransactionalWrites`.
+     */
+    requireTransactionalWrites?: boolean;
+    /** Nombre del driver (la clave en `relations.drivers`) para los mensajes de las dos puertas. Default `'relations'`. */
+    driverName?: string;
+}
+export declare class RelationsManager {
+    #private;
+    constructor(driver: RelationsDriver, config: RelationsConfig, options?: RelationsManagerOptions);
+    /** El driver crudo — salida documentada de las barreras (plataforma y tests). */
+    driver(): RelationsDriver;
+    /**
+     * **Lo que el driver de relaciones ACTIVO declara, de solo lectura**
+     * (2.4.0-alpha.4; pregunta 1 de COGNITIV). Para que el código de tenant
+     * ramifique —`if (relations.capabilities().transactionalWrites) relate(…,
+     * { transaction }) else relate(…)`— sin llamar a `driver()`, que sigue
+     * siendo API de PLATAFORMA. Síncrono, a diferencia del de roles: aquí el
+     * driver es eager (la puerta 2 ya corrió en el constructor) y no hay nada
+     * que resolver. Copia CONGELADA y NORMALIZADA (todas las claves de
+     * `RelationsDriverCapabilities`, `undefined` → `false`): mutarla no toca
+     * lo que lee la puerta 1.
+     */
+    capabilities(): Readonly<RelationsDriverCapabilities>;
+    relate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    unrelate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    /**
+     * **Las lecturas también pasan por F-05** (2.4.0-alpha.3, 🟠 2 del auditor):
+     * el `objectId` lleva la partición, así que `listSubjects('assignee',
+     * { type: 'role_binding', id: R }, S)` era la lista de asignados de un rol
+     * en un scope, por el puerto de relaciones, sin catálogo, sin `within`, sin
+     * `requireActor` (las lecturas no lo tienen) y sin visibilidad de rol
+     * (invariante 18). `check`/`listSubjects` validan el par (tipo, relación);
+     * `listObjects` el tipo; el userset del sujeto, su par. PRIMERA línea,
+     * cero llamadas al driver; el driver re-valida (defensa en profundidad).
+     */
+    check(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef): Promise<boolean>;
+    listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef, page?: RelationPage): Promise<RelationObjectsPage>;
+    listSubjects(relation: string, object: RelObject, partition: ScopeRef, page?: RelationPage): Promise<RelationSubjectsPage>;
+    /**
+     * **Las purgas notifican** (2.4.0-alpha.3 · E, hallazgo #4; D-1/D-3): UN
+     * evento por llamada —aunque el driver barra las dos ortografías del uuid
+     * de partición por dentro: el manager no canoniza particiones, y diverge a
+     * propósito de `scopes.detached`, que emite uno por ortografía porque ahí
+     * canoniza el MANAGER—, con el objetivo y la partición TAL COMO la pasó el
+     * llamante, sin `relation` y SIN conteo (el puerto devuelve `void`; un
+     * conteo lo rompería para terceros y un rollback lo desmentiría). Se
+     * notifica también cuando no borra nada: el hecho auditable es «alguien
+     * pidió borrar las llaves de X». Sujeta a `requireActor` (D-3, breaking) y
+     * al actor validado; NO pasa por `assertWrite` (su `RelationRef.operation`
+     * es `'relate' | 'unrelate'`, tipo publicado de R-13). Mismo `#write`
+     * (invariante 13) y mismo `#notify` que `relate`/`unrelate`.
+     *
+     * **Y pasan por F-05** (cierre del 🔴 1 del auditor de alpha.3): el mismo
+     * orden que `relate` —puerta 1, freeze, F-05 (solo el TIPO: una purga no
+     * nombra relación), id, actor, scope—. `purgeSubject` valida su sujeto como
+     * `relate` (`#assertSubject`, ⚪ 7: un userset no declarado o un holder mal
+     * formado es 422 ANTES del driver y no llega al evento).
+     */
+    purgeObject(object: RelObject, partition: ScopeRef, options?: RelationPurgeOptions): Promise<void>;
+    purgeSubject(subject: RelSubject, partition: ScopeRef, options?: RelationPurgeOptions): Promise<void>;
+    /**
+     * Membresía TRANSITIVA de un grupo (a través de usersets anidados) —
+     * DISTINTA de `listSubjects`, que da los hechos DIRECTOS. Solo la trae el
+     * driver `database` (`membersOfNative: true`); en `openfga` es 500
+     * `E_AUTHZ_UNSUPPORTED` nombrándola (la transitiva sería `ListUsers`, que
+     * trunca), jamás un `skip`.
+     */
+    membersOf(object: RelObject, relation: string, partition: ScopeRef, page?: RelationPage): Promise<RelationSubjectsPage>;
+    /** ORIGEN de `authz:reconcile` de relaciones. 500 `E_AUTHZ_UNSUPPORTED` si el driver no lo trae. */
+    enumerateRelations(partition: ScopeRef, page?: RelationPage): Promise<RelationTuplePage>;
+    /**
+     * **K particiones en UN barrido** (2.4.0-alpha.6) si el driver trae
+     * `enumerateRelationsMany` (los dos publicados lo traen desde alpha.8: el
+     * de `database` es una consulta con `partition_key IN (…)` y cursor
+     * estable); si no, K llamadas a `enumerateRelations` concatenadas
+     * (correcto, K barridos — el precio queda escrito en la tabla «Limits»).
+     * Sin particiones es 500: un barrido para nadie no es un éxito.
+     *
+     * **El respaldo es exhaustivo o RUIDOSO** (2.4.0-alpha.8 · C2; panel relay
+     * 2, analista §8, juez 7.1 🟠). Hasta alpha.7 acumulaba las K páginas y
+     * devolvía el cursor de la ÚLTIMA partición que tenía más; reanudar con él
+     * aplicaba `uuid > after` a TODAS y **perdía tuplas en silencio** (medido:
+     * 6 en el store, 5 vistas) — en el ORIGEN de una migración eso es «esa
+     * tupla no existía». Un cursor de una sola partición no sabe reanudar K,
+     * así que el respaldo no lo emite: si alguna partición devuelve cursor es
+     * 500 `E_AUTHZ_CONFIG` nombrando el método (misma doctrina que el barrido
+     * único: si no puede enumerar exhaustivamente, falla ruidoso), y un
+     * `after` que llegue aquí —un cursor que el respaldo nunca dio— es 500 con
+     * cero llamadas al driver. La salida: implementar `enumerateRelationsMany`
+     * en el driver, o paginar partición a partición con `enumerateRelations`
+     * (que es lo que hace `reconcileRelations`).
+     */
+    enumerateRelationsMany(partitions: ScopeRef[], page?: RelationPage): Promise<RelationTuplePage>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/build/src/relations/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/relations/manager.ts"],"names":[],"mappings":"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"}