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

package/build/src/types.js

@@ -12,10 +12,12 @@
  * suite corre contra cada driver — es el juez del contrato):
  *
  * 1. **Scopes jerárquicos, herencia SOLO hacia abajo.** La cadena de un scope
- *    es `[scope, ...ancestros]` (`app` es la raíz: su cadena es él mismo).
+ *    es `[scope canónico, ...ancestros]` (`app` es la raíz: su cadena es él
+ *    mismo); la identidad de un scope es la que devuelve el resolutor, nunca
+ *    la forma con la que lo escribió el llamante (2.5-B · K1).
  *    Un grant en un scope autoriza en ese scope y en TODOS sus descendientes;
  *    nunca en hermanos ni ancestros. En T1 solo opera `app` (los ancestros de
- *    `organization`/`unit` se completan en T2/T3 vía `resolveAncestors`).
+ *    `organization`/`unit` se completan en T2/T3 vía `resolveChain`).
  * 2. **Deny explícito gana.** Un deny de un permiso en cualquier scope de la
  *    cadena bloquea `authorize`, aunque un rol lo conceda (el deny también
  *    hereda hacia abajo). Quitar el deny restaura el permiso.
@@ -28,8 +30,12 @@
  *    holder sin asignación vigente → `false`, nunca throw en `authorize`.
  *    En cambio `grant`/`deny` con rol/permiso fuera del catálogo → throw
  *    (error de programación, no de autorización).
- * 6. **Idempotencia de escritura.** Re-`grant` no duplica (actualiza
- *    `expiresAt`); re-`revoke`/re-`deny`/re-`removeDeny` son no-ops seguros.
+ * 6. **Idempotencia de escritura.** Re-`grant` no duplica (`expiresAt` en
+ *    tres estados: omitido preserva, `null` quita, `Date` fija);
+ *    re-`revoke`/re-`deny`/re-`removeDeny` son no-ops seguros.
+ * 7. **El árbol es un hecho del contrato.** Un scope que el resolutor no
+ *    conoce (`null`) deniega, no lista y no admite escrituras; `purgeScope`
+ *    borra los hechos del scope exacto (los del catálogo) y demuestra cero.
  */
 /** Nombre reservado del scope raíz. */
 export const APP_SCOPE_TYPE = 'app';

package/build/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoBH,uCAAuC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAA;AAQnC,sDAAsD;AACtD,MAAM,CAAC,MAAM,SAAS,GAAa,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAoBH,uCAAuC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAA;AAQnC,sDAAsD;AACtD,MAAM,CAAC,MAAM,SAAS,GAAa,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA"}

package/build/stubs/config/app_acl.stub

@@ -17,9 +17,11 @@ import type { CatalogSpec } from '@jantstack/adonis-authz'
  * Para el ACL POR TENANT ver `config/organization_acl.ts` (migra al motor
  * en la tanda 2).
  *
- * Workflow para añadir un permiso:
+ * Workflow para añadir o quitar un permiso:
  *   1. Editar este archivo.
- *   2. `node ace db:seed:one app_acl_seeder`
+ *   2. `node ace authz:catalog:sync` (quitar un permiso de un rol lo retira
+ *      de verdad: el sync poda los vínculos que ya no listas).
+ *   3. En CI, `node ace authz:catalog:diff` falla si la base no coincide.
  */
 const appAclConfig = {
   /**

package/build/stubs/config/authorization.stub

@@ -2,8 +2,9 @@
   exports({ to: app.configPath('authorization.ts') })
 }}}
 import env from '#start/env'
-import { defineConfig, DatabaseAuthorizationDriver } from '@jantstack/adonis-authz'
+import { defineConfig, DatabaseAuthorizationDriver, APP_SCOPE } from '@jantstack/adonis-authz'
 import type { AuthzWriteEvent, ScopeRef } from '@jantstack/adonis-authz'
+import { appAclCatalog } from '#config/app_acl'
 
 /**
  * Holders de tu aplicación: morph name (`@MorphMap` del modelo) → tipo del
@@ -17,16 +18,40 @@ export const holderTypes = {
 }
 
 /**
- * Jerarquía de scopes de tu dominio. El motor solo conoce la raíz (`app`);
- * si tienes niveles propios (organizaciones, proyectos, sedes…), devuelve
- * aquí sus ancestros del más cercano a la raíz.
+ * Jerarquía de scopes de tu dominio: la ÚNICA costura entre tu dominio y el
+ * motor. El motor solo conoce la raíz (`app`); si tienes niveles propios
+ * (organizaciones, proyectos, sedes…), devuelve aquí la CADENA CANÓNICA del
+ * scope: él mismo TAL COMO ESTÁ EN TU TABLA (la fila leída, no lo que llegó
+ * en la pregunta) y después sus ancestros del más cercano a la raíz, con
+ * `APP_SCOPE` al final; y `null` si el scope NO existe (el motor deniega y
+ * rechaza escribir sobre él). Nunca devuelvas `[scope, APP_SCOPE]` para lo
+ * que no conoces: convertiría cualquier scope inventado en descendiente de la
+ * raíz. Devolver la fila (y no el argumento) es lo que impide que un alias del
+ * uuid —mayúsculas, guiones quitados, que el tipo `uuid` de PostgreSQL o una
+ * collation `*_ci` funden con la fila real— evada un deny escrito con la
+ * forma canónica. `hierarchicalScopeResolver({ nodeOf })` lo hace por ti a
+ * partir de un `nodeOf` que lea la fila.
  *
- *   organization → [APP_SCOPE]
- *   unit         → [padres…, su organization, APP_SCOPE]
+ *   organization → [la organization (fila), APP_SCOPE]                  (si existe; si no, null)
+ *   unit         → [la unit (fila), su organization (fila), APP_SCOPE]  (idem)
+ *
+ * Esta MISMA función va a tres sitios, y tiene que ser la misma:
+ *   - `scopes.resolveChain` (abajo): el manager valida con ella
+ *     `scopes.attached/moved` (padre existente, sin ciclos) antes de tocar
+ *     el driver;
+ *   - `resolveChain` de cada driver: con ella responde `authorize`,
+ *     `hasRole` y los `list*`, y valida `grant`/`deny`.
+ *   Un driver sin ella solo conoce `app` (422 al preguntar por otro nivel).
+ *
+ * Cuando tu árbol cambie, avisa al motor en todos los drivers:
+ *   authorization.scopes.attached(child, parent) / moved(child, newParent) /
+ *   detached(child)  ← purga los hechos del scope antes de que borres la fila.
  */
-async function resolveScopeAncestors(scope: ScopeRef): Promise<ScopeRef[]> {
-  if (scope.type === 'app') return []
-  return [{ type: 'app', uuid: null }]
+async function resolveScopeChain(scope: ScopeRef): Promise<ScopeRef[] | null> {
+  if (scope.type === 'app') return [APP_SCOPE]
+  // TODO: consulta tu tabla; devuelve null si `scope.uuid` no existe, y si
+  // existe, [{ type, uuid: fila.uuid }, ...ancestros, APP_SCOPE].
+  return null
 }
 
 /**
@@ -46,15 +71,28 @@ export default defineConfig({
     modelId: env.get('OPENFGA_MODEL_ID'),
   },
 
+  // La costura del árbol (ver arriba): la misma función que reciben los drivers.
+  // 2.1: añade `descendantsOf: sqlDescendantsOf({ table, uuidColumn, parentColumn, typeColumn })`
+  // (2.2: con `descendantsOf`, `scopes.detached` purga también los roles
+  //  locales del SUBÁRBOL —sin él, solo los del scope exacto— y el nivel de
+  //  un rol local se comprueba contra el árbol de hoy; delegar hacia abajo
+  //  —`lead@unit` con owner una org— funciona con o sin él)
+  // (o tu propia función) para `authorizedScopes`; y `requireWithin: true` / `requireActor: true`
+  // en cuanto todos los call-sites pasen `within` / `actor` (hasta entonces el manager avisa).
+  scopes: { resolveChain: resolveScopeChain },
+
   drivers: {
-    database: () => new DatabaseAuthorizationDriver({ resolveAncestors: resolveScopeAncestors }),
+    database: () => new DatabaseAuthorizationDriver({ resolveChain: resolveScopeChain }),
 
     /**
      * Backend externo opcional. Levanta el servidor y provisiona con
      * `node ace openfga:provision`; migra los hechos con `openfga:import`.
+     * El driver vive en el subpath `/openfga` (lo único que importa el peer
+     * opcional `@openfga/sdk`) y se carga DENTRO de la factory: sin
+     * AUTHZ_DRIVER=openfga el SDK ni se instala ni se importa.
      */
     openfga: async () => {
-      const { OpenFgaAuthorizationDriver } = await import('@jantstack/adonis-authz')
+      const { OpenFgaAuthorizationDriver } = await import('@jantstack/adonis-authz/openfga')
       const apiUrl = env.get('OPENFGA_URL')
       const storeId = env.get('OPENFGA_STORE_ID')
       if (!apiUrl || !storeId) {
@@ -64,11 +102,27 @@ export default defineConfig({
         apiUrl,
         storeId,
         modelId: env.get('OPENFGA_MODEL_ID'),
-        resolveAncestors: resolveScopeAncestors,
+        resolveChain: resolveScopeChain,
         holderTypes,
       })
     },
   },
 
+  /**
+   * Catálogos de roles/permisos (uno por módulo). `node ace authz:catalog:sync`
+   * los sincroniza en orden (podando los vínculos que el config ya no lista);
+   * `node ace authz:catalog:diff` falla en CI si la base no coincide.
+   */
+  catalogs: [async () => appAclCatalog()],
+
+  /**
+   * Roles locales a un scope (2.2): `defineScopedRole(actor, ownerScope, spec)`
+   * solo puede meter en un rol local permisos de esta lista blanca (y que el
+   * actor tenga efectivos en el owner). Vacía = nadie delega nada. Los
+   * permisos de plataforma (`admin:*`, ajustes de organización) no deberían
+   * estar aquí.
+   */
+  delegablePermissions: [],
+
   hooks: { onWrite: onAuthzWrite },
 })

package/build/stubs/migration.stub

@@ -14,31 +14,57 @@ import { BaseSchema } from '@adonisjs/lucid/schema'
  * El catálogo (roles/permissions/role_permissions) es metadata compartida
  * entre drivers; los HECHOS (assignments/denies) son lo único que otro
  * driver (p.ej. openfga) materializaría fuera.
+ *
+ * Decisiones observadas en PostgreSQL y MySQL (2.5 · J3, la suite corre en
+ * los tres motores):
+ *  - `holder_uuid`/`scope_uuid` son `varchar(64)`, NO `uuid`: la identidad
+ *    es una cadena validada por la gramática del paquete (`[A-Za-z0-9._-]`,
+ *    ≤ 36) y el uuid es del consumidor; el tipo `uuid` de PostgreSQL
+ *    rechazaba cualquier id que no fuera un UUID.
+ *  - Las columnas de identidad y los slugs llevan `collate 'utf8mb4_bin'`
+ *    (solo MySQL lo compila; en PG y SQLite la comparación ya es binaria):
+ *    con la collation por defecto (`*_ci`) `abc` y `ABC` eran la misma fila
+ *    y un grant a uno autorizaba al otro.
+ *  - `expires_at` es `DATETIME(3)` (`datetime` con precisión 3): el
+ *    `timestamp` de MySQL redondea al segundo (una caducidad de +600 ms
+ *    concedía hasta +1 s) y no admite fechas más allá de 2038.
  */
 export default class extends BaseSchema {
   public async up() {
     this.schema.createTable('authz_roles', (table) => {
       table.uuid('uuid').primary().notNullable()
-      table.string('slug', 100).notNullable()
+      table.string('slug', 100).notNullable().collate('utf8mb4_bin')
       table.string('name', 100).notNullable()
       table.string('description', 500).nullable()
       // Nivel al que el rol es asignable: 'app' | 'organization' | 'unit'.
-      table.string('scope_type', 20).notNullable()
+      // Identidad: byte a byte, como el resto (2.5-B, auditor ⚪4).
+      table.string('scope_type', 20).notNullable().collate('utf8mb4_bin')
       // Rango de privilegio (mayor = más poder). Lo consume la policy de
       // asignación (role_assignment_policy): nadie otorga/quita por encima
       // de su propio rango.
       table.integer('rank').notNullable().defaultTo(0)
+      // Quién define el rol (3B · B1): `global` (el catálogo del config,
+      // `syncAuthzCatalog`) o la clave del scope que lo define
+      // (`<tipo>|<uuid>`, `defineScopedRole`). Un rol local solo existe
+      // dentro de su owner; dos tenants pueden definir `lead@unit` cada uno.
+      // Es identidad: byte a byte. `app` nunca es owner (sería global).
+      table.string('owner_scope_key', 80).notNullable().defaultTo('global').collate('utf8mb4_bin')
       table.timestamp('created_at').notNullable()
       table.timestamp('updated_at').notNullable()
 
-      table.unique(['slug', 'scope_type'], 'authz_roles_slug_scope_uq')
+      table.unique(['slug', 'scope_type', 'owner_scope_key'], 'authz_roles_slug_scope_owner_uq')
+      table.index(['owner_scope_key'], 'authz_roles_owner_idx')
     })
 
     this.schema.createTable('authz_permissions', (table) => {
       table.uuid('uuid').primary().notNullable()
       // Formato `recurso:accion` (la misma gramática que las abilities M3).
-      table.string('slug', 100).notNullable().unique()
+      table.string('slug', 100).notNullable().unique().collate('utf8mb4_bin')
       table.string('description', 500).nullable()
+      // Niveles (scope types) cuyos roles PUEDEN llevar este permiso (3B ·
+      // B5): JSON `["app","organization"]`, o NULL = cualquiera. Control de
+      // COMPOSICIÓN (sync, defineScopedRole, grant); jamás de evaluación.
+      table.string('assignable_at', 500).nullable()
       table.timestamp('created_at').notNullable()
       table.timestamp('updated_at').notNullable()
     })
@@ -65,22 +91,23 @@ export default class extends BaseSchema {
     this.schema.createTable('authz_assignments', (table) => {
       table.uuid('uuid').primary().notNullable()
       // Holder polimórfico: morph name (users/admins/integrations/...).
-      table.string('holder_type', 50).notNullable()
-      table.uuid('holder_uuid').notNullable()
+      table.string('holder_type', 50).notNullable().collate('utf8mb4_bin')
+      table.string('holder_uuid', 64).notNullable().collate('utf8mb4_bin')
       table
         .uuid('role_uuid')
         .notNullable()
         .references('uuid')
         .inTable('authz_roles')
         .onDelete('RESTRICT')
-      table.string('scope_type', 20).notNullable()
+      table.string('scope_type', 20).notNullable().collate('utf8mb4_bin')
       // Sin FK: el scope es polimórfico. El nivel 'app' usa el uuid CENTINELA
       // 00000000-... (no NULL): los motores SQL tratan cada NULL como
       // distinto y el unique no aplicaría — con centinela la idempotencia
       // del grant la respalda la constraint en TODOS los niveles (sin
       // features específicas de un motor, regla M6).
-      table.uuid('scope_uuid').notNullable()
-      table.timestamp('expires_at').nullable()
+      table.string('scope_uuid', 64).notNullable().collate('utf8mb4_bin')
+      // Milisegundos y sin tope de 2038 (ver cabecera): DATETIME(3).
+      table.datetime('expires_at', { precision: 3 }).nullable()
       table.timestamp('created_at').notNullable()
 
       table.unique(
@@ -93,17 +120,17 @@ export default class extends BaseSchema {
 
     this.schema.createTable('authz_denies', (table) => {
       table.uuid('uuid').primary().notNullable()
-      table.string('holder_type', 50).notNullable()
-      table.uuid('holder_uuid').notNullable()
+      table.string('holder_type', 50).notNullable().collate('utf8mb4_bin')
+      table.string('holder_uuid', 64).notNullable().collate('utf8mb4_bin')
       table
         .uuid('permission_uuid')
         .notNullable()
         .references('uuid')
         .inTable('authz_permissions')
         .onDelete('CASCADE')
-      table.string('scope_type', 20).notNullable()
+      table.string('scope_type', 20).notNullable().collate('utf8mb4_bin')
       // Centinela 00000000-... para 'app' (ver nota en authz_assignments).
-      table.uuid('scope_uuid').notNullable()
+      table.string('scope_uuid', 64).notNullable().collate('utf8mb4_bin')
       table.timestamp('created_at').notNullable()
 
       table.unique(
@@ -112,9 +139,26 @@ export default class extends BaseSchema {
       )
       table.index(['holder_type', 'holder_uuid'], 'authz_deny_holder_idx')
     })
+
+    // Versión COMPARTIDA del catálogo (2.1): una fila (`id = 1`) cuyo entero
+    // sube `syncAuthzCatalog` dentro de su transacción. Los memos del
+    // catálogo de todos los procesos la contrastan antes de servir: un sync
+    // en un worker se ve en los demás sin reiniciar ni pub/sub. Quien
+    // escriba `authz_*` a mano lo hace con `withAuthzCatalogWrite(async (trx)
+    // => …)`: misma transacción, versión subida como última sentencia. Sin
+    // esta fila (id = 1) toda pregunta es 503: por eso se siembra aquí.
+    this.schema.createTable('authz_catalog_version', (table) => {
+      table.integer('id').primary().notNullable()
+      table.bigInteger('version').notNullable().defaultTo(0)
+      table.timestamp('updated_at').notNullable()
+    })
+    this.defer(async (db) => {
+      await db.table('authz_catalog_version').insert({ id: 1, version: 0, updated_at: new Date() })
+    })
   }
 
   public async down() {
+    this.schema.dropTable('authz_catalog_version')
     this.schema.dropTable('authz_denies')
     this.schema.dropTable('authz_assignments')
     this.schema.dropTable('authz_role_permissions')

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "@jantstack/adonis-authz",
-  "version": "1.1.0",
+  "version": "2.0.0-alpha.1",
   "description": "Driver-based authorization engine for AdonisJS + Lucid: hierarchical scopes with downward inheritance, explicit denies, expiring assignments and polymorphic holders. Ships a self-contained database driver and an OpenFGA driver, both judged by the same executable contract suite.",
   "type": "module",
   "license": "MIT",
-  "author": "Jose Tenorio",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/JantStack/adonis-authz.git"
+    "url": "git+https://github.com/jantstack/adonis-authz.git"
   },
-  "homepage": "https://github.com/JantStack/adonis-authz#readme",
+  "homepage": "https://github.com/jantstack/adonis-authz#readme",
   "bugs": {
-    "url": "https://github.com/JantStack/adonis-authz/issues"
+    "url": "https://github.com/jantstack/adonis-authz/issues"
   },
   "keywords": [
     "adonisjs",
@@ -43,6 +42,7 @@
   "types": "./build/index.d.ts",
   "exports": {
     ".": "./build/index.js",
+    "./openfga": "./build/src/openfga.js",
     "./authz_provider": "./build/providers/authz_provider.js",
     "./services/main": "./build/services/main.js",
     "./app_access_middleware": "./build/src/middleware/app_access_middleware.js",
@@ -61,7 +61,10 @@
     "prepublishOnly": "npm run build",
     "copy:stubs": "mkdir -p build/stubs/config && cp stubs/*.stub build/stubs/ && cp stubs/config/*.stub build/stubs/config/",
     "check:purity": "node scripts/check_purity.mjs",
-    "test": "node --import @poppinss/ts-exec bin/test.ts",
+    "test": "npm run check:purity && node --import @poppinss/ts-exec bin/test.ts",
+    "test:sqlite-file": "TEST_DB=sqlite-file npm test",
+    "test:pg": "TEST_DB=pg npm test",
+    "test:mysql": "TEST_DB=mysql npm test",
     "typecheck:build": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -87,6 +90,8 @@
     "@types/node": "^22.19.1",
     "better-sqlite3": "^13.0.1",
     "luxon": "^3.7.2",
+    "mysql2": "^3.24.2",
+    "pg": "^8.23.0",
     "typescript": "~5.9.3"
   },
   "publishConfig": {