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

package/build/src/relations/define_relations_config.js

@@ -16,8 +16,9 @@
  * (`../identity.js`); JAMÁS de `../manager` ni de `../drivers/*`. Es lo que
  * mantiene `relations/` desacoplado de `roles/`.
  */
-import { RelationConfigError, RelationConfigUnknownKeyError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, } from '../errors.js';
+import { RelationConfigError, RelationConfigUnknownKeyError, RelationNotDenyableError, RelationDenyExpiryError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, } from '../errors.js';
 import { RESERVED_FACTS_TYPES, RESERVED_SLUGS, RESERVED_SLUG_PREFIXES } from '../identity.js';
+import { assertGroupDepthSettings } from './group_depth.js';
 /**
  * **El ÚNICO userset que el modelo admite como sujeto** (plan 2.5 · lote B · B3):
  * `group#member`. El generador del modelo fusionado emite, para CADA relación de
@@ -28,6 +29,21 @@ export const RELATION_USERSET_TYPE = 'group';
 export const RELATION_USERSET_RELATION = 'member';
 /** La cota de FGA para el nombre de una relación (50). Un tipo de objeto llega a 254. */
 const RELATION_NAME_MAX = 50;
+/**
+ * **El prefijo de la relación ALMACENADA de un deny** (plan 2.5 · lote D · D1): `deny(u, viewer, doc)` escribe la
+ * tupla `doc#denied_viewer@u` —en `authz_relations` (`database`) y en el store (`openfga`)—. Es el MISMO prefijo que
+ * la familia del deny de roles (`FACTS_DENIED_PREFIX`) y está en `RESERVED_SLUG_PREFIXES`: ninguna relación de dominio
+ * puede empezar por él (⚪4), así que el nombre público y el almacenado nunca colisionan.
+ */
+export const RELATION_DENY_PREFIX = 'denied_';
+/**
+ * **La cota de una relación DENEGABLE** (D1, juez ronda 2 · fila D: «≤ 43 caracteres»): `denied_<rel>` tiene que caber
+ * en los 50 de FGA (y en la columna `relation` de `authz_relations`), así que una relación de un tipo con `deny`
+ * mide como mucho `50 − 'denied_'.length` = 43. DERIVADA, como `MAX_SLUG_LENGTH`. En un tipo SIN `deny` la cota sigue
+ * siendo 50 (D-18: una cota global sería una ruptura para quien no usa el deny).
+ */
+export const DENIABLE_RELATION_NAME_MAX = RELATION_NAME_MAX - RELATION_DENY_PREFIX.length;
+const DENY_PHASES = ['read', 'write'];
 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._-]*$/;
@@ -43,10 +59,10 @@ const FGA_NAME_FORMAT = /^[a-z0-9][a-z0-9._-]*$/;
  * Las claves del lote D entran AQUÍ, en el mismo commit que su efecto.
  */
 export const RELATIONS_SPEC_KEYS = Object.freeze({
-    root: Object.freeze(['objectTypes', 'holderTypes', 'database']),
-    objectType: Object.freeze(['type', 'relations']),
+    root: Object.freeze(['objectTypes', 'holderTypes', 'database', 'maxGroupDepth']),
+    objectType: Object.freeze(['type', 'relations', 'deny']),
     relation: Object.freeze(['name', 'includes']),
-    database: Object.freeze(['membersOf']),
+    database: Object.freeze(['membersOf', 'enforceGroupDepth']),
 });
 const _exhaustiveRelationsRoot = {};
 const _exhaustiveRelationsObjectType = {};
@@ -371,6 +387,23 @@ export function defineRelationsConfig(spec) {
                 }
             }
         }
+        // D1 · D10: el opt-in del deny, sus dos fases y la cota de 43 (D-18).
+        if (objectType.deny !== undefined) {
+            if (!DENY_PHASES.includes(objectType.deny)) {
+                reject(`Config de relaciones inválida: 'objectTypes[${typeIndex}].deny' de '${type}' es ${JSON.stringify(objectType.deny)}; ` +
+                    `los valores son 'read' (fase 1: el modelo declara denied_<rel> y las lecturas lo honran; deny() sigue siendo 422) ` +
+                    `y 'write' (fase 2: además se aceptan escrituras). No hay 'true': un interruptor único no tiene secuencia de ` +
+                    `despliegue segura (un pod con el modelo viejo ignora el deny que otro escribe) — publica 'read', despliega la ` +
+                    `flota entera con el modelId nuevo y solo entonces, en otro despliegue, 'write'.`);
+            }
+            for (const relation of objectType.relations) {
+                if (relation.name.length > DENIABLE_RELATION_NAME_MAX) {
+                    reject(`Config de relaciones inválida: la relación '${type}#${relation.name}' tiene ${relation.name.length} caracteres y el ` +
+                        `tipo declara deny: su relación almacenada '${RELATION_DENY_PREFIX}${relation.name}' no cabe en los ` +
+                        `${RELATION_NAME_MAX} de FGA. Una relación de un tipo denegable mide como mucho ${DENIABLE_RELATION_NAME_MAX}.`);
+                }
+            }
+        }
         // B1: ningún ciclo en el grafo de includes del tipo (directo, de 2, de N).
         const cycle = findIncludesCycle(objectType.relations);
         if (cycle) {
@@ -393,13 +426,179 @@ export function defineRelationsConfig(spec) {
     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) });
+        // D-29: un tipo SIN deny se congela con EXACTAMENTE las dos claves de 2.4.0-alpha.10 (el generador del modelo lo
+        // emite byte a byte igual); `deny` solo aparece cuando se declaró.
+        return objectType.deny === undefined
+            ? Object.freeze({ type: objectType.type, relations: Object.freeze(relations) })
+            : Object.freeze({ type: objectType.type, relations: Object.freeze(relations), deny: objectType.deny });
     });
+    // R1 (decisión del dueño 2026-10-17 (5); V2-1 del auditor): el techo se valida AL ARRANCAR, 500 y no 422 — un valor
+    // así no es una pregunta mal hecha, es un despliegue que apagaría el límite en silencio.
+    const { maxGroupDepth, enforceGroupDepth } = assertGroupDepthSettings(spec.maxGroupDepth, spec.database?.enforceGroupDepth);
     return Object.freeze({
         objectTypes: Object.freeze(frozenTypes),
         membersOf: spec.database?.membersOf === true,
+        ...(maxGroupDepth === undefined ? {} : { maxGroupDepth }),
+        ...(enforceGroupDepth === true ? { enforceGroupDepth: true } : {}),
         hasType: (objectType) => declared.has(objectType),
         isDeclared: (objectType, relation) => declared.get(objectType)?.has(relation) ?? false,
     });
 }
-//# sourceMappingURL=define_relations_config.js.map
+/* ── Deny (plan 2.5 · lote D · D1): la fase del opt-in y los cierres del grafo de `includes` ─────────────────── */
+/** La fase del opt-in del deny de un tipo (`undefined` = sin opt-in; `group` nunca). */
+export function denyPhaseOf(config, objectType) {
+    return config.objectTypes.find((t) => t.type === objectType)?.deny;
+}
+/** ¿Algún tipo de la config declara el opt-in (en cualquier fase)? Decide D14 (`modelId` fijado obligatorio en `openfga`). */
+export function hasDenyTypes(config) {
+    return config.objectTypes.some((t) => t.deny !== undefined);
+}
+/** La relación ALMACENADA del deny de `relation` (`viewer` ⇒ `denied_viewer`). */
+export function deniedRelationOf(relation) {
+    return `${RELATION_DENY_PREFIX}${relation}`;
+}
+/**
+ * **La consulta del README §Upgrading que cuenta los denies VIVOS de relaciones** (plan 2.5 · lote D · D2; D12/S17: no
+ * hay rollback por debajo de 2.5 con denies vivos — antes de volver atrás tiene que dar 0). Portable a los tres motores
+ * (`substr` existe en SQLite, PostgreSQL y MySQL; `LIKE 'denied\_%'` no: SQLite no tiene escape por defecto). La ejecutan
+ * `tests/upgrade_recipe.spec.ts` (los cuatro modos, contra el README byte a byte) y el paso 21 del runbook.
+ */
+export const RELATION_DENIES_COUNT_SQL = "SELECT count(*) AS n FROM authz_relations WHERE substr(relation, 1, 7) = 'denied_';";
+/**
+ * **La relación ALMACENADA, leída de vuelta: nombre público + `kind`** (plan 2.5 · lote D · D2; el reconcile con
+ * `kind`). Es el PUNTO DE PASO ÚNICO de `enumerateRelations(Many)` en los dos drivers y en el doble: `denied_viewer`
+ * ⇒ `{ relation: 'viewer', kind: 'deny' }`; cualquier otra ⇒ `{ relation, kind: 'allow' }`. Inequívoco porque el
+ * prefijo está en `RESERVED_SLUG_PREFIXES` (ninguna relación de dominio puede empezar por `denied_`). Hasta D2 los
+ * drivers emitían `relation: 'denied_viewer'` sin `kind`, y `reconcileRelations` lo contaba como relación NO
+ * declarada (`skipped.undeclared`): una migración `database → openfga` no llevaba los denies.
+ */
+export function storedRelationKind(stored) {
+    return typeof stored === 'string' && stored.startsWith(RELATION_DENY_PREFIX) && stored.length > RELATION_DENY_PREFIX.length
+        ? { relation: stored.slice(RELATION_DENY_PREFIX.length), kind: 'deny' }
+        : { relation: stored, kind: 'allow' };
+}
+/**
+ * **`down*(R)`: las relaciones cuyo hecho DIRECTO satisface `R`** (R y todo lo que incluye, transitivamente). Es el
+ * PUNTO DE PASO ÚNICO del grafo de `includes` hacia abajo (lote D: antes lo reimplementaban `#expandDown` del driver
+ * `database` y el doble; con el deny hacen falta las dos direcciones en tres sitios y, calculadas tres veces,
+ * divergen). En el retículo del contrato: `down*(viewer) = {viewer, editor, owner}`.
+ */
+export function relationsDown(config, objectType, relation) {
+    const out = new Set([relation]);
+    const type = config.objectTypes.find((t) => t.type === objectType);
+    const queue = [relation];
+    while (queue.length) {
+        const current = queue.pop();
+        const def = type?.relations.find((r) => r.name === current);
+        for (const inc of def?.includes ?? []) {
+            if (!out.has(inc)) {
+                out.add(inc);
+                queue.push(inc);
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * **`up*(R)`: las relaciones que INCLUYEN a `R`** (R y todo lo que la incluye, transitivamente). Un deny en cualquiera
+ * de ellas CORTA un grant de `R` (D5, corte de camino): `up*(owner) = {owner, editor, viewer}` ⇒ un deny en `editor`
+ * anula entero un grant de `owner`.
+ */
+export function relationsUp(config, objectType, relation) {
+    const out = new Set([relation]);
+    const type = config.objectTypes.find((t) => t.type === objectType);
+    const queue = [relation];
+    while (queue.length) {
+        const current = queue.pop();
+        for (const candidate of type?.relations ?? []) {
+            if ((candidate.includes ?? []).includes(current) && !out.has(candidate.name)) {
+                out.add(candidate.name);
+                queue.push(candidate.name);
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * **D5 · CORTE DE CAMINO, la regla ÚNICA** (decisión del dueño 2026-10-14; tester §2.1, la tabla T1 de 64 estados):
+ * `check(s, Q, o) = T` sii existe un grant `T ∈ A ∩ down*(Q)` tal que `up*(T) ∩ D = ∅`, con `A` = las relaciones con
+ * allow vivo que alcanzan al sujeto (directo o por `group#member`, anidado) y `D` = las relaciones con deny que lo
+ * alcanzan igual. Es EXACTAMENTE lo que el modelo FGA evalúa en el servidor (`X = (this ∨ I…) but not denied_X`,
+ * `denied_X = this ∨ denied_P` por cada `P ⊇ X`), y es la función que usan el driver `database`, el doble y el
+ * oráculo de la suite: tres copias divergirían (L8).
+ */
+export function cutPathAllows(config, objectType, relation, allowed, denied) {
+    for (const granted of relationsDown(config, objectType, relation)) {
+        if (!allowed.has(granted))
+            continue;
+        if (relationsUp(config, objectType, granted).every((above) => !denied.has(above)))
+            return true;
+    }
+    return false;
+}
+/** Las relaciones del deny que `decideMany`/`check` tienen que leer para `R`: `up*(down*(R))` (D9, definición AMPLIA). */
+export function deniableAbove(config, objectType, relation) {
+    const out = new Set();
+    for (const granted of relationsDown(config, objectType, relation)) {
+        for (const above of relationsUp(config, objectType, granted))
+            out.add(above);
+    }
+    return [...out];
+}
+/**
+ * **D9 · `decideMany` AMPLIO, la regla ÚNICA** (decisión del dueño 2026-10-14; juez ronda 2 §4): `allow` si `check`
+ * concede (el deny ya está aplicado dentro del objeto por corte de camino); si no, `deny` si el sujeto tiene un deny
+ * vivo sobre ALGUNA relación de `up*(down*(R))` en el objeto; si no, `none`. Más amplia que `check` a propósito
+ * (fail-closed en la cadena del llamante): un `viewer` heredado con un deny(`editor`) en el hijo da `deny`.
+ */
+export function decideFrom(config, objectType, relation, allowed, denied) {
+    if (cutPathAllows(config, objectType, relation, allowed, denied))
+        return 'allow';
+    return deniableAbove(config, objectType, relation).some((r) => denied.has(r)) ? 'deny' : 'none';
+}
+/**
+ * **La puerta de ESCRITURA del deny** (D10/D-17): `deny()` solo entra sobre un tipo en fase `'write'`; sin opt-in, en
+ * `'read'` o sobre `group` ⇒ 422 `E_AUTHZ_RELATION_NOT_DENYABLE`. La aplican el manager, los dos drivers y el doble,
+ * DESPUÉS de F-05 (un tipo no declarado sigue siendo `E_AUTHZ_RELATION_TYPE_UNKNOWN`). `removeDeny`/`listDenies` NO
+ * pasan por aquí: aceptan cualquier tipo declarado (D8/R2-4 b: retirar el opt-in tiene que ser reversible).
+ */
+export function assertRelationDenyable(config, object, relation) {
+    const phase = denyPhaseOf(config, object.type);
+    if (phase === 'write')
+        return;
+    const why = object.type === RELATION_USERSET_TYPE
+        ? `'${RELATION_USERSET_TYPE}' es el tipo built-in de los usersets: un deny sobre la pertenencia a un grupo no existe (para ` +
+            `sacar a alguien de un grupo, unrelate(u, member, group:g))`
+        : phase === 'read'
+            ? `el tipo '${object.type}' está en la FASE 1 del opt-in (deny: 'read'): el modelo y las lecturas ya honran el deny, ` +
+                `pero las escrituras no se aceptan hasta que TODA la flota sirva el modelo nuevo; pásalo a deny: 'write' en un ` +
+                `segundo despliegue`
+            : `el tipo '${object.type}' no declara deny en defineRelationsConfig (opt-in por tipo, en dos fases: 'read' y luego 'write')`;
+    throw new RelationNotDenyableError(`deny(…, '${relation}', ${object.type}): no se puede denegar — ${why}. No se ha escrito nada.`);
+}
+/**
+ * **El comodín `*` no es un sujeto de deny** (D-17): un deny a «todos» sería un apagado del objeto que nadie
+ * auditaría como tal. Hoy la gramática de holder ya rechaza `*` (422 `E_AUTHZ_INVALID_IDENTITY`); esta guarda lo dice
+ * con el código del deny ANTES de la gramática, para que un cambio de la gramática no lo abra en silencio.
+ */
+export function assertDenySubject(subject) {
+    if (subject && typeof subject === 'object' && subject.uuid === '*') {
+        throw new RelationNotDenyableError(`deny: el comodín '*' no es un sujeto de deny (un deny a «todos» apagaría el objeto sin que ningún grant lo explique). ` +
+            `Deniega a un holder o a un group#member. No se ha escrito nada.`);
+    }
+}
+/**
+ * **D3: el deny no caduca en v1.** `expiresAt` en las opciones de `deny`/`removeDeny` —incluso `null`, que en `relate`
+ * significa «quitar la caducidad»— es 422 `E_AUTHZ_DENY_EXPIRY_UNSUPPORTED` ANTES de tocar el backend, con la razón
+ * medida (M5). La clave PRESENTE es lo que se rechaza: un `null` aceptado sería una puerta para que la siguiente
+ * versión la lea como «permanente» sin que nadie lo decidiera.
+ */
+export function assertDenyNoExpiry(options) {
+    if (options && typeof options === 'object' && 'expiresAt' in options) {
+        throw new RelationDenyExpiryError(`deny/removeDeny: 'expiresAt' no se admite — el deny de relaciones NO caduca en v1 (D3). Medido en OpenFGA v1.19.0 ` +
+            `(M5): FGA rechaza delete+write de la misma clave en un Write (400 cannot_allow_duplicate_tuples_in_one_request) y ` +
+            `on_duplicate: ignore con otra condición es 409, así que cambiar la caducidad de un deny VIVO abre una ventana en la ` +
+            `que deja de bloquear (y si el segundo Write cae, el deny desaparece). Quita la clave; para un acceso temporal, ` +
+            `caduca el GRANT (relate con expiresAt), no el deny. No se ha escrito nada.`);
+    }
+}

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

@@ -0,0 +1,102 @@
+import type { RelationsConfig } from './define_relations_config.js';
+type ConfigLike = Pick<RelationsConfig, 'objectTypes'>;
+/** Un deny vivo, agregado por tipo y relación PÚBLICA (`editor`, no `denied_editor`). */
+export interface LiveDenyGroup {
+    objectType: string;
+    relation: string;
+    /**
+     * Cuántos denies vivos hay sobre `objectType#relation`: filas de `authz_relations` en la guarda; en el detector de
+     * reconcile, CLAVES DE TUPLA DISTINTAS (firma (8 · `count`): un deny espejado en origen y destino cuenta una vez).
+     */
+    count: number;
+}
+/**
+ * Por qué un grupo de denies vivos es un hallazgo: `shrunk`/`orphan` (la config nueva encoge su alcance), `no-baseline`
+ * (sin línea base utilizable no se puede juzgar) o `stale` (la línea base es más estrecha que lo servido; solo el detector).
+ */
+export type DenyReachReason = 'shrunk' | 'orphan' | 'no-baseline' | 'stale';
+/** Un grupo de denies vivos cuyo alcance encoge con la config nueva, con su receta. */
+export interface DenyReachFinding {
+    objectType: string;
+    relation: string;
+    reason: DenyReachReason;
+    count: number;
+    /**
+     * El alcance con la config VIEJA (`down*` en la línea base); `null` = sin línea base o ya huérfano allí. Con `stale`, el
+     * alcance que CREE la línea base (`null` si no declara la relación).
+     */
+    before: string[] | null;
+    /** El alcance con la config NUEVA; `[]` si quedó huérfano. Con `stale`, el de la config SERVIDA. */
+    after: string[];
+    /**
+     * Lo que deja de cortar (`before \ after`); con `orphan` sin línea base, `[relation]`; con `no-baseline`, `[]` (no se
+     * sabe); con `stale`, lo que el deny corta con lo servido y la línea base no sabe (`after \ before`).
+     */
+    lost: string[];
+    /** La receta (español, como el resto de la letra del paquete). */
+    recipe: string;
+}
+/**
+ * **El alcance de un deny sobre `objectType#relation`** con `config`: `down*(relation)` ordenado, o `null` si la config no
+ * declara ese tipo o esa relación (huérfano).
+ */
+export declare function denyReachOf(config: ConfigLike, objectType: string, relation: string): string[] | null;
+/** La relación ALMACENADA `denied_<rel>` ⇒ `<rel>`; cualquier otra ⇒ `null` (no es un deny). */
+export declare function deniedPublicRelation(stored: string): string | null;
+/** La clave `tipo#relación` de un grupo o hallazgo: la que nombra la salida forzada acotada (`allowDenyReachShrink`). */
+export declare function denyReachKey(group: {
+    objectType: string;
+    relation: string;
+}): string;
+/** La forma de una clave `tipo#relación` que acepta la salida forzada acotada (dos nombres no vacíos, sin `#` ni blancos). */
+export declare const DENY_REACH_KEY_PATTERN: RegExp;
+/**
+ * **La lectura de la LÍNEA BASE, TODO O NADA y tipada** (firma (8 · línea base); conflicto 6 del juez del panel): de la spec
+ * persistida (el JSON ya parseado) lee SOLO lo que decide un alcance —`objectTypes[].{type, relations[].{name, includes}}`—,
+ * sin pasar por `defineRelationsConfig` (una fila de 2.4/alpha.3 con una clave que 2.5 no conoce sigue siendo una línea
+ * base: la receta de B5, re-guardar la misma spec corregida, entra sin forzar). Cualquier forma rota EN LO QUE LEE —un
+ * objeto que no lo es, `objectTypes`/`relations` que no son arrays, un `type`/`name` que no es string, un `includes`
+ * presente que no es un array de strings— deja la línea base como NO UTILIZABLE (`null`): **nunca se filtra** (filtrar
+ * subestima el alcance viejo y deja pasar el estrechamiento: S-D3 del tester del panel). Un `includes` ausente es `[]`
+ * (la spec lo permite).
+ */
+export declare function denyReachBaselineOf(parsed: unknown): ConfigLike | null;
+/**
+ * **La propiedad de (8)**: para cada grupo de denies vivos, ¿`alcance(after) ⊇ alcance(before)`? Devuelve los que la
+ * violan (`shrunk` | `orphan`, orden estable por tipo y relación), vacío si ninguno. `before = null` = sin línea base: solo
+ * `orphan` (el motivo `no-baseline` lo añade `judgeDenyReach`).
+ */
+export declare function denyReachFindings(before: ConfigLike | null, after: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/**
+ * **El juicio de la guarda (y la mitad «persistida → servida» de los detectores)**: `denyReachFindings` más, SIN línea base
+ * utilizable (`baseline === null`), un hallazgo `no-baseline` por cada grupo de denies vivos que no sea ya `orphan` (de un
+ * huérfano sí se sabe que encoge: su alcance es ∅). Sin denies vivos no hay hallazgo alguno: la primera fila se crea sin
+ * forzar. Orden estable por tipo, relación y motivo.
+ */
+export declare function judgeDenyReach(baseline: ConfigLike | null, next: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/**
+ * **La línea base RANCIA** (firma (8 · rancia); conflicto 3 del juez): la dirección inversa, `denyReachFindings(servida,
+ * persistida)`. Un grupo de denies vivos cuyo alcance con lo SERVIDO no cabe en el de la línea base (la fila no declara la
+ * relación que se sirve, o la declara más estrecha) es un hallazgo `stale`: la flota sirvió (o sirve) algo que la fila no
+ * registra, y desde esa fila un estrechamiento de vuelta a ella parecería «sin cambio» (A1/S-B). Un grupo que lo servido
+ * tampoco declara no es rancio (es `orphan` en la otra dirección).
+ */
+export declare function staleDenyReach(baseline: ConfigLike, served: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/** Lo que devuelven los dos detectores (el de un driver y el de `--dry-run`) para un estado: las dos direcciones. */
+export interface DenyReachCheck {
+    /** `'persisted'`: hay línea base utilizable; `'none'`: no la hay (sin fila, o fila que la lectura TODO O NADA no tipa). */
+    baseline: 'persisted' | 'none';
+    /** Persistida → servida: `shrunk`, `orphan` y, sin línea base, `no-baseline` (el juicio de la guarda, sin salidas). */
+    findings: DenyReachFinding[];
+    /** Servida → persistida: `stale` (solo con línea base). */
+    staleBaseline: DenyReachFinding[];
+}
+/** **Los dos sentidos sobre el mismo estado** (firma (8 · detector de un driver)): el punto de paso de los detectores. */
+export declare function denyReachCheck(baseline: ConfigLike | null, served: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachCheck;
+/**
+ * Una línea por hallazgo, con el prefijo ESTABLE de su rama (CLAUDE.md punto 7): la usan el error de la guarda, el detector
+ * de un driver y el comando. Prefijos: «deny con alcance ENCOGIDO», «deny HUÉRFANO», «deny SIN línea base», «línea base
+ * RANCIA».
+ */
+export declare function denyReachLine(finding: DenyReachFinding): string;
+export {};

package/build/src/relations/deny_reach.js

@@ -0,0 +1,230 @@
+/**
+ * **El ALCANCE de un deny vivo, y cuándo un cambio de config lo ENCOGE** (lote RC · sublote (8); decisión §2026-10-15 (8)
+ * del dueño y firmas «(8 · panel)» 2026-10-22). Módulo PURO (sin `db`, sin drivers: regla 2 de pureza) y PUNTO DE PASO
+ * ÚNICO de las tres piezas de (8) —los gemelos guarda ↔ detector de un driver ↔ `--dry-run`—:
+ *
+ *  - la **guarda de `database`** (`saveRelationsConfig`, `src/relations_config_store.ts`): `judgeDenyReach` sobre la línea
+ *    base persistida (leída TODO O NADA por `denyReachBaselineOf`), la config nueva y los denies vivos de `authz_relations`;
+ *    niega (500 `E_AUTHZ_DENY_REACH_REFUSED`, cero escrituras) salvo las dos salidas con nombre: `establishBaseline: true`
+ *    (solo el motivo `no-baseline`) y `allowDenyReachShrink: ['tipo#relación', …]` (solo esos hallazgos);
+ *  - el **detector de un solo driver** (`checkRelationsConfigDenyReach`, mismo módulo de la guarda): `denyReachCheck`, la
+ *    misma línea base y los mismos denies, en las DOS direcciones (persistida → servida, y servida → persistida: la línea
+ *    base RANCIA, A1/S-B del panel);
+ *  - el **detector de `authz:relations:reconcile --dry-run`** (`reconcileRelations({ denyReach })`): `denyReachCheck` sobre
+ *    los denies que la pasada YA enumeró, en origen y destino. En `openfga` es solo detección (regla (ritmo): cero
+ *    arreglos hasta 2.6; la guarda de `openfga:provision` sigue siendo el límite declarado `openfga.provision.deny-reach`).
+ *
+ * **El alcance** de un deny sobre `T#X` es el conjunto de relaciones cuyos grants CORTA (D5, corte de camino:
+ * `cutPathAllows` corta un grant de `g` sii algún deny vivo está en `up*(g)`, o sea sii `g ∈ down*(X)`):
+ * `alcance(T#X) = down*(X)`. Con `editor: { includes: ['owner'] }` un deny en `editor` corta `{editor, owner}`; estrechado
+ * a `includes: []` corta solo `{editor}` y el owner directo vuelve a conceder (el escenario firmado).
+ *
+ * **La propiedad firmada es «para todo deny vivo, alcance_nuevo ⊇ alcance_viejo»**, NO «la relación sigue existiendo».
+ * Motivos de un hallazgo:
+ *  - `shrunk`: `T#X` sigue declarada pero `down*_nuevo(X) ⊉ down*_viejo(X)` —un `includes` estrechado, directo o
+ *    TRANSITIVO, o una relación de `down*_viejo(X)` retirada del tipo—;
+ *  - `orphan`: `T#X` ya no está declarada (relación o tipo retirados): el deny no lo lee nadie (alcance ∅) y ningún
+ *    `removeDeny` lo alcanza (F-05); si la relación se vuelve a declarar, el deny resucita. Se juzga SIEMPRE contra la
+ *    config nueva, con o sin línea base, y aunque ya fuera huérfano en la línea base (firma (8 · salida forzada): P2 «juzgar
+ *    por delta» NO entra — una AUSENCIA en una fila que puede estar rancia no prueba que el deny ya fuera huérfano en la flota);
+ *  - `no-baseline`: no hay línea base UTILIZABLE (sin fila, o una fila que la lectura TODO O NADA no puede tipar) y el deny
+ *    vive: no se puede juzgar si encoge (firma (8 · línea base));
+ *  - `stale` (solo el detector): la línea base no sabe que el deny corta algo que la config SERVIDA sí corta — la fila es
+ *    más estrecha que lo servido, y desde ella un estrechamiento de vuelta parecería «sin cambio» (firma (8 · rancia)).
+ *
+ * Decisiones que siguen (informe `loteRC-8-informe.md`, sin cambio del dueño): una relación de `down*_viejo(X)` RETIRADA del
+ * tipo cuenta como encogimiento aunque sus grants ya no concedan (la propiedad, literal); retirar el opt-in `deny` de un tipo
+ * NO cambia el alcance en `database` (las lecturas honran la fila igual) y no se juzga aquí — en `openfga` lo juzga la guarda
+ * de `provision` (`--allow-drop-deny`).
+ */
+import { RELATION_DENY_PREFIX, relationsDown } from './define_relations_config.js';
+/**
+ * **El alcance de un deny sobre `objectType#relation`** con `config`: `down*(relation)` ordenado, o `null` si la config no
+ * declara ese tipo o esa relación (huérfano).
+ */
+export function denyReachOf(config, objectType, relation) {
+    const type = config.objectTypes.find((t) => t.type === objectType);
+    if (!type || !type.relations.some((r) => r.name === relation))
+        return null;
+    return relationsDown(config, objectType, relation).sort();
+}
+/** La relación ALMACENADA `denied_<rel>` ⇒ `<rel>`; cualquier otra ⇒ `null` (no es un deny). */
+export function deniedPublicRelation(stored) {
+    return typeof stored === 'string' && stored.startsWith(RELATION_DENY_PREFIX) && stored.length > RELATION_DENY_PREFIX.length
+        ? stored.slice(RELATION_DENY_PREFIX.length)
+        : null;
+}
+/** La clave `tipo#relación` de un grupo o hallazgo: la que nombra la salida forzada acotada (`allowDenyReachShrink`). */
+export function denyReachKey(group) {
+    return `${group.objectType}#${group.relation}`;
+}
+/** La forma de una clave `tipo#relación` que acepta la salida forzada acotada (dos nombres no vacíos, sin `#` ni blancos). */
+export const DENY_REACH_KEY_PATTERN = /^[^#\s]+#[^#\s]+$/;
+/**
+ * **La lectura de la LÍNEA BASE, TODO O NADA y tipada** (firma (8 · línea base); conflicto 6 del juez del panel): de la spec
+ * persistida (el JSON ya parseado) lee SOLO lo que decide un alcance —`objectTypes[].{type, relations[].{name, includes}}`—,
+ * sin pasar por `defineRelationsConfig` (una fila de 2.4/alpha.3 con una clave que 2.5 no conoce sigue siendo una línea
+ * base: la receta de B5, re-guardar la misma spec corregida, entra sin forzar). Cualquier forma rota EN LO QUE LEE —un
+ * objeto que no lo es, `objectTypes`/`relations` que no son arrays, un `type`/`name` que no es string, un `includes`
+ * presente que no es un array de strings— deja la línea base como NO UTILIZABLE (`null`): **nunca se filtra** (filtrar
+ * subestima el alcance viejo y deja pasar el estrechamiento: S-D3 del tester del panel). Un `includes` ausente es `[]`
+ * (la spec lo permite).
+ */
+export function denyReachBaselineOf(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const objectTypes = parsed.objectTypes;
+    if (!Array.isArray(objectTypes))
+        return null;
+    const types = [];
+    for (const t of objectTypes) {
+        if (t === null || typeof t !== 'object' || Array.isArray(t))
+            return null;
+        if (typeof t.type !== 'string' || !Array.isArray(t.relations))
+            return null;
+        const relations = [];
+        for (const r of t.relations) {
+            if (r === null || typeof r !== 'object' || Array.isArray(r) || typeof r.name !== 'string')
+                return null;
+            if (r.includes !== undefined && !(Array.isArray(r.includes) && r.includes.every((i) => typeof i === 'string')))
+                return null;
+            relations.push({ name: r.name, includes: Array.isArray(r.includes) ? r.includes.filter((i) => typeof i === 'string') : [] });
+        }
+        types.push({ type: t.type, relations });
+    }
+    return { objectTypes: types };
+}
+function mergeGroups(denies) {
+    const groups = new Map();
+    for (const deny of denies) {
+        const key = denyReachKey(deny);
+        const seen = groups.get(key);
+        groups.set(key, seen ? { ...seen, count: seen.count + deny.count } : { ...deny });
+    }
+    return [...groups.values()];
+}
+const byKey = (a, b) => denyReachKey(a).localeCompare(denyReachKey(b)) || String(a.reason ?? '').localeCompare(String(b.reason ?? ''));
+/**
+ * **La propiedad de (8)**: para cada grupo de denies vivos, ¿`alcance(after) ⊇ alcance(before)`? Devuelve los que la
+ * violan (`shrunk` | `orphan`, orden estable por tipo y relación), vacío si ninguno. `before = null` = sin línea base: solo
+ * `orphan` (el motivo `no-baseline` lo añade `judgeDenyReach`).
+ */
+export function denyReachFindings(before, after, denies) {
+    const findings = [];
+    for (const group of mergeGroups(denies).sort(byKey)) {
+        const old = before ? denyReachOf(before, group.objectType, group.relation) : null;
+        const now = denyReachOf(after, group.objectType, group.relation);
+        if (now === null) {
+            findings.push({
+                ...group,
+                reason: 'orphan',
+                before: old,
+                after: [],
+                lost: old ?? [group.relation],
+                recipe: orphanRecipe(group),
+            });
+            continue;
+        }
+        if (old === null)
+            continue;
+        const lost = old.filter((relation) => !now.includes(relation));
+        if (lost.length === 0)
+            continue;
+        findings.push({ ...group, reason: 'shrunk', before: old, after: now, lost, recipe: shrunkRecipe(group, lost) });
+    }
+    return findings;
+}
+/**
+ * **El juicio de la guarda (y la mitad «persistida → servida» de los detectores)**: `denyReachFindings` más, SIN línea base
+ * utilizable (`baseline === null`), un hallazgo `no-baseline` por cada grupo de denies vivos que no sea ya `orphan` (de un
+ * huérfano sí se sabe que encoge: su alcance es ∅). Sin denies vivos no hay hallazgo alguno: la primera fila se crea sin
+ * forzar. Orden estable por tipo, relación y motivo.
+ */
+export function judgeDenyReach(baseline, next, denies) {
+    const groups = mergeGroups(denies);
+    const findings = denyReachFindings(baseline, next, groups);
+    if (baseline !== null)
+        return findings;
+    const judged = new Set(findings.map(denyReachKey));
+    for (const group of groups) {
+        if (judged.has(denyReachKey(group)))
+            continue;
+        findings.push({ ...group, reason: 'no-baseline', before: null, after: denyReachOf(next, group.objectType, group.relation) ?? [], lost: [], recipe: noBaselineRecipe(group) });
+    }
+    return findings.sort(byKey);
+}
+/**
+ * **La línea base RANCIA** (firma (8 · rancia); conflicto 3 del juez): la dirección inversa, `denyReachFindings(servida,
+ * persistida)`. Un grupo de denies vivos cuyo alcance con lo SERVIDO no cabe en el de la línea base (la fila no declara la
+ * relación que se sirve, o la declara más estrecha) es un hallazgo `stale`: la flota sirvió (o sirve) algo que la fila no
+ * registra, y desde esa fila un estrechamiento de vuelta a ella parecería «sin cambio» (A1/S-B). Un grupo que lo servido
+ * tampoco declara no es rancio (es `orphan` en la otra dirección).
+ */
+export function staleDenyReach(baseline, served, denies) {
+    return denyReachFindings(served, baseline, denies)
+        .filter((reverse) => reverse.before !== null)
+        .map((reverse) => ({
+        objectType: reverse.objectType,
+        relation: reverse.relation,
+        count: reverse.count,
+        reason: 'stale',
+        before: reverse.reason === 'orphan' ? null : reverse.after,
+        after: reverse.before,
+        lost: reverse.lost,
+        recipe: staleRecipe(reverse),
+    }));
+}
+/** **Los dos sentidos sobre el mismo estado** (firma (8 · detector de un driver)): el punto de paso de los detectores. */
+export function denyReachCheck(baseline, served, denies) {
+    const groups = mergeGroups(denies);
+    return {
+        baseline: baseline === null ? 'none' : 'persisted',
+        findings: judgeDenyReach(baseline, served, groups),
+        staleBaseline: baseline === null ? [] : staleDenyReach(baseline, served, groups),
+    };
+}
+function shrunkRecipe(group, lost) {
+    return (`antes de estrechar, vuelve a emitir cada uno de esos ${group.count} deny(s) sobre una relación de '${group.objectType}' que ` +
+        `con la config nueva siga cortando ${lost.map((r) => `'${r}'`).join(', ')} (deny(<sujeto>, '<esa relación>', <objeto>); ` +
+        `listDenies(<objeto>, '${group.relation}') los enumera), o deja el includes como estaba; si de verdad deben dejar de ` +
+        `cortarlo, nombra este hallazgo en la salida forzada: allowDenyReachShrink: ['${denyReachKey(group)}']`);
+}
+function orphanRecipe(group) {
+    return (`antes de retirar '${denyReachKey(group)}', quita esos ${group.count} deny(s) con removeDeny (o re-emítelos sobre ` +
+        `una relación que se quede) y retírala después; si ya la retiraste, vuelve a declararla, haz removeDeny y retírala — ` +
+        `un deny huérfano no lo lee nadie, ningún removeDeny lo alcanza (F-05) y resucita si la relación se vuelve a declarar ` +
+        `(y re-declararla tras forzar la retirada resucita también los grants que cortaba)`);
+}
+function noBaselineRecipe(group) {
+    return (`guarda UNA vez la spec que la flota sirve HOY, sin cambios, con saveRelationsConfig(spec, { establishBaseline: true }), ` +
+        `en una release que NO cambie relations.config (adoptar en una release que estrecha certifica el estrechamiento); ` +
+        `desde esa fila la guarda juzga cada cambio de '${denyReachKey(group)}'`);
+}
+function staleRecipe(reverse) {
+    return (`la línea base (authz_relations_config) es más estrecha que la config que se sirve: guarda con saveRelationsConfig la ` +
+        `config que sirve la flota —persistir la config es paso obligatorio de release si usas deny— y vuelve a correr la ` +
+        `comprobación; mientras la fila no lo sepa, un estrechamiento de vuelta a ella no lo niega la guarda y los ` +
+        `${reverse.count} deny(s) de '${denyReachKey(reverse)}' dejarían de cortar ${reverse.lost.map((r) => `'${r}'`).join(', ')}`);
+}
+/**
+ * Una línea por hallazgo, con el prefijo ESTABLE de su rama (CLAUDE.md punto 7): la usan el error de la guarda, el detector
+ * de un driver y el comando. Prefijos: «deny con alcance ENCOGIDO», «deny HUÉRFANO», «deny SIN línea base», «línea base
+ * RANCIA».
+ */
+export function denyReachLine(finding) {
+    const where = `${denyReachKey(finding)} (${finding.count} deny(s))`;
+    switch (finding.reason) {
+        case 'orphan':
+            return `deny HUÉRFANO ${where}: la config nueva no declara la relación (cortaba ${finding.lost.join(', ')}). Receta: ${finding.recipe}.`;
+        case 'no-baseline':
+            return (`deny SIN línea base ${where}: no hay config persistida utilizable en authz_relations_config con la que comparar, así que ` +
+                `no se puede saber si la config nueva encoge su alcance (hoy corta ${finding.after.join(', ')}). Receta: ${finding.recipe}.`);
+        case 'stale':
+            return (`línea base RANCIA ${where}: con la config servida el deny corta ${finding.after.join(', ')}, y la config persistida ` +
+                `${finding.before === null ? 'no declara la relación' : `solo sabe de ${finding.before.join(', ')}`} (no sabe de ` +
+                `${finding.lost.join(', ')}). Receta: ${finding.recipe}.`);
+        default:
+            return (`deny con alcance ENCOGIDO ${where}: cortaba ${finding.before.join(', ')} y con la config nueva solo ${finding.after.join(', ')} ` +
+                `(deja de cortar ${finding.lost.join(', ')}: lo que negaba vuelve a conceder). Receta: ${finding.recipe}.`);
+    }
+}