@jantstack/adonis-authz 1.1.0 → 2.0.0-alpha.1

package/build/src/drivers/openfga_driver.js

@@ -1,81 +1,139 @@
-import { Exception } from '@adonisjs/core/exceptions';
 import db from '@adonisjs/lucid/services/db';
-import { OpenFgaClient, ClientWriteRequestOnDuplicateWrites, ClientWriteRequestOnMissingDeletes, } from '@openfga/sdk';
-import { AuthorizationBackendError } from '../errors.js';
-import { APP_SCOPE, APP_SCOPE_TYPE } from '../types.js';
-import { APP_SCOPE_DB_UUID } from './database_driver.js';
-/** `:` no es válido en ids de FGA — se encodea (`audit:read` → `audit~read`). */
-function encodeSlug(slug) {
-    return slug.replaceAll(':', '~');
-}
-function decodeSlug(encoded) {
-    return encoded.replaceAll('~', ':');
-}
+import { OpenFgaClient, ClientWriteRequestOnDuplicateWrites, ClientWriteRequestOnMissingDeletes, ConsistencyPreference, } from '@openfga/sdk';
+import { AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, PurgeIncompleteError, StoreNotEmptyError, UnknownPermissionError, } from '../errors.js';
+import { APP_SCOPE_TYPE } from '../types.js';
+import { APP_SCOPE_DB_UUID, assertRoleAssignableAt, declaredRoleAt, hasRoleTargets, resolveRoleQuery, rolesToRevoke, visibleRoleFor, } from './database_driver.js';
+import { assertIdentity, assertScope, chainKeysFrom, isCatalogUuid, isValidScope, normalizeRoleQuery, scopeKey, } from '../identity.js';
+import { resolveGrantExpiry, sameInstant, toExpiryDate } from '../expiry.js';
+import { assertKnownScope, canonicalScope, guardSql, isTimeoutLike, resolveChain, rootOnlyResolver, withDeadline, } from './backend_guard.js';
+import { CatalogCache, assertCatalogOptions, isRoleVisibleWith } from '../catalog_cache.js';
+import { isClock, systemClock } from '../clock.js';
+import { sqlExpiryCodec } from './sql_expiry.js';
+/** Nombre de tipo admitido por FGA (`^[^:#@\s]{1,254}$`). */
+const FGA_TYPE_FORMAT = /^[^:#@\s]{1,254}$/;
 /**
- * Caracteres admitidos en un tipo de scope y en un uuid al construir la clave
- * del binding. `|` es el separador y `~` el escape de los slugs: si alguno
- * apareciera dentro de un componente, dos scopes DISTINTOS podrían producir
- * la misma clave —p. ej. `{org, 'anization|X'}` y `{'org|anization', 'X'}`—
- * y un grant en uno autorizaría en el otro (confusión de privilegios).
- *
- * El driver `database` es inmune por construcción (guarda tipo y uuid en
- * columnas separadas, sin codificar); esta validación protege la única ruta
- * que serializa el scope a un string.
+ * `holderTypes` tiene que ser INYECTIVO. Si dos morph names caen en el mismo
+ * tipo FGA, para el store son un solo holder: un grant a `users:U` autoriza a
+ * `integrations:U`, `listSubjects` devuelve el morph equivocado y un revoke
+ * borra al otro (invariante 4, L0.2). El generador del modelo lo "sabía"
+ * (deduplicaba con un Set) y publicaba sin quejarse: ahora lanza aquí, al
+ * construir el driver y al generar el modelo, antes de tocar nada.
  */
-const SCOPE_COMPONENT_FORMAT = /^[a-zA-Z0-9_.:-]+$/;
-function assertScopeComponent(kind, value) {
-    if (!SCOPE_COMPONENT_FORMAT.test(value)) {
-        throw new Exception(`${kind} inválido para el driver openfga: '${value}'. ` +
-            `Solo se admiten letras, dígitos y . _ - : (ni '|' ni '~').`, { status: 500 });
+export function assertHolderTypes(holderTypes) {
+    if (!holderTypes || typeof holderTypes !== 'object' || Object.keys(holderTypes).length === 0) {
+        throw new AuthorizationConfigError('holderTypes vacío: el driver openfga necesita al menos un holder (morph name → tipo FGA)');
+    }
+    const morphsByFgaType = new Map();
+    for (const [morph, fgaType] of Object.entries(holderTypes)) {
+        if (typeof fgaType !== 'string' || !FGA_TYPE_FORMAT.test(fgaType)) {
+            throw new AuthorizationConfigError(`holderTypes['${morph}'] = ${JSON.stringify(fgaType)} no es un tipo FGA válido ` +
+                `(1-254 caracteres, sin ':', '#', '@' ni espacios)`);
+        }
+        morphsByFgaType.set(fgaType, [...(morphsByFgaType.get(fgaType) ?? []), morph]);
+    }
+    const collisions = [...morphsByFgaType.entries()].filter(([, morphs]) => morphs.length > 1);
+    if (collisions.length) {
+        throw new AuthorizationConfigError(`holderTypes no es inyectivo: ` +
+            collisions.map(([fga, morphs]) => `${morphs.join(' y ')} → '${fga}'`).join('; ') +
+            `. Dos holders con el mismo tipo FGA serían uno solo para el store.`);
     }
 }
+// La clave de scope del id del binding (`app` | `<tipo>|<uuid>`) es la
+// misma `scopeKey` del paquete (`identity.ts`; desde 3B también el owner de
+// un rol local): `|` es el separador y `assertScope` impide que un
+// componente lo lleve (dos scopes distintos no producen la misma clave) y
+// rechaza `{app, uuid}` (L0.10).
 /**
- * Clave de scope dentro del id del binding: `app` para la raíz,
- * `<tipo>|<uuid>` para el resto. Genérico: sirve para cualquier nivel que
- * defina el consumidor sin tocar el driver.
+ * Id de binding (`<scopeKey>|<uuid>`: `app|<uuid>` o `<tipo>|<uuidScope>|<uuid>`)
+ * → scope + uuid del catálogo (del rol en `role_binding`, del permiso en
+ * `deny_binding`). Se parsea DESDE LA DERECHA (3A · A1): el último componente
+ * es el uuid y el resto la clave del scope, que tiene 1 parte (`app`) o 2
+ * (`<tipo>|<uuid>`). Antes el último componente era el slug codificado
+ * (`docs~read`) y el parseo contaba partes: ambiguo en cuanto la clave del
+ * scope variara de longitud (panel 2026-08-28, §2-C), y con un escape no
+ * inyectivo desde el llamante (L0.8a).
+ *
+ * `null` si no tiene la forma del motor O si alguna parte no pasa su
+ * gramática —el scope, la de identidad; el uuid, la de UUID canónico del
+ * catálogo—: un id que el driver no escribiría no es un hecho del motor
+ * aunque esté en el store. Los ids de 1.x/2.0–2.1 (con slug) caen aquí:
+ * 2.2 no los lee, y `openfga:import --reconcile` los cuenta como `extra`.
+ * Exportada para probarla sin servidor.
  */
-function scopeKey(scope) {
-    assertScopeComponent('Tipo de scope', scope.type);
-    if (scope.type === APP_SCOPE_TYPE)
-        return APP_SCOPE_TYPE;
-    assertScopeComponent('UUID de scope', String(scope.uuid ?? ''));
-    return `${scope.type}|${scope.uuid}`;
-}
-function parseBindingId(id) {
-    const parts = id.split('|');
-    if (parts.length === 2 && parts[0] === APP_SCOPE_TYPE) {
-        return { scope: { type: APP_SCOPE_TYPE, uuid: null }, slug: decodeSlug(parts[1]) };
+export function parseBindingId(id) {
+    const cut = id.lastIndexOf('|');
+    if (cut < 0)
+        return null;
+    const uuid = id.slice(cut + 1);
+    const keyParts = id.slice(0, cut).split('|');
+    let scope;
+    if (keyParts.length === 1 && keyParts[0] === APP_SCOPE_TYPE) {
+        scope = { type: APP_SCOPE_TYPE, uuid: null };
     }
-    if (parts.length === 3) {
-        return { scope: { type: parts[0], uuid: parts[1] }, slug: decodeSlug(parts[2]) };
+    else if (keyParts.length === 2) {
+        scope = { type: keyParts[0], uuid: keyParts[1] };
     }
-    return null;
+    else {
+        return null;
+    }
+    if (!isValidScope(scope) || !isCatalogUuid(uuid))
+        return null;
+    return { scope, uuid };
 }
 /** `<tipoFga>:<uuid>` a partir del morph name del holder. */
 function fgaSubjectWith(subject, holderTypes) {
     const fgaType = holderTypes[subject.type];
     if (!fgaType) {
-        throw new Exception(`Holder type '${subject.type}' no está en el modelo FGA ` +
+        // Contradicción de config (D15): el modelo del store no tiene ese tipo.
+        throw new AuthorizationConfigError(`Holder type '${subject.type}' no está en el modelo FGA ` +
             `(declarados: ${Object.keys(holderTypes).join(', ') || 'ninguno'}). ` +
-            `Añádelo a holderTypes y regenera el authorization model.`, { status: 500 });
+            `Añádelo a holderTypes y regenera el authorization model.`);
     }
     return `${fgaType}:${subject.uuid}`;
 }
-function checkContext() {
-    return { current_time: new Date().toISOString() };
+/**
+ * El `context` de TODA consulta que evalúe relaciones: checks de roles y de
+ * denies. Un único constructor a propósito (S17): en cuanto una tupla del
+ * camino lleva la condición `not_expired`, un check sin `current_time` falla
+ * entero (400 → 503). Hoy los denies no llevan condición; el modo facts (3b)
+ * evalúa deny y grant en un solo check, así que no hay margen. Las
+ * enumeraciones no evalúan nada (`Read` devuelve tuplas escritas): filtran
+ * la caducidad en cliente con el MISMO reloj del driver (`now()`, J1): el
+ * `current_time` que viaja en cada check es el instante que decide.
+ */
+function checkContext(now) {
+    return { current_time: now.toISOString() };
 }
 /**
- * ¿La expiración almacenada y la pedida son la misma? Compara el instante,
- * no la cadena: `2026-01-01T00:00:00Z` y `2026-01-01T00:00:00.000Z` son el
- * mismo momento y no justifican reescribir la tuple.
+ * Alinea los resultados de un batchCheck con los checks pedidos por
+ * `correlationId`, no por posición (L0.14). El SDK reparte el lote en
+ * sub-lotes paralelos y concatena las respuestas según llegan: el orden no es
+ * el de los checks. Cardinalidad igual no basta —un id duplicado y otro
+ * ausente pasan el conteo—: cada check debe tener EXACTAMENTE un resultado y
+ * ningún resultado puede ser de un check que no se pidió.
  */
-function sameExpiry(storedValidUntil, requested) {
-    if (!storedValidUntil && !requested)
-        return true;
-    if (!storedValidUntil || !requested)
-        return false;
-    const stored = Date.parse(storedValidUntil);
-    return Number.isFinite(stored) && stored === requested.getTime();
+export function correlateBatchResults(checks, results) {
+    const byId = new Map();
+    for (const result of results) {
+        const id = result.correlationId;
+        if (byId.has(id)) {
+            throw new AuthorizationInternalError(`OpenFGA batchCheck devolvió dos resultados para el correlationId '${id}'`);
+        }
+        byId.set(id, result);
+    }
+    const aligned = checks.map((check) => {
+        const result = byId.get(check.correlationId);
+        if (!result) {
+            throw new AuthorizationInternalError(`OpenFGA batchCheck no devolvió resultado para el check '${check.correlationId}' (${check.relation} ${check.object})`);
+        }
+        return result;
+    });
+    if (byId.size !== checks.length) {
+        const requested = new Set(checks.map((c) => c.correlationId));
+        const foreign = [...byId.keys()].filter((id) => !requested.has(id));
+        throw new AuthorizationInternalError(`OpenFGA batchCheck devolvió resultados de checks no pedidos: ${foreign.join(', ')}`);
+    }
+    return aligned;
 }
 /**
  * El authorization model en formato JSON del API de FGA, generado a partir
@@ -83,7 +141,8 @@ function sameExpiry(storedValidUntil, requested) {
  * driver: si difieren, los checks no encuentran las tuplas.
  */
 export function openFgaAuthorizationModel(holderTypeMap) {
-    const holderTypes = [...new Set(Object.values(holderTypeMap))];
+    assertHolderTypes(holderTypeMap);
+    const holderTypes = Object.values(holderTypeMap);
     const direct = holderTypes.map((type) => ({ type }));
     const directWithExpiry = [
         ...direct,
@@ -133,6 +192,41 @@ export async function provisionOpenFgaStore(apiUrl, name, holderTypeMap) {
     const model = await scoped.writeAuthorizationModel(openFgaAuthorizationModel(holderTypeMap));
     return { storeId: store.id, modelId: model.authorization_model_id };
 }
+/**
+ * ¿El error (o su cadena de causas) es el rechazo de FGA a escribir una tuple
+ * key que ya existe? Es la ÚNICA señal de carrera check-then-write que
+ * `grant` acepta: un 400 de validación (`validation_error`) o un 5xx no son
+ * "alguien escribió antes" y se propagan clasificados, con el error del SDK
+ * como causa (D6). Verificado contra OpenFGA v1.19: el duplicado llega como
+ * HTTP 400 con `apiErrorCode: 'write_failed_due_to_invalid_input'` y el
+ * mensaje "cannot write a tuple which already exists"; un 409 se acepta por
+ * si una versión del servidor lo devuelve así.
+ */
+export function isDuplicateWrite(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 6; depth++) {
+        if (current.statusCode === 409)
+            return true;
+        if (current.apiErrorCode === 'write_failed_due_to_invalid_input' &&
+            /already exists/i.test(String(current.apiErrorMessage ?? current.message ?? ''))) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Receta que acompaña al 503 de un `grant` SIN `expiresAt` cuando no se pudo
+ * leer la caducidad vigente: preservar exige saber qué hay, y asumir
+ * "permanente" sería L0.4 en modo degradado. Se añade al mensaje del error
+ * ya clasificado (mismo tipo, mismo `code`, misma causa).
+ */
+function withPreserveRecipe(error) {
+    error.message +=
+        `. 'grant' sin 'expiresAt' necesita leer la caducidad vigente para preservarla y no se ` +
+            `escribe a ciegas: si la intención es "permanente", pasa { expiresAt: null }; si es temporal, una Date.`;
+    return error;
+}
 /**
  * Devuelve el cliente con TODOS sus métodos envueltos: un fallo de red o un
  * 5xx sale como `AuthorizationBackendError` (503) y no como el `FgaError` del
@@ -148,21 +242,28 @@ export async function provisionOpenFgaStore(apiUrl, name, holderTypeMap) {
  * ahí el error del SDK es la información más útil y no rompe ninguna
  * abstracción.
  */
-function guardBackendErrors(client) {
+function guardBackendErrors(client, timeoutMs) {
     return new Proxy(client, {
         get(target, prop, receiver) {
             const value = Reflect.get(target, prop, receiver);
             if (typeof value !== 'function')
                 return value;
             return (...args) => {
-                const fail = (cause) => new AuthorizationBackendError('openfga', String(prop), cause);
+                const operation = String(prop);
+                const fail = (cause) => isTimeoutLike(cause)
+                    ? new AuthorizationBackendTimeoutError('openfga', operation, timeoutMs, cause)
+                    : new AuthorizationBackendError('openfga', operation, cause);
                 try {
                     const result = value.apply(target, args);
-                    return result instanceof Promise
-                        ? result.catch((error) => {
-                            throw fail(error);
-                        })
-                        : result;
+                    if (!(result instanceof Promise))
+                        return result;
+                    // Deadline TOTAL por llamada (reintentos del SDK incluidos): el
+                    // `timeout` de axios corta cada intento, pero el SDK reintenta los
+                    // errores de red con backoff y sin esto el llamante esperaría la
+                    // suma de todos. Un deadline es un deadline.
+                    return withDeadline(result.catch((error) => {
+                        throw fail(error);
+                    }), timeoutMs, () => new AuthorizationBackendTimeoutError('openfga', operation, timeoutMs));
                 }
                 catch (error) {
                     throw fail(error);
@@ -171,6 +272,62 @@ function guardBackendErrors(client) {
         },
     });
 }
+export const DEFAULT_TIMEOUT_MS = 5_000;
+/** Tope de operaciones por `Write` en FGA (verificado: `exceeded_entity_limit` a partir de 100). */
+const PURGE_BATCH_SIZE = 100;
+/** Tamaño de página de `Read` (máximo del servidor). */
+const READ_PAGE_SIZE = 100;
+/**
+ * Cota de páginas de una enumeración (1.000.000 de tuplas a 100 por página).
+ * Un `continuation_token` que no avanza —un servidor roto, un proxy o una
+ * caché delante— era un bucle infinito que ningún deadline cortaba, porque
+ * el deadline es por llamada (D12, auditor H7).
+ */
+export const MAX_READ_PAGES = 10_000;
+/**
+ * Recorre TODAS las páginas de un `Read` con la misma cota que el driver
+ * (D12): token repetido o más de `MAX_READ_PAGES` páginas ⇒ 500. Lo usa el
+ * importador, que trabaja con un cliente crudo (herramienta FGA).
+ */
+async function* readPages(client, filter) {
+    let continuationToken;
+    const seen = new Set();
+    let pages = 0;
+    do {
+        const response = await client.read(filter, {
+            pageSize: READ_PAGE_SIZE,
+            continuationToken,
+            consistency: ConsistencyPreference.HigherConsistency,
+        });
+        pages += 1;
+        for (const tuple of response.tuples ?? [])
+            yield tuple;
+        continuationToken = response.continuation_token || undefined;
+        if (continuationToken) {
+            if (seen.has(continuationToken)) {
+                throw new AuthorizationInternalError(`Read: el continuation_token se repite (página ${pages})`);
+            }
+            if (pages >= MAX_READ_PAGES) {
+                throw new AuthorizationInternalError(`Read: más de ${MAX_READ_PAGES} páginas sin agotar el continuation_token`);
+            }
+            seen.add(continuationToken);
+        }
+    } while (continuationToken);
+}
+/** Clave textual de una tupla, para comparar conjuntos. */
+function tupleId(key) {
+    return `${key.user}#${key.relation}@${key.object}`;
+}
+function tupleOf(fact) {
+    return fact.expiresAt
+        ? {
+            ...fact.key,
+            condition: { name: 'not_expired', context: { valid_until: fact.expiresAt.toISOString() } },
+        }
+        : fact.key;
+}
+/** Tope de tuplas por `Write` transaccional de FGA. */
+const IMPORT_BATCH_SIZE = 100;
 /**
  * Migración de hechos database → openfga: copia las asignaciones vigentes y
  * los denies de las tablas `authz_*` como tuples del store FGA.
@@ -179,225 +336,528 @@ function guardBackendErrors(client) {
  *   volver a AUTHZ_DRIVER=database (solo se pierde lo escrito mientras se
  *   operó con openfga). El catálogo y la jerarquía nunca migran: son
  *   metadata local para ambos drivers.
- * - Idempotente: re-ejecutar no duplica (onDuplicateWrites: Ignore).
  * - Las asignaciones ya expiradas se saltan (no tiene sentido copiarlas);
  *   las de expiración futura viajan con la condition `not_expired`.
+ * - NUNCA `onDuplicateWrites: Ignore` (S7): en FGA la condición no es parte
+ *   de la clave, así que "ignorar el duplicado" dejaba la caducidad vieja y
+ *   reportaba éxito. Un store con tuplas exige `reconcile`, que compara
+ *   tupla a tupla, reescribe las que difieren y cuenta las que SQL no tiene
+ *   (`extra`); con `prune` las borra (`deleted`) y el reconcile converge
+ *   (D14). Nunca silencioso: el reporte distingue written / updated /
+ *   unchanged / extra / deleted / skippedExpired.
+ *
+ * Herramienta explícitamente de OpenFGA: los errores del SDK salen crudos.
  */
 export async function importAuthzFactsToOpenFga(options) {
+    assertHolderTypes(options.holderTypes);
+    if (options.prune && !options.reconcile) {
+        throw new AuthorizationConfigError('openfga:import: `prune` solo tiene sentido con `reconcile` (es lo que sobra respecto a SQL lo que se borra)');
+    }
     const client = new OpenFgaClient({
         apiUrl: options.apiUrl,
         storeId: options.storeId,
         authorizationModelId: options.modelId,
     });
-    const now = new Date();
+    const now = (options.now ?? systemClock)();
     const result = {
-        assignments: 0,
-        denies: 0,
+        written: 0,
+        updated: 0,
+        unchanged: 0,
+        extra: 0,
+        deleted: 0,
         skippedExpired: 0,
         dryRun: options.dryRun ?? false,
     };
-    const tuples = [];
-    const assignments = await db
-        .from('authz_assignments as a')
-        .join('authz_roles as r', 'r.uuid', 'a.role_uuid')
-        .select('a.holder_type', 'a.holder_uuid', 'a.scope_type', 'a.scope_uuid', 'a.expires_at')
-        .select('r.slug as role_slug');
     const rowScope = (row) => ({
         type: row.scope_type,
         uuid: row.scope_uuid === APP_SCOPE_DB_UUID ? null : row.scope_uuid,
     });
+    const facts = [];
+    // `expires_at` se lee con el codec del motor (2.5-B · K2): en MySQL como
+    // cadena UTC vía DATE_FORMAT, sin depender de la zona del cliente.
+    const expiry = sqlExpiryCodec(db.connection());
+    const assignments = await db
+        .from('authz_assignments as a')
+        .join('authz_roles as r', 'r.uuid', 'a.role_uuid')
+        .select('a.holder_type', 'a.holder_uuid', 'a.scope_type', 'a.scope_uuid', expiry.select('a.expires_at', 'expires_at'))
+        .select('r.uuid as role_uuid');
     for (const row of assignments) {
-        const expiresAt = row.expires_at ? new Date(row.expires_at) : null;
+        const expiresAt = expiry.fromDb(row.expires_at);
         if (expiresAt && expiresAt <= now) {
             result.skippedExpired++;
             continue;
         }
-        const scope = rowScope(row);
-        const key = {
-            user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
-            relation: 'assignee',
-            object: `role_binding:${scopeKey(scope)}|${encodeSlug(row.role_slug)}`,
-        };
-        tuples.push(expiresAt
-            ? {
-                ...key,
-                condition: { name: 'not_expired', context: { valid_until: expiresAt.toISOString() } },
-            }
-            : key);
-        result.assignments++;
+        facts.push({
+            key: {
+                user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
+                relation: 'assignee',
+                object: `role_binding:${scopeKey(rowScope(row))}|${row.role_uuid}`,
+            },
+            expiresAt,
+        });
     }
     const denies = await db
         .from('authz_denies as d')
         .join('authz_permissions as p', 'p.uuid', 'd.permission_uuid')
         .select('d.holder_type', 'd.holder_uuid', 'd.scope_type', 'd.scope_uuid')
-        .select('p.slug as permission_slug');
+        .select('p.uuid as permission_uuid');
     for (const row of denies) {
-        const scope = rowScope(row);
-        tuples.push({
-            user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
-            relation: 'denied',
-            object: `deny_binding:${scopeKey(scope)}|${encodeSlug(row.permission_slug)}`,
+        facts.push({
+            key: {
+                user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
+                relation: 'denied',
+                object: `deny_binding:${scopeKey(rowScope(row))}|${row.permission_uuid}`,
+            },
+            expiresAt: null,
         });
-        result.denies++;
     }
-    if (!result.dryRun && tuples.length > 0) {
-        // Chunks: el write transaccional de FGA tiene límite de tuples por request.
-        for (let i = 0; i < tuples.length; i += 50) {
-            await client.writeTuples(tuples.slice(i, i + 50), {
-                conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
-            });
+    // ¿Store vacío? Un Read sin filtro devuelve cualquier tupla que haya.
+    const probe = await client.read({}, { pageSize: 1 });
+    const storeIsEmpty = (probe.tuples ?? []).length === 0;
+    if (!storeIsEmpty && !options.reconcile) {
+        throw new StoreNotEmptyError(`El store ${options.storeId} ya tiene tuplas. Importar encima sin comparar dejaría ` +
+            `caducidades viejas en pie: usa --reconcile (compara tupla a tupla) o un store nuevo.`);
+    }
+    const toWrite = [];
+    const toReplace = [];
+    const toDelete = [];
+    if (storeIsEmpty) {
+        toWrite.push(...facts);
+    }
+    else {
+        for (const fact of facts) {
+            const stored = await client.read(fact.key);
+            const tuple = stored.tuples?.[0];
+            if (!tuple) {
+                toWrite.push(fact);
+                continue;
+            }
+            const storedExpiry = toExpiryDate(tuple.key?.condition?.context?.valid_until);
+            if (sameInstant(storedExpiry, fact.expiresAt))
+                result.unchanged++;
+            else
+                toReplace.push(fact);
+        }
+        // Lo que el store tiene de MÁS (D14): se lee entero y se resta el
+        // conjunto de SQL. Solo los objetos del motor; nada más vive en este
+        // modelo, pero si algo hubiera no es asunto del importador.
+        const wanted = new Set(facts.map((f) => tupleId(f.key)));
+        for await (const tuple of readPages(client, {})) {
+            const k = tuple?.key;
+            if (!k?.user || !k?.relation || !k?.object)
+                continue;
+            if (!/^(role_binding|deny_binding):/.test(k.object))
+                continue;
+            const key = { user: k.user, relation: k.relation, object: k.object };
+            if (!wanted.has(tupleId(key)))
+                toDelete.push(key);
+        }
+    }
+    result.written = toWrite.length;
+    result.updated = toReplace.length;
+    result.extra = toDelete.length;
+    result.deleted = options.prune ? toDelete.length : 0;
+    if (result.dryRun)
+        return result;
+    // Sin Ignore: en un store vacío un duplicado es un bug (dos filas de SQL
+    // con la misma clave, imposible por el unique) y debe verse.
+    for (let i = 0; i < toWrite.length; i += IMPORT_BATCH_SIZE) {
+        await client.writeTuples(toWrite.slice(i, i + IMPORT_BATCH_SIZE).map(tupleOf));
+    }
+    // delete + write no caben en una misma request para la misma clave.
+    for (let i = 0; i < toReplace.length; i += IMPORT_BATCH_SIZE) {
+        const batch = toReplace.slice(i, i + IMPORT_BATCH_SIZE);
+        await client.deleteTuples(batch.map((f) => f.key));
+        await client.writeTuples(batch.map(tupleOf));
+    }
+    if (options.prune) {
+        for (let i = 0; i < toDelete.length; i += IMPORT_BATCH_SIZE) {
+            await client.deleteTuples(toDelete.slice(i, i + IMPORT_BATCH_SIZE));
         }
     }
     return result;
 }
 export class OpenFgaAuthorizationDriver {
     client;
-    resolveAncestors;
+    chainResolver;
     holderTypes;
+    /**
+     * Contadores observables del driver. `unparseableBindings`: ids del store
+     * que el motor no entiende (L0.16). Cada uno es un hecho que las
+     * enumeraciones NO muestran; se registra y se cuenta, jamás un `continue`
+     * mudo — quien opera el store tiene que poder verlo.
+     */
+    diagnostics = { unparseableBindings: 0 };
+    logger;
+    timeoutMs;
+    consistency;
+    /** Reloj de pared del driver (J1): el ÚNICO `now` de checks, filtros y re-grant. */
+    now;
+    /**
+     * Memo del catálogo (2A): permisos, roles por nivel y roles que conceden
+     * cada permiso se leen de aquí en el camino caliente; antes eran dos
+     * consultas SQL por `authorize`. Los hechos siguen en FGA en cada pregunta.
+     * Se revalida contra `authz_catalog_version` (2D · F1): cada operación
+     * toma la foto UNA vez (`view()`) y lee de ella todo lo que necesita.
+     * `catalog.invalidate()` fuerza la recarga de ESTE memo.
+     */
+    catalog;
     constructor(options) {
+        assertHolderTypes(options.holderTypes);
+        assertCatalogOptions('OpenFgaAuthorizationDriver', options);
+        if (options.now !== undefined && !isClock(options.now)) {
+            throw new AuthorizationConfigError(`OpenFgaAuthorizationDriver: 'now' debe ser una función () => Date (llegó ${typeof options.now})`);
+        }
+        this.now = options.now ?? systemClock;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.catalog =
+            options.catalog ?? new CatalogCache({ driver: 'openfga', timeoutMs, revalidate: options.catalogRevalidate });
         this.client = guardBackendErrors(new OpenFgaClient({
             apiUrl: options.apiUrl,
             storeId: options.storeId,
             authorizationModelId: options.modelId,
-        }));
-        this.resolveAncestors =
-            options.resolveAncestors ??
-                (async (scope) => (scope.type === APP_SCOPE_TYPE ? [] : [APP_SCOPE]));
+            // `baseOptions` se funde en la config de axios de cada request: es la
+            // única vía del SDK (no tiene `timeoutMs` propio; su default es 10 s).
+            baseOptions: { timeout: timeoutMs },
+            // Sin reintentos a escondidas (ver `OpenFgaDriverOptions.retryParams`).
+            retryParams: { maxRetry: 0, ...options.retryParams },
+        }), timeoutMs);
+        // Sin resolutor solo existe la raíz (L0.3: el default plano desapareció).
+        this.chainResolver = options.resolveChain ?? rootOnlyResolver;
         this.holderTypes = options.holderTypes;
+        this.logger = options.logger ?? console;
+        this.timeoutMs = timeoutMs;
+        this.consistency =
+            options.consistency === 'minimize_latency'
+                ? ConsistencyPreference.MinimizeLatency
+                : ConsistencyPreference.HigherConsistency;
+    }
+    /**
+     * `[scope canónico, ...ancestros]`, o `null` si el scope no existe
+     * (lecturas: denegar). `chain[0]` —la fila del consumidor, no lo que
+     * escribió el llamante— es el scope que va en la clave de cada binding
+     * (2.5-B · K1): un alias del uuid que el árbol funde con la fila real
+     * llega aquí ya canónico y el `deny_binding` escrito canónico casa.
+     */
+    chain(scope, operation) {
+        return resolveChain(this.chainResolver, scope, operation);
+    }
+    /** La cadena o 422: una escritura no puede ir a un scope que nadie reconoce. */
+    knownScope(scope, operation) {
+        return assertKnownScope(this.chainResolver, scope, operation);
+    }
+    /** El scope canónico para `revoke`/`removeDeny`/`purgeScope` (ver `canonicalScope`). */
+    canonicalOrSelf(scope, operation) {
+        return canonicalScope(this.chainResolver, scope, operation);
+    }
+    /**
+     * Vista de este driver con OTRO resolutor de ancestros y el mismo estado
+     * (cliente, memo del catálogo, deadline, diagnósticos). Es lo que usa
+     * `AuthorizationManager.forRequest()` para leer con un resolutor memoizado
+     * sin tocar el driver compartido: hereda por prototipo y solo sobrescribe
+     * el resolutor.
+     */
+    withChainResolver(resolveChain) {
+        const view = Object.create(this);
+        view.chainResolver = resolveChain;
+        return view;
+    }
+    /**
+     * Vista de este driver con OTRO reloj de pared (2.5 · J1): mismo cliente,
+     * store, memo y resolutor; solo cambia el `now` que viaja como
+     * `current_time` y filtra las enumeraciones. Lo aplica el manager con
+     * `config.clock` y el juez para fijar el instante.
+     */
+    withClock(now) {
+        if (!isClock(now)) {
+            throw new AuthorizationConfigError(`withClock: now debe ser una función () => Date (llegó ${typeof now})`);
+        }
+        const view = Object.create(this);
+        view.now = now;
+        return view;
+    }
+    /**
+     * El `context` de los checks de UNA operación, con el reloj de ESTE driver
+     * (o vista): se construye una vez por operación y viaja en todos sus
+     * checks (2.5-B · K9). Antes se leía el reloj por check y un mismo
+     * `authorize` evaluaba el deny en un instante y el rol en otro.
+     */
+    checkContext() {
+        return checkContext(this.now());
     }
-    async chain(scope) {
-        return [scope, ...(await this.resolveAncestors(scope))];
+    /**
+     * Consulta al catálogo local clasificando su fallo. Con este driver el
+     * catálogo SQL sigue siendo una dependencia dura de cada pregunta: su caída
+     * era un error crudo de Lucid que se presentaba como bug de aplicación (N3).
+     */
+    sql(operation, fn) {
+        return guardSql('openfga', operation, this.timeoutMs, fn);
     }
     fgaSubject(subject) {
         return fgaSubjectWith(subject, this.holderTypes);
     }
     /**
-     * batchCheck troceado al límite del servidor FGA (50 checks/request) y con
-     * verificación de completitud: TODOS los checks deben volver respondidos.
+     * Un batchCheck con TODOS los checks (el SDK trocea a 50 por request y
+     * paraleliza), cada uno con un `correlationId` propio, y la respuesta
+     * alineada por ese id: un resultado por check, ni uno más ni uno menos.
      */
     async batchCheckAll(checks) {
-        const results = [];
-        for (let i = 0; i < checks.length; i += 50) {
-            const slice = checks.slice(i, i + 50);
-            const response = await this.client.batchCheck({ checks: slice });
-            results.push(...response.result);
-        }
-        if (results.length !== checks.length) {
-            throw new Exception('OpenFGA batchCheck devolvió menos resultados que checks', {
-                status: 500,
-            });
+        if (checks.length === 0)
+            return [];
+        const withIds = checks.map((check, index) => ({
+            ...check,
+            correlationId: String(index),
+        }));
+        const response = await this.client.batchCheck({ checks: withIds }, { consistency: this.consistency });
+        const results = correlateBatchResults(withIds, response.result);
+        // Un 200 con `error` en un check individual (`input_error`,
+        // `internal_error`…) es una caída parcial del backend, no un "sin
+        // permiso": se clasifica igual que un 5xx (invariante 5, D1). Antes la
+        // fase de roles y `hasRole` lo colapsaban en `false`.
+        const failed = results.find((r) => r.error);
+        if (failed) {
+            throw new AuthorizationBackendError('openfga', `batchCheck (${failed.request?.relation} ${failed.request?.object})`, failed.error);
         }
         return results;
     }
-    // ── Catálogo local (compartido entre drivers) ─────────────────────────
+    // ── Catálogo local (compartido entre drivers), desde el memo (2A) ──────
+    // Una carga por driver/proceso en vez de una o dos consultas SQL por
+    // pregunta, más una revalidación por operación (2D · F1). Un fallo de
+    // carga sale como 503, igual que antes.
     async findPermission(slug) {
-        return db.from('authz_permissions').where('slug', slug).select('uuid').first();
-    }
-    async findRoleOrFail(slug, scopeType) {
-        const role = await db
-            .from('authz_roles')
-            .where('slug', slug)
-            .where('scope_type', scopeType)
-            .select('uuid')
-            .first();
-        if (!role) {
-            throw new Exception(`Rol '${slug}' no existe en el catálogo para el nivel '${scopeType}'`, {
-                status: 422,
-            });
-        }
+        return (await this.catalog.view()).permission(slug);
     }
-    /** Roles del catálogo que conceden el permiso, agrupados por scope_type. */
-    async rolesGranting(permissionUuid) {
-        const rows = await db
-            .from('authz_role_permissions as rp')
-            .join('authz_roles as r', 'r.uuid', 'rp.role_uuid')
-            .where('rp.permission_uuid', permissionUuid)
-            .select('r.slug', 'r.scope_type');
-        const byScopeType = new Map();
-        for (const row of rows) {
-            const list = byScopeType.get(row.scope_type) ?? [];
-            list.push(row.slug);
-            byScopeType.set(row.scope_type, list);
-        }
-        return byScopeType;
+    /**
+     * Filtro por catálogo de las lecturas de membresía (`listRoles`,
+     * `listRoleScopes`, `rolesInChain`, `listScopes`): un binding cuyo uuid ya
+     * no está en `authz_roles` —o está, pero declarado para OTRO nivel, o es
+     * local a un scope que no está en la cadena del binding (3B · B2)— es una
+     * tupla huérfana, no una membresía; igual que en `database`, donde el
+     * catálogo lo excluye (D5). La tupla la recoge `authz:reconcile`. Desde 3A
+     * la resolución es por uuid (`roleByUuid`), nunca por slug. `chainKeys` es
+     * la cadena del scope del BINDING (desde él hacia la raíz).
+     */
+    declaredRole(catalog, binding, chainKeys) {
+        return declaredRoleAt(catalog, binding.uuid, binding.scope.type, chainKeys);
     }
     // ── Contrato ──────────────────────────────────────────────────────────
+    /**
+     * Los checks de UNA pregunta (subject, permiso, cadena): los denies de cada
+     * nivel y los roles del catálogo que conceden el permiso en cada nivel.
+     * Sin rol que conceda ⇒ `null`: la respuesta es `false` digan lo que digan
+     * los denies y no se pregunta al backend (2A).
+     */
+    checksFor(user, permissionUuid, chain, granting, context) {
+        // Por nivel, solo los roles que EXISTEN ahí (3B · B2): globales, o locales
+        // a un scope de la cadena desde ese nivel. Un rol de otro tenant no
+        // cuesta un check (mismo número de checks que sin roles locales).
+        const keysFrom = chainKeysFrom(chain);
+        const roles = chain.flatMap((s, i) => (granting.get(s.type) ?? [])
+            .filter((role) => isRoleVisibleWith(role, keysFrom[i]))
+            .map((role) => ({
+            user,
+            relation: 'assignee',
+            object: `role_binding:${scopeKey(s)}|${role.uuid}`,
+            context,
+        })));
+        if (roles.length === 0)
+            return null;
+        const denies = chain.map((s) => ({
+            user,
+            relation: 'denied',
+            object: `deny_binding:${scopeKey(s)}|${permissionUuid}`,
+            context,
+        }));
+        return { denies, roles };
+    }
     async authorize(subject, permission, scope) {
-        const perm = await this.findPermission(permission);
+        assertIdentity({ subject, permission, scope });
+        // Una foto del catálogo por pregunta: permiso y roles que conceden salen
+        // de la misma versión (y se paga una sola revalidación).
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
         if (!perm)
             return false;
         const user = this.fgaSubject(subject);
-        const chain = await this.chain(scope);
-        // 1. Denies en la cadena. FAIL-CLOSED: un check de deny con error se
-        //    trata como denegado (jamás se ignora un deny por un fallo puntual).
-        const denyChecks = chain.map((s) => ({
-            user,
-            relation: 'denied',
-            object: `deny_binding:${scopeKey(s)}|${encodeSlug(permission)}`,
-        }));
-        const denyResults = await this.batchCheckAll(denyChecks);
-        if (denyResults.some((r) => r.allowed || r.error))
+        const chain = await this.chain(scope, 'authorize');
+        if (!chain)
             return false;
-        // 2. Alguna asignación vigente en la cadena cuyo rol concede el permiso.
-        //    Aquí un error individual falla cerrado por sí solo (no concede).
-        const granting = await this.rolesGranting(perm.uuid);
-        const checks = chain.flatMap((s) => (granting.get(s.type) ?? []).map((roleSlug) => ({
-            user,
-            relation: 'assignee',
-            object: `role_binding:${scopeKey(s)}|${encodeSlug(roleSlug)}`,
-            context: checkContext(),
-        })));
-        if (checks.length === 0)
+        // Si ningún rol de la cadena concede el permiso, la respuesta es `false`
+        // digan lo que digan los denies: no se pregunta al backend.
+        const checks = this.checksFor(user, perm.uuid, chain, catalog.rolesGranting(perm.uuid), this.checkContext());
+        if (!checks)
             return false;
-        const results = await this.batchCheckAll(checks);
-        return results.some((r) => r.allowed && !r.error);
+        // UN solo batchCheck (2A): los denies de la cadena y los roles que
+        // conceden van en la misma request; el SDK trocea a 50 y paraleliza.
+        // Regla, en este orden: cualquier `error` ⇒ 503 (D1, dentro de
+        // `batchCheckAll`, antes de mirar nada); algún deny `allowed` ⇒ false;
+        // algún rol `allowed` ⇒ true. Antes eran dos requests secuenciales
+        // (denies, luego roles) con la misma regla.
+        const results = await this.batchCheckAll([...checks.denies, ...checks.roles]);
+        if (results.slice(0, checks.denies.length).some((r) => r.allowed))
+            return false;
+        return results.slice(checks.denies.length).some((r) => r.allowed);
+    }
+    /**
+     * `authorize` sobre N scopes con UN batchCheck (2.1, B6): los checks de
+     * todas las cadenas viajan juntos (el SDK trocea a 50 y paraleliza) y se
+     * atribuyen a su scope por posición dentro del lote correlacionado
+     * (L0.14). Misma regla que `authorize`, por scope: `error` en cualquier
+     * check ⇒ 503 entero (D1); deny `allowed` ⇒ false; rol `allowed` ⇒ true.
+     * Scope desconocido o sin rol que conceda ⇒ false sin checks.
+     */
+    async authorizeMany(subject, permission, scopes) {
+        assertIdentity({ subject, permission });
+        for (const scope of scopes)
+            assertIdentity({ scope });
+        if (scopes.length === 0)
+            return [];
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
+        if (!perm)
+            return scopes.map(() => false);
+        const user = this.fgaSubject(subject);
+        const granting = catalog.rolesGranting(perm.uuid);
+        // Un instante para todo el lote (K9): N scopes, una pregunta.
+        const context = this.checkContext();
+        const batch = [];
+        /** Por posición: `null` = false sin preguntar; si no, [inicio, nºDenies, nºRoles] dentro del lote. */
+        const slots = [];
+        // Un scope repetido comparte slot (y cadena) con su primera aparición
+        // (G2, CR9): mismos checks, misma respuesta por posición, sin duplicar
+        // el lote.
+        const slotByScope = new Map();
+        for (const scope of scopes) {
+            const scopeId = scopeKey(scope);
+            if (slotByScope.has(scopeId)) {
+                slots.push(slotByScope.get(scopeId));
+                continue;
+            }
+            const chain = await this.chain(scope, 'authorizeMany');
+            const checks = chain ? this.checksFor(user, perm.uuid, chain, granting, context) : null;
+            const slot = checks ? [batch.length, checks.denies.length, checks.roles.length] : null;
+            if (checks)
+                batch.push(...checks.denies, ...checks.roles);
+            slotByScope.set(scopeId, slot);
+            slots.push(slot);
+        }
+        const results = await this.batchCheckAll(batch);
+        return slots.map((slot) => {
+            if (!slot)
+                return false;
+            const [start, denies, roles] = slot;
+            if (results.slice(start, start + denies).some((r) => r.allowed))
+                return false;
+            return results.slice(start + denies, start + denies + roles).some((r) => r.allowed);
+        });
     }
     async grant(subject, role, scope, options = {}) {
-        await this.findRoleOrFail(role, scope.type);
+        assertIdentity({ subject, role, scope, expiresAt: options.expiresAt });
+        // El binding lleva la identidad canónica del árbol (K1), nunca la forma
+        // del llamante, y el uuid del rol, nunca su slug (3A · A1). El rol tiene
+        // que EXISTIR en ese scope (3B · B2: global, o local a un ancestro-o-igual)
+        // con una composición legal (B5).
+        const chain = await this.knownScope(scope, 'grant');
+        const [target] = chain;
+        const catalog = await this.catalog.view();
+        const declared = resolveRoleQuery(catalog, role, target, chainKeysFrom(chain)[0]);
+        assertRoleAssignableAt(catalog, declared);
+        const roleUuid = declared.uuid;
         const key = {
             user: this.fgaSubject(subject),
             relation: 'assignee',
-            object: `role_binding:${scopeKey(scope)}|${encodeSlug(role)}`,
+            object: `role_binding:${scopeKey(target)}|${roleUuid}`,
         };
-        const write = options.expiresAt
+        const tupleFor = (expiresAt) => expiresAt
             ? {
                 ...key,
                 condition: {
                     name: 'not_expired',
-                    context: { valid_until: options.expiresAt.toISOString() },
+                    context: { valid_until: expiresAt.toISOString() },
                 },
             }
             : key;
         // FGA no admite delete+write de la misma tuple key en una transacción, así
-        // que refrescar la expiración obliga a dos llamadas — y entre ellas hay un
+        // que cambiar la expiración obliga a dos llamadas — y entre ellas hay un
         // instante en el que authorize() responde false.
         //
         // Se mira primero qué hay, para NO pagar esa ventana cuando no hace falta:
         //  - si no existe la tuple → solo write (el caso del primer grant);
-        //  - si existe idéntica → no-op (re-ejecutar un seeder no toca nada);
-        //  - solo si la expiración CAMBIA de verdad se hace delete+write.
-        // La ventana pasa de "cada re-grant" a "cuando el llamante quiso cambiarla".
+        //  - si existe con la caducidad que toca → no-op (un seeder no toca nada);
+        //  - solo si la caducidad CAMBIA de verdad se hace delete+write.
+        // Y la lectura es lo que hace posible "omitido = preservar" (L0.4).
         const current = await this.readAssignment(key);
-        // Solo se salta la escritura si SABEMOS que lo almacenado ya es esto.
-        if (current.kind === 'present' && sameExpiry(current.validUntil, options.expiresAt))
-            return;
-        if (current.kind === 'absent') {
-            // No había nada: un write basta y no hay ventana de denegación. Si entre
-            // el read y el write otro proceso escribió la misma key, este write
-            // choca — y entonces sí toca el camino largo, para que gane el último
-            // escritor y no se pierda esta expiración en silencio.
-            try {
-                await this.client.writeTuples([write]);
-                return;
+        if (current.kind === 'unknown') {
+            // Sin lectura no hay forma de preservar una caducidad vigente: asumir
+            // "permanente" sería exactamente el defecto en modo degradado. Con un
+            // objetivo explícito (`Date`/`null`) sí se puede escribir a ciegas.
+            if (options.expiresAt === undefined)
+                throw withPreserveRecipe(current.error);
+            const expiresAt = options.expiresAt;
+            const existed = await this.writeAssignment(key, tupleFor(expiresAt));
+            return { existed, expiresAt };
+        }
+        if (current.kind === 'present') {
+            const expiresAt = resolveGrantExpiry(current.validUntil, options.expiresAt, this.now());
+            if (sameInstant(current.validUntil, expiresAt)) {
+                return { existed: true, previousExpiresAt: current.validUntil, expiresAt };
             }
-            catch {
-                // cae al delete+write de abajo
+            await this.replaceAssignment(key, tupleFor(expiresAt));
+            return { existed: true, previousExpiresAt: current.validUntil, expiresAt };
+        }
+        // No había nada: un write basta y no hay ventana de denegación. Si entre
+        // el read y el write otro proceso escribió la misma key, este write
+        // choca con un 409 — entonces se relee y se aplica el re-grant sobre lo
+        // que quedó, para que gane el último escritor y no se pierda esta
+        // caducidad. Cualquier otro fallo del write no es una carrera (D6).
+        const expiresAt = options.expiresAt ?? null;
+        try {
+            await this.client.writeTuples([tupleFor(expiresAt)]);
+            return { existed: false, expiresAt };
+        }
+        catch (error) {
+            if (!isDuplicateWrite(error))
+                throw error;
+            const raced = await this.readAssignment(key);
+            if (raced.kind === 'present') {
+                const target = resolveGrantExpiry(raced.validUntil, options.expiresAt, this.now());
+                if (!sameInstant(raced.validUntil, target))
+                    await this.replaceAssignment(key, tupleFor(target));
+                return { existed: true, previousExpiresAt: raced.validUntil, expiresAt: target };
             }
+            if (options.expiresAt === undefined) {
+                // El write chocó y la relectura no ve la tupla (o falló): sin objetivo
+                // explícito no se sabe qué preservar. El 409 original va como causa.
+                throw withPreserveRecipe(raced.kind === 'unknown'
+                    ? raced.error
+                    : new AuthorizationBackendError('openfga', 'grant (el write chocó y la relectura no ve la tupla)', error));
+            }
+            const existed = await this.writeAssignment(key, tupleFor(options.expiresAt));
+            return { existed, expiresAt: options.expiresAt };
+        }
+    }
+    /**
+     * Write directo; si la key ya existía (409), camino largo. Devuelve si
+     * existía. Cualquier otro fallo se propaga tal cual (ya clasificado).
+     */
+    async writeAssignment(key, tuple) {
+        try {
+            await this.client.writeTuples([tuple]);
+            return false;
         }
+        catch (error) {
+            if (!isDuplicateWrite(error))
+                throw error;
+            await this.replaceAssignment(key, tuple);
+            return true;
+        }
+    }
+    /** delete + write (dos llamadas: FGA no admite ambas sobre la misma key en una). */
+    async replaceAssignment(key, tuple) {
         await this.client.deleteTuples([key], {
             conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
         });
-        await this.client.writeTuples([write], {
+        await this.client.writeTuples([tuple], {
             conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
         });
     }
@@ -406,144 +866,433 @@ export class OpenFgaAuthorizationDriver {
      *
      * Distinguir `unknown` de `present` sin condición es lo que impide un bug
      * feo: si un fallo de lectura se pareciera a "existe y sin expiración", un
-     * grant sin expiración saldría por el atajo del no-op y se perdería —
-     * mientras el hook onWrite ya habría auditado que se concedió.
+     * grant sin expiración saldría por el atajo del no-op y se perdería. El
+     * error de lectura (ya clasificado como 503) viaja con el resultado para
+     * que quien no pueda seguir sin él lo propague.
      */
     async readAssignment(key) {
         try {
-            const response = await this.client.read(key);
+            const response = await this.client.read(key, { consistency: this.consistency });
             const tuple = response.tuples?.[0];
             if (!tuple)
                 return { kind: 'absent' };
             const validUntil = tuple.key?.condition?.context?.valid_until;
-            return { kind: 'present', validUntil: validUntil ? String(validUntil) : undefined };
+            return { kind: 'present', validUntil: toExpiryDate(validUntil) };
         }
-        catch {
-            // No se pudo leer: se asume lo peor y se toma el camino largo, que
-            // funciona exista o no la tuple.
-            return { kind: 'unknown' };
+        catch (error) {
+            return { kind: 'unknown', error };
         }
     }
     async revoke(subject, role, scope) {
-        await this.client.deleteTuples([
-            {
-                user: this.fgaSubject(subject),
-                relation: 'assignee',
-                object: `role_binding:${scopeKey(scope)}|${encodeSlug(role)}`,
-            },
-        ], { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
+        assertIdentity({ subject, role, scope });
+        // Rol fuera del catálogo para ese nivel ⇒ 422, como en `grant` (D10). Se
+        // quitan los bindings de TODOS los roles con ese nombre en el scope
+        // exacto (3B): a lo sumo uno es visible ahí; quitar nunca concede.
+        const named = rolesToRevoke(await this.catalog.view(), role, scope);
+        const target = await this.canonicalOrSelf(scope, 'revoke');
+        const user = this.fgaSubject(subject);
+        await this.client.deleteTuples(named.map((r) => ({ user, relation: 'assignee', object: `role_binding:${scopeKey(target)}|${r.uuid}` })), { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
     }
     async hasRole(subject, role, scope) {
+        assertIdentity({ subject, role, scope });
         const user = this.fgaSubject(subject);
-        const chain = await this.chain(scope);
-        const results = await this.batchCheckAll(chain.map((s) => ({
+        const chain = await this.chain(scope, 'hasRole');
+        if (!chain)
+            return false;
+        // El id del binding lleva el scope (y con él su tipo) y el UUID del rol
+        // que el catálogo declara con ese slug para el tipo de ESE nivel (3A):
+        // en cada nivel solo casa el rol de ese nivel. Con `{ slug, scopeType }`
+        // se recorta la cadena a los niveles de ese tipo (L0.6). Y solo se
+        // pregunta por los niveles para los que el catálogo declara el rol (D5):
+        // un rol retirado no es membresía aunque su tupla siga en el store.
+        const catalog = await this.catalog.view();
+        const targets = hasRoleTargets(catalog, role, chain);
+        if (targets.length === 0)
+            return false;
+        const context = this.checkContext();
+        const results = await this.batchCheckAll(targets.map(({ scope: s, roleUuid }) => ({
             user,
             relation: 'assignee',
-            object: `role_binding:${scopeKey(s)}|${encodeSlug(role)}`,
-            context: checkContext(),
+            object: `role_binding:${scopeKey(s)}|${roleUuid}`,
+            context,
         })));
-        return results.some((r) => r.allowed && !r.error);
+        return results.some((r) => r.allowed);
     }
     async deny(subject, permission, scope) {
+        assertIdentity({ subject, permission, scope });
         const perm = await this.findPermission(permission);
-        if (!perm) {
-            throw new Exception(`Permiso '${permission}' no existe en el catálogo`, { status: 422 });
-        }
+        if (!perm)
+            throw new UnknownPermissionError(permission);
+        const [target] = await this.knownScope(scope, 'deny');
         await this.client.writeTuples([
             {
                 user: this.fgaSubject(subject),
                 relation: 'denied',
-                object: `deny_binding:${scopeKey(scope)}|${encodeSlug(permission)}`,
+                object: `deny_binding:${scopeKey(target)}|${perm.uuid}`,
             },
         ], { conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore } });
     }
     async removeDeny(subject, permission, scope) {
+        assertIdentity({ subject, permission, scope });
+        const perm = await this.findPermission(permission);
+        if (!perm)
+            throw new UnknownPermissionError(permission);
+        const target = await this.canonicalOrSelf(scope, 'removeDeny');
         await this.client.deleteTuples([
             {
                 user: this.fgaSubject(subject),
                 relation: 'denied',
-                object: `deny_binding:${scopeKey(scope)}|${encodeSlug(permission)}`,
+                object: `deny_binding:${scopeKey(target)}|${perm.uuid}`,
             },
         ], { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
     }
+    /**
+     * Holders con asignación vigente del rol en el scope exacto: `Read` por
+     * objeto exacto, paginado, con la caducidad filtrada en cliente. Antes era
+     * `ListUsers`, que trunca al tope del servidor sin señal (L0.7).
+     */
     async listSubjects(role, scope) {
-        // ListUsers exige EXACTAMENTE un user_filter → una consulta por tipo.
-        const results = [];
+        assertIdentity({ role, scope });
+        // Un rol que el catálogo no declara para ese nivel (en ningún owner) no
+        // tiene holders (D5): nada que leer, ni árbol ni store. Un scope que el
+        // árbol no conoce no existe para el motor (D8, K1): nada; uno que conoce
+        // se lee bajo su identidad canónica, y el rol tiene que existir AHÍ (3B ·
+        // B2); el que existe se lee por su uuid (3A).
+        const catalog = await this.catalog.view();
+        const asked = normalizeRoleQuery(role);
+        if (asked.uuid !== undefined ? catalog.roleByUuid(asked.uuid) === null : catalog.rolesNamed(asked.slug, asked.scopeType ?? scope.type).length === 0) {
+            return [];
+        }
+        const chain = await this.chain(scope, 'listSubjects');
+        if (!chain)
+            return [];
+        const declared = visibleRoleFor(catalog, asked, scope, chainKeysFrom(chain)[0]);
+        if (!declared)
+            return [];
         const fgaToMorph = Object.fromEntries(Object.entries(this.holderTypes).map(([morph, fga]) => [fga, morph]));
-        for (const fgaType of [...new Set(Object.values(this.holderTypes))]) {
-            const response = await this.client.listUsers({
-                object: { type: 'role_binding', id: `${scopeKey(scope)}|${encodeSlug(role)}` },
-                relation: 'assignee',
-                user_filters: [{ type: fgaType }],
-                context: checkContext(),
-            });
-            for (const u of response.users ?? []) {
-                if (u.object) {
-                    results.push({ type: fgaToMorph[u.object.type] ?? u.object.type, uuid: u.object.id });
-                }
+        const tuples = await this.readAllTuples({
+            relation: 'assignee',
+            object: `role_binding:${scopeKey(chain[0])}|${declared.uuid}`,
+        });
+        const results = [];
+        for (const tuple of tuples) {
+            // `<tipoFga>:<uuid>`; un userset (`#`) o un tipo que no está en el mapa
+            // no es un holder que este driver haya escrito.
+            const separator = tuple.user.indexOf(':');
+            const fgaType = separator > 0 ? tuple.user.slice(0, separator) : '';
+            const uuid = separator > 0 ? tuple.user.slice(separator + 1) : '';
+            const morph = fgaToMorph[fgaType];
+            if (!morph || !uuid || uuid.includes('#')) {
+                this.diagnostics.unparseableBindings += 1;
+                this.warn(`authz(openfga): el user '${tuple.user}' de '${tuple.object}' no es un holder del motor; se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+                continue;
             }
+            results.push({ type: morph, uuid });
         }
         return results;
     }
-    /** role_binding ids del subject (asignaciones directas vigentes). */
-    async listBindings(subject) {
-        const response = await this.client.listObjects({
+    /**
+     * Bindings del subject ya parseados (asignaciones directas vigentes). Los
+     * ids que no se entienden se registran y se cuentan, no se descartan.
+     */
+    async listBindings(subject, at) {
+        const tuples = await this.readAllTuples({
             user: this.fgaSubject(subject),
             relation: 'assignee',
-            type: 'role_binding',
-            context: checkContext(),
-        });
-        return (response.objects ?? []).map((obj) => obj.replace(/^role_binding:/, ''));
+            object: 'role_binding:',
+        }, { at });
+        return this.parseBindings('role_binding', tuples.map((t) => t.object));
+    }
+    /** Scopes (por clave) donde el subject tiene un deny directo del permiso (por su uuid). */
+    async deniedScopeKeys(subject, permissionUuid, at) {
+        const tuples = await this.readAllTuples({
+            user: this.fgaSubject(subject),
+            relation: 'denied',
+            object: 'deny_binding:',
+        }, { at });
+        return new Set(this.parseBindings('deny_binding', tuples.map((t) => t.object))
+            .filter((p) => p.uuid === permissionUuid)
+            .map((p) => scopeKey(p.scope)));
+    }
+    parseBindings(type, objects) {
+        const parsed = [];
+        for (const obj of objects) {
+            const id = obj.replace(new RegExp(`^${type}:`), '');
+            const binding = parseBindingId(id);
+            if (binding) {
+                parsed.push(binding);
+            }
+            else {
+                this.diagnostics.unparseableBindings += 1;
+                this.warn(`authz(openfga): binding '${type}:${id}' no tiene la forma del motor; se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+            }
+        }
+        return parsed;
+    }
+    warn(message) {
+        this.logger.warn(message);
     }
     async listRoles(subject, scope) {
-        const prefix = scopeKey(scope);
+        assertIdentity({ subject, scope });
+        // Un scope que el árbol no conoce no existe para el motor (D8): nada.
+        const chain = await this.chain(scope, 'listRoles');
+        if (!chain)
+            return [];
+        const prefix = scopeKey(chain[0]);
+        const keys = chainKeysFrom(chain)[0];
+        const catalog = await this.catalog.view();
         const roles = new Set();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (parsed && scopeKey(parsed.scope) === prefix)
-                roles.add(parsed.slug);
+        for (const binding of await this.listBindings(subject)) {
+            if (scopeKey(binding.scope) !== prefix)
+                continue;
+            const declared = this.declaredRole(catalog, binding, keys);
+            if (declared)
+                roles.add(declared.slug);
         }
         return [...roles];
     }
+    /**
+     * Roles directos vigentes del holder en cada scope de la cadena (2D · G5):
+     * UNA lectura (`Read` paginado de sus bindings) agrupada por scope, en vez
+     * de un `listRoles` por nivel. Solo roles que el catálogo declara para ese
+     * nivel (D5). La cadena viene ya resuelta por el manager.
+     */
+    async rolesInChain(subject, chain) {
+        assertIdentity({ subject });
+        for (const scope of chain)
+            assertScope(scope);
+        if (chain.length === 0)
+            return [];
+        const catalog = await this.catalog.view();
+        const keysFrom = chainKeysFrom(chain);
+        const wanted = new Map(chain.map((s, i) => [scopeKey(s), { scope: s, keys: keysFrom[i] }]));
+        const seen = new Set();
+        const result = [];
+        for (const binding of await this.listBindings(subject)) {
+            const id = scopeKey(binding.scope);
+            const level = wanted.get(id);
+            if (!level)
+                continue;
+            const scope = level.scope;
+            const declared = this.declaredRole(catalog, binding, level.keys);
+            if (!declared)
+                continue;
+            // Dedupe por IDENTIDAD (3D · M1: el uuid, no el slug).
+            const dedupe = `${id}\u001f${declared.uuid}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            result.push({ scope, role: declared });
+        }
+        return result;
+    }
     async listRoleScopes(subject, scopeType) {
-        const seen = new Map();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (parsed && parsed.scope.type === scopeType) {
-                seen.set(scopeKey(parsed.scope), parsed.scope);
-            }
+        assertIdentity({ subject, scopeType });
+        const catalog = await this.catalog.view();
+        const byScope = new Map();
+        for (const binding of await this.listBindings(subject)) {
+            if (binding.scope.type !== scopeType)
+                continue;
+            const k = scopeKey(binding.scope);
+            if (!byScope.has(k))
+                byScope.set(k, { scope: binding.scope, bindings: [] });
+            byScope.get(k).bindings.push(binding);
         }
-        return [...seen.values()];
+        // Los scopes que el árbol ya no conoce no se listan (D8): una consulta
+        // al resolutor por scope, el mismo coste que `listScopes`. Y con la
+        // cadena se decide si alguno de sus roles existe ahí (D5, 3B · B2).
+        const known = [];
+        for (const { scope, bindings } of byScope.values()) {
+            const chain = await this.chain(scope, 'listRoleScopes');
+            if (!chain)
+                continue;
+            const keys = chainKeysFrom(chain)[0];
+            if (bindings.some((b) => this.declaredRole(catalog, b, keys)))
+                known.push(scope);
+        }
+        return known;
     }
     async listScopes(subject, permission) {
-        const perm = await this.findPermission(permission);
+        assertIdentity({ subject, permission });
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
         if (!perm)
             return [];
-        const granting = await this.rolesGranting(perm.uuid);
-        // Denies del subject para este permiso (una sola consulta).
-        const denyResponse = await this.client.listObjects({
-            user: this.fgaSubject(subject),
-            relation: 'denied',
-            type: 'deny_binding',
-        });
-        const deniedKeys = new Set((denyResponse.objects ?? [])
-            .map((obj) => obj.replace(/^deny_binding:/, ''))
-            .map((id) => parseBindingId(id))
-            .filter((p) => Boolean(p && p.slug === permission))
-            .map((p) => scopeKey(p.scope)));
+        const granting = catalog.rolesGranting(perm.uuid);
+        // Denies directos del subject para este permiso: TODOS, paginando. Con
+        // `ListObjects` el tope del servidor se consumía con los denies de
+        // cualquier permiso y el relevante podía quedar fuera: fail-open (L0.7).
+        // Las dos lecturas filtran la caducidad con el MISMO instante (K9).
+        const at = this.now();
+        const deniedKeys = await this.deniedScopeKeys(subject, perm.uuid, at);
         const result = new Map();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (!parsed)
+        for (const binding of await this.listBindings(subject, at)) {
+            const role = (granting.get(binding.scope.type) ?? []).find((r) => r.uuid === binding.uuid);
+            if (!role)
                 continue;
-            if (!(granting.get(parsed.scope.type) ?? []).includes(parsed.slug))
+            // Un scope que el árbol ya no conoce no concede: no se lista. Y el rol
+            // tiene que existir ahí (3B · B2: global u owner en la cadena).
+            const chain = await this.chain(binding.scope, 'listScopes');
+            if (!chain)
+                continue;
+            if (!isRoleVisibleWith(role, chainKeysFrom(chain)[0]))
                 continue;
-            const chain = await this.chain(parsed.scope);
             const blocked = chain.some((s) => deniedKeys.has(scopeKey(s)));
             if (!blocked)
-                result.set(scopeKey(parsed.scope), parsed.scope);
+                result.set(scopeKey(binding.scope), binding.scope);
         }
         return [...result.values()];
     }
+    /**
+     * Denies directos del holder (2.1, B5): `Read` paginado de sus
+     * `deny_binding` (nunca ListObjects, L0.7), filtrados por el catálogo (un
+     * permiso retirado no es un deny, D5), por scope exacto si se pide, y por
+     * scopes que el árbol conoce (D8).
+     */
+    async listDenies(subject, scope) {
+        assertIdentity(scope ? { subject, scope } : { subject });
+        const chain = scope ? await this.chain(scope, 'listDenies') : null;
+        if (scope && !chain)
+            return [];
+        const wanted = chain ? scopeKey(chain[0]) : null;
+        const view = await this.catalog.view();
+        const tuples = await this.readAllTuples({
+            user: this.fgaSubject(subject),
+            relation: 'denied',
+            object: 'deny_binding:',
+        });
+        const result = [];
+        for (const binding of this.parseBindings('deny_binding', tuples.map((t) => t.object))) {
+            const permission = view.permissionSlug(binding.uuid);
+            if (!permission)
+                continue;
+            if (wanted !== null) {
+                if (scopeKey(binding.scope) !== wanted)
+                    continue;
+            }
+            else if (!(await this.chain(binding.scope, 'listDenies'))) {
+                continue;
+            }
+            result.push({ permission, scope: binding.scope });
+        }
+        return result;
+    }
+    /**
+     * Purga del scope exacto en FGA (N7, S6, B2). No hay "borrar todo lo de
+     * este objeto": se leen por objeto EXACTO los bindings posibles — un
+     * `role_binding` por cada rol del catálogo de ese `scope_type` y un
+     * `deny_binding` por cada permiso — paginando `Read` (nunca ListObjects:
+     * trunca sin avisar, L0.7), se borra en lotes ≤ 100 (límite del Write) y
+     * se vuelve a leer cada objeto: si queda algo, se lanza. Un rol retirado
+     * del catálogo deja bindings inalcanzables por esta vía; es el precio de no
+     * tener un índice por objeto, y lo vigilará `authz:reconcile` (3b).
+     */
+    async purgeScope(purged) {
+        assertScope(purged);
+        if (purged.type === APP_SCOPE_TYPE) {
+            throw new InvalidIdentityError('purgeScope: la raíz `app` no se purga');
+        }
+        // La identidad canónica si el árbol aún lo conoce (K1); tal cual si ya no.
+        const scope = await this.canonicalOrSelf(purged, 'purgeScope');
+        const key = scopeKey(scope);
+        const roles = await this.sql('purgeScope.roles', () => db.from('authz_roles').where('scope_type', scope.type).select('uuid'));
+        const permissions = await this.sql('purgeScope.permissions', () => db.from('authz_permissions').select('uuid'));
+        const objects = [
+            ...roles.map((r) => `role_binding:${key}|${r.uuid}`),
+            ...permissions.map((p) => `deny_binding:${key}|${p.uuid}`),
+        ];
+        for (const object of objects) {
+            const keys = await this.readAllTuples({ object }, { includeExpired: true });
+            for (let i = 0; i < keys.length; i += PURGE_BATCH_SIZE) {
+                await this.client.deleteTuples(keys.slice(i, i + PURGE_BATCH_SIZE), {
+                    conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
+                });
+            }
+        }
+        // Demostrar cero: lo que no se puede demostrar, se reporta.
+        const residue = [];
+        for (const object of objects) {
+            const left = await this.readAllTuples({ object }, { includeExpired: true });
+            if (left.length)
+                residue.push(`${object} (${left.length})`);
+        }
+        if (residue.length) {
+            throw new PurgeIncompleteError(`purgeScope ${key}: quedan tuplas tras el borrado — ${residue.join('; ')}. ` +
+                `No confirmes el borrado del scope; reintenta la purga.`);
+        }
+    }
+    // `purgeRole` NO existe en este driver (3B · B4, capacidad `purgeRole:
+    // false`): los bindings de un rol viven en objetos
+    // `role_binding:<scopeKey>|<roleUuid>` de scopes que el driver no puede
+    // enumerar por rol sin leer el store entero (`Read` filtra por prefijo de
+    // objeto, no por sufijo). Borrar la fila del catálogo sin sus tuplas
+    // dejaría hechos huérfanos que resucitarían al recrear el slug.
+    //
+    // Hasta 3E el método existía y lanzaba 500 al LLAMARLO, y eso era el
+    // callejón que encontró el code-review (3E · P4): `defineScopedRole`
+    // escribía el rol tan tranquilo y después nada podía borrarlo — ni
+    // `deleteScopedRole` ni `scopes.detached` de ese scope, para siempre.
+    // Desde 3E el método es OPCIONAL en el puerto (Q4) y NO declararlo es la
+    // forma de decir «no sé purgar»: el manager lo comprueba ANTES de escribir
+    // (500 `E_AUTHZ_UNSUPPORTED` nombrándolo). Llega con 3b (`facts` +
+    // `authz:reconcile`).
+    /**
+     * TODAS las tuplas que casan con el filtro, paginando `Read` hasta agotar
+     * el `continuation_token`, sin las caducadas. Es la única primitiva de
+     * enumeración del driver (L0.7): `Read` no tiene tope de resultados —a
+     * diferencia de `ListObjects`/`ListUsers`, que cortan al máximo del
+     * servidor sin ninguna señal— y devuelve la condición de cada tupla, así
+     * que la caducidad se filtra aquí con el mismo reloj que `checkContext`.
+     *
+     * Contrapartida, documentada en el README: `Read` devuelve tuplas
+     * ESCRITAS, no relaciones computadas. Con el modelo que genera este paquete
+     * (`assignee`/`denied` directas) es exactamente lo mismo; un modelo
+     * extendido con relaciones derivadas sobre `role_binding` no se enumeraría
+     * por aquí.
+     */
+    async readAllTuples(filter, options = {}) {
+        // El instante con el que se filtra: el de la operación si lo trae (K9), o
+        // el de esta lectura.
+        const now = options.at ?? this.now();
+        const keys = [];
+        let continuationToken;
+        const seenTokens = new Set();
+        let pages = 0;
+        do {
+            const response = await this.client.read(filter, {
+                pageSize: READ_PAGE_SIZE,
+                continuationToken,
+                consistency: this.consistency,
+            });
+            pages += 1;
+            for (const tuple of response.tuples ?? []) {
+                const k = tuple?.key;
+                if (!k?.user || !k?.relation || !k?.object) {
+                    // Una tupla que el motor no puede leer es un hecho que las
+                    // enumeraciones NO muestran: se cuenta y se registra (L0.16, H16).
+                    this.diagnostics.unparseableBindings += 1;
+                    this.warn(`authz(openfga): tupla malformada en Read ${JSON.stringify(filter)} (${JSON.stringify(k ?? null)}); se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+                    continue;
+                }
+                if (!options.includeExpired) {
+                    const validUntil = toExpiryDate(k.condition?.context?.valid_until);
+                    if (validUntil && validUntil <= now)
+                        continue;
+                }
+                keys.push({ user: k.user, relation: k.relation, object: k.object });
+            }
+            continuationToken = response.continuation_token || undefined;
+            if (continuationToken) {
+                if (seenTokens.has(continuationToken)) {
+                    throw new AuthorizationInternalError(`Read ${JSON.stringify(filter)}: el continuation_token se repite (página ${pages}); el servidor no avanza`);
+                }
+                if (pages >= MAX_READ_PAGES) {
+                    throw new AuthorizationInternalError(`Read ${JSON.stringify(filter)}: más de ${MAX_READ_PAGES} páginas sin agotar el continuation_token`);
+                }
+                seenTokens.add(continuationToken);
+            }
+        } while (continuationToken);
+        return keys;
+    }
 }
 //# sourceMappingURL=openfga_driver.js.map