@jantstack/adonis-authz 2.5.0-alpha.3 → 2.5.0-rc.1

package/build/src/drivers/database_driver.js

@@ -1,7 +1,7 @@
 import db from '@adonisjs/lucid/services/db';
 import { v7 as uuidv7 } from 'uuid';
 import { APP_SCOPE_TYPE } from '../types.js';
-import { assertCatalogUuid, assertIdentity, assertScope, chainKeysFrom, normalizeRoleQuery } from '../identity.js';
+import { assertCatalogUuid, assertIdentity, assertScope, assertSnapshotReads, chainKeysFrom, normalizeRoleQuery } from '../identity.js';
 import { resolveGrantExpiry, sameInstant } from '../expiry.js';
 import { AuthorizationBackendError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, MassReconcileRefusedError, ReconcileTooLargeError, RoleNotVisibleError, UnknownPermissionError, UnknownRoleError, UnsupportedOperationError, WriteConflictError, } from '../errors.js';
 import { RECONCILE_MAX_DETAILS, emptyReconcilePhases, reconcileBatchSize, reconcileMaxTuples, sumReconcilePhases, } from '../reconcile.js';
@@ -243,6 +243,12 @@ export function whereScopeIn(query, column, scopes, intent) {
         }
     });
 }
+/**
+ * Las partes posibles de la FOTO de una decisión (rotación 2 · cierre 3, `readFoto`): `grant` = asignaciones que
+ * conceden UN permiso (con el vínculo rol→permiso por `JOIN`), `role` = asignaciones sin filtrar por permiso
+ * (`rolesInChain`) y `deny` = denies. El literal de `foto_kind` sale de esta tabla CERRADA, jamás de un dato.
+ */
+const FOTO_KINDS = { grant: 'grant', deny: 'deny', role: 'role' };
 export const DEFAULT_TIMEOUT_MS = 5_000;
 /**
  * Driver `database`: motor de autorización propio sobre las tablas `authz_*`.
@@ -262,7 +268,7 @@ export class DatabaseAuthorizationDriver {
     /**
      * Lo que este driver declara (3b-2e · E2). El árbol es del consumidor
      * (`resolveChain`), así que no hay hechos de jerarquía ni deriva que
-     * mitigar; `authorize` son varias consultas SQL; la membresía la resuelve
+     * mitigar; `authorize` es UNA consulta SQL de hechos (la foto, rotación 2 · cierre 3) más el catálogo y el árbol, no un `Check`; la membresía la resuelve
      * el propio SQL contra la cadena que le pasan; los `list*` no enumeran
      * herencia (invariante 7); y `purgeRole` está implementado en una
      * transacción.
@@ -327,12 +333,27 @@ export class DatabaseAuthorizationDriver {
             // `resolveChain` y la barrera del freeze (autoridad). Un despliegue con
             // pool 1 lo declara `false` (ver `DatabaseDriverOptions`).
             transactionalWrites: this.transactionalWrites,
+            // Estrategia 2.5.0 · firma 4 (D15): `false` EXPLÍCITO — `database` es el driver ESTABLE de 2.5.0 (el experimental
+            // es `openfga`). Explícito para que la copia de `authorization.capabilities()` y este objeto digan lo mismo.
+            experimental: false,
+            // Rotación 2 · cierre 3 (D15, L12): toda decisión que combina concesión y deny se lee en UNA sentencia
+            // (`readFoto`), y `readSnapshot` da esa foto a las composiciones del manager.
+            snapshotDecisions: true,
         });
         assertCatalogOptions('DatabaseAuthorizationDriver', options);
         this.catalog =
             options.catalog ??
                 new CatalogCache({ driver: 'database', timeoutMs: this.timeoutMs, revalidate: options.catalogRevalidate });
     }
+    /**
+     * **El catálogo de una ESCRITURA** (K4; asentar · cierre 2, D-1): con la versión contrastada en fresco SIEMPRE
+     * (`CatalogCache.freshView`), ignore o no la ventana `{ everyMs }`. Un `catalog` inyectado que no lo traiga cae en
+     * `view()` (el contrato del memo es suyo). Gemelo de `OpenFgaAuthorizationDriver.writeCatalog`.
+     */
+    writeCatalog() {
+        const catalog = this.catalog;
+        return typeof catalog.freshView === 'function' ? catalog.freshView() : catalog.view();
+    }
     /**
      * Vista de este driver con OTRO resolutor de la cadena y el mismo estado
      * (conexión, memo del catálogo, deadline). Es lo que usa
@@ -395,6 +416,54 @@ export class DatabaseAuthorizationDriver {
         const rows = await this.sql(operation, () => fn().limit(1));
         return rows[0] ?? null;
     }
+    /**
+     * **La FOTO de una decisión: el punto de paso ÚNICO** (rotación 2 · cierre 3; 4.ª aparición del linaje L12 «lector
+     * rasgado», la primera en `database`). Propiedad universal: *toda DECISIÓN de `database` que combina concesión y deny
+     * se lee en UNA foto*. Hasta aquí `authorize` leía los denies y las asignaciones en DOS sentencias, y una escritura
+     * que caía entre las dos daba una respuesta que NINGÚN estado real daba (un `deny` y después un `grant` ⇒ `true` una
+     * vez; repro `.claude/reproducciones/database-authorize-rasgado.spec.ts`).
+     *
+     * La foto es **UNA sentencia**: las partes van unidas con `UNION ALL` y cada fila dice de qué parte es
+     * (`foto_kind`). Una sentencia ve UN estado en los tres motores y en cualquier aislamiento —PostgreSQL toma la foto
+     * por SENTENCIA en READ COMMITTED, InnoDB una vista de lectura por sentencia, SQLite una transacción de lectura
+     * implícita—, así que no hace falta abrir una transacción REPEATABLE READ como `withSourceSnapshot` del reconcile:
+     * eso costaría BEGIN/COMMIT por pregunta en el camino caliente y, con un pool de 1 (`:memory:`), retendría la única
+     * conexión mientras el catálogo o un `resolveChain` SQL del consumidor esperan otra. Elegido por eso: una ida y
+     * vuelta (antes dos), sin conexión retenida y sin nivel por motor.
+     *
+     * Lo que va DENTRO de la foto: los HECHOS (asignaciones —con el vínculo rol→permiso por `JOIN` cuando la parte lo
+     * filtra— y denies). Lo que va FUERA, antes o después: el catálogo (memo contrastado con la versión compartida,
+     * invariante 14) y la cadena del consumidor (`resolveChain`). «Cadena frente a hechos» (un `scopes.moved` entre el
+     * `resolveChain` y la foto) depende del resolutor del consumidor y está DECLARADO en README «Limits» (fila «Torn
+     * read»), no se arregla aquí.
+     *
+     * Columnas comunes de cada parte: `foto_kind`, `foto_scope_type`, `foto_scope_uuid`, `foto_role` y
+     * `foto_permission` (`null` en la parte que no la tiene). Solo SQL estándar del query builder (M6). Una sola parte
+     * es una sola `SELECT`, sin `UNION`. La guardia `database.decision.snapshot` cuenta las sentencias que tocan
+     * `authz_assignments`/`authz_denies` por decisión: con dos, rojo.
+     */
+    async readFoto(operation, parts) {
+        const foto = { grant: [], deny: [], role: [] };
+        const live = parts.filter((part) => part !== null);
+        if (live.length === 0)
+            return foto;
+        const selects = live.map((part) => part.query.select(db.raw(`'${FOTO_KINDS[part.kind]}' as foto_kind`), `${part.scope}_type as foto_scope_type`, `${part.scope}_uuid as foto_scope_uuid`, part.role ? `${part.role} as foto_role` : db.raw('null as foto_role'), part.permission ? `${part.permission} as foto_permission` : db.raw('null as foto_permission')));
+        const [head, ...rest] = selects;
+        const rows = await this.sql(operation, () => (rest.length ? head.unionAll(rest) : head));
+        for (const row of rows) {
+            const kind = row.foto_kind;
+            if (!(kind in foto)) {
+                throw new AuthorizationInternalError(`database.${operation}: la foto devolvió una fila de una parte desconocida (${String(kind)})`);
+            }
+            foto[kind].push({
+                scope_type: row.foto_scope_type,
+                scope_uuid: row.foto_scope_uuid,
+                role_uuid: row.foto_role ?? null,
+                permission_uuid: row.foto_permission ?? null,
+            });
+        }
+        return foto;
+    }
     /**
      * Por dónde escribe `operation` (L-3): la transacción ABIERTA del llamante
      * si llegó en `options.transaction` —validada contra la conexión de este
@@ -499,8 +568,6 @@ export class DatabaseAuthorizationDriver {
             .where('permission_uuid', perm.uuid), 'scope', chain, 'read');
         if (!deniedQuery)
             return false;
-        if (await this.first('authorize.denies', () => deniedQuery))
-            return false;
         // Una asignación vigente, en la cadena, cuyo rol concede el permiso Y es
         // visible en su nivel (global u owner ancestro-o-igual del scope de la
         // asignación, 3B · B2). `assignableAt`/`rank` no entran: composición.
@@ -513,8 +580,13 @@ export class DatabaseAuthorizationDriver {
             .where('a.holder_uuid', subject.uuid), chain);
         if (!grantedQuery)
             return false;
-        const granted = await this.first('authorize.assignments', () => this.whereActive(grantedQuery, 'a.expires_at'));
-        return Boolean(granted);
+        // Los denies y las asignaciones en UNA foto (rotación 2 · cierre 3, L12): deny en la cadena ⇒ false; si no, una
+        // asignación vigente que concede ⇒ true. Nunca dos sentencias: ver `readFoto`.
+        const foto = await this.readFoto('authorize', [
+            { kind: 'deny', query: deniedQuery, scope: 'scope', permission: 'permission_uuid' },
+            { kind: 'grant', query: this.whereActive(grantedQuery, 'a.expires_at'), scope: 'a.scope', role: 'a.role_uuid' },
+        ]);
+        return foto.deny.length === 0 && foto.grant.length > 0;
     }
     async grant(subject, role, scope, options = {}) {
         assertIdentity({ subject, role, scope, expiresAt: options.expiresAt });
@@ -610,7 +682,11 @@ export class DatabaseAuthorizationDriver {
         // a lo sumo uno es visible ahí y los demás serían filas huérfanas; el
         // scope puede no existir ya para el árbol (D8), así que no se filtra por
         // visibilidad — quitar nunca concede.
-        const named = rolesToRevoke(await this.catalog.view(), role, scope);
+        // Asentar · cierre 2 (D-1 del re-ataque; gemelo del 🟡 5 de `openfga`, K4): el catálogo de una ESCRITURA, con la
+        // versión en fresco. Con el memo de `{ everyMs }` un local recién definido en otro proceso que ensombrece al global
+        // no salía en `rolesToRevoke`: el DELETE no tocaba su fila y la asignación local seguía concediendo (un «revocado»
+        // falso, mudo y persistente).
+        const named = rolesToRevoke(await this.writeCatalog(), role, scope);
         // Sin cadena con la que canonizar, TODAS las ortografías de las que el
         // uuid puede ser alias (3b-8 · A4, mismo fan-out que `scopes.detached`):
         // con una sola, un alias hacía del DELETE un no-op silencioso y la fila
@@ -768,13 +844,21 @@ export class DatabaseAuthorizationDriver {
         assertIdentity({ subject });
         for (const scope of chain)
             assertScope(scope);
+        const foto = await this.readFoto('rolesInChain', [this.rolesInChainPart(subject, chain)]);
+        return this.rolesInChainFrom(foto.role, chain);
+    }
+    /** La parte de la foto de `rolesInChain`: asignaciones vigentes del holder en los scopes de la cadena (`null` sin cadena). */
+    rolesInChainPart(subject, chain) {
         const query = whereScopeIn(db
             .from('authz_assignments as a')
             .where('a.holder_type', subject.type)
             .where('a.holder_uuid', subject.uuid), 'a.scope', chain, 'read');
         if (!query)
-            return [];
-        const rows = await this.sql('rolesInChain', () => this.whereActive(query, 'a.expires_at').distinct('a.scope_type', 'a.scope_uuid', 'a.role_uuid'));
+            return null;
+        return { kind: 'role', query: this.whereActive(query, 'a.expires_at'), scope: 'a.scope', role: 'a.role_uuid' };
+    }
+    /** De las filas de la foto a la respuesta de `rolesInChain` (catálogo DESPUÉS de la foto: es memo, no hechos). */
+    async rolesInChainFrom(rows, chain) {
         const catalog = await this.catalog.view();
         const keysFrom = chainKeysFrom(chain);
         const levelOf = new Map(chain.map((s, i) => [dbScopeKey(s), i]));
@@ -837,25 +921,38 @@ export class DatabaseAuthorizationDriver {
         const perm = await this.findPermission(permission);
         if (!perm)
             return [];
-        const rows = await this.sql('listScopes.assignments', () => this.whereActive(db
+        // Las asignaciones que conceden y los denies del permiso en UNA foto (rotación 2 · cierre 3, L12): antes eran dos
+        // sentencias y un offboarding (revoke, luego removeDeny) entre ellas listaba un scope que ningún estado concedía.
+        const foto = await this.readFoto('listScopes', [this.grantsOfPart(subject, perm.uuid), this.deniesPart(subject, perm.uuid)]);
+        return this.listScopesFrom(foto.grant, foto.deny);
+    }
+    /** La parte «asignaciones vigentes del holder cuyo rol concede el permiso», en todo scope (la de `listScopes`). */
+    grantsOfPart(subject, permissionUuid) {
+        const query = this.whereActive(db
             .from('authz_assignments as a')
             .join('authz_role_permissions as rp', 'rp.role_uuid', 'a.role_uuid')
-            .where('rp.permission_uuid', perm.uuid)
+            .where('rp.permission_uuid', permissionUuid)
             .where('a.holder_type', subject.type)
-            .where('a.holder_uuid', subject.uuid), 'a.expires_at').distinct('a.scope_type', 'a.scope_uuid', 'a.role_uuid'));
-        const denies = await this.sql('listScopes.denies', () => db
-            .from('authz_denies')
-            .where('holder_type', subject.type)
-            .where('holder_uuid', subject.uuid)
-            .where('permission_uuid', perm.uuid)
-            .select('scope_type', 'scope_uuid'));
+            .where('a.holder_uuid', subject.uuid), 'a.expires_at');
+        return { kind: 'grant', query, scope: 'a.scope', role: 'a.role_uuid', permission: 'rp.permission_uuid' };
+    }
+    /** La parte «denies del holder» (de UN permiso si se da; si no, todos), en todo scope. */
+    deniesPart(subject, permissionUuid) {
+        const query = db.from('authz_denies').where('holder_type', subject.type).where('holder_uuid', subject.uuid);
+        if (permissionUuid !== undefined)
+            query.where('permission_uuid', permissionUuid);
+        return { kind: 'deny', query, scope: 'scope', permission: 'permission_uuid' };
+    }
+    /**
+     * De la foto a la respuesta de `listScopes` (árbol y catálogo DESPUÉS de la foto). `denies` son los del permiso: por
+     * scope, el conjunto de roles que conceden; el scope se lista si el árbol lo conoce, alguno de esos roles existe ahí
+     * (3B · B2) y ningún deny de la cadena lo bloquea — exactamente lo que `authorize` diría.
+     */
+    async listScopesFrom(grants, denies) {
         const deniedKeys = new Set(denies.map((d) => `${d.scope_type}:${fromDbScopeUuid(d.scope_uuid) ?? ''}`));
-        // Por scope: el conjunto de roles que conceden; el scope se lista si el
-        // árbol lo conoce, alguno de esos roles existe ahí (3B · B2) y ningún
-        // deny de la cadena lo bloquea — exactamente lo que `authorize` diría.
         const catalog = await this.catalog.view();
         const byScope = new Map();
-        for (const row of rows) {
+        for (const row of grants) {
             const k = rowScopeKey(row);
             if (!byScope.has(k))
                 byScope.set(k, { scope: { type: row.scope_type, uuid: fromDbScopeUuid(row.scope_uuid) }, roles: [] });
@@ -894,7 +991,11 @@ export class DatabaseAuthorizationDriver {
         const query = chain ? whereScopeIn(base, 'scope', [chain[0]], 'read') : base;
         if (!query)
             return [];
-        const rows = await this.sql('listDenies', () => query.select('permission_uuid', 'scope_type', 'scope_uuid'));
+        const foto = await this.readFoto('listDenies', [{ kind: 'deny', query, scope: 'scope', permission: 'permission_uuid' }]);
+        return this.deniesFrom(foto.deny, scope === undefined);
+    }
+    /** De las filas de denies a `DenyRef[]` (catálogo y, sin `scope` pedido, árbol DESPUÉS de la foto). */
+    async deniesFrom(rows, resolveEach) {
         const view = await this.catalog.view();
         const result = [];
         for (const row of rows) {
@@ -902,12 +1003,42 @@ export class DatabaseAuthorizationDriver {
             if (!permission)
                 continue;
             const denyScope = { type: row.scope_type, uuid: fromDbScopeUuid(row.scope_uuid) };
-            if (!scope && !(await this.chain(denyScope, 'listDenies')))
+            if (resolveEach && !(await this.chain(denyScope, 'listDenies')))
                 continue;
             result.push({ permission, scope: denyScope });
         }
         return result;
     }
+    /**
+     * **Varias lecturas del puerto en UNA foto** (rotación 2 · cierre 3, L12; método OPCIONAL del puerto,
+     * `AuthorizationDriver.readSnapshot`, capacidad `snapshotDecisions`). Es lo que el manager usa para las decisiones
+     * que COMPONE con dos métodos del puerto —`effectivePermissions` y la policy de delegación (`rolesInChain` +
+     * `listDenies`), `authorizedScopes` (`listScopes` + `listDenies`)—: cada respuesta pedida es EXACTAMENTE la del método
+     * homónimo, y todas salen de la MISMA foto de los hechos (`readFoto`: una sentencia). Lo no pedido no viene.
+     * Árbol y catálogo se leen después de la foto, como en cada método suelto.
+     */
+    async readSnapshot(subject, reads) {
+        assertIdentity({ subject });
+        const asked = assertSnapshotReads(reads);
+        const chain = asked.rolesInChain;
+        const perm = asked.listScopes !== undefined ? await this.findPermission(asked.listScopes) : null;
+        // Los denies: todos si se pidió `listDenies`; si solo hace falta para `listScopes`, los de ese permiso.
+        const wantsDenies = asked.listDenies === true || perm !== null;
+        const foto = await this.readFoto('readSnapshot', [
+            chain ? this.rolesInChainPart(subject, chain) : null,
+            perm ? this.grantsOfPart(subject, perm.uuid) : null,
+            wantsDenies ? this.deniesPart(subject, asked.listDenies === true ? undefined : perm.uuid) : null,
+        ]);
+        const answer = {};
+        if (chain)
+            answer.rolesInChain = await this.rolesInChainFrom(foto.role, chain);
+        if (asked.listScopes !== undefined) {
+            answer.listScopes = perm ? await this.listScopesFrom(foto.grant, foto.deny.filter((d) => d.permission_uuid === perm.uuid)) : [];
+        }
+        if (asked.listDenies === true)
+            answer.listDenies = await this.deniesFrom(foto.deny, true);
+        return answer;
+    }
     /**
      * Borra asignaciones y denies del scope exacto, en una transacción. Si el
      * árbol aún lo conoce se purga su identidad canónica (K1); si ya no (el
@@ -1141,6 +1272,11 @@ export class DatabaseAuthorizationDriver {
                     scope_type: target.type,
                     scope_uuid: toDbScopeUuid(target),
                 };
+                // Cierre-2 de L11 (C1): un deny que el origen guarda con una condición ajena se migra como deny (fail-closed:
+                // perderlo concedería) pero se DECLARA: `invalid-condition` es deriva y el operador decide.
+                if (fact.invalidCondition !== undefined) {
+                    note('deny', 'invalid-condition', `${fact.detail} (${fact.invalidCondition})`);
+                }
                 usableFacts += 1;
                 const denyId = denyKey(row);
                 if (wantedDenies.has(denyId))
@@ -1309,4 +1445,3 @@ export class DatabaseAuthorizationDriver {
         }
     }
 }
-//# sourceMappingURL=database_driver.js.map

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

@@ -88,6 +88,13 @@ export declare class DatabaseRelationsDriver implements RelationsDriver {
     deny(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationDenyOptions): Promise<void>;
     /** `removeDeny`: borra la tupla `denied_<rel>`. Sobre CUALQUIER tipo declarado (D8/R2-4 b). No-op si no está. */
     removeDeny(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationDenyOptions): Promise<void>;
+    /**
+     * **El techo de anidación de grupos de ESTE driver** (lote «antes de RC» · R1, decisión del dueño 2026-10-17 (5)):
+     * `database` no tiene techo técnico (la CTE deduplica y termina con ciclos), así que es `null` SALVO el opt-in
+     * explícito `database.enforceGroupDepth: true`, que aplica el `maxGroupDepth` de la config (obligatorio y numérico
+     * con el opt-in: lo valida `defineRelationsConfig` al arrancar).
+     */
+    groupDepthLimit(): Promise<number | null>;
     unrelate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
     /**
      * **F-05 en las LECTURAS y las PURGAS del driver** (2.4.0-alpha.3, cierre
@@ -117,14 +124,14 @@ export declare class DatabaseRelationsDriver implements RelationsDriver {
      * misma función que el doble y `openfga` cuando alinea su `batchCheck`). Tope, `[]` y F-05 por ítem como `checkMany`.
      */
     decideMany(subject: RelSubject, relation: string, objects: RelObject[], partition: ScopeRef): Promise<RelationDecision[]>;
-    listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef, _page?: RelationPage): Promise<RelationObjectsPage>;
-    listSubjects(relation: string, object: RelObject, partition: ScopeRef, _page?: RelationPage): Promise<RelationSubjectsPage>;
+    listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef): Promise<RelationObjectsPage>;
+    listSubjects(relation: string, object: RelObject, partition: ScopeRef): Promise<RelationSubjectsPage>;
     /**
      * **`listDenies`** (lote D · D1): los sujetos con deny DIRECTO de `relation` sobre `object` —hechos, como
      * `listSubjects` sobre la relación almacenada `denied_<rel>`; no resta ni deriva—. Sobre CUALQUIER tipo declarado
      * (D8/R2-4 b: con el opt-in retirado, los denies vivos se siguen pudiendo listar y borrar).
      */
-    listDenies(relation: string, object: RelObject, partition: ScopeRef, page?: RelationPage): Promise<RelationSubjectsPage>;
+    listDenies(relation: string, object: RelObject, partition: ScopeRef): Promise<RelationSubjectsPage>;
     /**
      * **`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 (`'write'`, `'read'` o `null`). F-05 estricto del par (422), cero sentencias: es
@@ -140,7 +147,7 @@ export declare class DatabaseRelationsDriver implements RelationsDriver {
      * directos): en un grupo con `member(g1#member, g2)`, `membersOf(g2)` trae a
      * los holders de g1 y `listSubjects(member, g2)` solo el userset `g1#member`.
      */
-    membersOf(object: RelObject, relation: string, partition: ScopeRef, _page?: RelationPage): Promise<RelationSubjectsPage>;
+    membersOf(object: RelObject, relation: string, partition: ScopeRef): Promise<RelationSubjectsPage>;
     purgeObject(object: RelObject, partition: ScopeRef, options?: RelationTransactionOptions): Promise<void>;
     purgeSubject(subject: RelSubject, partition: ScopeRef, options?: RelationTransactionOptions): Promise<void>;
     /**
@@ -184,4 +191,3 @@ export declare class DatabaseRelationsDriver implements RelationsDriver {
      */
     enumerateRelationsMany(partitions: ScopeRef[], page?: RelationPage): Promise<RelationTuplePage>;
 }
-//# sourceMappingURL=database_relations_driver.d.ts.map