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

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

@@ -0,0 +1,215 @@
+/**
+ * **El límite de anidación de grupos** (lote «antes de RC» · R1; decisiones del dueño 2026-10-17 (5) «límite SEGÚN EL
+ * DRIVER» y (5-bis) opción (a) tras F0 · M-c). Piezas PURAS (sin backend), compartidas por los dos drivers de relaciones
+ * y por el plan de `reconcileRelations`, para que la regla sea UNA:
+ *
+ *  - **qué es una arista de anidación**: `group:<Gp>#member@group:<Gc>#member` (los miembros de Gc son miembros de Gp);
+ *  - **la profundidad es el camino MÁS LARGO** de aristas grupo⊂grupo (T-3 del tester: en un DAG con un camino corto y
+ *    otro largo hacia la misma cima, OpenFGA da 503 a los NO-miembros por el largo; un BFS por niveles admitiría ese
+ *    grafo). Un ciclo PREEXISTENTE se cuenta de forma CONSERVADORA: sus k nodos pesan k − 1 saltos (cota superior del
+ *    camino simple más largo que lo atraviesa) — más negativas, nunca menos;
+ *  - **la validación de `maxGroupDepth`** (V2-1 del auditor): entero 1..`GROUP_DEPTH_CONFIG_MAX` o `false` (el ÚNICO
+ *    «apagado»), y nada más — `''`, `NaN`, `0`, `-1`, `Infinity`, `24.5`, `'24'`, `null`, `true` ⇒ 500 al ARRANCAR
+ *    (`defineRelationsConfig`), jamás un gate apagado en silencio;
+ *  - **la calibración** (decisión 5 + 5-bis): el techo de `openfga` se MIDE contra el servidor con tuplas contextuales
+ *    (solo lectura) y es el MÍNIMO de la sonda POSITIVA (un miembro: T) y la NEGATIVA (un no-miembro CON alguna
+ *    membresía: F; una sonda sin membresías es CIEGA, F a cualquier profundidad, F0 · M-c). La búsqueda es pura sobre
+ *    una sonda inyectada.
+ *
+ * Pureza (regla 2): solo depende de los errores. Nada de `manager`/`drivers/*`.
+ */
+import { AuthorizationBackendError, GroupDepthLimitError } from '../errors.js';
+import type { RelObject, RelSubject } from '../types.js';
+/**
+ * **El techo medido** en OpenFGA v1.19.0 con `--resolve-node-limit` por defecto (25): un miembro resuelve 24 saltos
+ * grupo⊂grupo y un no-miembro CON membresías 22 (F0 · M-c, 200/200 en los dos bordes, independiente de `includes` 0..3 y
+ * del deny) ⇒ el MÍNIMO, 22. Es la cifra de la fila de «Limits»; la VERDAD de cada despliegue es la calibración.
+ */
+export declare const RELATIONS_GROUP_DEPTH_MEASURED = 22;
+/**
+ * **El mayor `maxGroupDepth` que se acepta** (auditor M4): la calibración usa una cadena de tuplas CONTEXTUALES y el
+ * servidor admite 100 por `Check`; la forma de dominio cuesta K + 2. Por encima no hay nada que medir.
+ */
+export declare const GROUP_DEPTH_CONFIG_MAX = 97;
+/**
+ * **El mayor K que la calibración prueba**: la sonda NEGATIVA lleva dos tuplas más (la membresía del no-miembro y la
+ * suya propia, M-c) ⇒ K + 4 ≤ 100. Un `maxGroupDepth: 97` es válido en la config y, contra un servidor que resolviera
+ * todo, la calibración lo deja en 96 ⇒ 500 (el techo pedido no se puede DEMOSTRAR).
+ */
+export declare const GROUP_DEPTH_CALIBRATION_MAX = 96;
+/**
+ * **Cuántos grupos recorre como mucho la comprobación de UNA arista** (hacia arriba desde Gp más hacia abajo desde Gc).
+ * Pasarla ⇒ 422 `E_AUTHZ_GROUP_DEPTH_LIMIT` con motivo `too-many-groups`, nunca «pasa». El recorrido además se corta en
+ * cuanto un nivel del BFS supera el techo (el camino más corto ya excede: el largo también).
+ */
+export declare const GROUP_DEPTH_MAX_NODES = 10000;
+/**
+ * **El presupuesto de la comprobación de UNA arista en `openfga`** (cierre de R1 · 🟠 1 del auditor: amplificación de
+ * lecturas contra el store COMPARTIDO). En `openfga` el gate hace un `Read` por grupo de la frontera, y el `Read` hacia
+ * ABAJO (objeto + `member`) trae también los HOLDERS —el servidor no admite filtrar por tipo de `user` (`user: 'group:'`
+ * ⇒ 400 `validation_error`, medido en :8090 v1.19)—: sin presupuesto, quien controla la anidación hacía pagar O(grupos ×
+ * miembros/100) requests a cada `relate`. Pasar cualquiera de los tres ⇒ 422 `E_AUTHZ_GROUP_DEPTH_LIMIT`, motivo
+ * `too-many-groups` (fail-closed: no se escribe). Requests (páginas de `Read`), tuplas leídas y un deadline TOTAL del
+ * veredicto (comprobado antes de cada request; una request en vuelo la acota el `timeoutMs` del cliente).
+ */
+export declare const GROUP_DEPTH_MAX_READS = 2000;
+export declare const GROUP_DEPTH_MAX_TUPLES = 50000;
+export declare const GROUP_DEPTH_DEADLINE_MS = 10000;
+/**
+ * **La espera tras una calibración FALLIDA** (cierre-2 de R1 · D5 (a), injerto del auditor; decisión del dueño 2026-10-20):
+ * la calibración de `openfga` son ~14 `Check` (bisección 0..96, dos sondas). Si cae (servidor caído, 503, deadline, el
+ * 500 de una sonda ciega), durante esta ventana la siguiente escritura de anidación recibe un error de la MISMA clase —una
+ * instancia nueva con el memorizado de `cause`, y un timeout como 503 no-timeout (cierre-3 · R-5)— sin volver a
+ * sondear —una flota de `relate` contra un servidor que se cae no lo remata con 14 `Check` cada uno—; pasada, la
+ * siguiente vuelve a calibrar (el fallo nunca se memoriza para siempre, C13a). Reloj MONÓTONO del driver.
+ */
+export declare const GROUP_DEPTH_CALIBRATION_BACKOFF_MS = 2000;
+/**
+ * **La cota de frecuencia de la RE-calibración** (cierre-2 de R1 · D5 (a) + P2 del juez): una lectura de `openfga` que
+ * recibe 503 `E_AUTHZ_RESOLUTION_LIMIT` (el servidor ya no resuelve lo que el techo memorizado prometía: el operador BAJÓ
+ * `OPENFGA_RESOLVE_NODE_LIMIT` sin reiniciar la app) invalida la calibración memorizada, como mucho UNA vez por este
+ * intervalo y por proceso; la siguiente escritura de anidación vuelve a medir. Sin la cota, una forma que dé 503 en cada
+ * lectura dispararía una calibración por lectura. SUBIR el límite del servidor no produce ningún 503 que lo delate: eso
+ * sigue pidiendo reiniciar la app.
+ */
+export declare const GROUP_DEPTH_RECALIBRATION_MIN_INTERVAL_MS = 60000;
+/** Qué cota del presupuesto se pasó (va en `details.budget` del 422). */
+export type GroupDepthBudgetKind = 'nodes' | 'reads' | 'tuples' | 'deadline';
+/** Señal INTERNA: el lector la lanza al pasar el presupuesto y `groupNestingVerdict` la convierte en `too-many-groups`. */
+export declare class GroupDepthBudgetExceeded extends Error {
+    readonly budget: Exclude<GroupDepthBudgetKind, 'nodes'>;
+    constructor(budget: Exclude<GroupDepthBudgetKind, 'nodes'>);
+}
+/** El contador de UN veredicto: `beforeRead()` antes de cada request, `charge(n)` con las tuplas de cada página. */
+export declare class GroupDepthBudget {
+    #private;
+    readonly limits: {
+        reads: number;
+        tuples: number;
+        deadlineMs: number;
+    };
+    readonly clock: () => number;
+    reads: number;
+    tuples: number;
+    constructor(limits?: {
+        reads: number;
+        tuples: number;
+        deadlineMs: number;
+    }, clock?: () => number);
+    beforeRead(): void;
+    charge(tuples: number): void;
+}
+/** Las opciones de `relate` de UNA arista planificada por el reconcile (solo el reconcile del paquete las crea). */
+export declare function plannedRelateOptions<T extends object>(options: T, tuple: {
+    subject: RelSubject;
+    relation: string;
+    object: RelObject;
+    partition: {
+        type: string;
+        uuid: string | null;
+    };
+}): T;
+/** ¿Llega ESTA arista (`child ⊂ parent` en `partition`) con las opciones que el reconcile creó para ella? */
+export declare function plannedByReconcile(options: unknown, partition: {
+    type: string;
+    uuid: string | null;
+}, edge: GroupEdge): boolean;
+/** `group:<Gp>#member@group:<Gc>#member`: la ÚNICA forma de anidar (B3: el único userset admitido es `group#member`). */
+export declare function isGroupNesting(subject: RelSubject, relation: string, object: RelObject): subject is Extract<RelSubject, {
+    relation: string;
+}>;
+/**
+ * **Valida `maxGroupDepth`** (V2-1; decisión 5: «entero 1..97 o `false`»): `undefined` ⇒ sin valor (el driver usa su
+ * techo), `false` ⇒ apagado EXPLÍCITO, entero en [1, 97] ⇒ ese techo. Cualquier otra cosa ⇒ 500 `E_AUTHZ_CONFIG`: el
+ * paquete no lee variables de entorno, y la línea típica `Number(env.get('X') ?? 24)` produce `0` (`''`) y `NaN` (`'abc'`),
+ * que con `if (depth > max)` o `if (!max)` APAGARÍAN el gate en silencio.
+ */
+export declare function assertMaxGroupDepth(value: unknown, where?: string): number | false | undefined;
+/**
+ * **Valida el PAR (`maxGroupDepth`, `enforceGroupDepth`)** — en `defineRelationsConfig` al arrancar y, desde el cierre de
+ * R1 (🟡 4 del auditor), OTRA VEZ en los dos drivers: una config extendida con spread
+ * (`{ ...defineRelationsConfig(spec), maxGroupDepth: Number(env.get('X')) }`) llegaba al driver sin pasar por la
+ * validación, y con `NaN` toda comparación `> limit` es `false`: el gate quedaba APAGADO en silencio. `enforceGroupDepth`
+ * solo admite `true`/`false`/ausente y `true` exige un número. Todo lo demás ⇒ 500 `E_AUTHZ_CONFIG`.
+ */
+export declare function assertGroupDepthSettings(maxGroupDepth: unknown, enforceGroupDepth: unknown, where?: string): {
+    maxGroupDepth: number | false | undefined;
+    enforceGroupDepth: boolean;
+};
+/** Una arista grupo⊂grupo: `child` es miembro de `parent` (ids de objeto del grupo, sin partición). */
+export interface GroupEdge {
+    child: string;
+    parent: string;
+}
+/**
+ * **La cadena más larga** (en aristas grupo⊂grupo) de un conjunto de aristas, con los ciclos colapsados de forma
+ * CONSERVADORA (cada componente fuertemente conexa de k nodos pesa k − 1). Devuelve la profundidad y una cadena
+ * representativa (los grupos, de abajo arriba) para la letra. Lineal en nodos + aristas (Tarjan iterativo + DP).
+ */
+export declare function groupChainDepth(edges: Iterable<GroupEdge>): {
+    depth: number;
+    chain: string[];
+};
+/** El veredicto de UNA arista nueva sobre la región recorrida. */
+export type GroupNestingVerdict = {
+    kind: 'ok';
+    depth: number;
+} | {
+    kind: 'cycle';
+    depth: null;
+} | {
+    kind: 'too-deep';
+    depth: number;
+    chain: string[];
+} | {
+    kind: 'too-many-groups';
+    depth: null;
+    budget: GroupDepthBudgetKind;
+};
+/** Cómo leer los vecinos de un conjunto de grupos (UNA llamada por nivel del BFS en SQL; una `Read` por grupo en FGA). */
+export interface GroupNeighbourReader {
+    /** Las aristas VIVAS cuyo `child` está en `groups` (los grupos que los contienen). */
+    parentsOf(groups: string[]): Promise<GroupEdge[]>;
+    /** Las aristas VIVAS cuyo `parent` está en `groups` (los grupos que contienen). */
+    childrenOf(groups: string[]): Promise<GroupEdge[]>;
+}
+/**
+ * **El veredicto de la arista `child ⊂ parent`** (gate de escritura de R1): recorre hacia ARRIBA desde `parent` y hacia
+ * ABAJO desde `child` (BFS por niveles, una lectura por nivel), y decide:
+ *
+ *  - `cycle` si `child` es `parent` o aparece por encima de `parent` (la arista lo cerraría);
+ *  - `too-deep` si el camino MÁS LARGO que atraviesa la arista (`alto(parent) + 1 + bajo(child)`) supera `limit` — y
+ *    también, sin terminar el recorrido, en cuanto los niveles del BFS ya lo superan (el camino corto es una cota
+ *    inferior del largo);
+ *  - `too-many-groups` si la región pasa de `maxNodes`, o si el LECTOR agota su presupuesto (`GroupDepthBudgetExceeded`:
+ *    requests, tuplas o deadline — `openfga`, cierre de R1 · 🟠 1 del auditor);
+ *  - `ok` en otro caso.
+ *
+ * La arista misma (si ya existe: renovación) no se cuenta dos veces.
+ */
+export declare function groupNestingVerdict(edge: GroupEdge, limit: number, reader: GroupNeighbourReader, maxNodes?: number): Promise<GroupNestingVerdict>;
+/**
+ * **El error de un veredicto que no es `ok`** (cierre-3 de R1 · R-2 del re-ataque; decisión firmada (3): lo transitorio es
+ * 503): el agotamiento del DEADLINE del presupuesto (`budget: 'deadline'`) no dice nada de los datos —el mismo grafo da
+ * `ok` con el servidor descargado— sino que el backend va LENTO (o lo satura otro tenant del store compartido), así que es
+ * 503 `AuthorizationBackendError` transitorio —NO la subclase timeout: la escritura no ocurrió y el manager no notifica
+ * `indeterminate` (invariante 13)— y nunca el 422 «aplana la anidación», que un cliente no reintenta. Las otras cotas
+ * (`nodes`, `reads`, `tuples`) son deterministas sobre los datos y siguen siendo 422 `too-many-groups`.
+ */
+export declare function groupNestingError(driver: string, verdict: Exclude<GroupNestingVerdict, {
+    kind: 'ok';
+}>, edge: string, limit: number): GroupDepthLimitError | AuthorizationBackendError;
+/** El 422 de un veredicto que no es `ok` (letra de `E_AUTHZ_SCOPE_DEPTH_LIMIT`: el `message` no nombra el backend). */
+export declare function groupDepthLimitError(verdict: Exclude<GroupNestingVerdict, {
+    kind: 'ok';
+}>, edge: string, limit: number): GroupDepthLimitError;
+/** Resultado de una sonda de calibración: el `Check` resolvió con la respuesta esperada, excedió, o dio la OTRA respuesta. */
+export type CalibrationProbe = 'ok' | 'too-complex' | 'blind';
+/**
+ * **La calibración del techo** (decisión 5 + 5-bis, opción (a)): el mayor K en [0, `max`] para el que la sonda
+ * POSITIVA (un miembro, T) Y la NEGATIVA (un no-miembro con membresía, F) resuelven — el MÍNIMO de las dos —, por
+ * bisección (el borde es determinista en relaciones, M-c: 200/200). Una sonda que da la OTRA respuesta (`blind`: el
+ * miembro F, el no-miembro T) es un servidor o un modelo que no evalúa como el medido ⇒ 500, jamás «pasa». Cualquier
+ * otro fallo de la sonda (503, deadline) se PROPAGA: quien llama no lo memoriza.
+ */
+export declare function calibrateGroupDepth(probe: (depth: number, side: 'positive' | 'negative') => Promise<CalibrationProbe>, max?: number): Promise<number>;