@jantstack/adonis-authz 1.0.0

package/build/stubs/migration.stub

@@ -0,0 +1,124 @@
+{{{
+  exports({ to: app.migrationsPath(migration.folder ?? '', migration.fileName) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * Tablas del motor de autorización propio (driver `database`).
+ *
+ * Esquema jerárquico desde el día uno: scope_type/scope_uuid preparan los
+ * niveles organization (T2) y unit (T3) aunque en T1 solo opere `app`
+ * (scope_uuid null). Todo es SQL estándar del schema builder — sin features
+ * específicas de un motor (regla M6 del chasis).
+ *
+ * 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.
+ */
+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('name', 100).notNullable()
+      table.string('description', 500).nullable()
+      // Nivel al que el rol es asignable: 'app' | 'organization' | 'unit'.
+      table.string('scope_type', 20).notNullable()
+      // 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)
+      table.timestamp('created_at').notNullable()
+      table.timestamp('updated_at').notNullable()
+
+      table.unique(['slug', 'scope_type'], 'authz_roles_slug_scope_uq')
+    })
+
+    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('description', 500).nullable()
+      table.timestamp('created_at').notNullable()
+      table.timestamp('updated_at').notNullable()
+    })
+
+    this.schema.createTable('authz_role_permissions', (table) => {
+      table.uuid('uuid').primary().notNullable()
+      table
+        .uuid('role_uuid')
+        .notNullable()
+        .references('uuid')
+        .inTable('authz_roles')
+        .onDelete('CASCADE')
+      table
+        .uuid('permission_uuid')
+        .notNullable()
+        .references('uuid')
+        .inTable('authz_permissions')
+        .onDelete('CASCADE')
+      table.timestamp('created_at').notNullable()
+
+      table.unique(['role_uuid', 'permission_uuid'], 'authz_role_perms_uq')
+    })
+
+    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
+        .uuid('role_uuid')
+        .notNullable()
+        .references('uuid')
+        .inTable('authz_roles')
+        .onDelete('RESTRICT')
+      table.string('scope_type', 20).notNullable()
+      // 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.timestamp('created_at').notNullable()
+
+      table.unique(
+        ['holder_type', 'holder_uuid', 'role_uuid', 'scope_type', 'scope_uuid'],
+        'authz_asg_holder_role_scope_uq'
+      )
+      table.index(['holder_type', 'holder_uuid'], 'authz_asg_holder_idx')
+      table.index(['scope_type', 'scope_uuid'], 'authz_asg_scope_idx')
+    })
+
+    this.schema.createTable('authz_denies', (table) => {
+      table.uuid('uuid').primary().notNullable()
+      table.string('holder_type', 50).notNullable()
+      table.uuid('holder_uuid').notNullable()
+      table
+        .uuid('permission_uuid')
+        .notNullable()
+        .references('uuid')
+        .inTable('authz_permissions')
+        .onDelete('CASCADE')
+      table.string('scope_type', 20).notNullable()
+      // Centinela 00000000-... para 'app' (ver nota en authz_assignments).
+      table.uuid('scope_uuid').notNullable()
+      table.timestamp('created_at').notNullable()
+
+      table.unique(
+        ['holder_type', 'holder_uuid', 'permission_uuid', 'scope_type', 'scope_uuid'],
+        'authz_deny_holder_perm_scope_uq'
+      )
+      table.index(['holder_type', 'holder_uuid'], 'authz_deny_holder_idx')
+    })
+  }
+
+  public async down() {
+    this.schema.dropTable('authz_denies')
+    this.schema.dropTable('authz_assignments')
+    this.schema.dropTable('authz_role_permissions')
+    this.schema.dropTable('authz_permissions')
+    this.schema.dropTable('authz_roles')
+  }
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@jantstack/adonis-authz",
+  "version": "1.0.0",
+  "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"
+  },
+  "homepage": "https://github.com/JantStack/adonis-authz#readme",
+  "bugs": {
+    "url": "https://github.com/JantStack/adonis-authz/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "adonisjs-7",
+    "adonisjs-package",
+    "lucid",
+    "lucid-orm",
+    "authorization",
+    "authz",
+    "rbac",
+    "acl",
+    "permissions",
+    "roles",
+    "openfga",
+    "zanzibar",
+    "multi-tenancy",
+    "typescript",
+    "esm",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "backend"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": "./build/index.js",
+    "./authz_provider": "./build/providers/authz_provider.js",
+    "./services/main": "./build/services/main.js",
+    "./app_access_middleware": "./build/src/middleware/app_access_middleware.js",
+    "./commands": "./build/commands/main.js",
+    "./commands/*": "./build/commands/*.js",
+    "./testing": "./build/src/testing/main.js",
+    "./types": "./build/src/types.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run check:purity && rm -rf build && tsc && npm run copy:stubs",
+    "typecheck": "tsc --noEmit",
+    "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"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/lucid": "^22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@openfga/sdk": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "^7.3.1",
+    "@adonisjs/lucid": "^22.4.2",
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^5.3.0",
+    "@openfga/sdk": "^0.9.6",
+    "@types/luxon": "^3.7.2",
+    "@types/node": "^22.19.1",
+    "luxon": "^3.7.2",
+    "typescript": "~5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "axios": "^1.18.1"
+  }
+}