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

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

@@ -1,8 +1,26 @@
 import type { Clock } from '../clock.js';
-import type { RelObject, RelSubject, RelationObjectsPage, RelationSubjectsPage, RelationPage, RelationTuplePage, RelationsDriver, RelationsDriverCapabilities, RelationTransactionOptions, RelationWriteOptions, ScopeRef } from '../types.js';
+import type { RelObject, RelSubject, RelationObjectsPage, RelationSubjectsPage, RelationPage, RelationTuplePage, RelationsDriver, RelationsDriverCapabilities, RelationTransactionOptions, RelationWriteOptions, RelationDenyOptions, RelationDecision, ScopeRef } from '../types.js';
 import type { HolderTypeMap } from './openfga_driver.js';
 import type { RelationsConfig } from '../relations/define_relations_config.js';
 export declare const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * **Tope de operaciones por `Write` en FGA** — `--max-tuples-per-write` del servidor, default 100. MEDIDO en v1.19.0
+ * (`openfga-dev`, lote D · cierre 1 de D1): 100 deletes en un `Write` entran; 101 —o 50 writes + 51 deletes— es 400
+ * «The number of write operations exceeds the allowed limit of 100» y NO se aplica nada (el `Write` es transaccional).
+ * Es también la frontera de la purga atómica PARA EL ESCRITOR (`#purgeByFilters`): una purga que cabe aquí es UN
+ * `Write`, sin PREFIJO que cortar —un `Check` concurrente SÍ puede observar ese `Write` a medias: lector rasgado, fila
+ * «torn read» de Limits, decisión (6a) del dueño—; con más membresías de grupo que esto, el residuo es una fila DECLARADA
+ * (README, «Deny on relations»).
+ * **Requisito del despliegue: `--max-tuples-per-write` ≥ 100** (README, «Limits»). Un servidor con el tope MÁS BAJO
+ * responde 400 `exceeded_entity_limit` al primer `Write` que lo pase, y ése puede no ser el primero de la purga (con
+ * tope 50 y `[3 allows][60 membresías][40 denies]` el `Write` de 3 ya se aplicó): el driver lo dice como **500
+ * `E_AUTHZ_CONFIG`** nombrando el requisito —no como un 503 que parece transitorio: repetida, la purga vuelve a pedir
+ * un `Write` de más de lo que el servidor admite y no termina nunca— y, si ya borró algo, **marcado como escritura
+ * parcial** (`indeterminate: true`, invariante 13). Cierre 2 de D1 · ⚪ N3 del auditor (la letra anterior, «503 sin
+ * haber borrado nada», era falsa con varios `Write`). Uno con el tope más alto no cambia nada (el driver sigue partiendo
+ * en 100). Sin opción para bajarlo: la cota es del servidor y el remedio es su arranque.
+ */
+export declare const RELATIONS_PURGE_WRITE_MAX = 100;
 /**
  * **B4 (plan 2.5 · lote B): el corte EFECTIVO de `ListObjects` del servidor**.
  * Pasado, el servidor devuelve lo que llevaba resuelto con 200 y SIN señal
@@ -40,8 +58,12 @@ export declare const MONOTONIC_CLOCK: unique symbol;
 export interface OpenFgaRelationsDriverOptions {
     apiUrl: string;
     storeId: string;
-    /** Pin del model FUSIONADO; si se omite, FGA usa el último del store. */
-    modelId?: string;
+    /**
+     * **Pin del model FUSIONADO — OBLIGATORIO** (L11, decisión del dueño 2026-10-17 (2): D14 ampliado a los dos drivers
+     * `openfga`, siempre). Sin él cada `Check` evalúa contra el ÚLTIMO modelo del store mientras la puerta L11 compara
+     * el del arranque. `openfga:provision` lo imprime (`OPENFGA_MODEL_ID`).
+     */
+    modelId: string;
     /** Holders del consumidor: morph name → tipo FGA. El MISMO mapa del driver de roles. */
     holderTypes: HolderTypeMap;
     /** Deadline de cada llamada en ms (default 5000): vencido ⇒ 503. */
@@ -90,6 +112,12 @@ export interface OpenFgaRelationsDriverOptions {
      * `RelationsManager` con `clock` (`withClock`).
      */
     now?: Clock;
+    /**
+     * **`openfga` es EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4): el MISMO literal versionado que el driver de roles.
+     * Sin él, 500 `E_AUTHZ_CONFIG` al construir (primera línea, sin crear el cliente). Opcional en el tipo para que el stub
+     * que solo registra la factory compile; obligatorio al construir.
+     */
+    experimental?: 'openfga@2.5';
 }
 export declare class OpenFgaRelationsDriver implements RelationsDriver {
     #private;
@@ -133,7 +161,36 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      */
     withClock(now: Clock): RelationsDriver;
     relate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    /**
+     * **El techo de anidación de grupos de ESTE driver** (lote «antes de RC» · R1, decisiones del dueño 2026-10-17 (5) y
+     * (5-bis), opción (a)): ACTIVO por defecto. Se CALIBRA contra el servidor (`#calibratedGroupDepth`) y es el mínimo de
+     * la sonda positiva y la negativa (22 en OpenFGA v1.19 con `--resolve-node-limit` por defecto, medido en F0 · M-c); el
+     * `maxGroupDepth` de la config solo puede BAJARLO — uno mayor que el calibrado es 500 `E_AUTHZ_CONFIG` con las dos
+     * cifras (el despliegue promete un techo que el servidor no resuelve) —, y `false` lo apaga de forma explícita (sin
+     * calibrar). Solo lectura: lo usa `relate` antes de escribir una arista `group#member` y el plan de
+     * `reconcileRelations` sobre el destino.
+     */
+    groupDepthLimit(): Promise<number | null>;
     unrelate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    /**
+     * **`deny` = UN `Write` de la tupla `denied_<rel>`** (lote D · D1): sin caducidad (D3), así que no hay renovación
+     * ni ventana —un re-deny idéntico lo ignora el servidor (`on_duplicate: ignore`)—; una tupla de deny escrita a mano
+     * CON condición devuelve 409 y, desde el cierre 1 de D2 (🟡 4), sale como 500 `E_AUTHZ_CONFIG` con la receta
+     * (`AuthorizationConfigError.conditionalDeny`; hasta entonces era un 503 que se repetía para siempre). Antes del `Write`: la
+     * puerta de `{ transaction }` (L-5), F-05 sobre el nombre PÚBLICO, la puerta del opt-in (fase `'write'`), sin
+     * caducidad, la partición, `*`, el sujeto y la puerta del modelo (L11). CERO llamadas si algo de eso falla.
+     */
+    deny(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationDenyOptions): Promise<void>;
+    /**
+     * **`removeDeny` = UN delete de `denied_<rel>`** (no-op si no está). Sobre CUALQUIER tipo declarado (D8/R2-4 b):
+     * `Write` con delete no valida la relación contra el modelo (medido en v1.19.0), así que un deny vivo de un tipo
+     * que retiró el opt-in se puede borrar. Ojo: quitar un deny CONCEDE (filas declaradas S8–S10).
+     * **La puerta del modelo (L11, antes D-31) SÍ corre aquí** (letra corregida en el cierre 1 de D1, ⚪ 5 del auditor:
+     * la decisión 4 del informe decía que no): con el opt-in vivo y un modelo fijado sin `denied_*` ⇒ 500 antes del
+     * delete. Con el opt-in RETIRADO no hay guarda (el tipo no está en la config con `deny`) y el delete borra de verdad
+     * (medido por el auditor: `listDenies` de 1 a 0 y `check` vuelve a `true` con el modelo viejo) — retirar es reversible.
+     */
+    removeDeny(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationDenyOptions): Promise<void>;
     /**
      * **F-05 en las LECTURAS y las PURGAS del driver** (2.4.0-alpha.3, cierre
      * del 🔴 1 / 🟠 2 del auditor; la MISMA función y la misma posición que
@@ -161,6 +218,29 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      * del id POR ÍTEM antes de componer nada (defensa en profundidad).
      */
     checkMany(subject: RelSubject, relation: string, objects: RelObject[], partition: ScopeRef): Promise<boolean[]>;
+    /**
+     * **`decideMany` = un `batchCheck` con `R` y los `denied_<m>` de las relaciones FUENTE de `down*(R)`** (lote D ·
+     * D9, juez ronda 2 §4): por el cierre ascendente del modelo (`denied_X = this ∨ denied_P`), `denied_<fuente>`
+     * cubre todo `up*(down*(R))` — en el retículo del contrato, 2 ítems por objeto (`R` y `denied_owner`). Mismo
+     * `current_time` en TODOS los ítems (un `now` por lote), alineado por `correlationId` (`alignBatchResults`, la
+     * misma función que `checkMany` y roles), troceado por `FGA_MAX_BATCH_CHECK`, y un `error` en UN ítem ⇒ 503 para
+     * todo el lote (nunca `none`: S15). La decisión sale de `decideFrom`, la regla ÚNICA (la misma que `database` y el
+     * doble). En un tipo sin opt-in se pregunta el deny solo si el modelo que sirve el driver lo declara (opt-in
+     * retirado con el modelo aún publicado, D8); si no, cada posición es `allow` o `none` (no hay deny posible).
+     */
+    decideMany(subject: RelSubject, relation: string, objects: RelObject[], partition: ScopeRef): Promise<RelationDecision[]>;
+    /**
+     * **`denyPhase` — ¿admite este driver escrituras de deny en el tipo?** (lote D · D2, R2-5). La fase del opt-in EN
+     * LA CONFIG DE ESTE DRIVER y, con opt-in, el modelo FIJADO comprobado con la MISMA puerta L11 que `deny` (500 si
+     * no declara `denied_<rel>`). F-05 estricto del par, antes de nada (422, cero llamadas). La llama
+     * `reconcileRelations` en la fase de plan cuando el origen trae denies: un destino `openfga` sin `'write'` en el
+     * tipo, o con un pin a un modelo sin el deny, NIEGA la pasada antes de la primera escritura (jamás `skipped`).
+     */
+    denyPhase(object: {
+        type: string;
+    }, relation: string): Promise<'read' | 'write' | null>;
+    /** `listDenies` = `Read` por `(object, denied_<rel>)`: los denies DIRECTOS (hechos). Cualquier tipo declarado (D8). */
+    listDenies(relation: string, object: RelObject, partition: ScopeRef): Promise<RelationSubjectsPage>;
     /**
      * `listObjects` = `ListObjects` (resuelve includes + usersets del lado del
      * servidor) + FILTRO por partición + señal de TRUNCADO (`#listObjectsPage`:
@@ -169,14 +249,14 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      * se consume entre todas — otra razón para señalar el truncado y no callar
      * (documentado en el README).
      */
-    listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef, _page?: RelationPage): Promise<RelationObjectsPage>;
+    listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef): Promise<RelationObjectsPage>;
     /**
      * `listSubjects` = `Read` por `(object, relation)` — hechos DIRECTOS del
      * relation EXACTO (invariante 7): ni transitivo (eso es `membersOf`) ni
      * derivado por includes. `usersetSubjects: true` ⇒ los usersets
      * (`group#member`) salen junto con los holders.
      */
-    listSubjects(relation: string, object: RelObject, partition: ScopeRef, _page?: RelationPage): Promise<RelationSubjectsPage>;
+    listSubjects(relation: string, object: RelObject, partition: ScopeRef): Promise<RelationSubjectsPage>;
     /**
      * **`membersOf` ⇒ 500 `E_AUTHZ_UNSUPPORTED`** (cara `whenFalse`): la
      * membresía TRANSITIVA de un grupo sería `ListUsers`, que trunca al tope del
@@ -202,12 +282,19 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      * la CADUCADA también llega, con su `expiresAt` (R-15), para que el destino
      * la cuente en `skipped`.
      *
+     * **Una tupla con condición AJENA llega marcada** (`invalidCondition`, L11) y
+     * con `expiresAt` = la ÉPOCA. Eso es conservador SOLO para los allows: un
+     * lector que ignore la marca lee el deny (o la membresía de `group` que lo
+     * transporta) como VENCIDO y deja de negar —fail-OPEN— (cierre-2 · ⚪ C3).
+     * Ninguna fecha sirve para los dos tipos de tupla: el lector tiene que mirar
+     * `invalidCondition` ANTES que `expiresAt` (el plan del paquete lo hace).
+     *
      * **Coste: O(tuplas del store) por PASADA** (2.4.0-alpha.6): es un barrido
      * entero por llamada, sea cual sea el tamaño de la partición (medido: 5 000
      * tuplas ⇒ 50 páginas ≈ 170 ms; 15 000 ⇒ 151 páginas ≈ 0,5 s). Para K
      * particiones usa `enumerateRelationsMany`: UN barrido en vez de K.
      */
-    enumerateRelations(partition: ScopeRef, _page?: RelationPage): Promise<RelationTuplePage>;
+    enumerateRelations(partition: ScopeRef, page?: RelationPage): Promise<RelationTuplePage>;
     /**
      * **`enumerateRelationsMany` — K particiones en UN barrido** (2.4.0-alpha.6;
      * panel relay, analista §3: con 3 particiones 1,4 s → 0,46 s). MISMA
@@ -234,7 +321,7 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      * se cuenta en `diagnostics.unparseableTuples` y se avisa. Sin particiones
      * es 500 `E_AUTHZ_CONFIG` con cero lecturas: no hay «éxito vacío».
      */
-    enumerateRelationsMany(partitions: ScopeRef[], _page?: RelationPage): Promise<RelationTuplePage>;
+    enumerateRelationsMany(partitions: ScopeRef[], page?: RelationPage): Promise<RelationTuplePage>;
     /**
      * Borra TODAS las tuplas del objeto (cualquier relación) y demuestra cero.
      * Hasta 2.5.0 barría las DOS ortografías del uuid de partición (🟡2);
@@ -252,4 +339,18 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      */
     purgeSubject(subject: RelSubject, partition: ScopeRef, options?: RelationTransactionOptions): Promise<void>;
 }
-//# sourceMappingURL=openfga_relations_driver.d.ts.map
+/**
+ * **Los `Write` de una purga, en orden** (lote D · cierre 1 de D1, 🟠 1; ver `#purgeByFilters`): uno solo si todo cabe
+ * en `RELATIONS_PURGE_WRITE_MAX`; si no, en el orden de BORRADO del punto de paso ÚNICO `relationDeleteOrder`
+ * (`src/relations/tuple_order.ts`, cierre 1 de D2 · 🟠 1: el MISMO que usa el reconcile) — allows sobre objetos que no
+ * son `group`, luego las membresías `group:*#member` (las portadoras de deny al final, ordenadas por objeto y sujeto) y
+ * al final los `denied_*` —, con CADA CLASE en sus PROPIOS `Write` (con ≤ 100 membresías, uno). Pura: la tabla de verdad
+ * del caso la juzga contra el servidor, y la PROPIEDAD la juzga sin servidor la guardia de superficie
+ * (`GS · P · openfga.purge.order`, cierre 2 de D1 · ⚪ N2), con los mutantes de orden en el corredor publicado
+ * (`npm run check:guard-mutants`). Exportada solo para eso: no sale por `/openfga`.
+ */
+export declare function purgeWrites<K extends {
+    user: string;
+    relation: string;
+    object: string;
+}>(keys: readonly K[]): K[][];