@jantstack/adonis-authz 2.5.0-alpha.2 → 2.5.0-alpha.4

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

@@ -22,4 +22,3 @@ export interface RelationTupleIdentity {
  */
 export declare function relationSubjectKey(subject: RelSubject): string;
 export declare function relationTupleKey(tuple: RelationTupleIdentity): string;
-//# sourceMappingURL=tuple_key.d.ts.map

package/build/src/relations/tuple_key.js

@@ -57,4 +57,3 @@ export function relationTupleKey(tuple) {
     assertRelationId('la relación', tuple.relation);
     return `${kind}|${scopeKey(tuple.partition)}|${tuple.object.type}:${tuple.object.id}#${tuple.relation}@${relationSubjectKey(tuple.subject)}`;
 }
-//# sourceMappingURL=tuple_key.js.map

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

@@ -0,0 +1,127 @@
+/**
+ * **El ORDEN de las escrituras y de los borrados de relaciones — punto de paso ÚNICO** (plan 2.5 · lote D; linaje L10
+ * «el estado intermedio de una operación multi-request concede», PROMOVIDO: 3b-2f R3, 3b-6 P1, D1 🟠 1 —la purga de
+ * `openfga`—, D2 🟠 1 —el reconcile— y, en el cierre 2 de D2, 🟡 N3 —escrituras y poda COMPUESTAS—). Lo usan los DOS
+ * caminos que escriben o borran relaciones en varias requests: `applyPartition` del reconcile
+ * (`src/relations/reconcile.ts`) y `purgeWrites` de las purgas de `openfga` (`src/drivers/openfga_relations_driver.ts`).
+ *
+ * **Cierre 2 de D2 · 🟡 N3 (estructural).** Hasta aquí había DOS órdenes (uno de escritura y otro de borrado) y el reconcile
+ * los encadenaba: TODAS las escrituras y luego TODA la poda. Un ex-miembro componía con un allow nuevo (U ∈ g sobra,
+ * `g#member viewer X` es nuevo: cortada tras la 1.ª escritura, U concedía sobre X y ni el inicial ni el final lo hacían).
+ * Ahora hay UNA función, `relationTransitionOrder`, que ordena la TRANSICIÓN entera (escrituras, borrados y renovaciones)
+ * y una propiedad que se DEMUESTRA por fuerza bruta (`tests/helpers/order_bruteforce.ts`, propiedad
+ * `relations.order.exhaustive` de la guardia y `tests/relations_order_exhaustive.spec.ts`).
+ *
+ * **Cinco fases** (las cuatro de los extremos solo restringen o solo amplían; lo difícil es la de en medio):
+ *
+ *  1. escribir los DENIES nuevos (y rehacer los que cambian) — solo restringe;
+ *  2. borrar los ALLOWS sobrantes sobre objetos que no son `group` — solo restringe;
+ *  3. las MEMBRESÍAS `group:*#member` que entran y que salen, en el orden de un GRAFO DE PRECEDENCIAS (abajo); con los
+ *     allows reducidos a los que están en los dos estados y TODOS los denies de los dos estados presentes, que es el
+ *     contexto más restrictivo posible para el paso difícil;
+ *  4. escribir los ALLOWS nuevos (y las renovaciones que no son denies) — con las membresías y los denies finales
+ *     presentes, solo puede conceder lo que concede el final;
+ *  5. borrar los DENIES sobrantes, los ÚLTIMOS — idem.
+ *
+ * **El grafo de la fase 3.** Para cada membresía que cambia (arista `sujeto → grupo`) se calcula, en el grafo UNIÓN de
+ * los dos estados, qué objetos DENIEGA lo que alcanza su grupo (`D`) y qué objetos le CONCEDE de forma efectiva (`A`: los
+ * allows que están en los dos estados, menos los que cortan los denies que su grupo alcanza por aristas que no cambian —
+ * el «auto-corte», que solo se aplica con el predicado `cuts` de la config: sin él, ningún allow se da por cortado, lo
+ * conservador). Las precedencias, entre aristas que comparten algún sujeto:
+ *
+ *  - **C1** (dos que entran): la que trae un deny sobre X antes que la que trae un allow sobre X;
+ *  - **C2** (dos que salen): la que lleva un allow sobre X antes que la que lleva un deny sobre X (salvo que el sujeto
+ *    solo alcance la primera a través de la segunda);
+ *  - **C3** (una que sale y otra que entra en el MISMO camino anidado, `U ∈ h` sobra y `h ⊂ g` es nueva): la que sale
+ *    antes, si el camino compuesto llevaría un allow efectivo — es el 🟡 N3 con anidamiento;
+ *  - **C4** (una que entra y otra que sale y las dos traen un deny sobre X que protege un allow del sujeto): la que entra
+ *    antes — el sujeto cambia de grupo denegado sin un instante sin deny.
+ *
+ * Se ordena por componentes fuertemente conexas (Tarjan) en orden topológico; entre las disponibles, escrituras antes que
+ * borrados, las escrituras de más lejos del sujeto primero y los borrados de más cerca primero, y (objeto, sujeto): el
+ * reparto NO depende del orden de enumeración del origen ni del `Read`.
+ *
+ * **Lo que garantiza, exactamente** (demostrado por fuerza bruta; README «Denies migrate as denies»): **si el grafo de
+ * precedencias no tiene un CICLO, ningún PREFIJO (el estado del store tras cada `Write` de la secuencia) concede algo que
+ * no concedían el estado inicial o el final, y ningún sujeto denegado en los dos concede en ninguno.** Es una garantía
+ * sobre PREFIJOS —una operación CORTADA—, no sobre lectores: un `Check` que abarca dos `Write` consecutivos puede mezclar
+ * lecturas de uno y otro (lector rasgado, fila «torn read» de Limits; decisión (6a) del dueño, linaje L12). El RESIDUO es exactamente el ciclo (`residue`): dos membresías
+ * que cambian en la misma pasada cuyas exigencias se contradicen —la forma típica: el mismo sujeto entra (o sale) a la
+ * vez en dos grupos y cada uno trae un deny que corta un allow que trae el otro—. Ahí NO existe en general ningún orden
+ * seguro (la fuerza bruta lo mide: de los casos del ciclo que conceden, una parte no admite NINGUNA permutación del diff
+ * segura), así que el orden aplica las aristas del ciclo en el orden de prioridad y lo DEVUELVE para que la pasada lo diga.
+ *
+ * Pura (regla 2 de pureza): no importa nada del paquete. Coste: lineal en las tuplas más los pares de membresías que
+ * cambian de un MISMO sujeto, y los de cada arista anidada (`group:x#member`) con las de los sujetos que tiene debajo.
+ */
+/** La clase de una tupla para el orden. */
+export type RelationOrderClass = 'deny' | 'membership' | 'allow';
+/**
+ * La vista mínima de una tupla para ordenarla, en la forma del STORE: `object` = `<tipo>:<id>`, `user` =
+ * `<tipo>:<id>` (holder) o `<tipo>:<id>#<rel>` (userset); `relation` = la relación PÚBLICA (sin `denied_`), que solo hace
+ * falta con el predicado `cuts`. Basta con que sea CONSISTENTE dentro de una llamada (el reconcile la compone sin
+ * partición; `openfga` con la clave de partición en el id).
+ */
+export interface RelationOrderView {
+    deny: boolean;
+    object: string;
+    user: string;
+    relation?: string;
+}
+/** ¿Un deny de `deniedRelation` corta un allow de `allowedRelation` sobre un objeto de `objectType`? (D5: `d ∈ up*(a)`). */
+export type RelationCuts = (objectType: string, deniedRelation: string, allowedRelation: string) => boolean;
+/** Un paso del orden: `write` (la tupla entra), `delete` (sale) o `renew` (está en los dos estados y se reescribe). */
+export interface RelationOrderStep<T> {
+    item: T;
+    op: 'write' | 'delete' | 'renew';
+}
+/** El orden de una transición y su RESIDUO: las membresías de un ciclo del grafo de precedencias (sin garantía). */
+export interface RelationOrderPlan<T> {
+    steps: RelationOrderStep<T>[];
+    residue: T[];
+}
+export interface RelationTransition<T> {
+    /** Las tuplas que ENTRAN (no están en el estado inicial). */
+    writes?: readonly T[];
+    /** Las tuplas que SALEN (no están en el estado final). */
+    deletes?: readonly T[];
+    /** Las que están en los dos estados y se reescriben (otra caducidad): no cambian lo que se concede EN `now`. */
+    renewals?: readonly T[];
+    /**
+     * Cierre 4 de D2 · 🟡 horizonte: las de `renewals` que ACORTAN la caducidad (el resto la alarga o la quita). En `now` una
+     * renovación no cambia nada, pero en el instante en que vence la caducidad más corta de las dos es una tupla que SALE
+     * (acorta) o que ENTRA (alarga) — y un corte de la pasada que dure hasta entonces lo ve. Por eso una renovación de
+     * MEMBRESÍA entra en el grafo de la fase 3 como una salida o una entrada (sin cambiar lo que hace: `op: 'renew'`), y la
+     * de un allow que ACORTA va con los borrados de la fase 2.
+     */
+    shortening?: readonly T[];
+    /** Las tuplas que EXISTEN en el estado inicial o en el final (pueden incluir las de arriba). */
+    context?: readonly RelationOrderView[];
+}
+export declare function relationOrderClass(view: RelationOrderView): RelationOrderClass;
+/**
+ * Los grupos PORTADORES de deny: el `#member` de cada uno es sujeto de algún deny de `views`, más el cierre por la
+ * anidación (`group:G#member@group:H#member` con G portador ⇒ H portador). Devuelve los OBJETOS (`group:<id>`). Lo usa
+ * el reconcile para clasificar la renovación de una membresía PORTADORA (cierre 2 de D2 · 🟠 N1, `renewal-unsafe`).
+ */
+export declare function denyCarrierGroups(views: Iterable<RelationOrderView>): Set<string>;
+/**
+ * **Los denies que TRANSPORTA un grupo** (cierre 6 de D2 · ⚪ D5-3, para la letra): los `deny` cuyo sujeto es el `#member`
+ * del grupo o de un grupo que lo contiene, transitivamente (`group:G#member@group:H#member`: los miembros de H heredan los
+ * denies de G). Devuelve las VISTAS de esos denies, en el orden de entrada. Misma regla que `denyCarrierGroups`, al revés.
+ */
+export declare function carriedDenies(views: Iterable<RelationOrderView>, group: string): RelationOrderView[];
+/**
+ * **El orden de una TRANSICIÓN** (cierre 2 de D2 · 🟡 N3): ver el docblock del módulo. `residue` = las membresías de los
+ * ciclos del grafo de precedencias (sin garantía); vacío ⇒ ningún PREFIJO concede fuera de inicial ∪ final.
+ */
+export declare function relationTransitionOrder<T>(transition: RelationTransition<T>, view: (item: T) => RelationOrderView, options?: {
+    cuts?: RelationCuts;
+}): RelationOrderPlan<T>;
+/**
+ * **El orden de ESCRITURA** de un conjunto que solo ENTRA (atajo de `relationTransitionOrder` sin borrados): `context` =
+ * las tuplas que existen y no se escriben.
+ */
+export declare function relationWriteOrder<T>(items: readonly T[], view: (item: T) => RelationOrderView, context?: readonly RelationOrderView[]): T[];
+/** **El orden de BORRADO** de un conjunto que solo SALE (las purgas de `openfga`): allows → membresías → denies. */
+export declare function relationDeleteOrder<T>(items: readonly T[], view: (item: T) => RelationOrderView, context?: readonly RelationOrderView[]): T[];