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

package/build/src/drivers/openfga_driver.d.ts

@@ -142,8 +142,12 @@ export declare function isDuplicateWrite(error: unknown): boolean;
 export interface OpenFgaDriverOptions {
     apiUrl: string;
     storeId: string;
-    /** Pin del model; si se omite, FGA usa el último. */
-    modelId?: string;
+    /**
+     * **Pin del model — OBLIGATORIO** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2)): el driver comprueba
+     * UNA vez por proceso que ese modelo es el que genera su config (la puerta L11) y el servidor evalúa con ÉL. Sin él,
+     * 500 `E_AUTHZ_CONFIG` al construir con la receta (`openfga:provision` imprime `OPENFGA_MODEL_ID`).
+     */
+    modelId: string;
     /** Jerarquía del consumidor (ver ScopeChainResolver). */
     resolveChain?: ScopeChainResolver;
     /**
@@ -225,6 +229,14 @@ export interface OpenFgaDriverOptions {
      * valor «truthy» no es una aceptación.
      */
     acceptScopeDriftRisk?: boolean;
+    /**
+     * **`openfga` es EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21): no apto para producción,
+     * con límites declarados en README «Limits» que se cierran en 2.6. Construirlo exige este LITERAL, versionado; sin él
+     * (o con `true`, `'acknowledged'`, otra versión…) el constructor lanza 500 `E_AUTHZ_CONFIG` como primera línea, sin
+     * crear el cliente. Opcional en el TIPO —como `acceptScopeDriftRisk`— para que un config que solo REGISTRA la factory
+     * `openfga` (el stub publicado) siga compilando; obligatorio al construir.
+     */
+    experimental?: 'openfga@2.5';
 }
 /**
  * **El gate de construcción de `facts`** (3b-2d, panel 2 cruce 4 · S5).
@@ -247,6 +259,13 @@ export declare function assertScopeDriftGuarded(options: {
     acceptScopeDriftRisk?: boolean;
 }): void;
 export declare const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * **Vueltas del settle** (lote C · carreras, resolución 7 del juez; linaje L13): aplicaciones que
+ * `settleRoleVisibility` intenta antes de rendirse. Al agotarlas BORRA las aristas `scope#binding` de los pares (fail-CLOSED,
+ * intra-tenant: el churn exige `within` en los dos padres) y lanza 409 `E_AUTHZ_WRITE_CONFLICT` marcado PARCIAL
+ * (invariante 13: `indeterminate: true` en `onWrite`).
+ */
+export declare const SETTLE_MAX_ROUNDS = 5;
 /**
  * Cota de páginas de una enumeración (1.000.000 de tuplas a 100 por página).
  * Un `continuation_token` que no avanza —un servidor roto, un proxy o una
@@ -284,6 +303,7 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
         canonicalScopeReads: false;
         enumerateFacts: true;
         transactionalWrites: false;
+        experimental: true;
     }>;
     private client;
     private chainResolver;
@@ -306,6 +326,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * con el que este driver escribe y responde, no el último del store.
      */
     private readonly modelId;
+    /**
+     * **La comparación modelo ↔ config de L11, UNA por proceso** (`modelGate`). Es un OBJETO que se MUTA y nunca se
+     * reasigna (H11 b): las vistas `withChainResolver`/`withClock` son `Object.create(this)` y lo heredan por prototipo,
+     * así que `forRequest()` no relee el modelo por petición.
+     */
+    private readonly modelMemo;
     private consistency;
     /** Reloj de pared del driver (J1): el ÚNICO `now` de checks, filtros y re-grant. */
     private now;
@@ -355,6 +381,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * `authorize` evaluaba el deny en un instante y el rol en otro.
      */
     private checkContext;
+    /**
+     * **La lectura del modelo, UNA por proceso** (L11): `readAuthorizationModel` del `modelId` FIJADO y
+     * `factsModelDifferences` con `slice: 'roles'` (los holders, `role`, `role_binding`, `scope` y las condiciones; la
+     * igualdad es «módulo el catálogo»: `P_M` sale del propio modelo). Se memoriza el ÉXITO —también con diferencias— y un
+     * generador que no puede generar (500); **un fallo al LEER el modelo NO se memoriza, sea 503 o 500** (cierre de L11).
+     */
+    private modelGate;
+    /**
+     * **La puerta L11 del driver de ROLES** (lote «antes de RC», decisión del dueño 2026-10-17 (1); hasta L11 este driver
+     * no comparaba NINGUNA regla —P7: solo el conjunto de `permits_*`, «no es una barrera de seguridad»—: un `can_<P>` sin
+     * `but not denied_<P>`, un `rooted` cambiado o un `assignee` sin `not_expired` concedían o negaban sin error). Toda
+     * operación que llega al store la pasa ENTERA, justo después de validar su entrada y antes de la primera llamada
+     * (catálogo, resolutor y cliente incluidos); `enumerateFacts` —el ORIGEN de una migración— solo la parte
+     * `conditions`. Distinta ⇒ 500 `E_AUTHZ_CONFIG` con las rutas y CERO llamadas que evalúen o escriban.
+     */
+    private assertModel;
     /**
      * Consulta al catálogo local clasificando su fallo. Con este driver el
      * catálogo SQL sigue siendo una dependencia dura de cada pregunta: su caída
@@ -368,6 +410,58 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * alineada por ese id: un resultado por check, ni uno más ni uno menos.
      */
     private batchCheckAll;
+    /**
+     * **El catálogo de una ESCRITURA** (K4, resolución 2 del juez): con la versión contrastada en fresco SIEMPRE
+     * (`CatalogCache.freshView`), ignore o no la ventana `{ everyMs }`. Un `catalog` inyectado que no lo traiga cae en
+     * `view()` (el contrato del memo es suyo).
+     */
+    private writeCatalog;
+    /**
+     * K4 (segunda mitad): un uuid de rol que el STORE tiene y el catálogo de la escritura no conoce fuerza UNA recarga del
+     * memo (`invalidate` + foto en fresco). Si tras ella sigue ausente, el rol se borró: quien llama BORRA su arista.
+     */
+    private writeCatalogKnowing;
+    /**
+     * Un `batchCheck` con `HIGHER_CONSISTENCY` para el settle, SIN colapsar los errores por ítem: el llamante decide qué
+     * hacer con un `E_AUTHZ_RESOLUTION_LIMIT` de `ancestor` (caer a `storeChain`, condición 2 de la resolución 9) y propaga
+     * el resto (clasificados por el MISMO `fgaFailureError` que `alignBatchResults`).
+     */
+    private checkForWrite;
+    /**
+     * **La decisión del settle**, con el STORE (todas las lecturas con HIGHER, en UN `batchCheck`): para cada par, si la
+     * arista TIENE que estar (`want`) y si ESTÁ (`has`). `want` exige, por este orden:
+     *  - el rol en el catálogo de la escritura (K4: en fresco y, si falta, tras una recarga; si sigue faltando, `known: false`
+     *    y la arista se borra — «rol ausente ⇒ borra»);
+     *  - declarado para el NIVEL del scope (3b-2g · R1);
+     *  - `role_binding#role` VIVO (auditor ⚪ 8: tras un `revoke`/`purgeScope`/`purgeRole` concurrente el settle no resucita
+     *    la arista; `liveness: false` solo en la decisión PREVIA del `grant`, que escribe esa arista en el mismo `Write`);
+     *  - y, si el rol es LOCAL, su owner ancestro-o-igual del scope EN EL STORE: atajo `scope == owner` (`ancestor` no es
+     *    reflexivo, K6), `Check(scope:<owner> ancestor scope:<S>)` y, si ese `Check` excede la cota del servidor (medido en M2:
+     *    solo cuando el owner SÍ es ancestro a > 26 saltos), la cadena del store salto a salto (`storeChain`) — nunca «borrar
+     *    por si acaso» (fail-closed aleatorio cerca de la cota). La laxitud de `ancestor` ante DOS padres es deriva que ya
+     *    denuncian `moved` y reconcile (riesgo declarado del juez).
+     */
+    private decideRoleVisibility;
+    /**
+     * **El ÚNICO sitio que da de ALTA una arista `scope#binding` de rol local** (y borra las que se le pidan), en lotes ≤ 100
+     * (`Write` con `Ignore` en las dos direcciones: dice el estado que DEBE quedar, no el delta — invariante 6).
+     */
+    private writeBindingEdges;
+    /**
+     * **`settleRoleVisibility`** — el punto de paso de L13. Decide con el store (`decideRoleVisibility`), y si alguna
+     * arista no está como tiene que estar, aplica la diferencia y VUELVE A LEER; termina cuando una lectura POSTERIOR a su
+     * última escritura ve el store coherente (punto fijo: «borro una vez» deja CLOSED persistente al entrar, R1-entrar).
+     *
+     * **Cota** (resolución 7): tras `SETTLE_MAX_ROUNDS` aplicaciones sin converger (un churn que mueve el árbol en cada
+     * relectura) se RINDE: borra las aristas de los pares que NO convergieron —y, en el mismo `Write`, `giveUpDeletes` (el `assignee` de un
+     * `grant` que CREÓ la asignación: vuelta a «no ocurrió»)— y lanza 409 `E_AUTHZ_WRITE_CONFLICT` marcado PARCIAL
+     * (`indeterminate: true`). Fail-CLOSED declarado e intra-tenant; en un re-grant el 409 NO significa «no asignado».
+     *
+     * Devuelve los pares cuyo rol el catálogo ya no conoce (`known: false`): el `grant` que los CREÓ deshace su asignación.
+     */
+    private settleRoleVisibility;
+    /** Las vueltas del settle (lo que hasta el cierre 1 era el cuerpo de `settleRoleVisibility`). */
+    private settleRounds;
     private findPermission;
     /**
      * Filtro por catálogo de las lecturas de membresía (`listRoles`,
@@ -438,6 +532,13 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      */
     private rejectTransaction;
     grant(subject: SubjectRef, role: RoleQuery, scope: ScopeRef, options?: GrantOptions): Promise<GrantOutcome>;
+    /**
+     * El cuerpo de ESCRITURA del `grant` (sin la decisión de visibilidad): lee la asignación, decide entre no-op, write o
+     * delete+write, y re-aplica ante una carrera. `structure` son las aristas que van con el `assignee` en el MISMO `Write`
+     * (las tres para un rol global; sin la `scope#binding` si el store dice que el rol local no es visible ahí). `progress`
+     * cuenta los `Write` INTENTADOS (el settle del `grant` local corre si hubo alguno, también si falló: invariante 13).
+     */
+    private writeGrant;
     /**
      * Write directo de la asignación CON su estructura (3b-2f · R3); si algo ya
      * estaba, camino largo. Devuelve si existía la ASIGNACIÓN —lo dice la
@@ -550,8 +651,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * borrar una tupla inexistente—, la cadena del padre NUEVO en el store
      * (3b-8 · A5: el anti-ciclos del consumidor no ve un store
      * desincronizado) y **UN solo `Write`** con el delete del padre viejo y el
-     * write del nuevo, que es atómico dentro de la request. O(profundidad)
-     * requests, UNA mutación.
+     * write del nuevo, que es atómico PARA EL ESCRITOR (el store nunca guarda
+     * los dos padres ni ninguno) pero NO para un lector concurrente: un `Check`
+     * que dura lo que el `Write` puede leer la arista vieja por una rama del
+     * modelo y la nueva por otra (lector rasgado, fila «torn read» de Limits del
+     * README; medido 1,2–7,1 %, decisión del dueño 6b). O(profundidad) requests;
+     * con roles locales, además el barrido F4 (ver `reparent`).
      */
     onScopeMoved(child: ScopeRef, newParent: ScopeRef): Promise<void>;
     /**
@@ -623,8 +728,8 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      */
     private reparent;
     /**
-     * **El barrido del rol local** (3b-2e · E1; decisión del dueño del
-     * 2026-08-30, opción 1).
+     * **El barrido PREVIO del rol local** (3b-2e · E1; decisión del dueño del
+     * 2026-08-30, opción 1; F4: solo borra).
      *
      * En (c2) el modelo no tiene `owner`, así que `authorize` NO vuelve a
      * decidir con el árbol de hoy si un rol LOCAL sigue siendo visible: un
@@ -634,11 +739,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * un **fail-open** — y encima uno que solo se ve comparando drivers.
      *
      * Lo que se toca es la arista `scope#binding`, que es lo que hace
-     * ALCANZABLE la asignación: se BORRA donde el owner del rol ya no está en
-     * la cadena y se REESCRIBE donde vuelve a estarlo (invariante 18: volver la
-     * unit a su sitio restaura). No se toca el `assignee` —el hecho de la
-     * asignación no cambia porque el árbol se mueva, igual que en `database`—
-     * ni nada de un rol GLOBAL, cuya visibilidad no depende del árbol.
+     * ALCANZABLE la asignación: el barrido previo la BORRA donde el owner del
+     * rol no estará en la cadena NUEVA; las ALTAS (volver a su sitio restaura)
+     * son del settle de después (`settleSubtree`), el punto de paso único de
+     * L13. No se toca el `assignee` —el hecho de la asignación no cambia porque
+     * el árbol se mueva, igual que en `database`— ni nada de un rol GLOBAL, cuya
+     * visibilidad no depende del árbol.
      *
      * **Por subárbol, no por nodo** (consecuencia 2): los descendientes del
      * nodo movido también cambian de cadena.
@@ -647,9 +753,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * que no usa delegación— son **cero** requests y `moved` sigue siendo el
      * `Read` + `Write` del cruce 8. Con roles locales: una lectura por rol local
      * (sus bindings, por `role_binding#role`), la bajada del subárbol y un
-     * `Write` por lote.
+     * `Write` por lote (el coste O(roles locales) por `moved` es el 🟡 6, declarado hasta 2.6).
      */
     private sweepLocalRoleBindings;
+    /**
+     * Los bindings de roles LOCALES que cuelgan del subárbol de `movedKey` en el STORE (HIGHER), con la cadena de cada
+     * scope del subárbol. El catálogo es el de una ESCRITURA (K4: en fresco), y un uuid que el store tiene y el catálogo no
+     * conoce fuerza una recarga (`writeCatalogKnowing`); los roles se enumeran por el catálogo (el amarillo 6 —enumerar
+     * desde el store— es de 2.6). `chain` es la cadena que el nodo TENDRÁ (barrido previo) o, sin ella, la del store.
+     */
+    private localBindingsBelow;
+    /**
+     * **El settle del subárbol de un cambio de árbol** (lote C · L13): los bindings de roles locales del subárbol de
+     * `movedKey` (en el store, HIGHER, catálogo en fresco) pasan por `settleRoleVisibility`. Lo llaman `reparent` tras la
+     * arista, su atajo idempotente y su `finally`.
+     */
+    private settleSubtree;
     /**
      * **El barrido por NIVEL** (3b-2g · R1; decisión del dueño del 2026-08-30
      * (2), mismo mecanismo que E1).
@@ -660,18 +779,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * —donde `declaredRoleAt` se evalúa en cada pregunta— y **sigue
      * concediendo** en `facts`, que es la divergencia R1 del lote 2e.
      *
-     * Se cierra igual que el owner: barriendo la arista `scope#binding` de los
-     * bindings de ESE rol con la regla única de visibilidad. Lo llama
+     * Se cierra igual que el owner: dejando la arista `scope#binding` de los
+     * bindings de ESE rol como dice la regla única de visibilidad. Lo llama
      * `projectCatalogRole`, que es el hook de «una escritura de catálogo cambió
      * este rol»: el manager lo dispara tras `defineScopedRole`/`updateScopedRole`
      * y un escritor «a mano» de `authz_*` tiene el mismo deber que ya tenía con
      * el espejo de permisos (sin él, en `facts` un rol recién definido no
      * concedería nada y quitarle un permiso seguiría concediéndolo).
      *
-     * Coste: una lectura (los bindings del rol) y, **solo si el rol es LOCAL y
-     * tiene bindings**, la cadena del store de cada scope distinto donde cuelga
-     * uno; un `Write` por lote si hay algo que barrer. Un rol sin bindings —el
-     * caso de todo `defineScopedRole`— son 0 escrituras.
+     * **Desde el lote C pasa ENTERO por el settle** (L13; 🟠 1 de F4-carreras: este barrido leía `storeChain` y escribía
+     * DESPUÉS, y un `moved` que barriera entre medias quedaba pisado — fail-OPEN persistente entre tenants). El catálogo es
+     * el de una escritura (K4, hallazgo 4 del panel TREE): con un memo rancio un rol recién definido en otro proceso se
+     * ignoraba. Un rol que el catálogo ya no declara —tras la recarga— no tiene visibilidad que decidir: sus aristas se BORRAN
+     * («rol ausente ⇒ borra», K4); el resto de sus hechos son de `purgeRole`/`authz:reconcile`.
+     *
+     * Coste: una lectura (los bindings del rol) y un `batchCheck` (HIGHER) por vuelta del settle; un `Write` por lote solo
+     * si hay algo que corregir. Un rol sin bindings —todo `defineScopedRole`— son 0 escrituras.
      */
     private sweepRoleVisibility;
     /**
@@ -681,15 +804,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * NIVEL de ese scope (3b-2g · R1) y ser global o tener a su owner en la
      * cadena (3b-2e · E1). Visible ⇒ la arista se (re)escribe; no visible ⇒ se
      * borra. El `assignee` no se toca: la asignación existe igual, lo que
-     * cambia es dónde se la ve.
+     * cambia es dónde se la ve. (Desde el lote C solo lo usa el barrido PREVIO, que solo borra.)
      */
     private classifyBindingEdge;
     /**
-     * Aplica el barrido en lotes ≤ 100 (el límite del `Write`).
-     *
-     * `Ignore` en las dos direcciones: el barrido dice el estado que DEBE
-     * quedar, no el delta — borrar lo que ya no está y reescribir lo que ya
-     * estaba son no-ops, no errores (invariante 6).
+     * Aplica los BORRADOS de un barrido (lote C · L13: `applyBindingSweep` ya no da ALTAS; las altas de `scope#binding` de
+     * rol local solo salen del settle). Borrar nunca concede, así que va directo, en lotes ≤ 100 con `Ignore`.
      */
     private applyBindingSweep;
     /**
@@ -698,7 +818,8 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * tiene que gobernar el barrido; el resolutor del consumidor no participa.
      * Un nodo con más de un padre es deriva y se dice (`assertOneParent`), y el
      * recorrido está acotado por el mismo tope de páginas que las
-     * enumeraciones: un ciclo escrito a mano no cuelga el proceso.
+     * enumeraciones: un ciclo escrito a mano no cuelga el proceso. Alimenta
+     * escrituras (anti-ciclos de `reparent`, barrido, caída del settle) ⇒ HIGHER (hallazgo 3 TREE).
      */
     private storeChain;
     /**
@@ -826,6 +947,13 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * divergencia R1 del lote 2e.
      */
     projectCatalogRole(roleUuid: string): Promise<void>;
+    /**
+     * La proyección `permits_<P>` de UN rol (la otra mitad de `projectCatalogRole`). **Hallazgo 4 del panel TREE (K4)**: el
+     * catálogo es el de una ESCRITURA (`writeCatalog`, versión en fresco) — con un memo `{ everyMs }` que todavía no conoce
+     * un rol recién definido en otro proceso, `rolePermissionsOf` devolvía `[]` y esto BORRABA sus `permits_*` (fail-closed
+     * medido: `dave@C`). Mutante `project.memo-catalog`.
+     */
+    private projectRolePermits;
     /**
      * **Reconstruye el store desde `authz_*` + el árbol del consumidor.**
      *
@@ -1085,6 +1213,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * default `?? []` sobre `tuples` vuelva a este fichero.
      */
     private tuplesOrThrow;
+    /**
+     * **`readAllTuples` para una lectura que ALIMENTA UNA ESCRITURA** (lote C · carreras, resolución 8; hallazgo 3 TREE):
+     * con `HIGHER_CONSISTENCY` siempre (`WRITE_CONSISTENCY`). Es el helper ÚNICO: la guardia de fuente de
+     * `tests/visibility_settle.spec.ts` exige que los métodos que escriben lean por aquí (o por `checkForWrite`).
+     */
+    private readForWrite;
     private readAllTuples;
 }
 /**
@@ -1120,4 +1254,3 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
  * en silencio los datos de quien ya usaba ese nombre).
  */
 export declare const OWN_FACTS_OBJECT_TYPES: ReadonlySet<string>;
-//# sourceMappingURL=openfga_driver.d.ts.map