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

package/build/index.js

@@ -4,7 +4,7 @@
  */
 export { AuthorizationManager, DEFAULT_MAX_SCOPES, DEFAULT_MAX_DESCENDANTS, MAX_SCOPE_BOUND, DEFAULT_VIEW_MAX_AGE_MS, expandExcludedSubtrees } from './src/manager.js';
 export { defineConfig } from './src/define_config.js';
-export { syncAuthzCatalog, diffAuthzCatalog, catalogInSync, formatCatalogDiff, formatScopedRoles, formatShadowedRoles, runCatalogDiff, syncCatalogs, } from './src/catalog.js';
+export { syncAuthzCatalog, diffAuthzCatalog, catalogInSync, formatCatalogDiff, formatScopedRoles, formatShadowedRoles, runCatalogDiff, syncCatalogs, } from './src/catalog/catalog.js';
 /**
  * Memo del catálogo (2.1): se revalida contra la versión compartida
  * `authz_catalog_version`, que `syncAuthzCatalog` sube como última sentencia
@@ -13,7 +13,7 @@ export { syncAuthzCatalog, diffAuthzCatalog, catalogInSync, formatCatalogDiff, f
  * final: todos los procesos lo ven) — `bumpAuthzCatalogVersion(trx)` exige
  * ese trx; `invalidateAuthzCatalog()` solo alcanza a este proceso.
  */
-export { CatalogCache, invalidateAuthzCatalog, bumpAuthzCatalogVersion, withAuthzCatalogWrite, readAuthzCatalogVersion, CATALOG_VERSION_TABLE, GLOBAL_OWNER_KEY, } from './src/catalog_cache.js';
+export { CatalogCache, invalidateAuthzCatalog, bumpAuthzCatalogVersion, withAuthzCatalogWrite, readAuthzCatalogVersion, CATALOG_VERSION_TABLE, GLOBAL_OWNER_KEY, } from './src/catalog/catalog_cache.js';
 /**
  * Memo de ancestros de una instancia (2.1), solo para el camino de lectura.
  * `authorization.forRequest()` ya lo aplica por ti.
@@ -25,21 +25,49 @@ export { memoizeAncestors } from './src/memoize_ancestors.js';
  * `descendantsOf` opt-in (CTE recursiva, PG y SQLite) para `authorizedScopes`.
  */
 export { hierarchicalScopeResolver } from './src/hierarchical_resolver.js';
-export { sqlDescendantsOf } from './src/sql_descendants.js';
+export { sqlDescendantsOf, sqlScopeEdges } from './src/sql_descendants.js';
+/**
+ * **La outbox del árbol** (3b-2d): `sqlScopeOutbox` implementa el puerto
+ * `ScopeOutbox` sobre Lucid, con la tabla de
+ * `stubs/scopes_outbox_migration.stub` (cópiala a tus migraciones:
+ * `configure` no la publica, porque la outbox es opt-in). Con
+ * `scopes.outbox` declarada, `authorization.scopes.attached/moved/detached`
+ * ENCOLAN el cambio en tu transacción en vez de escribir en el backend, y lo
+ * aplica `node ace authz:scopes:relay`. Cualquier implementación del puerto
+ * vale: el paquete no impone tabla.
+ */
+export { sqlScopeOutbox } from './src/scope_outbox.js';
 /**
  * El backend de autorización no respondió (503). Tipo PROPIO a propósito: sin
  * él escaparía el error del SDK del driver, y distinguir "backend caído"
  * obligaría a importar ese SDK — acoplando el call-site al backend que este
  * paquete existe para abstraer.
  */
-export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, StoreNotEmptyError, ActorRequiredError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, UnsupportedDialectError, ScopeTooDeepError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, } from './src/errors.js';
+export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, WriteConflictError, ActorRequiredError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, TooManyLocalRolesError, MassPurgeRefusedError, PruneInterruptedError, UnsupportedDialectError, ScopeTooDeepError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, ModelTooLargeError, RelationConfigError, RelationTypeUnknownError, RelationUnknownError, ScopeTreeDriftError, ScopeDriftUnguardedError, AuthorizationFrozenError, FreezeHeldError, MassReconcileRefusedError, ReconcileTooLargeError, } from './src/errors.js';
 /**
  * Validación de identidad y de slugs (422). La aplica el manager en cada
  * llamada y los drivers por defensa en profundidad; se exporta para que un
  * consumidor valide en su borde (un formulario, un importador) con la MISMA
  * regla y no con una copia.
  */
-export { assertIdentity, assertSubject, assertScope, assertValidSlug, assertExpiresAt, assertNoSlugCollisions, normalizeRoleQuery, scopeKey, scopeFromKey, IDENTITY_LIMITS, MAX_SLUG_LENGTH, RESERVED_SLUGS, RESERVED_SLUG_PREFIXES, } from './src/identity.js';
+export { assertIdentity, assertSubject, assertScope, assertValidSlug, assertExpiresAt, assertNoSlugCollisions, normalizeRoleQuery, scopeKey, scopeFromKey, IDENTITY_LIMITS, MAX_SLUG_LENGTH, RESERVED_SLUGS, RESERVED_SLUG_PREFIXES, RESERVED_FACTS_TYPES, } from './src/identity.js';
+/**
+ * ReBAC genérico (Fase 4, `relations/`). El puerto `RelationsDriver` vive en
+ * `./src/types.js` (el contrato); aquí salen la API declarativa
+ * `defineRelationsConfig`, la fachada `RelationsManager` (F-05 + `assertWrite`
+ * + `actor`) y los tipos de la config.
+ */
+export { defineRelationsConfig } from './src/relations/define_relations_config.js';
+export { RelationsManager } from './src/relations/manager.js';
+export { reconcileRelations } from './src/relations/reconcile.js';
+// La config de relaciones PERSISTIDA (🟡3): API de PLATAFORMA (bajo el gate de
+// versión, invariante 14). La CONSUME `authz:relations:reconcile` (config del
+// destino, para la deriva del modelo fusionado en --dry-run).
+export { saveRelationsConfig, readRelationsConfig, readRelationsConfigSpec, } from './src/relations_config_store.js';
+// El driver `database` de relaciones (el consumidor lo cablea en
+// `relations.drivers` de config/authorization.ts). El driver `openfga` de
+// relaciones NO sale de aquí: vive en el subpath `/openfga` (peer opcional).
+export { DatabaseRelationsDriver } from './src/drivers/database_relations_driver.js';
 export { resolveGrantExpiry, isActiveExpiry, sameInstant } from './src/expiry.js';
 export { DatabaseAuthorizationDriver, APP_SCOPE_DB_UUID } from './src/drivers/database_driver.js';
 /**
@@ -47,7 +75,18 @@ export { DatabaseAuthorizationDriver, APP_SCOPE_DB_UUID } from './src/drivers/da
  * `@jantstack/adonis-authz/openfga`, que es lo único que importa el peer
  * opcional `@openfga/sdk`. Un consumidor solo-database arranca sin él (D9).
  */
-export { APP_SCOPE, APP_SCOPE_TYPE } from './src/types.js';
+export { APP_SCOPE, APP_SCOPE_TYPE, DEFAULT_RECONCILE_MAX_TUPLES } from './src/types.js';
+export { isRelUserset } from './src/types.js';
+/**
+ * **¿De quién es esta transacción?** (L-1 · 🟠 9, regla del puerto `{trx}`):
+ * la ÚNICA comprobación con la que una escritura del paquete —la outbox de
+ * `scopes.*` hoy; `grant`/`relate` de un driver con `transactionalWrites:
+ * true`— se inscribe en `{ transaction }`: tiene que ser una transacción
+ * ABIERTA de Lucid de la conexión de quien escribe (otra conexión, un
+ * `QueryClient` o el `db` entero son 500 `E_AUTHZ_CONFIG`). Un driver de
+ * terceros que declare `transactionalWrites: true` la llama con SU conexión.
+ */
+export { assertCallerTransaction } from './src/shared/transaction_guard.js';
 export { default as AuthzRole } from './src/models/authz_role.js';
 export { default as AuthzPermission } from './src/models/authz_permission.js';
 export { default as AuthzRolePermission } from './src/models/authz_role_permission.js';

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,eAAe,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAEtK,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAErD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAA;AAGzB;;;;;;;GAOG;AACH,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,wBAAwB,CAAA;AAY/B;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAE7D;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAE1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAG3D;;;;;GAKG;AACH,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,OAAO,EACL,cAAc,EACd,aAAa,EACb,WAAW,EACX,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,GACvB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAEjF,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAGjG;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AA8B1D,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,kCAAkC,CAAA;AAC7E,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uCAAuC,CAAA;AACtF,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,kCAAkC,CAAA;AAC7E,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/build/providers/authz_provider.d.ts

@@ -1,13 +1,37 @@
 import type { ApplicationService } from '@adonisjs/core/types';
 import { AuthorizationManager } from '../src/manager.js';
+import { RelationsManager } from '../src/relations/manager.js';
+import type { AuthorizationConfig } from '../src/define_config.js';
 declare module '@adonisjs/core/types' {
     interface ContainerBindings {
         'authz.manager': AuthorizationManager;
+        'authz.relations': RelationsManager;
     }
 }
 /**
- * Registra el manager de autorización como singleton del contenedor,
- * construido desde `config/authorization.ts` de la aplicación.
+ * **Construye el `RelationsManager` de servicio desde el config** (Fase 4-8) —
+ * el análogo de resolver el `AuthorizationManager` del provider, pero para el
+ * puerto de relaciones. Función PURA (no toca el contenedor) para tener su caso
+ * sin montar la app: recibe el config y devuelve el manager cableado.
+ *
+ * El driver ACTIVO sale de `relations.drivers[relations.default ?? default]`
+ * (los drivers de relaciones se nombran igual que los de roles); la config, de
+ * `relations.config` (la MISMA que capturan las factories de `drivers`, así que
+ * la frontera F-05 del manager y la del driver son la misma). `requireActor` se
+ * hereda del config de roles: la política de auditoría es una sola.
+ *
+ * Sin `relations.config` o sin el driver activo lanza con la receta: las
+ * relaciones son OPT-IN y este servicio solo existe si el consumidor las
+ * declaró.
+ */
+export declare function buildRelationsManager(config: AuthorizationConfig): Promise<RelationsManager>;
+/**
+ * Registra los managers de autorización como singletons del contenedor,
+ * construidos desde `config/authorization.ts` de la aplicación:
+ *
+ *  - `authz.manager`: el motor de roles (siempre).
+ *  - `authz.relations`: el motor de ReBAC (solo si el consumidor declaró
+ *    `relations.config`; si no, resolverlo lanza con la receta).
  */
 export default class AuthzProvider {
     protected app: ApplicationService;

package/build/providers/authz_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authz_provider.d.ts","sourceRoot":"","sources":["../../providers/authz_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAExD,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAiB,iBAAiB;QAChC,eAAe,EAAE,oBAAoB,CAAA;KACtC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IACpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;CAWT"}
+{"version":3,"file":"authz_provider.d.ts","sourceRoot":"","sources":["../../providers/authz_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAElE,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAiB,iBAAiB;QAChC,eAAe,EAAE,oBAAoB,CAAA;QACrC,iBAAiB,EAAE,gBAAgB,CAAA;KACpC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4BlG;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IACpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;CAqBT"}

package/build/providers/authz_provider.js

@@ -1,7 +1,53 @@
 import { AuthorizationManager } from '../src/manager.js';
+import { RelationsManager } from '../src/relations/manager.js';
 /**
- * Registra el manager de autorización como singleton del contenedor,
- * construido desde `config/authorization.ts` de la aplicación.
+ * **Construye el `RelationsManager` de servicio desde el config** (Fase 4-8) —
+ * el análogo de resolver el `AuthorizationManager` del provider, pero para el
+ * puerto de relaciones. Función PURA (no toca el contenedor) para tener su caso
+ * sin montar la app: recibe el config y devuelve el manager cableado.
+ *
+ * El driver ACTIVO sale de `relations.drivers[relations.default ?? default]`
+ * (los drivers de relaciones se nombran igual que los de roles); la config, de
+ * `relations.config` (la MISMA que capturan las factories de `drivers`, así que
+ * la frontera F-05 del manager y la del driver son la misma). `requireActor` se
+ * hereda del config de roles: la política de auditoría es una sola.
+ *
+ * Sin `relations.config` o sin el driver activo lanza con la receta: las
+ * relaciones son OPT-IN y este servicio solo existe si el consumidor las
+ * declaró.
+ */
+export async function buildRelationsManager(config) {
+    const relations = config.relations;
+    if (!relations?.config) {
+        throw new Error('No hay `relations.config` en config/authorization.ts: declara `relations: { config: ' +
+            'defineRelationsConfig({...}), drivers: {...} }` para usar el servicio de relaciones ' +
+            '(@jantstack/adonis-authz/services/relations).');
+    }
+    const driverKey = relations.default ?? config.default;
+    const factory = relations.drivers?.[driverKey];
+    if (!factory) {
+        throw new Error(`No hay driver de relaciones '${driverKey}' en \`relations.drivers\` de config/authorization.ts ` +
+            `(declara la factory bajo esa clave, o fija \`relations.default\`).`);
+    }
+    const driver = await factory();
+    return new RelationsManager(driver, relations.config, {
+        requireActor: config.requireActor,
+        // R-15: el MISMO reloj que el motor de roles (`config.clock`, 2.5 · J1).
+        clock: config.clock,
+        // L-1 · J1: la MISMA barrera del freeze (y su deadline) que el motor de roles.
+        freezeTimeoutMs: config.freezeTimeoutMs,
+        // L-2 · puerta 2: el flag de relaciones manda; si no está, el del raíz.
+        requireTransactionalWrites: relations.requireTransactionalWrites ?? config.requireTransactionalWrites,
+        driverName: driverKey,
+    });
+}
+/**
+ * Registra los managers de autorización como singletons del contenedor,
+ * construidos desde `config/authorization.ts` de la aplicación:
+ *
+ *  - `authz.manager`: el motor de roles (siempre).
+ *  - `authz.relations`: el motor de ReBAC (solo si el consumidor declaró
+ *    `relations.config`; si no, resolverlo lanza con la receta).
  */
 export default class AuthzProvider {
     app;
@@ -16,6 +62,13 @@ export default class AuthzProvider {
             }
             return new AuthorizationManager(config);
         });
+        this.app.container.singleton('authz.relations', async () => {
+            const config = this.app.config.get('authorization');
+            if (!config) {
+                throw new Error('Falta config/authorization.ts — ejecuta: node ace configure @jantstack/adonis-authz');
+            }
+            return buildRelationsManager(config);
+        });
     }
 }
 //# sourceMappingURL=authz_provider.js.map

package/build/providers/authz_provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"authz_provider.js","sourceRoot":"","sources":["../../providers/authz_provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAQxD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IACV;IAAtB,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,QAAQ;QACN,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,eAAe,EAAE,KAAK,IAAI,EAAE;YACvD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAQ,CAAA;YAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAA;YACH,CAAC;YACD,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAA;QACzC,CAAC,CAAC,CAAA;IACJ,CAAC;CACF"}
+{"version":3,"file":"authz_provider.js","sourceRoot":"","sources":["../../providers/authz_provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAU9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAA2B;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IAClC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,sFAAsF;YACpF,sFAAsF;YACtF,+CAA+C,CAClD,CAAA;IACH,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAA;IACrD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAA;IAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,gCAAgC,SAAS,wDAAwD;YAC/F,oEAAoE,CACvE,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAA;IAC9B,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE;QACpD,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,yEAAyE;QACzE,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,+EAA+E;QAC/E,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,wEAAwE;QACxE,0BAA0B,EAAE,SAAS,CAAC,0BAA0B,IAAI,MAAM,CAAC,0BAA0B;QACrG,UAAU,EAAE,SAAS;KACtB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IACV;IAAtB,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,QAAQ;QACN,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,eAAe,EAAE,KAAK,IAAI,EAAE;YACvD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAQ,CAAA;YAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAA;YACH,CAAC;YACD,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAA;QACzC,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAQ,CAAA;YAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAA;YACH,CAAC;YACD,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAA;QACtC,CAAC,CAAC,CAAA;IACJ,CAAC;CACF"}

package/build/services/relations.d.ts

@@ -0,0 +1,14 @@
+import type { RelationsManager } from '../src/relations/manager.js';
+/**
+ * Singleton del motor de relaciones (ReBAC), resuelto del contenedor cuando la
+ * app ha booteado — el análogo de `services/main` para el puerto
+ * `RelationsDriver`. Solo existe si el consumidor declaró `relations.config` en
+ * `config/authorization.ts`; si no, resolverlo lanza con la receta.
+ *
+ *   import relations from '@jantstack/adonis-authz/services/relations'
+ *   await relations.relate(user, 'viewer', { type: 'document', id }, APP_SCOPE)
+ *   await relations.check(user, 'viewer', { type: 'document', id }, APP_SCOPE)
+ */
+declare let relations: RelationsManager;
+export { relations as default };
+//# sourceMappingURL=relations.d.ts.map

package/build/services/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../services/relations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAEnE;;;;;;;;;GASG;AACH,QAAA,IAAI,SAAS,EAAE,gBAAgB,CAAA;AAM/B,OAAO,EAAE,SAAS,IAAI,OAAO,EAAE,CAAA"}

package/build/services/relations.js

@@ -0,0 +1,17 @@
+import app from '@adonisjs/core/services/app';
+/**
+ * Singleton del motor de relaciones (ReBAC), resuelto del contenedor cuando la
+ * app ha booteado — el análogo de `services/main` para el puerto
+ * `RelationsDriver`. Solo existe si el consumidor declaró `relations.config` en
+ * `config/authorization.ts`; si no, resolverlo lanza con la receta.
+ *
+ *   import relations from '@jantstack/adonis-authz/services/relations'
+ *   await relations.relate(user, 'viewer', { type: 'document', id }, APP_SCOPE)
+ *   await relations.check(user, 'viewer', { type: 'document', id }, APP_SCOPE)
+ */
+let relations;
+await app.booted(async () => {
+    relations = await app.container.make('authz.relations');
+});
+export { relations as default };
+//# sourceMappingURL=relations.js.map

package/build/services/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../../services/relations.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,6BAA6B,CAAA;AAG7C;;;;;;;;;GASG;AACH,IAAI,SAA2B,CAAA;AAE/B,MAAM,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC1B,SAAS,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;AACzD,CAAC,CAAC,CAAA;AAEF,OAAO,EAAE,SAAS,IAAI,OAAO,EAAE,CAAA"}

package/build/src/{catalog.d.ts → catalog/catalog.d.ts}

@@ -1,4 +1,4 @@
-import type { CatalogRoleRef, CatalogSpec, ScopeChainResolver, ScopeType } from './types.js';
+import type { CatalogProjection, CatalogProjectionReport, CatalogProjectionSnapshot, CatalogRoleRef, CatalogSpec, ScopeChainResolver, ScopeType } from '../types.js';
 /**
  * `assignableAt` de un permiso tal como se GUARDA (`authz_permissions.assignable_at`):
  * JSON ordenado y sin duplicados, o `null` = cualquier nivel. Ordenado para
@@ -60,6 +60,12 @@ export interface CatalogSyncReport {
         role: CatalogRoleRef;
         permission: string;
     }>;
+    /**
+     * Lo que movió la proyección del driver, si se pasó una (3b-2a · A5).
+     * Ausente sin `projection`. Nunca un booleano: una proyección que no dice
+     * cuánto escribió y cuánto borró no se vigila.
+     */
+    projection?: CatalogProjectionReport;
 }
 export interface SyncCatalogOptions {
     /**
@@ -76,6 +82,22 @@ export interface SyncCatalogOptions {
      * cliente SQL: el sync corre en el arranque de un despliegue (D15).
      */
     timeoutMs?: number;
+    /**
+     * Proyección DERIVADA del catálogo en el backend de un driver (3b-2a · A5;
+     * regla del catálogo reescrita, panel 2 cruce 7). Se INYECTA en vez de
+     * importarse: este módulo es la ruta de un consumidor solo-database y no
+     * puede tirar del SDK de OpenFGA (regla 3 de `check_purity.mjs`).
+     *
+     * Con ella, el sync (a) comprueba ANTES de escribir que el catálogo que va
+     * a quedar es publicable en ese backend —cotas de nombre y techo del
+     * modelo, A3/A4—, y (b) rehace la proyección con el catálogo ya
+     * CONFIRMADO. En ese orden: la fuente de verdad son las tablas `authz_*`,
+     * y una proyección que se adelantara a la transacción concedería lo que la
+     * base no respalda. Si la proyección falla, el catálogo ya está escrito y
+     * lo que queda es deriva reconstruible (`authz:reconcile`), no una
+     * decisión inventada.
+     */
+    projection?: CatalogProjection;
 }
 /**
  * Sincroniza un catálogo (roles + permisos + vínculos) a las tablas `authz_*`.
@@ -97,6 +119,23 @@ export interface SyncCatalogOptions {
  * driver externo (openfga) materializa aparte solo los hechos.
  */
 export declare function syncAuthzCatalog(catalog: CatalogSpec, options?: SyncCatalogOptions): Promise<CatalogSyncReport>;
+/**
+ * **La foto del catálogo que se PROYECTA** (3b-2a · A5), leída de `authz_*`.
+ *
+ * Es el catálogo ENTERO, no el spec que se está sincronizando: la proyección
+ * es un espejo y lo que sobra en el backend solo se sabe comparando contra
+ * todo. `syncAuthzCatalog` la lee DENTRO de su transacción (coherente con lo
+ * que acaba de escribir) y `authz:reconcile` fuera, contra la base: las dos
+ * tienen que construir exactamente la misma foto, o reconcile "arreglaría" en
+ * cada pasada lo que el sync acaba de dejar bien. Por eso está aquí y no
+ * duplicada en el driver.
+ *
+ * `source` es cualquier cosa con `from(tabla)` (el `db` de Lucid o una
+ * transacción) y `sql` envuelve cada consulta con el deadline de quien llama.
+ */
+export declare function readCatalogProjectionSnapshot(source: {
+    from(table: string): any;
+}, sql?: <T>(operation: string, fn: () => Promise<T>) => Promise<T>): Promise<CatalogProjectionSnapshot>;
 export interface CatalogLinkRef {
     role: string;
     scopeType: ScopeType;
@@ -223,7 +262,7 @@ export declare function formatScopedRoles(diff: CatalogDiff): string[];
  * mientras duren, ese slug es 422 `E_AUTHZ_AMBIGUOUS_ROLE` en la cadena de
  * su owner y hay que operar por `{ uuid }` (o purgar uno de los dos).
  */
-export declare function formatShadowedRoles(diff: CatalogDiff): string[];
+export declare function formatShadowedRoles(diff: Pick<CatalogDiff, 'shadowedByGlobal' | 'shadowedByAncestor'>): string[];
 /** Fábricas de catálogo tal como se declaran en `config.catalogs`. */
 export type CatalogSource = () => Promise<CatalogSpec> | CatalogSpec;
 /**

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

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

package/build/src/{catalog.js → catalog/catalog.js}

@@ -1,10 +1,10 @@
 import db from '@adonisjs/lucid/services/db';
 import { v7 as uuidv7 } from 'uuid';
-import { assertCatalogUuid, assertNoSlugCollisions, assertScopeType, assertValidSlug, scopeFromKey, scopeKey } from './identity.js';
-import { CatalogConflictError, InvalidIdentityError, RoleNotAssignableAtError, UnknownPermissionError } from './errors.js';
-import { guardSql } from './drivers/backend_guard.js';
+import { assertCatalogUuid, assertNoSlugCollisions, assertScopeType, assertValidSlug, scopeFromKey, scopeKey } from '../identity.js';
+import { CatalogConflictError, InvalidIdentityError, RoleNotAssignableAtError, UnknownPermissionError } from '../errors.js';
+import { guardSql } from '../shared/backend_guard.js';
 import { GLOBAL_OWNER_KEY, invalidateAuthzCatalog, parseAssignableAt, withAuthzCatalogWrite } from './catalog_cache.js';
-import { systemClock } from './clock.js';
+import { systemClock } from '../clock.js';
 /**
  * `assignableAt` de un permiso tal como se GUARDA (`authz_permissions.assignable_at`):
  * JSON ordenado y sin duplicados, o `null` = cualquier nivel. Ordenado para
@@ -158,15 +158,29 @@ export async function syncAuthzCatalog(catalog, options = {}) {
     // que confirmó tiene que verse en la siguiente pregunta también con
     // `everyMs`, y uno que falló al confirmar no se sabe si confirmó. Recargar
     // de más es gratis; servir un catálogo viejo no.
+    let report;
+    let snapshot = null;
     try {
-        return await syncInTransaction(catalog, prune, sql, one, timeoutMs);
+        const done = await syncInTransaction(catalog, prune, sql, one, timeoutMs, options.projection);
+        report = done.report;
+        snapshot = done.snapshot;
     }
     finally {
         invalidateAuthzCatalog();
     }
+    // La proyección se rehace con el catálogo YA CONFIRMADO y fuera de la
+    // transacción: el store no participa del commit de SQL (no hay 2PC), así
+    // que la fuente de verdad se escribe primero y lo derivado después. Un
+    // fallo aquí deja deriva —reconstruible con `authz:reconcile`—, nunca una
+    // concesión que las tablas no respalden.
+    if (options.projection && snapshot) {
+        report.projection = await options.projection.project(snapshot);
+    }
+    return report;
 }
-async function syncInTransaction(catalog, prune, sql, one, timeoutMs) {
+async function syncInTransaction(catalog, prune, sql, one, timeoutMs, projection) {
     const report = { shadowedByGlobal: [], assignableAtViolations: [] };
+    let snapshot = null;
     await sql('sync', () => withAuthzCatalogWrite(async (trx) => {
         // 0. Colisión tras codificar también contra lo que YA hay en la base:
         //    `docs:write` de otro catálogo y `docs_write` de este serían UNA
@@ -176,6 +190,19 @@ async function syncInTransaction(catalog, prune, sql, one, timeoutMs) {
             ...catalog.permissions.map((p) => p.slug),
             ...stored.map((p) => p.slug),
         ]);
+        // 0.5 ¿El catálogo que va a quedar es PUBLICABLE en el backend del
+        //     driver? (3b-2a · A3/A4). ANTES de escribir nada: si se escribiera
+        //     primero, un catálogo que rebasa el techo del modelo quedaría en la
+        //     base sin poder proyectarse nunca y con el store sin poder
+        //     regenerarse. Los permisos que van a existir son los de la base más
+        //     los del spec (el sync no borra permisos).
+        if (projection) {
+            const willExist = new Set([
+                ...stored.map((p) => String(p.slug)),
+                ...catalog.permissions.map((p) => p.slug),
+            ]);
+            projection.assertPublishable([...willExist].sort());
+        }
         // 1. Permisos: upsert por slug; `assignable_at` manda el config (B5).
         for (const perm of catalog.permissions) {
             const existing = await one('sync.permission', () => trx.from('authz_permissions').where('slug', perm.slug).select('uuid', 'assignable_at'));
@@ -331,11 +358,54 @@ async function syncInTransaction(catalog, prune, sql, one, timeoutMs) {
                 });
             }
         }
+        // 3.9 Foto del catálogo para la proyección del driver (3b-2a · A5).
+        //     Se lee DENTRO de la transacción para que sea coherente, y se
+        //     proyecta fuera, con el commit hecho. Es el catálogo ENTERO, no el
+        //     spec: la proyección es un espejo, y lo que sobra en el store solo
+        //     se sabe comparando contra todo.
+        if (projection) {
+            snapshot = await readCatalogProjectionSnapshot(trx, (operation, fn) => sql(`sync.projection.${operation}`, fn));
+        }
         // 4. La versión compartida la sube `withAuthzCatalogWrite` al salir de
         //    aquí, como última sentencia: o se confirma todo (catálogo nuevo +
         //    versión nueva) o nada.
     }, { driver: 'catalog', timeoutMs }));
-    return report;
+    return { report, snapshot };
+}
+/**
+ * **La foto del catálogo que se PROYECTA** (3b-2a · A5), leída de `authz_*`.
+ *
+ * Es el catálogo ENTERO, no el spec que se está sincronizando: la proyección
+ * es un espejo y lo que sobra en el backend solo se sabe comparando contra
+ * todo. `syncAuthzCatalog` la lee DENTRO de su transacción (coherente con lo
+ * que acaba de escribir) y `authz:reconcile` fuera, contra la base: las dos
+ * tienen que construir exactamente la misma foto, o reconcile "arreglaría" en
+ * cada pasada lo que el sync acaba de dejar bien. Por eso está aquí y no
+ * duplicada en el driver.
+ *
+ * `source` es cualquier cosa con `from(tabla)` (el `db` de Lucid o una
+ * transacción) y `sql` envuelve cada consulta con el deadline de quien llama.
+ */
+export async function readCatalogProjectionSnapshot(source, sql = (_operation, fn) => fn()) {
+    const permissions = await sql('permissions', () => source.from('authz_permissions').select('uuid', 'slug'));
+    const roles = await sql('roles', () => source.from('authz_roles').select('uuid'));
+    const links = await sql('links', () => source.from('authz_role_permissions').select('role_uuid', 'permission_uuid'));
+    const slugByUuid = new Map(permissions.map((p) => [String(p.uuid), String(p.slug)]));
+    const permissionsByRole = new Map(roles.map((r) => [String(r.uuid), []]));
+    for (const link of links) {
+        const slug = slugByUuid.get(String(link.permission_uuid));
+        const list = permissionsByRole.get(String(link.role_uuid));
+        // Un vínculo sin rol o sin permiso no existe (FK): si apareciera,
+        // proyectarlo sería inventar catálogo.
+        if (slug && list)
+            list.push(slug);
+    }
+    return {
+        permissions: [...slugByUuid.values()].sort(),
+        roles: [...permissionsByRole.entries()]
+            .map(([uuid, perms]) => ({ uuid, permissions: perms.sort() }))
+            .sort((a, b) => (a.uuid < b.uuid ? -1 : a.uuid > b.uuid ? 1 : 0)),
+    };
 }
 /**
  * Compara un spec con lo que hay en `authz_*`, sin escribir. Igual que el
@@ -555,12 +625,22 @@ async function classifyHomonyms(sql, resolveChain) {
         // eso dejaba de detectarse una pareja de locales CONTRADICTORIA (dos
         // owners que se declaran ancestro el uno del otro), que es la única
         // deriva de verdad de esta clasificación: un caso ciego nuevo.
-        for (const a of locals) {
-            for (const b of locals) {
+        // 3b-1 · T-3b 3 (tester 3F · §6.3): UNA línea por rol ENSOMBRECIDO, no
+        // una por pareja. Con owners anidados a > b > c salían tres (a→b, a→c,
+        // b→c) para tres roles, y la tercera no añadía nada: lo que el operador
+        // necesita saber es qué `(slug, nivel)` está muerto y quién manda ahí.
+        // El ensombrecedor que se nombra es el MÁS AUTORIZADO —el ancestro más
+        // alto de la cadena del ensombrecido—, que es el orden que 3F · S3 fijó.
+        for (const b of locals) {
+            const chainB = await chainOf(b);
+            if (!chainB)
+                continue;
+            const shadowers = [];
+            for (const a of locals) {
                 if (a === b)
                     continue;
                 // `a` está en la cadena de `b`: `a` es su ancestro y lo ensombrece.
-                if (!(await chainOf(b))?.includes(a))
+                if (!chainB.includes(a))
                     continue;
                 if ((await chainOf(a))?.includes(b)) {
                     // Y `b` en la de `a`: el árbol se contradice y nadie manda.
@@ -570,8 +650,13 @@ async function classifyHomonyms(sql, resolveChain) {
                     }
                     continue;
                 }
-                result.shadowedByAncestor.push({ slug, scopeType, owner: b, shadowedBy: a });
+                shadowers.push(a);
             }
+            if (!shadowers.length)
+                continue;
+            // Más lejos en la cadena de `b` = más arriba en el árbol = más autoridad.
+            shadowers.sort((x, y) => chainB.indexOf(y) - chainB.indexOf(x));
+            result.shadowedByAncestor.push({ slug, scopeType, owner: b, shadowedBy: shadowers[0] });
         }
     }
     return result;
@@ -692,11 +777,31 @@ export async function runCatalogDiff(catalogs, options = {}) {
     // extraerlos, y sus líneas salían indentadas DENTRO del bloque de
     // diferencias del último catálogo, como si fueran suyas).
     let scoped = [];
-    let shadowed = [];
+    // 3b-1 · T-3b 1 (tester 3F · §6.1): las sombras se ACUMULAN sobre todos los
+    // catálogos, con deduplicación. `diff.shadowedByGlobal` tiene una fuente
+    // DEPENDIENTE del spec (un rol del spec homónimo de un local), así que
+    // tomarlas del índice 0 perdía por completo las que causaba un rol del
+    // catálogo #2: no salían como línea de sombras ni como diferencia de ese
+    // catálogo. `scopedRoles` sí sale del índice 0: lee la BASE y no depende
+    // del spec, así que repetir el diff entero solo para él sería gratuito
+    // (3E · Q6).
+    const sombras = {
+        shadowedByGlobal: [],
+        shadowedByAncestor: [],
+    };
     for (const [index, spec] of specs.entries()) {
         const diff = await diffAuthzCatalog(spec, options);
-        if (index === 0)
-            shadowed = formatShadowedRoles(diff);
+        for (const s of diff.shadowedByGlobal) {
+            if (sombras.shadowedByGlobal.some((x) => x.slug === s.slug && x.scopeType === s.scopeType && x.owner === s.owner))
+                continue;
+            sombras.shadowedByGlobal.push(s);
+        }
+        for (const s of diff.shadowedByAncestor) {
+            if (sombras.shadowedByAncestor.some((x) => x.slug === s.slug && x.scopeType === s.scopeType && x.owner === s.owner && x.shadowedBy === s.shadowedBy)) {
+                continue;
+            }
+            sombras.shadowedByAncestor.push(s);
+        }
         if (index === 0)
             scoped = formatScopedRoles(diff);
         if (catalogInSync(diff)) {
@@ -708,6 +813,7 @@ export async function runCatalogDiff(catalogs, options = {}) {
         for (const line of formatCatalogDiff(diff))
             lines.push(`  ${line}`);
     }
+    const shadowed = formatShadowedRoles(sombras);
     if (shadowed.length) {
         lines.push('roles locales ENSOMBRECIDOS por una definición más autorizada (no son deriva: 3F · S3):');
         for (const line of shadowed)