@jantstack/adonis-authz 2.4.0-alpha.1 → 2.4.0-alpha.10

package/build/src/testing/contract.js

@@ -7,6 +7,26 @@ import db from '@adonisjs/lucid/services/db';
 import { CatalogCache, GLOBAL_OWNER_KEY, withAuthzCatalogWrite } from '../catalog/catalog_cache.js';
 import { scopeKey } from '../identity.js';
 import { descendantsFrom, memoryScopeTree, resolveChainFrom } from './scope_tree.js';
+/** El default de `DriverContractHarness.transactions`: Lucid + `authz_*`. */
+export function lucidContractTransactions() {
+    const count = async (table, subject) => {
+        const rows = await db
+            .from(table)
+            .where('holder_type', subject.type)
+            .where('holder_uuid', subject.uuid)
+            .count('* as n');
+        return Number(rows[0]?.n ?? 0);
+    };
+    return {
+        async begin() {
+            const trx = await db.transaction();
+            return { client: trx, commit: () => trx.commit(), rollback: () => trx.rollback() };
+        },
+        async census(subject) {
+            return { assignments: await count('authz_assignments', subject), denies: await count('authz_denies', subject) };
+        },
+    };
+}
 /**
  * Catálogo de prueba: roles a nivel app y a nivel organization. Los dos
  * últimos existen solo para el invariante 8: `rank` es metadata y el motor no
@@ -1689,8 +1709,9 @@ export function registerAuthorizationDriverContract(harness, api) {
             }
         });
         // ── Concurrencia (2.5 · J4) ──────────────────────────────────────────
-        // Sin `{trx}` en el puerto (`transactions: false` sigue; es el diferido
-        // 2.6): lo que se fija es que dos escrituras solapadas nunca dejan un
+        // Sin `{trx}` en estos casos (la escritura en la transacción del
+        // llamante tiene su par, `transactionalWrites`, abajo): lo que se fija
+        // es que dos escrituras solapadas nunca dejan un
         // estado que ninguna de las dos habría dejado sola. Con el harness en
         // memoria (pool 1) se solapan a nivel de consulta; con `sqlite-file`, PG
         // y MySQL (pool ≥ 2) a nivel de conexión.
@@ -2223,7 +2244,10 @@ export function registerAuthorizationDriverContract(harness, api) {
                     await driver.grant(alice, 'propio', unitA1);
                     await driver.grant(alice, 'nieto', unitA1x);
                     assert.isTrue(await driver.authorize(alice, 'docs:write', unitA1));
-                    assert.isUndefined(await authz.scopes.detached(unitA1), 'no devuelve nada que declarar a medias');
+                    // Desde 2.4.0-alpha.5 `scopes.*` devuelven el RECIBO del encolado
+                    // (`{ queued }`); sin outbox, `{ queued: [] }` = aplicado en línea. Lo
+                    // que Z1 fija —ningún contador de lo purgado a medias— sigue en pie.
+                    assert.deepEqual(await authz.scopes.detached(unitA1), { queued: [] }, 'no devuelve nada que declarar a medias: el recibo vacío no es un contador de lo purgado');
                     assert.deepEqual(await driver.listRoles(alice, unitA1), [], 'los HECHOS del scope, purgados');
                     assert.isFalse(await driver.authorize(alice, 'docs:write', unitA1));
                     const view = await new CatalogCache().view();
@@ -3255,9 +3279,201 @@ export function registerAuthorizationDriverContract(harness, api) {
         // `hierarchyFacts: false` → lo observan N1b/N2/N4/N5 (arriba): el driver
         // responde según el árbol que le resuelve el consumidor, y `tree.move`
         // cambia la respuesta sin escritura. `true` llega en Fase 3b.
-        // `injectableClock` tiene su par arriba (2.5 · J1). `transactions` (2.6)
-        // y `singleCheckAuthorize` (Fase 3b): pares en su fase; hoy solo pueden
-        // declararse `false`.
+        // `injectableClock` tiene su par arriba (2.5 · J1). `transactionalWrites`
+        // (L-2) tiene su par al final: la cara `false` hoy, la `true` con L-3.
+        // ── L-2 · `transactionalWrites` (panel `{trx}`, (C)) ──────────────────
+        // Las DOS caras son obligatorias en este par (`BOTH_FACES_REQUIRED`): una
+        // `whenFalse` ausente se saltaba en silencio y «rechazo activo» sería
+        // una etiqueta. Lo que la cara `false` fija es la PUERTA 1 (por llamada,
+        // siempre activa) y la PUERTA 2 (por config, opt-in), las dos con el
+        // manager construido sobre el driver del harness, en TODOS los niveles:
+        // son composición del manager sobre `driver.capabilities`, así que un
+        // driver de terceros de nivel `core` también las observa.
+        caseFor('transactionalWrites', {
+            // L-3: la cara `true`. Lo que se juzga es «los dos o ninguno con TU
+            // transacción» POR CENSO: el rollback deja CERO filas nuevas (no solo
+            // `authorize` false — una respuesta puede salir bien con la fila viva),
+            // el commit las deja escritas, y mientras la transacción está abierta
+            // la autoridad (que lee por la conexión del motor) no ve nada. Y la
+            // otra mitad de la regla: una transacción que NO es la del driver no
+            // recibe ni una sentencia. Cuatro escrituras, las dos caras cada una.
+            whenTrue: () => {
+                test('transactionalWrites: true · grant/revoke/deny/removeDeny con { transaction } + rollback ⇒ authorize sin cambio Y CERO filas (censo); + commit ⇒ aplicado; una transacción ajena, un cliente sin transacción o el `db` entero ⇒ 500 E_AUTHZ_CONFIG sin UNA sentencia por ella', async ({ assert, }) => {
+                    assert.equal(driver.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: true y el driver no: declara lo observable');
+                    const tx = harness.transactions ?? lucidContractTransactions();
+                    const alice = subject();
+                    const org = await orgUnder(tree, APP_SCOPE);
+                    const authz = managerOver({});
+                    const can = () => driver.authorize(alice, 'docs:read', org);
+                    const census = () => tx.census(alice);
+                    // Una transacción que se queda abierta tras una aserción fallida
+                    // retiene una conexión del pool y arrastra a los casos siguientes:
+                    // el rollback va en `finally`, y el commit solo si nada falló.
+                    const rolledBack = async (fn) => {
+                        const t = await tx.begin();
+                        try {
+                            await fn(t.client);
+                        }
+                        finally {
+                            await t.rollback();
+                        }
+                    };
+                    const committed = async (fn) => {
+                        const t = await tx.begin();
+                        try {
+                            await fn(t.client);
+                        }
+                        catch (error) {
+                            await t.rollback();
+                            throw error;
+                        }
+                        await t.commit();
+                    };
+                    // grant: dentro no se ve desde fuera; rollback ⇒ nada; commit ⇒ concede.
+                    let seenInside;
+                    await rolledBack(async (transaction) => {
+                        await authz.grant(alice, 'org-editor', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 0, denies: 0 }, 'ROJO: la asignación sobrevivió al rollback (la escritura NO fue por la transacción del llamante)');
+                    assert.isFalse(await can(), 'grant + rollback ⇒ no concede');
+                    assert.isFalse(seenInside, 'la autoridad lee por la conexión del motor: el grant sin confirmar no concede');
+                    await committed(async (transaction) => {
+                        await authz.grant(alice, 'org-editor', org, { transaction });
+                    });
+                    assert.isTrue(await can(), 'grant + commit ⇒ concede');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 });
+                    // revoke: rollback ⇒ la asignación sigue; commit ⇒ se va.
+                    await rolledBack(async (transaction) => {
+                        await authz.revoke(alice, 'org-editor', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 }, 'ROJO: el revoke sobrevivió al rollback');
+                    assert.isTrue(await can(), 'revoke + rollback ⇒ sigue concediendo');
+                    assert.isTrue(seenInside, 'el revoke sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.revoke(alice, 'org-editor', org, { transaction });
+                    });
+                    assert.isFalse(await can(), 'revoke + commit ⇒ no concede');
+                    assert.deepEqual(await census(), { assignments: 0, denies: 0 });
+                    // deny (sobre un grant confirmado): rollback ⇒ sigue concediendo; commit ⇒ deniega.
+                    await authz.grant(alice, 'org-editor', org);
+                    await rolledBack(async (transaction) => {
+                        await authz.deny(alice, 'docs:read', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 }, 'ROJO: el deny sobrevivió al rollback');
+                    assert.isTrue(await can(), 'deny + rollback ⇒ sigue concediendo');
+                    assert.isTrue(seenInside, 'el deny sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.deny(alice, 'docs:read', org, { transaction });
+                    });
+                    assert.isFalse(await can(), 'deny + commit ⇒ deniega');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 1 });
+                    // removeDeny: rollback ⇒ el deny sigue; commit ⇒ restaura.
+                    await rolledBack(async (transaction) => {
+                        await authz.removeDeny(alice, 'docs:read', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 1 }, 'ROJO: el removeDeny sobrevivió al rollback');
+                    assert.isFalse(await can(), 'removeDeny + rollback ⇒ sigue denegando');
+                    assert.isFalse(seenInside, 'el removeDeny sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.removeDeny(alice, 'docs:read', org, { transaction });
+                    });
+                    assert.isTrue(await can(), 'removeDeny + commit ⇒ restaura');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 });
+                    // Una transacción que NO es la del driver (`assertCallerTransaction`):
+                    // 500 `E_AUTHZ_CONFIG` y ni una sentencia por ella (espía).
+                    const statements = [];
+                    const spy = (shape) => new Proxy(shape, {
+                        get(target, prop) {
+                            if (prop === 'from' || prop === 'table' || prop === 'raw' || prop === 'query' || prop === 'knexQuery') {
+                                return (...args) => {
+                                    statements.push(`${String(prop)}(${String(args[0] ?? '')})`);
+                                    return { where: () => ({}), select: async () => [], insert: async () => [], delete: async () => 0 };
+                                };
+                            }
+                            return Reflect.get(target, prop);
+                        },
+                    });
+                    const foreign = spy({ isTransaction: true, connectionName: `not-${harness.name}-${uuidv7()}` });
+                    const notATransaction = spy({ isTransaction: false, connectionName: 'primary' });
+                    const wholeDb = spy({ connection() { }, primaryConnectionName: 'primary' });
+                    const bob = subject();
+                    for (const [label, transaction] of [
+                        ['otra conexión', foreign],
+                        ['un cliente sin transacción', notATransaction],
+                        ['el db entero', wholeDb],
+                    ]) {
+                        for (const [operation, run] of [
+                            ['grant', () => authz.grant(bob, 'org-editor', org, { transaction })],
+                            ['revoke', () => authz.revoke(bob, 'org-editor', org, { transaction })],
+                            ['deny', () => authz.deny(bob, 'docs:read', org, { transaction })],
+                            ['removeDeny', () => authz.removeDeny(bob, 'docs:read', org, { transaction })],
+                        ]) {
+                            const error = await rejectsWith(assert, run, { status: 500, code: 'E_AUTHZ_CONFIG' });
+                            assert.include(error.message, operation, `${label}/${operation}: nombra la operación`);
+                        }
+                    }
+                    assert.deepEqual(statements, [], 'ni una sentencia por una transacción que no es la del driver');
+                    assert.deepEqual(await tx.census(bob), { assignments: 0, denies: 0 });
+                    assert.isFalse(await driver.authorize(bob, 'docs:read', org));
+                })?.timeout(30_000);
+            },
+            whenFalse: () => {
+                test('transactionalWrites: false · { transaction } en grant/revoke/deny/removeDeny es 500 E_AUTHZ_UNSUPPORTED nombrando driver y operación, con CERO llamadas al driver (espía); y requireTransactionalWrites: true ⇒ 500 E_AUTHZ_CONFIG al RESOLVER el driver', async ({ assert, }) => {
+                    // El harness declara `false`: el driver tiene que decir lo mismo
+                    // (el manager lee `driver.capabilities`, no el harness).
+                    assert.notEqual(driver.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: false y el driver declara true: declara lo observable');
+                    const touched = [];
+                    const spied = new Proxy(driver, {
+                        get(target, prop, receiver) {
+                            const value = Reflect.get(target, prop, receiver);
+                            if (typeof value === 'function' && typeof prop === 'string') {
+                                return (...args) => {
+                                    touched.push(prop);
+                                    return value.apply(receiver, args);
+                                };
+                            }
+                            return value;
+                        },
+                    });
+                    // La forma de un `TransactionClientContract` de Lucid: la puerta
+                    // decide por la CAPACIDAD, antes de mirar qué transacción es.
+                    const trx = { from() { }, table() { }, isTransaction: true, connectionName: 'primary' };
+                    const alice = subject();
+                    const org = await orgUnder(tree, APP_SCOPE);
+                    const authz = managerOver({}, spied);
+                    const writes = [
+                        ['grant', () => authz.grant(alice, 'org-editor', org, { transaction: trx })],
+                        ['revoke', () => authz.revoke(alice, 'org-editor', org, { transaction: trx })],
+                        ['deny', () => authz.deny(alice, 'docs:read', org, { transaction: trx })],
+                        ['removeDeny', () => authz.removeDeny(alice, 'docs:read', org, { transaction: trx })],
+                    ];
+                    for (const [operation, run] of writes) {
+                        const error = await rejectsWith(assert, run, { status: 500, code: 'E_AUTHZ_UNSUPPORTED' });
+                        assert.include(error.message, `'${harness.name}'`, `${operation}: nombra el driver`);
+                        assert.include(error.message, operation, `${operation}: nombra la operación`);
+                        assert.include(error.message, 'requireTransactionalWrites', `${operation}: la letra lleva la salida`);
+                    }
+                    assert.deepEqual(touched, [], 'cero llamadas al driver: el rechazo va ANTES del backend');
+                    // Sin `{ transaction }` la MISMA escritura entra: la puerta es del
+                    // parámetro, no del driver.
+                    await authz.grant(alice, 'org-editor', org);
+                    assert.isTrue(await driver.authorize(alice, 'docs:read', org));
+                    assert.include(touched, 'grant');
+                    // Puerta 2, opt-in: quien quiera fallar al ARRANCAR lo pide, y
+                    // entonces el driver ni se resuelve (tampoco para leer).
+                    const strict = managerOver({ requireTransactionalWrites: true }, spied);
+                    const atResolve = await rejectsWith(assert, () => strict.driver(), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                    assert.include(atResolve.message, `'${harness.name}'`);
+                    assert.include(atResolve.message, 'transactionalWrites');
+                    await rejectsWith(assert, () => strict.authorize(alice, 'docs:read', org), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                    await rejectsWith(assert, () => strict.grant(alice, 'org-editor', org), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                });
+            },
+        });
         // ── 3b-2e · E6 · `singleCheckAuthorize` ──────────────────────────────
         caseFor('singleCheckAuthorize', {
             whenTrue: () => {
@@ -3626,11 +3842,30 @@ export function registerAuthorizationDriverContract(harness, api) {
         });
     });
     // Al cerrar el grupo: toda capacidad declarada `true` tiene que haber
-    // registrado su par. Es la regla "jamás un skip" hecha ejecutable.
-    const uncovered = Object.keys(harness.capabilities).filter((capability) => harness.capabilities[capability] && !covered.has(capability));
+    // registrado su par — y las de `BOTH_FACES_REQUIRED`, también con `false`.
+    // Es la regla "jamás un skip" hecha ejecutable.
+    const uncovered = uncoveredCapabilities(harness.capabilities, covered);
     if (uncovered.length) {
-        throw new Error(`[contrato ${harness.name}] declara ${uncovered.map((c) => `'${c}: true'`).join(', ')} ` +
+        throw new Error(`[contrato ${harness.name}] declara ${uncovered.map((c) => `'${c}: ${String(harness.capabilities[c])}'`).join(', ')} ` +
             `pero el contrato no tiene caso para ese valor todavía. Declara lo observable hoy.`);
     }
 }
+/**
+ * La regla del guard, PURA (para que `contract_harness.spec.ts` la juzgue sin
+ * borrar caras): una capacidad `true` sin caso registrado queda sin cubrir;
+ * y una de `BOTH_FACES_REQUIRED` queda sin cubrir con CUALQUIER valor.
+ */
+export function uncoveredCapabilities(capabilities, covered) {
+    return Object.keys(capabilities).filter((capability) => (capabilities[capability] || BOTH_FACES_REQUIRED.has(capability)) && !covered.has(capability));
+}
+/**
+ * Capacidades cuyas DOS caras son obligatorias (L-2): declarar `false` sin
+ * un caso `whenFalse` registrado lanza igual que declarar `true` sin
+ * `whenTrue`. El guard general solo obliga a la cara `true` porque los pares
+ * de nivel (`listDenies`, `purgeRole`…) no registran nada en un harness
+ * `core` y `false` ahí es legítimo; `transactionalWrites` es composición del
+ * manager y se observa en todos los niveles, así que su `false` sin caso es
+ * un skip disfrazado — «rechazo activo» sería una etiqueta.
+ */
+const BOTH_FACES_REQUIRED = new Set(['transactionalWrites']);
 //# sourceMappingURL=contract.js.map