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

package/build/src/testing/contract.d.ts

@@ -1,6 +1,6 @@
 import '@japa/assert';
 import type { Assert } from '@japa/assert';
-import type { AuthorizationDriver, CatalogSpec } from '../types.js';
+import type { AuthorizationDriver, CatalogSpec, SubjectRef } from '../types.js';
 import type { ContractScopeTree } from './scope_tree.js';
 /**
  * Suite de contrato del sistema de autorización — EL JUEZ.
@@ -12,7 +12,7 @@ import type { ContractScopeTree } from './scope_tree.js';
  *   runAuthorizationDriverContract({
  *     name: 'mi-driver',
  *     level: '2.0',                      // omitido = 'core': solo los casos de 1.x
- *     capabilities: { hierarchyFacts: false, transactions: false, truncationSignal: false,
+ *     capabilities: { hierarchyFacts: false, transactionalWrites: false, truncationSignal: false,
  *                     singleCheckAuthorize: false, injectableClock: false },
  *     seedCatalog: (catalog) => ...,     // materializa roles/permisos
  *     makeDriver: (tree) => new MiDriver({ resolveChain: ... }), // recibe el árbol
@@ -41,8 +41,29 @@ import type { ContractScopeTree } from './scope_tree.js';
 export interface DriverCapabilities {
     /** El driver materializa el árbol como hechos propios (Fase 3b). */
     hierarchyFacts: boolean;
-    /** Acepta `{ trx }` externa en las escrituras (Fase 2.5). */
-    transactions: boolean;
+    /**
+     * **`{ transaction }` en `grant`/`revoke`/`deny`/`removeDeny` ESCRIBE en
+     * la transacción del consumidor** — «los dos o ninguno con TU transacción»,
+     * nunca «no se pierde» (L-2, panel `{trx}` (C); mismo nombre que
+     * `AuthorizationDriverCapabilities.transactionalWrites` y que su par de
+     * relaciones). Es el ÚNICO par del juez con las DOS caras obligatorias:
+     * `true` sin caso `whenTrue` Y `false` sin caso `whenFalse` hacen que la
+     * suite lance al registrarse (los demás pares solo exigen la cara `true`;
+     * la lección de 4-2 es que una `whenFalse` ausente se salta en silencio).
+     * Con `false` el juez fija que `{ transaction }` es 500 `E_AUTHZ_UNSUPPORTED`
+     * nombrando driver y operación con CERO llamadas al driver (espía), y que
+     * `requireTransactionalWrites: true` lo convierte en 500 `E_AUTHZ_CONFIG`
+     * al RESOLVER. Con `true` (L-3) el juez abre una transacción de la conexión
+     * del driver (`DriverContractHarness.transactions`, default Lucid +
+     * `authz_*`) y fija, para las cuatro escrituras, que **rollback ⇒ CERO
+     * filas por CENSO** (no solo `authorize`), commit ⇒ aplicado, la escritura
+     * sin confirmar invisible para la autoridad, y que una transacción ajena es
+     * 500 `E_AUTHZ_CONFIG` sin una sentencia. `database` declara `true` (con
+     * pool ≥ 2; en `:memory:` el harness del paquete declara `false` porque la
+     * autoridad no tendría por dónde leer); `openfga` no puede ser otra cosa que
+     * `false`: una tupla no entra en una transacción SQL.
+     */
+    transactionalWrites: boolean;
     /**
      * Los `list*` lanzan si el backend trunca. Ningún driver del paquete trunca
      * (L0.7 se cerró enumerando con `Read` paginado), así que no hay caso para
@@ -89,6 +110,19 @@ export interface DriverCapabilities {
      * store entero. En un harness por debajo de `'2.2'` declara `false`.
      */
     purgeRole: boolean;
+    /**
+     * `countRoleAssignments(uuids)` está implementado de verdad (3b-2j): el
+     * driver sabe decir cuántos hechos VIGENTES tiene cada rol, que es lo que
+     * hace verdadero el `stillGranting` de `pruneOrphanRoles` —el campo que se
+     * lee justo antes de un borrado destructivo—. Con `true` se juzga el
+     * conteo (caducidad estricta, por posición, 422 por uuid mal formado); con
+     * `false`, que el barrido diga `undefined` y **nunca** `false`: «no lo sé»
+     * no puede degradar a «no concede». Solo tiene casos en `level: '2.2'`.
+     *
+     * **Es la capacidad que este lote estrena y es breaking**: un driver de
+     * terceros de 2.2 la declara `false` hasta que traiga el método.
+     */
+    countRoleAssignments: boolean;
     /**
      * Las escrituras del CATÁLOGO se serializan de verdad en el motor (3E ·
      * R2, tester): dos `defineScopedRole` del mismo `(slug, nivel)` en
@@ -105,6 +139,67 @@ export interface DriverCapabilities {
      * convierte la colisión en 503. Solo tiene casos en `level: '2.2'`.
      */
     serializedCatalogWrites: boolean;
+    /**
+     * El backend resuelve la MEMBRESÍA por sí mismo (3b-2e · E2). **`false` en
+     * los dos drivers del paquete, también en el modo `facts`** (panel 2, cruce
+     * 6): `hasRole`, `listRoles`, `listRoleScopes`, `listSubjects` y
+     * `listScopes` siguen usando el `resolveChain` del consumidor. Con `false`
+     * el juez lo DEMUESTRA con un espía sobre el árbol, que es lo que impide
+     * vender «sin SQL en el camino caliente» a secas: lo cierto es «sin SQL por
+     * request en `authorize`». La cara `true` no tiene caso todavía: no hay
+     * driver que lo cumpla.
+     */
+    roleInheritanceNative: boolean;
+    /**
+     * Los `list*` enumeran también lo HEREDADO (3b-2e · E2). **`false` siempre
+     * en este paquete** (invariante 7): enumerar descendientes sería abierto, y
+     * en `openfga` obligaría a `ListObjects`, que trunca al tope del servidor
+     * SIN señal (S16, y `Check` y `ListObjects` ni siquiera coinciden en
+     * profundidad). Con `false` el juez fija que un grant en el ANCESTRO no
+     * aparece en las listas del descendiente aunque `authorize` diga `true`.
+     */
+    listObjectsInherited: boolean;
+    /**
+     * **Las LECTURAS canonizan la ortografía del scope contra el árbol del
+     * consumidor antes de buscar los hechos** (3b-2k · K1 · R2 (c)). El árbol
+     * del consumidor puede fundir dos formas del mismo id —el tipo `uuid` de
+     * PostgreSQL y la collation `*_ci` de MySQL leen `bbbb…` con y sin guiones
+     * como la MISMA fila—, y `authz_*` compara por bytes.
+     *
+     * Con `true` (driver `database`) `authorize` resuelve la cadena y usa
+     * `chain[0]`, la identidad CANÓNICA (invariante 17): un alias que el árbol
+     * funde con la fila real encuentra exactamente los mismos hechos que la
+     * forma canónica.
+     *
+     * Con `false` (`openfga` en modo `facts`) la DECISIÓN no pasa por el árbol
+     * —es la contrapartida de `singleCheckAuthorize`— así que el objeto del
+     * store se compone con la ortografía del LLAMANTE y un alias no encuentra
+     * nada: `authorize` responde `false` donde la forma canónica concede. Es
+     * fail-**CLOSED** y no evade ningún deny, pero **no es la misma respuesta
+     * que `database`** y por eso se declara. Lo que NO cambia es la ESCRITURA:
+     * `grant`/`revoke`/`removeDeny`/`purgeScope` sí canonizan en los dos
+     * drivers (3b-2h · 🟠 3 cerró la cara fail-open), y el juez lo fija en las
+     * DOS caras del par para que nadie lea esta capacidad como «en `facts` la
+     * ortografía da igual».
+     */
+    canonicalScopeReads: boolean;
+    /**
+     * El driver sabe ser el **ORIGEN** de `authz:reconcile` (3b-3b):
+     * `enumerateFacts` entrega sus hechos por páginas, con su caducidad y **sin
+     * filtrar** (una asignación caducada tiene que LLEGAR para que el destino
+     * la cuente en `skipped`; filtrarla la haría desaparecer sin rastro).
+     *
+     * Con `true` el juez pasea las páginas, comprueba que el cursor avanza,
+     * que no se devuelven más de `limit` hechos y que la caducada sale con su
+     * instante. Con `false` juzga que el driver no puede ser origen y que
+     * `authz:reconcile` lo DICE —500 `E_AUTHZ_UNSUPPORTED` nombrando el
+     * método— en vez de leer cero hechos y vaciar el destino con `--prune`.
+     *
+     * `false` en el driver `database` a propósito: sus hechos son
+     * `authz_assignments`/`authz_denies`, el esquema publicado del paquete, y
+     * el destino los lee de ahí. Solo tiene casos en `level: '2.2'`.
+     */
+    enumerateFacts: boolean;
 }
 export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
@@ -133,7 +228,31 @@ export interface DriverContractHarness {
      */
     makeTwin?(driver: AuthorizationDriver, tree: ContractScopeTree): AuthorizationDriver | Promise<AuthorizationDriver>;
     cleanup(): Promise<void>;
+    /**
+     * Solo con `transactionalWrites: true` (L-3): cómo abre el juez una
+     * transacción de LA CONEXIÓN DEL DRIVER y cómo cuenta los hechos de un
+     * holder en el backend — el CENSO: el rollback se juzga por filas, no solo
+     * por la respuesta de `authorize` (la lección del contrato de migración).
+     * Default: `db.transaction()` de Lucid (conexión primaria) y
+     * `authz_assignments`/`authz_denies`, lo que vale para el driver `database`.
+     * Un driver de terceros con otra conexión u otras tablas trae el suyo.
+     */
+    transactions?: ContractTransactions;
+}
+/** Ver `DriverContractHarness.transactions`. */
+export interface ContractTransactions {
+    begin(): Promise<{
+        client: unknown;
+        commit(): Promise<unknown>;
+        rollback(): Promise<unknown>;
+    }>;
+    census(subject: SubjectRef): Promise<{
+        assignments: number;
+        denies: number;
+    }>;
 }
+/** El default de `DriverContractHarness.transactions`: Lucid + `authz_*`. */
+export declare function lucidContractTransactions(): ContractTransactions;
 /**
  * Lo mínimo que el juez necesita del runner. En producción es el `test` de
  * Japa; en `tests/contract_harness.spec.ts` es una API falsa que solo anota
@@ -155,4 +274,10 @@ export interface ContractTestApi {
 }
 export declare function runAuthorizationDriverContract(harness: DriverContractHarness): void;
 export declare function registerAuthorizationDriverContract(harness: DriverContractHarness, api: ContractTestApi): void;
+/**
+ * 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 declare function uncoveredCapabilities(capabilities: DriverCapabilities, covered: ReadonlySet<keyof DriverCapabilities>): (keyof DriverCapabilities)[];
 //# sourceMappingURL=contract.d.ts.map

package/build/src/testing/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contract.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAG1C,OAAO,KAAK,EACV,mBAAmB,EAEnB,WAAW,EAKZ,MAAM,aAAa,CAAA;AAQpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAA;IACvB,6DAA6D;IAC7D,YAAY,EAAE,OAAO,CAAA;IACrB;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAA;IACzB,uEAAuE;IACvE,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;;;OAOG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;;;;;;OAOG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;;;;;;;OASG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,EAAE,OAAO,CAAA;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;AAE1D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,kLAAkL;IAClL,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,kBAAkB,CAAA;IAChC,wFAAwF;IACxF,MAAM,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACvC,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACvF;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACnH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAiPD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CACH,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,KAAK,EAAE;QACd,IAAI,EAAE;YAAE,KAAK,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;SAAE,CAAA;QACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;KAC3C,KAAK,IAAI,GACT,OAAO,CAAA;IACV,IAAI,CACF,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC7C;QAAE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI,CAAA;CACvD;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qBAAqB,QAK5E;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,eAAe,QAuyGrB"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contract.ts"],"names":[],"mappings":"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"}