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

package/build/src/models/authz_role.js.map

@@ -1 +1 @@
-{"version":3,"file":"authz_role.js","sourceRoot":"","sources":["../../../src/models/authz_role.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAChD,OAAO,eAAe,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAE/C;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC;IACzD,MAAM,CAAC,KAAK,GAAG,aAAa,CAAA;IAC5B,MAAM,CAAC,UAAU,GAAG,MAAM,CAAA;;AAGzB;IADP,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;uCACR;AAGZ;IADP,MAAM,EAAE;;uCACW;AAGZ;IADP,MAAM,EAAE;;uCACW;AAGZ;IADP,MAAM,EAAE;;8CACyB;AAG1B;IADP,MAAM,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;;4CACZ;AAIjB;IADP,MAAM,EAAE;;uCACW;AAUZ;IARP,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE;QACjC,UAAU,EAAE,wBAAwB;QACpC,QAAQ,EAAE,MAAM;QAChB,eAAe,EAAE,WAAW;QAC5B,UAAU,EAAE,MAAM;QAClB,sBAAsB,EAAE,iBAAiB;QACzC,eAAe,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE;KAC/D,CAAC;;8CACqD;AAG/C;IADP,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;8BAC7C,QAAQ;4CAAA;AAGnB;IADP,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;8BAC/D,QAAQ;4CAAA"}
+{"version":3,"file":"authz_role.js","sourceRoot":"","sources":["../../../src/models/authz_role.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAChD,OAAO,eAAe,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAE/C;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC;IACzD,MAAM,CAAC,KAAK,GAAG,aAAa,CAAA;IAC5B,MAAM,CAAC,UAAU,GAAG,MAAM,CAAA;;AAGzB;IADP,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;uCACR;AAGZ;IADP,MAAM,EAAE;;uCACW;AAGZ;IADP,MAAM,EAAE;;uCACW;AAGZ;IADP,MAAM,EAAE;;8CACyB;AAG1B;IADP,MAAM,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;;4CACZ;AAIjB;IADP,MAAM,EAAE;;uCACW;AAQZ;IADP,MAAM,CAAC,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;;gDACb;AAUrB;IARP,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE;QACjC,UAAU,EAAE,wBAAwB;QACpC,QAAQ,EAAE,MAAM;QAChB,eAAe,EAAE,WAAW;QAC5B,UAAU,EAAE,MAAM;QAClB,sBAAsB,EAAE,iBAAiB;QACzC,eAAe,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE;KAC/D,CAAC;;8CACqD;AAG/C;IADP,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;8BAC7C,QAAQ;4CAAA;AAGnB;IADP,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;8BAC/D,QAAQ;4CAAA"}

package/build/src/models/authz_role_permission.d.ts

@@ -62,15 +62,18 @@ declare const AuthzRolePermission_base: {
     selfAssignPrimaryKey: boolean;
     generateUuid(model: any): void;
     nextUuid(): string;
+    all: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<InstanceType<T>[]>;
     find: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, value: any, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<null | InstanceType<T>>;
+    table: string;
+    connection?: string | undefined;
+    first: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<null | InstanceType<T>>;
+    truncate: (cascade?: boolean) => Promise<void>;
     readonly booted: boolean;
     $columnsDefinitions: Map<string, import("@adonisjs/lucid/types/model").ModelColumnOptions>;
     $relationsDefinitions: Map<string, import("@adonisjs/lucid/types/relations").RelationshipsContract>;
     $computedDefinitions: Map<string, import("@adonisjs/lucid/types/model").ComputedOptions>;
     primaryKey: string;
-    connection?: string | undefined;
     namingStrategy: import("@adonisjs/lucid/types/model").NamingStrategyContract;
-    table: string;
     $adapter: import("@adonisjs/lucid/types/model").AdapterContract;
     useAdapter: (adapter: import("@adonisjs/lucid/types/model").AdapterContract) => void;
     $hooks: import("@poppinss/hooks").default<any>;
@@ -128,7 +131,6 @@ declare const AuthzRolePermission_base: {
         <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, clause: Record<string, unknown>, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions): Promise<InstanceType<T>[]>;
         <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, key: string, value: any, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions): Promise<InstanceType<T>[]>;
     };
-    first: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<null | InstanceType<T>>;
     firstOrFail: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<InstanceType<T>>;
     findMany: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, value: any[], options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<InstanceType<T>[]>;
     firstOrNew: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, searchPayload: Partial<import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>>, savePayload?: Partial<import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>>, options?: import("@adonisjs/lucid/types/model").ModelAssignOptions) => Promise<InstanceType<T>>;
@@ -137,10 +139,8 @@ declare const AuthzRolePermission_base: {
     fetchOrNewUpMany: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, predicate: keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>> | (keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>)[], payload: Partial<import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>>[], options?: import("@adonisjs/lucid/types/model").ModelAssignOptions) => Promise<InstanceType<T>[]>;
     fetchOrCreateMany: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, predicate: keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>> | (keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>)[], payload: Partial<import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>>[], options?: import("@adonisjs/lucid/types/model").ModelAssignOptions) => Promise<InstanceType<T>[]>;
     updateOrCreateMany: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, predicate: keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>> | (keyof import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>)[], payload: Partial<import("@adonisjs/lucid/types/model").ModelAttributes<InstanceType<T>>>[], options?: import("@adonisjs/lucid/types/model").ModelAssignOptions) => Promise<InstanceType<T>[]>;
-    all: <T extends import("@adonisjs/lucid/types/model").LucidModel>(this: T, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => Promise<InstanceType<T>[]>;
     query: <Model extends import("@adonisjs/lucid/types/model").LucidModel, Result = InstanceType<Model>>(this: Model, options?: import("@adonisjs/lucid/types/model").ModelAdapterOptions) => import("@adonisjs/lucid/types/model").ModelQueryBuilderContract<Model, Result>;
     transaction: import("@adonisjs/lucid/types/database").TransactionFn;
-    truncate: (cascade?: boolean) => Promise<void>;
 } & import("@adonisjs/lucid/types/model").LucidModel;
 /** Pivot rol ↔ permiso del motor de autorización propio. */
 export default class AuthzRolePermission extends AuthzRolePermission_base {

package/build/src/models/authz_role_permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authz_role_permission.d.ts","sourceRoot":"","sources":["../../../src/models/authz_role_permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oZAsBoxtB,gDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAjBr2tB,4DAA4D;AAC5D,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,wBAA2B;IAC1E,OAAc,KAAK,SAA2B;IAC9C,OAAc,UAAU,SAAS;IAGzB,IAAI,EAAE,MAAM,CAAA;IAGZ,QAAQ,EAAE,MAAM,CAAA;IAGhB,cAAc,EAAE,MAAM,CAAA;IAGtB,SAAS,EAAE,QAAQ,CAAA;CAC5B"}
+{"version":3,"file":"authz_role_permission.d.ts","sourceRoot":"","sources":["../../../src/models/authz_role_permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oZAsBoxtB,gDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAjBr2tB,4DAA4D;AAC5D,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,wBAA2B;IAC1E,OAAc,KAAK,SAA2B;IAC9C,OAAc,UAAU,SAAS;IAGzB,IAAI,EAAE,MAAM,CAAA;IAGZ,QAAQ,EAAE,MAAM,CAAA;IAGhB,cAAc,EAAE,MAAM,CAAA;IAGtB,SAAS,EAAE,QAAQ,CAAA;CAC5B"}

package/build/src/openfga.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Entrada del subpath `@jantstack/adonis-authz/openfga` — TODO lo que tira de
+ * `@openfga/sdk` (peer opcional) vive detrás de esta puerta (D9):
+ *
+ *   const { OpenFgaAuthorizationDriver } = await import('@jantstack/adonis-authz/openfga')
+ *
+ * La entrada principal (`@jantstack/adonis-authz`) no importa este módulo ni
+ * el driver: un consumidor solo-database arranca sin el SDK instalado, y
+ * `scripts/check_purity.mjs` (regla 3) lo vigila en cada build.
+ */
+export { OpenFgaAuthorizationDriver, openFgaAuthorizationModel, provisionOpenFgaStore, importAuthzFactsToOpenFga, assertHolderTypes, parseBindingId, correlateBatchResults, isDuplicateWrite, DEFAULT_TIMEOUT_MS, } from './drivers/openfga_driver.js';
+export type { HolderTypeMap, OpenFgaDriverOptions, ImportFactsOptions, ImportFactsResult, } from './drivers/openfga_driver.js';
+//# sourceMappingURL=openfga.d.ts.map

package/build/src/openfga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfga.d.ts","sourceRoot":"","sources":["../../src/openfga.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,6BAA6B,CAAA"}

package/build/src/openfga.js

@@ -0,0 +1,12 @@
+/**
+ * Entrada del subpath `@jantstack/adonis-authz/openfga` — TODO lo que tira de
+ * `@openfga/sdk` (peer opcional) vive detrás de esta puerta (D9):
+ *
+ *   const { OpenFgaAuthorizationDriver } = await import('@jantstack/adonis-authz/openfga')
+ *
+ * La entrada principal (`@jantstack/adonis-authz`) no importa este módulo ni
+ * el driver: un consumidor solo-database arranca sin el SDK instalado, y
+ * `scripts/check_purity.mjs` (regla 3) lo vigila en cada build.
+ */
+export { OpenFgaAuthorizationDriver, openFgaAuthorizationModel, provisionOpenFgaStore, importAuthzFactsToOpenFga, assertHolderTypes, parseBindingId, correlateBatchResults, isDuplicateWrite, DEFAULT_TIMEOUT_MS, } from './drivers/openfga_driver.js';
+//# sourceMappingURL=openfga.js.map

package/build/src/openfga.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfga.js","sourceRoot":"","sources":["../../src/openfga.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAA"}

package/build/src/sql_descendants.d.ts

@@ -0,0 +1,51 @@
+import type { ScopeDescendantsResolver } from './types.js';
+/**
+ * `descendantsOf` opt-in sobre una tabla del consumidor con columna padre
+ * (2.1, B2). Genera UNA CTE recursiva (`WITH RECURSIVE`), la misma para
+ * PostgreSQL, SQLite y MySQL 8 (2.5 · J3: solo cambia el carácter con el que
+ * se citan los identificadores); cualquier otro dialecto lanza 500
+ * `E_AUTHZ_UNSUPPORTED_DIALECT` en la primera llamada hasta que la suite lo
+ * observe. El paquete sigue sin conocer el árbol del consumidor: aquí solo
+ * se le dice qué tabla y qué columnas lo guardan.
+ *
+ *   scopes: {
+ *     resolveChain,
+ *     descendantsOf: sqlDescendantsOf({
+ *       table: 'organization_nodes', uuidColumn: 'uuid', parentColumn: 'parent_uuid', typeColumn: 'kind',
+ *     }),
+ *   }
+ *
+ * Cotas: la consulta lee como mucho `maxNodes + 1` filas (`LIMIT`) y no baja
+ * más de `maxNodes + 1` niveles, así que un ciclo en la tabla termina Y se
+ * nota: un ciclo alcanzable produce al menos una fila por nivel, es decir
+ * más de `maxNodes` ⇒ 422 `E_AUTHZ_TOO_MANY_SCOPES` con «posible ciclo» en
+ * el mensaje (con `depth < maxNodes` un ciclo de dos nodos devolvía
+ * `maxNodes - 1` filas duplicadas en silencio). No hay segunda barrera por
+ * uuid repetido: con esta profundidad un ciclo NUNCA cabe en `maxNodes`
+ * filas, así que era código muerto (G1, CR6). Nunca una lista parcial. Un
+ * scope que no está en la tabla ⇒ `null`. `scopeType` pasa por la gramática
+ * de identidad al construir (auditor 11).
+ */
+export interface SqlDescendantsOptions {
+    table: string;
+    uuidColumn: string;
+    /** Columna con el uuid del padre; `NULL` = el nodo cuelga de `app`. */
+    parentColumn: string;
+    /** Columna con el `ScopeRef.type` de cada fila. Excluyente con `scopeType`. */
+    typeColumn?: string;
+    /** Tipo fijo de todos los nodos de la tabla (sin columna de tipo). Excluyente con `typeColumn`. */
+    scopeType?: string;
+    /** Cota propia del helper: se aplica `min(maxNodes del llamante, esta)`. */
+    maxNodes?: number;
+    /** Nombre de la conexión Lucid (default: la primaria). */
+    connection?: string;
+    /** Deadline de cada consulta en ms (default 5000): vencido ⇒ 503. */
+    timeoutMs?: number;
+}
+/** Lo que necesita del `db` de Lucid; inyectable para probar el dialecto sin servidor. */
+interface DatabaseLike {
+    connection(name?: string): any;
+}
+export declare function sqlDescendantsOf(options: SqlDescendantsOptions, database?: DatabaseLike): ScopeDescendantsResolver;
+export {};
+//# sourceMappingURL=sql_descendants.d.ts.map

package/build/src/sql_descendants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql_descendants.d.ts","sourceRoot":"","sources":["../../src/sql_descendants.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAY,MAAM,YAAY,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAuBD,0FAA0F;AAC1F,UAAU,YAAY;IACpB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAC/B;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,GAAE,YAAiB,GAC1B,wBAAwB,CAiH1B"}

package/build/src/sql_descendants.js

@@ -0,0 +1,129 @@
+import db from '@adonisjs/lucid/services/db';
+import { AuthorizationConfigError, TooManyScopesError, UnsupportedDialectError } from './errors.js';
+import { assertScope, assertScopeType } from './identity.js';
+import { guardSql } from './drivers/backend_guard.js';
+import { APP_SCOPE_TYPE } from './types.js';
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Dialecto → carácter con el que cita identificadores (MySQL: backtick; el resto: comilla doble ANSI). */
+const QUOTE_BY_DIALECT = {
+    'postgres': '"',
+    'sqlite3': '"',
+    'better-sqlite3': '"',
+    'mysql': '`',
+    'mysql2': '`',
+};
+const DEFAULT_TIMEOUT_MS = 5_000;
+function identifier(kind, value) {
+    if (typeof value !== 'string' || !IDENTIFIER.test(value)) {
+        throw new AuthorizationConfigError(`sqlDescendantsOf: ${kind} '${String(value)}' no es un identificador SQL simple (letras, dígitos y _); ` +
+            `nada que no lo sea se interpola en la consulta.`);
+    }
+    return value;
+}
+export function sqlDescendantsOf(options, database = db) {
+    const table = identifier('table', options.table);
+    const uuidCol = identifier('uuidColumn', options.uuidColumn);
+    const parentCol = identifier('parentColumn', options.parentColumn);
+    if ((options.typeColumn === undefined) === (options.scopeType === undefined)) {
+        throw new AuthorizationConfigError('sqlDescendantsOf: declara exactamente uno de typeColumn (el tipo viene de la fila) o scopeType (tipo fijo).');
+    }
+    const typeCol = options.typeColumn === undefined ? null : identifier('typeColumn', options.typeColumn);
+    const fixedType = options.scopeType ?? null;
+    if (fixedType !== null) {
+        // Es identidad de scope (minúsculas, ≤ 20, sin separadores) y nunca la
+        // raíz: `app` no tiene fila ni uuid.
+        try {
+            assertScopeType(fixedType);
+        }
+        catch (error) {
+            throw new AuthorizationConfigError(`sqlDescendantsOf: scopeType inválido: ${error.message}`);
+        }
+        if (fixedType === APP_SCOPE_TYPE) {
+            throw new AuthorizationConfigError("sqlDescendantsOf: scopeType no puede ser 'app' (la raíz no tiene fila)");
+        }
+    }
+    if (options.maxNodes !== undefined && !(Number.isInteger(options.maxNodes) && options.maxNodes >= 1)) {
+        throw new AuthorizationConfigError(`sqlDescendantsOf: maxNodes debe ser un entero >= 1 (llegó ${String(options.maxNodes)})`);
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const connectionName = options.connection;
+    /** El SQL por carácter de cita (se construye una vez por dialecto). */
+    const statements = new Map();
+    function statementsFor(quote) {
+        let built = statements.get(quote);
+        if (built)
+            return built;
+        const q = (name) => `${quote}${name}${quote}`;
+        const typeSelect = typeCol ? `t.${q(typeCol)}` : 'NULL';
+        // MySQL corta una CTE recursiva a `cte_max_recursion_depth` iteraciones
+        // (1000 por defecto) con el error 3636: con una cota mayor, un ciclo
+        // salía como 503 «backend caído» en vez del 422 «posible ciclo» del
+        // contrato (2.5 · J3, hallazgo). El hint `SET_VAR` sube el tope SOLO para
+        // esta sentencia, a la cota + 1 que la propia consulta ya impone con
+        // `depth < ?`; el placeholder `%DEPTH%` se rellena con ese entero (nunca
+        // con entrada del consumidor). Los demás dialectos no tienen tope.
+        const hint = quote === '`' ? '/*+ SET_VAR(cte_max_recursion_depth = %DEPTH%) */ ' : '';
+        built = {
+            exists: `SELECT 1 AS ${q('ok')} FROM ${q(table)} t WHERE %WHERE% LIMIT 1`,
+            walk: `WITH RECURSIVE ${q('authz_descendants')}(${q('uuid')}, ${q('type')}, ${q('depth')}) AS (` +
+                ` SELECT t.${q(uuidCol)}, ${typeSelect}, 1 FROM ${q(table)} t WHERE ` +
+                `%ANCHOR%` +
+                ` UNION ALL` +
+                ` SELECT t.${q(uuidCol)}, ${typeSelect}, d.${q('depth')} + 1 FROM ${q(table)} t` +
+                ` JOIN ${q('authz_descendants')} d ON t.${q(parentCol)} = d.${q('uuid')} WHERE d.${q('depth')} < ?` +
+                `) SELECT ${hint}${q('uuid')}, ${q('type')} FROM ${q('authz_descendants')} LIMIT ?`,
+        };
+        statements.set(quote, built);
+        return built;
+    }
+    return async (scope, { maxNodes }) => {
+        assertScope(scope);
+        const cap = Math.min(maxNodes, options.maxNodes ?? Infinity);
+        if (!(Number.isInteger(cap) && cap >= 1)) {
+            throw new AuthorizationConfigError(`sqlDescendantsOf: maxNodes debe ser un entero >= 1 (llegó ${String(maxNodes)})`);
+        }
+        const connection = database.connection(connectionName);
+        const dialect = connection?.dialect?.name ?? connection?.client?.driverName ?? 'desconocido';
+        const quote = QUOTE_BY_DIALECT[dialect];
+        if (!quote) {
+            throw new UnsupportedDialectError(`sqlDescendantsOf: dialecto '${dialect}' sin observación en la suite (hoy: PostgreSQL, MySQL 8 y SQLite). ` +
+                `Implementa scopes.descendantsOf a mano para este motor.`);
+        }
+        const q = (name) => `${quote}${name}${quote}`;
+        const sql = statementsFor(quote);
+        const query = (operation, text, bindings) => guardSql('sqlDescendantsOf', operation, timeoutMs, () => connection.rawQuery(text, bindings));
+        // Forma del resultado crudo por cliente: pg `{ rows }`, sqlite `rows[]`,
+        // mysql2 `[rows[], fields[]]` (2.5 · J3).
+        const rowsOf = (result) => {
+            if (Array.isArray(result)) {
+                return result.length === 2 && Array.isArray(result[0]) && Array.isArray(result[1]) ? result[0] : result;
+            }
+            return result?.rows ?? [];
+        };
+        let anchor;
+        let bindings;
+        if (scope.type === APP_SCOPE_TYPE) {
+            anchor = `t.${q(parentCol)} IS NULL`;
+            bindings = [];
+        }
+        else {
+            if (fixedType !== null && scope.type !== fixedType)
+                return null;
+            const where = `t.${q(uuidCol)} = ?` + (typeCol ? ` AND t.${q(typeCol)} = ?` : '');
+            const args = typeCol ? [scope.uuid, scope.type] : [scope.uuid];
+            const exists = rowsOf(await query('descendantsOf.exists', sql.exists.replace('%WHERE%', where), args));
+            if (exists.length === 0)
+                return null;
+            anchor = `t.${q(parentCol)} = ?`;
+            bindings = [scope.uuid];
+        }
+        const walk = sql.walk.replace('%ANCHOR%', anchor).replace('%DEPTH%', String(cap + 2));
+        const rows = rowsOf(await query('descendantsOf', walk, [...bindings, cap + 1, cap + 1]));
+        if (rows.length > cap) {
+            throw new TooManyScopesError(`sqlDescendantsOf: ${scope.type}:${scope.uuid ?? ''} tiene más de ${cap} descendientes — o la tabla tiene un ` +
+                `posible ciclo (un ciclo alcanzable produce una fila por nivel hasta la cota); no se devuelve una lista parcial.`);
+        }
+        return rows.map((row) => ({ type: typeCol ? row.type : fixedType, uuid: row.uuid }));
+    };
+}
+//# sourceMappingURL=sql_descendants.js.map

package/build/src/sql_descendants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql_descendants.js","sourceRoot":"","sources":["../../src/sql_descendants.ts"],"names":[],"mappings":"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"}

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

@@ -1,27 +1,158 @@
 import '@japa/assert';
+import type { Assert } from '@japa/assert';
 import type { AuthorizationDriver, CatalogSpec } from '../types.js';
+import type { ContractScopeTree } from './scope_tree.js';
 /**
  * Suite de contrato del sistema de autorización — EL JUEZ.
  *
  * Cualquier driver (database, openfga, custom del consumidor) debe pasar
  * estos casos sin modificarlos: son la definición ejecutable de la semántica
- * documentada en `#services/authorization/types`. Para enchufar un driver:
+ * documentada en `../types.js`. Para enchufar un driver:
  *
  *   runAuthorizationDriverContract({
  *     name: 'mi-driver',
- *     makeDriver: () => new MiDriver(),
- *     seedCatalog: (catalog) => ...,   // materializa roles/permisos
- *     cleanup: () => ...,              // borra hechos + catálogo entre tests
+ *     level: '2.0',                      // omitido = 'core': solo los casos de 1.x
+ *     capabilities: { hierarchyFacts: false, transactions: false, truncationSignal: false,
+ *                     singleCheckAuthorize: false, injectableClock: false },
+ *     seedCatalog: (catalog) => ...,     // materializa roles/permisos
+ *     makeDriver: (tree) => new MiDriver({ resolveChain: ... }), // recibe el árbol
+ *     cleanup: () => ...,                // borra hechos + catálogo entre tests
  *   })
  *
+ * Llámala en el TOP LEVEL del spec (no dentro de un `test` ni de un hook):
+ * Japa registra los grupos al importar el archivo y descarta los tardíos.
+ *
  * `seedCatalog`/`cleanup` son del harness (no del contrato) porque cada
  * backend materializa el catálogo a su manera (tablas propias, FGA model...).
+ *
+ * El ÁRBOL de scopes también es del harness (`makeTree`, por defecto
+ * `memoryScopeTree()`): la suite lo construye caso a caso con `tree.attach` y
+ * el driver lo ve a través de lo que el harness le inyecte (un
+ * `resolveChain` que lo camina, o hechos en el backend). Así el
+ * invariante 1 se prueba con cadenas reales y no con el resolutor plano.
+ */
+/**
+ * Lo que un driver DECLARA poder hacer. Cada capacidad tiene en la suite un
+ * par de casos `{ whenTrue, whenFalse }` — nunca un `skip`. Hoy hay par para
+ * `truncationSignal: false` (con `exhaustiveLists`) y `hierarchyFacts: false`;
+ * los demás llegan con su fase, y mientras tanto declararlos `true` hace que
+ * la suite lance al registrarse: una promesa sin juez no pasa.
  */
+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;
+    /**
+     * 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
+     * `true`: es el par que un driver de terceros con backend con tope tendría
+     * que traer.
+     */
+    truncationSignal: boolean;
+    /** `authorize` = una sola llamada al backend (modo facts, Fase 3b). */
+    singleCheckAuthorize: boolean;
+    /**
+     * El driver acepta un reloj inyectado (2.5 · J1): `withClock(now)` en el
+     * puerto devuelve una vista que evalúa la caducidad con ESE `now` (SQL,
+     * `current_time` de FGA, filtros en cliente y los tres estados del
+     * re-grant). Con `true` el juez fija el instante y observa la caducidad
+     * exacta (T−1 ms concede, T no) sin dormir; con `false` solo puede
+     * observarla en tiempo real (el caso de los tres estados espera 1,5 s).
+     */
+    injectableClock: boolean;
+    /**
+     * Los `list*` devuelven TODO sin tope. Es la verdad de los dos drivers del
+     * paquete: `database` (SQL sin límite) y `openfga` (enumeración por `Read`
+     * paginado, L0.7). Con `false` el harness debe dar `limits.listMaxResults`
+     * y el juez prueba solo la frontera exacta: es la declaración honesta de
+     * un driver de terceros cuyo backend trunca y que no lo señala.
+     */
+    exhaustiveLists: boolean;
+    /**
+     * El driver implementa el método opcional `listDenies` (2.1). Solo tiene
+     * casos en `level: '2.1'` (2E · I5): con `true` se juzgan `listDenies`,
+     * `effectivePermissions`, `authorizedScopes` y la versión compartida del
+     * catálogo; con `false` se juzga que esas primitivas lo digan (500
+     * `E_AUTHZ_UNSUPPORTED` nombrándolo) en vez de simular «sin denies». En un
+     * harness `core`/`'2.0'` no hay caso que lo observe: declara `false`.
+     */
+    listDenies: boolean;
+    /**
+     * `purgeRole(roleUuid)` está implementado de verdad (3B · B4): revoca
+     * todas las asignaciones del rol en todos los scopes, borra sus vínculos
+     * y el rol, atómicamente, y recrear el slug no revive nada. Solo tiene
+     * casos en `level: '2.2'`: con `true` se juzga la purga; con `false` se
+     * juzga que el driver lo DIGA (500 `E_AUTHZ_UNSUPPORTED`) y que no deje
+     * nada a medias — el driver `openfga` del paquete hasta 3b (`facts` +
+     * `reconcile`): sus bindings no son enumerables por rol sin leer el
+     * store entero. En un harness por debajo de `'2.2'` declara `false`.
+     */
+    purgeRole: boolean;
+    /**
+     * Las escrituras del CATÁLOGO se serializan de verdad en el motor (3E ·
+     * R2, tester): dos `defineScopedRole` del mismo `(slug, nivel)` en
+     * paralelo terminan con EXACTAMENTE uno confirmado y el otro con 422
+     * `E_AUTHZ_CATALOG_CONFLICT` — nunca un fallo de backend. Es lo que da el
+     * cerrojo sobre la fila de `authz_catalog_version` (3D · M2) en PostgreSQL
+     * y MySQL, y es la promesa que el README hace.
+     *
+     * Con `false` (SQLite, que serializa bloqueando la BASE ENTERA) el juez
+     * solo puede exigir lo innegociable: nunca dos ganadores y el perdedor no
+     * escribe — su transacción puede morir con `SQLITE_BUSY`, que es un 503
+     * legítimo. Declararlo `true` en un motor así convierte un flake en un
+     * fallo; declararlo `false` en PG/MySQL deja pasar un mutante que
+     * convierte la colisión en 503. Solo tiene casos en `level: '2.2'`.
+     */
+    serializedCatalogWrites: boolean;
+}
+export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
     name: string;
-    makeDriver: () => AuthorizationDriver | Promise<AuthorizationDriver>;
-    seedCatalog: (catalog: CatalogSpec) => Promise<void>;
-    cleanup: () => Promise<void>;
+    /** `core` (default): los casos de 1.x. `'2.0'`: además los de la Fase 0/1. `'2.1'`: además las primitivas de la Fase 2. `'2.2'`: además los roles locales a un scope (Fase 3). */
+    level?: ContractLevel;
+    capabilities: DriverCapabilities;
+    /** Tope de resultados del backend de test. Obligatorio con `exhaustiveLists: false`. */
+    limits?: {
+        listMaxResults?: number;
+    };
+    /**
+     * Materializa el catálogo del juez. Devuelve lo que quiera (3E: el
+     * `syncAuthzCatalog` del paquete devuelve su reporte): el juez no lo mira.
+     */
+    seedCatalog(catalog: CatalogSpec): Promise<unknown>;
+    /** Árbol que usará la suite. Default: `memoryScopeTree()`. */
+    makeTree?(): Promise<ContractScopeTree>;
+    makeDriver(tree: ContractScopeTree): AuthorizationDriver | Promise<AuthorizationDriver>;
+    /**
+     * OTRA instancia del driver sobre el MISMO backend de hechos y con su
+     * propio memo del catálogo — lo que sería el mismo driver en otro proceso
+     * (2D · F1). Default: si el driver expone `catalog` (`CatalogCache`, los
+     * dos del paquete), una vista por prototipo con un memo nuevo; si no, el
+     * mismo driver (un driver que lea el catálogo en vivo pasa igual).
+     */
+    makeTwin?(driver: AuthorizationDriver, tree: ContractScopeTree): AuthorizationDriver | Promise<AuthorizationDriver>;
+    cleanup(): Promise<void>;
+}
+/**
+ * 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
+ * títulos, porque Japa no permite registrar grupos desde un test en marcha y
+ * la regla de capacidades hay que poder probarla.
+ */
+export interface ContractTestApi {
+    group(title: string, define: (group: {
+        each: {
+            setup(fn: () => Promise<void>): unknown;
+        };
+        teardown(fn: () => Promise<void>): unknown;
+    }) => void): unknown;
+    test(title: string, fn: (ctx: {
+        assert: Assert;
+    }) => Promise<void>): {
+        timeout(ms: number): unknown;
+    } | undefined | void;
 }
 export declare function runAuthorizationDriverContract(harness: DriverContractHarness): void;
+export declare function registerAuthorizationDriverContract(harness: DriverContractHarness, api: ContractTestApi): void;
 //# 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;AAGrB,OAAO,KAAK,EACV,mBAAmB,EACnB,WAAW,EAGZ,MAAM,aAAa,CAAA;AAGpB;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACpE,WAAW,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAoBD,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qBAAqB,QAkP5E"}
+{"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"}