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

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

@@ -1,3 +1,4 @@
+import { AuthorizationConfigError } from '../errors.js';
 import type { CatalogProjectionRole, HolderTypeMap } from '../types.js';
 /**
  * `holderTypes` tiene que ser INYECTIVO. Si dos morph names caen en el mismo
@@ -402,4 +403,93 @@ export declare function factsRelationRewrites(objectType: RelationObjectType): R
  * con nombre y no se toca). Cualquier otra diferencia es una regla DISTINTA.
  */
 export declare function canonicalRewrite(node: unknown): unknown;
-//# sourceMappingURL=openfga_facts.d.ts.map
+/**
+ * Qué tipos compara cada puerta (L11): `roles` (los holders, `role`, `role_binding`, `scope`), `relations` (los holders,
+ * `group` y los tipos de la config) y `all` (el modelo ENTERO que generaría la config, más todo tipo que el servido
+ * traiga de más: la relectura de `openfga:provision`). Las condiciones y `schema_version` se comparan SIEMPRE.
+ */
+export type FactsModelSlice = 'roles' | 'relations' | 'all';
+/** Una diferencia del modelo servido respecto del generado, por RUTA legible. `type: null` = global (condiciones…). */
+export interface FactsModelDifference {
+    type: string | null;
+    path: string;
+}
+export interface FactsModelComparison {
+    equal: boolean;
+    differences: FactsModelDifference[];
+    /**
+     * La forma con la que el modelo servido trae cada tipo de relaciones de la config: `deny` (con `denied_<rel>`) o
+     * `plain`. Con opt-in siempre `deny`; sin él, **D8 por TIPO ENTERO** (cierra P2: un modelo MEZCLADO, unas relaciones
+     * con la forma con deny y otras sin ella, no lo genera ninguna config y es diferencia). Lo usa `decideMany`.
+     */
+    denyForm: ReadonlyMap<string, 'plain' | 'deny'>;
+    /** P_M: los permisos que declara el propio modelo servido (las bases de `role#permits_*`), ordenados. */
+    permissions: string[];
+}
+/**
+ * **Forma canónica de un modelo (o de cualquier trozo) de OpenFGA** para compararlo con el que genera el paquete
+ * (L11; extiende `canonicalRewrite`). MEDIDO contra v1.19.0 (`:8090`): el servidor devuelve el ruido de proto3
+ * —`module: ""`, `source_info: null`, `condition: ""` en cada restricción, `metadata: null`, `generic_types: []`,
+ * `object: ""` en cada `computedUserset`— y otro orden de claves. Se quitan los valores por defecto de proto3 (`""`,
+ * `null`, `[]`), **NUNCA un `{}`** (`this: {}` y `wildcard: {}` significan algo), se ordenan las claves y los hijos
+ * CONMUTATIVOS (`child` de `union`/`intersection` y `directly_related_user_types`; `difference` tiene `base`/
+ * `subtract` con nombre y no se toca). Una restricción DUPLICADA no se funde: es una diferencia.
+ */
+export declare function canonicalModel(node: unknown): unknown;
+/**
+ * **El punto de paso ÚNICO de L11** (lote «antes de RC», decisión del dueño 2026-10-17 (1); linaje L11): compara el
+ * modelo que SIRVE el servidor con el que genera la config de este proceso, POR TIPO, en reglas, restricciones de
+ * tipo (con su condición) y condiciones. Pura y sin SDK. Determinista: no busca entre combinaciones.
+ *
+ *  1. `P_M` = los permisos que declara el propio servido (`role#permits_*`): la igualdad es «módulo el catálogo», que
+ *     cambia en runtime (el desfase catálogo ↔ modelo lo cuenta el reconcile, `permission-not-in-model`).
+ *  2. `D8_M` = los tipos de la config SIN opt-in que el servido trae con la forma con deny (algún `denied_*`): se
+ *     generan con `deny` para comparar — por TIPO ENTERO —.
+ *  3. Se genera `openFgaFactsModel(holderTypes, P_M, config con D8_M)`; si el generador lanza (un `permits_*` del
+ *     servido que no es un nombre publicable), es 500 `E_AUTHZ_CONFIG`, nunca «igual» (H11 d).
+ *  4. Diferencias por ruta: `<tipo> (tipo ausente)`, `<tipo>#<rel> (falta)`, `(relación de más)` —una relación EXTRA
+ *     es deriva, D-L11-3—, `(regla)`, `(restricciones de tipo)`, `<tipo>.<campo>`, `conditions.<nombre> (…)`,
+ *     `schema_version`. Un tipo AJENO al `slice` no se mira (límite declarado y razonado, caso C7); con `all`, sí.
+ */
+export declare function factsModelDifferences(served: unknown, inputs: {
+    holderTypes: HolderTypeMap;
+    relations?: FactsRelationsConfig;
+    slice: FactsModelSlice;
+}): FactsModelComparison;
+/** Cuántas rutas nombra como mucho la letra del 500 de L11 (el resto se cuenta). */
+export declare const FACTS_MODEL_DRIFT_LISTED = 20;
+/**
+ * **La LETRA del 500 de la puerta L11**, la MISMA en los dos drivers `openfga`: qué driver, qué operación, qué
+ * `modelId`, las diferencias por ruta y la receta. Cero llamadas que evalúen o escriban.
+ */
+export declare function factsModelDriftError(driver: string, operation: string, modelId: string | undefined, differences: readonly FactsModelDifference[]): AuthorizationConfigError & {
+    modelDifferences: string[];
+};
+/**
+ * **El token del opt-in de `openfga` EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21, «(b) con
+ * candado»). Lleva la VERSIÓN a propósito (auditor B1/B7, tester E1): con `true` nada obligaría a releer los límites NUEVOS
+ * cuando cambien; con `'openfga@2.5'` la 2.6 cambiará el token y un `^2.5.0` que se actualice hace ruido (500) en vez de
+ * colarse. NO se exporta por `/openfga`: el consumidor escribe el LITERAL, que es lo que demuestra que leyó «Limits».
+ */
+export declare const OPENFGA_EXPERIMENTAL_TOKEN = "openfga@2.5";
+/**
+ * **La puerta del opt-in experimental, en los DOS constructores `openfga`** (firma 4; mismo patrón que
+ * `E_AUTHZ_SCOPE_DRIFT_UNGUARDED`: «una recomendación no es un mecanismo»). En 2.5.x `openfga` tiene límites declarados
+ * en README «Limits» (carreras entre escritores, árbol con outbox sin medir, el gemelo `permits_*`…) que se cierran en
+ * 2.6, así que construirlo exige escribir `experimental: 'openfga@2.5'`. Cualquier otra cosa —ausente, `true`,
+ * `'acknowledged'`, otra versión, el token con espacios— es 500 `E_AUTHZ_CONFIG` al CONSTRUIR, como PRIMERA línea del
+ * constructor: ni se valida lo demás ni se crea el cliente, así que hay CERO llamadas al servidor. Va en el constructor
+ * y no en el stub ni en el registro de la factory: `manager.driver()` (y con él `authz:catalog:sync`),
+ * `authz:reconcile --to=openfga`, `authz:relations:reconcile`, el provider y la construcción directa pasan todos por
+ * aquí, y un config solo-`database` que REGISTRA la factory `openfga` sin usarla arranca (las factories son perezosas).
+ * `openfga:provision` NO construye un driver (crea el store y publica el modelo con el SDK): corre sin la marca, y el
+ * primer driver que sirva con ese store, no.
+ */
+export declare function assertExperimentalOptIn(driver: string, value: unknown): void;
+/**
+ * **`modelId` OBLIGATORIO en los dos drivers `openfga`** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2);
+ * D14 ampliado: siempre, con o sin deny). Sin el pin la puerta L11 compara el modelo que el driver lee al arrancar y el
+ * servidor evalúa cada petición con el ÚLTIMO del store: un `openfga:provision` desde otro proceso cambiaría lo que se
+ * concede sin que ninguna comparación lo vea. 500 al CONSTRUIR, con la receta.
+ */
+export declare function assertPinnedModel(driver: string, modelId: unknown): void;

package/build/src/drivers/openfga_facts.js

@@ -1,6 +1,7 @@
-import { InvalidIdentityError, InvalidSlugError, ModelTooLargeError, AuthorizationConfigError, RelationConfigError, } from '../errors.js';
+import { InvalidIdentityError, InvalidSlugError, ModelTooLargeError, AuthorizationConfigError, RelationConfigError, markDeploymentFailure, } from '../errors.js';
 import { slugAsRelation, RESERVED_SLUG_PREFIXES, RESERVED_FACTS_TYPES } from '../identity.js';
 import { APP_SCOPE_TYPE } from '../types.js';
+import { FGA_EXPIRY_CONDITION } from '../expiry.js';
 /**
  * Modo `facts` — el MODELO (c2) y la proyección del catálogo, sin `@openfga/sdk`.
  *
@@ -202,7 +203,7 @@ export const FACTS_ROOTED_RELATION = 'rooted';
  * `role_binding#assignee` desde el modo `facts`, y desde R-15 también la de
  * cada sujeto de una relación ReBAC (`document#viewer`, `group#member`…).
  */
-export const FACTS_EXPIRY_CONDITION = 'not_expired';
+export const FACTS_EXPIRY_CONDITION = FGA_EXPIRY_CONDITION;
 /* ── Relaciones derivadas de un permiso ─────────────────────────────────── */
 /**
  * Relaciones propias del modelo (no derivadas de ningún permiso). Un permiso
@@ -899,4 +900,277 @@ export function canonicalRewrite(node) {
     }
     return out;
 }
-//# sourceMappingURL=openfga_facts.js.map
+/**
+ * **Forma canónica de un modelo (o de cualquier trozo) de OpenFGA** para compararlo con el que genera el paquete
+ * (L11; extiende `canonicalRewrite`). MEDIDO contra v1.19.0 (`:8090`): el servidor devuelve el ruido de proto3
+ * —`module: ""`, `source_info: null`, `condition: ""` en cada restricción, `metadata: null`, `generic_types: []`,
+ * `object: ""` en cada `computedUserset`— y otro orden de claves. Se quitan los valores por defecto de proto3 (`""`,
+ * `null`, `[]`), **NUNCA un `{}`** (`this: {}` y `wildcard: {}` significan algo), se ordenan las claves y los hijos
+ * CONMUTATIVOS (`child` de `union`/`intersection` y `directly_related_user_types`; `difference` tiene `base`/
+ * `subtract` con nombre y no se toca). Una restricción DUPLICADA no se funde: es una diferencia.
+ */
+export function canonicalModel(node) {
+    if (Array.isArray(node))
+        return node.map(canonicalModel);
+    if (node === null || typeof node !== 'object')
+        return node;
+    // Cierre de L11 (⚪ A3.2 del auditor): SIN prototipo — una relación o condición de más llamada `__proto__` (el servidor
+    // v1.19 la acepta, medido) cambiaba el prototipo de un objeto literal en vez de ser una clave, y el comparador decía
+    // «igual» (D-L11-3: relación de más = deriva). Con `Object.create(null)` es una clave propia más y se ve.
+    const out = Object.create(null);
+    for (const key of Object.keys(node).sort()) {
+        const value = node[key];
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        out[key] = canonicalModel(value);
+    }
+    for (const key of ['child', 'directly_related_user_types']) {
+        if (Array.isArray(out[key]))
+            out[key] = sortByJson(out[key]);
+    }
+    return out;
+}
+function sortByJson(items) {
+    return [...items].sort((a, b) => {
+        const x = JSON.stringify(a);
+        const y = JSON.stringify(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+}
+const sameCanon = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * **El punto de paso ÚNICO de L11** (lote «antes de RC», decisión del dueño 2026-10-17 (1); linaje L11): compara el
+ * modelo que SIRVE el servidor con el que genera la config de este proceso, POR TIPO, en reglas, restricciones de
+ * tipo (con su condición) y condiciones. Pura y sin SDK. Determinista: no busca entre combinaciones.
+ *
+ *  1. `P_M` = los permisos que declara el propio servido (`role#permits_*`): la igualdad es «módulo el catálogo», que
+ *     cambia en runtime (el desfase catálogo ↔ modelo lo cuenta el reconcile, `permission-not-in-model`).
+ *  2. `D8_M` = los tipos de la config SIN opt-in que el servido trae con la forma con deny (algún `denied_*`): se
+ *     generan con `deny` para comparar — por TIPO ENTERO —.
+ *  3. Se genera `openFgaFactsModel(holderTypes, P_M, config con D8_M)`; si el generador lanza (un `permits_*` del
+ *     servido que no es un nombre publicable), es 500 `E_AUTHZ_CONFIG`, nunca «igual» (H11 d).
+ *  4. Diferencias por ruta: `<tipo> (tipo ausente)`, `<tipo>#<rel> (falta)`, `(relación de más)` —una relación EXTRA
+ *     es deriva, D-L11-3—, `(regla)`, `(restricciones de tipo)`, `<tipo>.<campo>`, `conditions.<nombre> (…)`,
+ *     `schema_version`. Un tipo AJENO al `slice` no se mira (límite declarado y razonado, caso C7); con `all`, sí.
+ */
+export function factsModelDifferences(served, inputs) {
+    const model = served;
+    if (!model || typeof model !== 'object' || !Array.isArray(model.type_definitions)) {
+        throw new AuthorizationConfigError('L11: el modelo servido no trae type_definitions; no se puede comparar con el que genera la config (no se toma por igual).');
+    }
+    const differences = [];
+    const servedTypes = new Map();
+    for (const definition of model.type_definitions) {
+        const type = definition?.type;
+        if (typeof type !== 'string' || type === '') {
+            differences.push({ type: null, path: 'type_definitions (un tipo sin nombre)' });
+            continue;
+        }
+        if (servedTypes.has(type))
+            differences.push({ type, path: `${type} (tipo duplicado)` });
+        servedTypes.set(type, definition);
+    }
+    const permissions = inputs.slice === 'relations'
+        ? []
+        : Object.keys(servedTypes.get(FACTS_ROLE_TYPE)?.relations ?? {})
+            .filter((name) => name.startsWith(FACTS_PERMITS_PREFIX))
+            .map((name) => name.slice(FACTS_PERMITS_PREFIX.length))
+            .sort();
+    const denyForm = new Map();
+    let relationsConfig;
+    if (inputs.relations && inputs.slice !== 'roles') {
+        relationsConfig = {
+            objectTypes: inputs.relations.objectTypes.map((spec) => {
+                if (spec.deny !== undefined) {
+                    denyForm.set(spec.type, 'deny');
+                    return spec;
+                }
+                const d8 = Object.keys(servedTypes.get(spec.type)?.relations ?? {}).some((name) => name.startsWith(FACTS_DENIED_PREFIX));
+                denyForm.set(spec.type, d8 ? 'deny' : 'plain');
+                return d8 ? { ...spec, deny: 'read' } : spec;
+            }),
+        };
+    }
+    let generated;
+    try {
+        generated = openFgaFactsModel(inputs.holderTypes, permissions, relationsConfig);
+    }
+    catch (error) {
+        throw markDeploymentFailure(new AuthorizationConfigError(`L11: no se puede generar el modelo de la config con los permisos que declara el modelo servido ` +
+            `(${error?.message ?? String(error)}); no se toma por igual.`, { cause: error }));
+    }
+    const generatedTypes = new Map(generated.type_definitions.map((definition) => [definition.type, definition]));
+    const holders = Object.values(inputs.holderTypes);
+    const sliceTypes = inputs.slice === 'all'
+        ? [...generatedTypes.keys()]
+        : inputs.slice === 'roles'
+            ? [...holders, FACTS_ROLE_TYPE, FACTS_BINDING_TYPE, FACTS_SCOPE_TYPE]
+            : [...holders, FACTS_GROUP_TYPE, ...(inputs.relations?.objectTypes ?? []).map((t) => t.type)];
+    for (const type of sliceTypes)
+        compareTypeDefinition(type, servedTypes.get(type), generatedTypes.get(type), differences);
+    if (inputs.slice === 'all') {
+        for (const type of servedTypes.keys()) {
+            if (!generatedTypes.has(type))
+                differences.push({ type, path: `${type} (tipo de más)` });
+        }
+    }
+    const servedConditions = (canonicalModel(model.conditions ?? {}) ?? {});
+    const generatedConditions = canonicalModel(generated.conditions);
+    for (const name of [...new Set([...Object.keys(servedConditions), ...Object.keys(generatedConditions)])].sort()) {
+        if (!(name in servedConditions))
+            differences.push({ type: null, path: `conditions.${name} (falta)` });
+        else if (!(name in generatedConditions))
+            differences.push({ type: null, path: `conditions.${name} (condición de más)` });
+        else if (!sameCanon(servedConditions[name], generatedConditions[name]))
+            differences.push({ type: null, path: `conditions.${name} (distinta)` });
+    }
+    if (!sameCanon(canonicalModel(model.schema_version), generated.schema_version)) {
+        differences.push({ type: null, path: `schema_version (${JSON.stringify(model.schema_version ?? null)})` });
+    }
+    for (const key of Object.keys(model).sort()) {
+        if (['id', 'schema_version', 'type_definitions', 'conditions'].includes(key))
+            continue;
+        const value = model[key];
+        if (value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0))
+            continue;
+        differences.push({ type: null, path: `modelo.${key}` });
+    }
+    return { equal: differences.length === 0, differences, denyForm, permissions };
+}
+function compareTypeDefinition(type, served, generated, out) {
+    if (generated === undefined)
+        return;
+    if (served === undefined) {
+        out.push({ type, path: `${type} (tipo ausente del modelo)` });
+        return;
+    }
+    const s = canonicalModel(served);
+    const g = canonicalModel(generated);
+    const sRelations = s.relations ?? {};
+    const gRelations = g.relations ?? {};
+    const reported = new Set();
+    for (const name of [...new Set([...Object.keys(sRelations), ...Object.keys(gRelations)])].sort()) {
+        if (!(name in sRelations))
+            out.push({ type, path: `${type}#${name} (falta)` });
+        else if (!(name in gRelations))
+            out.push({ type, path: `${type}#${name} (relación de más)` });
+        else if (!sameCanon(sRelations[name], gRelations[name]))
+            out.push({ type, path: `${type}#${name} (regla)` });
+        else
+            continue;
+        reported.add(name);
+    }
+    const sMeta = s.metadata?.relations ?? {};
+    const gMeta = g.metadata?.relations ?? {};
+    for (const name of [...new Set([...Object.keys(sMeta), ...Object.keys(gMeta)])].sort()) {
+        if (reported.has(name))
+            continue;
+        if (!sameCanon(sMeta[name], gMeta[name]))
+            out.push({ type, path: `${type}#${name} (restricciones de tipo)` });
+    }
+    const rest = (definition) => {
+        const { type: _t, relations: _r, metadata, ...others } = definition;
+        const { relations: _mr, ...metaOthers } = (metadata ?? {});
+        return { others, metaOthers };
+    };
+    const sr = rest(s);
+    const gr = rest(g);
+    for (const key of [...new Set([...Object.keys(sr.others), ...Object.keys(gr.others)])].sort()) {
+        if (!sameCanon(sr.others[key], gr.others[key]))
+            out.push({ type, path: `${type}.${key}` });
+    }
+    for (const key of [...new Set([...Object.keys(sr.metaOthers), ...Object.keys(gr.metaOthers)])].sort()) {
+        if (!sameCanon(sr.metaOthers[key], gr.metaOthers[key]))
+            out.push({ type, path: `${type}.metadata.${key}` });
+    }
+}
+/** Cuántas rutas nombra como mucho la letra del 500 de L11 (el resto se cuenta). */
+export const FACTS_MODEL_DRIFT_LISTED = 20;
+/**
+ * **La LETRA del 500 de la puerta L11**, la MISMA en los dos drivers `openfga`: qué driver, qué operación, qué
+ * `modelId`, las diferencias por ruta y la receta. Cero llamadas que evalúen o escriban.
+ */
+export function factsModelDriftError(driver, operation, modelId, differences) {
+    const paths = differences.map((d) => d.path);
+    const listed = paths.slice(0, FACTS_MODEL_DRIFT_LISTED).join('; ');
+    const more = paths.length > FACTS_MODEL_DRIFT_LISTED ? ` … y ${paths.length - FACTS_MODEL_DRIFT_LISTED} más` : '';
+    const error = new AuthorizationConfigError(`${driver}.${operation}: el modelo que sirve este driver (modelId ${modelId ?? '(ninguno)'}) NO es el que genera la ` +
+        `config de este proceso (L11: reglas, restricciones de tipo y condiciones, por tipo) — ${listed}${more}. Con ese ` +
+        'modelo el servidor decide con reglas o condiciones que la config no declara: puede conceder lo que la config —y ' +
+        'database con la misma config— niega, o leer caducidades con otra condición. Republica el modelo desde la config ' +
+        'actual (node ace openfga:provision --store-id=…) y fija el modelId nuevo (OPENFGA_MODEL_ID) en TODA la flota antes ' +
+        'de desplegar. No se ha llamado al servidor para evaluar ni escribir nada.');
+    error.modelDifferences = paths;
+    // Cierre de L11 (🟠 A1): fallo del DESPLIEGUE ⇒ transitorio para el relay (no consume intento ni aparca).
+    return markDeploymentFailure(error);
+}
+/**
+ * **El token del opt-in de `openfga` EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21, «(b) con
+ * candado»). Lleva la VERSIÓN a propósito (auditor B1/B7, tester E1): con `true` nada obligaría a releer los límites NUEVOS
+ * cuando cambien; con `'openfga@2.5'` la 2.6 cambiará el token y un `^2.5.0` que se actualice hace ruido (500) en vez de
+ * colarse. NO se exporta por `/openfga`: el consumidor escribe el LITERAL, que es lo que demuestra que leyó «Limits».
+ */
+export const OPENFGA_EXPERIMENTAL_TOKEN = 'openfga@2.5';
+/**
+ * **La puerta del opt-in experimental, en los DOS constructores `openfga`** (firma 4; mismo patrón que
+ * `E_AUTHZ_SCOPE_DRIFT_UNGUARDED`: «una recomendación no es un mecanismo»). En 2.5.x `openfga` tiene límites declarados
+ * en README «Limits» (carreras entre escritores, árbol con outbox sin medir, el gemelo `permits_*`…) que se cierran en
+ * 2.6, así que construirlo exige escribir `experimental: 'openfga@2.5'`. Cualquier otra cosa —ausente, `true`,
+ * `'acknowledged'`, otra versión, el token con espacios— es 500 `E_AUTHZ_CONFIG` al CONSTRUIR, como PRIMERA línea del
+ * constructor: ni se valida lo demás ni se crea el cliente, así que hay CERO llamadas al servidor. Va en el constructor
+ * y no en el stub ni en el registro de la factory: `manager.driver()` (y con él `authz:catalog:sync`),
+ * `authz:reconcile --to=openfga`, `authz:relations:reconcile`, el provider y la construcción directa pasan todos por
+ * aquí, y un config solo-`database` que REGISTRA la factory `openfga` sin usarla arranca (las factories son perezosas).
+ * `openfga:provision` NO construye un driver (crea el store y publica el modelo con el SDK): corre sin la marca, y el
+ * primer driver que sirva con ese store, no.
+ */
+export function assertExperimentalOptIn(driver, value) {
+    if (typeof value === 'string' && value === OPENFGA_EXPERIMENTAL_TOKEN)
+        return;
+    throw new AuthorizationConfigError(experimentalOptInMessage(driver, describeOptInValue(value)));
+}
+/**
+ * Qué llegó, SIN tocar el valor (cierre 1 del candado, ⚪ 5 del auditor): `String(value)` de un `Object.create(null)` o de
+ * un objeto cuyo `toString` lanza sustituía el 500 por un `TypeError` o por el error del consumidor. Solo `typeof` y, para
+ * un string, `JSON.stringify` (que no invoca nada del valor).
+ */
+function describeOptInValue(value) {
+    if (value === undefined)
+        return 'nada';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'bigint')
+        return `${typeof value} ${value}`;
+    return `un ${Array.isArray(value) ? 'array' : typeof value}`;
+}
+function experimentalOptInMessage(driver, got) {
+    return (`${driver}: el driver openfga es EXPERIMENTAL en 2.5.x y NO es apto para producción: tiene límites declarados ` +
+        '(README «Limits»: carreras entre escritores del driver de roles, el árbol con outbox sin medir, el gemelo ' +
+        'permits_*…) que se cierran en 2.6. Para usarlo igualmente (CI, ensayo, desarrollo) opta de forma EXPLÍCITA con ' +
+        `experimental: '${OPENFGA_EXPERIMENTAL_TOKEN}' en las opciones del driver (llegó ${got}). El token lleva la versión ` +
+        'a propósito: true u otra versión no valen; el token y el comportamiento experimental de openfga pueden cambiar en ' +
+        '2.6 (una minor) sin major. ' +
+        'En producción usa database; para MIGRAR a database desde openfga (authz:reconcile --to=database, con openfga como ' +
+        'ORIGEN) la factory openfga también necesita la marca: leer el store para salir de él es construir este driver. ' +
+        'No se ha creado el cliente ni se ha llamado al servidor.');
+}
+/**
+ * **`modelId` OBLIGATORIO en los dos drivers `openfga`** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2);
+ * D14 ampliado: siempre, con o sin deny). Sin el pin la puerta L11 compara el modelo que el driver lee al arrancar y el
+ * servidor evalúa cada petición con el ÚLTIMO del store: un `openfga:provision` desde otro proceso cambiaría lo que se
+ * concede sin que ninguna comparación lo vea. 500 al CONSTRUIR, con la receta.
+ */
+export function assertPinnedModel(driver, modelId) {
+    if (typeof modelId === 'string' && modelId.trim() !== '')
+        return;
+    throw new AuthorizationConfigError(`${driver}: falta modelId (llegó ${JSON.stringify(modelId ?? null)}). Desde 2.5.0-alpha.4 el modelo FIJADO es ` +
+        'obligatorio en los dos drivers openfga, con o sin deny (L11): el driver comprueba UNA vez que ese modelo es el que ' +
+        'genera tu config y el servidor evalúa con ESE modelo; sin el pin evaluaría con el último del store. Receta: ' +
+        '`node ace openfga:provision` (o `--store-id=$OPENFGA_STORE_ID` sobre un store existente) imprime OPENFGA_MODEL_ID; ' +
+        'ponlo en el .env de TODA la flota y pásalo como modelId (el stub de config/authorization.ts lo hace con ' +
+        "env.get('OPENFGA_MODEL_ID')).");
+}

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

@@ -7,8 +7,10 @@ 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 (`#purgeByFilters`): una purga que cabe aquí es UN `Write`, sin estado
- * intermedio; con más membresías de grupo que esto, el residuo es una fila DECLARADA (README, «Deny on relations»).
+ * 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
@@ -56,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. */
@@ -106,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;
@@ -149,6 +161,16 @@ 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
@@ -156,14 +178,14 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
      * 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 guarda del modelo (D-31). CERO llamadas si algo de eso falla.
+     * 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 guarda D-31 SÍ corre aquí para los tipos CON opt-in** (letra corregida en el cierre 1 de D1, ⚪ 5 del auditor:
+     * **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.
@@ -209,7 +231,7 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
     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 guarda D-31 que `deny` (500 si
+     * 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`).
@@ -218,7 +240,7 @@ export declare class OpenFgaRelationsDriver implements RelationsDriver {
         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, _page?: RelationPage): Promise<RelationSubjectsPage>;
+    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`:
@@ -227,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
@@ -260,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
@@ -292,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);
@@ -325,4 +354,3 @@ export declare function purgeWrites<K extends {
     relation: string;
     object: string;
 }>(keys: readonly K[]): K[][];
-//# sourceMappingURL=openfga_relations_driver.d.ts.map