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

package/build/providers/authz_provider.js

@@ -1,7 +1,46 @@
 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,
+    });
+}
+/**
+ * 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 +55,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;KAClC,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/catalog.d.ts

@@ -0,0 +1,289 @@
+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
+ * que dos specs equivalentes sean la misma cadena (el sync compara texto).
+ */
+export declare function encodeAssignableAt(levels: ScopeType[] | undefined): string | null;
+/**
+ * `assignable_at` tal como está EN LA BASE, normalizado a la forma en la que
+ * el spec lo codifica (3D · N5): es lo que permite que el sync y el diff
+ * comparen lo mismo. Hasta aquí el sync comparaba la cadena cruda y el diff
+ * la lista parseada, así que un valor desordenado a mano (`["unit","app"]`)
+ * salía «en sync» y el sync lo reescribía. Un valor CORRUPTO no lanza aquí:
+ * cuenta como distinto, para que el sync lo repare en vez de atragantarse
+ * (leerlo sí es 500, `parseAssignableAt`).
+ */
+export declare function storedAssignableAt(slug: string, raw: unknown): string | null;
+/** Marca de `storedAssignableAt` para una fila que no se puede leer (3D · N5). */
+export declare const CORRUPT_ASSIGNABLE_AT = "\0corrupto";
+/** Un rol de nivel `scopeType` que lleva `permission` con esos `levels` (o `null`): legal, o 422 `E_AUTHZ_ROLE_NOT_ASSIGNABLE_AT`. */
+export declare function assertAssignableAt(role: {
+    slug: string;
+    scopeType: ScopeType;
+}, permission: string, levels: readonly ScopeType[] | null): void;
+/**
+ * Longitud de `authz_permissions.assignable_at` (`varchar(500)` en el stub y
+ * en el espejo). El JSON codificado tiene que caber (3D · N3).
+ */
+export declare const ASSIGNABLE_AT_MAX = 500;
+/** Deadline de cada consulta del catálogo (D15); configurable por `timeoutMs`. */
+export declare const DEFAULT_CATALOG_TIMEOUT_MS = 5000;
+/**
+ * Lo que un `syncAuthzCatalog` deja DICHO (3E · P1 b / P6). El sync del
+ * despliegue es todo-o-nada para lo que ESCRIBE, pero no puede abortar por
+ * lo que un tenant hizo en su scope: hasta 3E, un rol local homónimo tumbaba
+ * el catálogo entero de la plataforma (auditor A1: el actor de menor
+ * privilegio del sistema paraba el deploy). La política es **reportar y
+ * seguir**, nunca romper en silencio: se escribe el global —los globales
+ * ganan— y aquí queda quién se ve afectado.
+ */
+export interface CatalogSyncReport {
+    /**
+     * Roles LOCALES cuyo `(slug, nivel)` acaba de ocupar un rol GLOBAL del
+     * spec (3E · P1 b). El global manda; el local sigue en la base pero desde
+     * ya toda ruta por slug en su cadena es 422 `E_AUTHZ_AMBIGUOUS_ROLE` (M1,
+     * fail-closed): su tenant tiene que direccionar por `{ uuid }` o pedir que
+     * lo purguen. `authz:catalog:diff` los lista y sale con código ≠ 0.
+     */
+    shadowedByGlobal: CatalogRoleRef[];
+    /**
+     * Vínculos rol→permiso que YA existían y que el `assignableAt` nuevo del
+     * config ya no admite (3E · P6): estrechar `assignableAt` no revalidaba
+     * los roles que ya llevaban el permiso —ni el diff los mencionaba—, así
+     * que la restricción entraba a medias y en silencio. No se borran (lo
+     * asignado sigue concediendo, invariante 1): se reportan para que el
+     * operador decida (`updateScopedRole`, `deleteScopedRole` o ampliar el
+     * `assignableAt`).
+     */
+    assignableAtViolations: Array<{
+        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 {
+    /**
+     * Qué hacer con los vínculos rol→permiso que el spec YA NO lista, para los
+     * roles DEL SPEC (L0.9). `'links'` (default): se eliminan en la misma
+     * transacción. `'none'`: sync solo aditivo (el comportamiento de 1.x).
+     * Nunca se borran roles ni permisos, y los roles ajenos al spec no se
+     * tocan: dos catálogos (plataforma y tenant) coexisten.
+     */
+    prune?: 'links' | 'none';
+    /**
+     * Deadline de cada consulta en ms (default 5000). La base caída o lenta
+     * es 503 `E_AUTHZ_BACKEND_UNAVAILABLE`/`_TIMEOUT`, no un error crudo del
+     * 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_*`.
+ *
+ * Idempotente y transaccional. Permisos y roles se crean si faltan (nunca se
+ * borran: la limpieza de un rol o permiso retirado es una decisión explícita
+ * del consumidor, porque arrastra asignaciones). Los vínculos rol→permiso
+ * son la excepción: con `prune: 'links'` (default) el spec MANDA sobre los
+ * roles que declara. Antes el sync era solo aditivo y quitar un permiso de
+ * un rol en el config no lo quitaba de ningún entorno — la única fuente de
+ * verdad visible mentía sobre los permisos efectivos (L0.9, N1).
+ *
+ * Un rol que concede un permiso que no existe ni en este spec ni en la base
+ * (sincronizado por otro catálogo) es 422 `E_AUTHZ_UNKNOWN_PERMISSION`:
+ * antes se saltaba en silencio.
+ *
+ * Lo usan el seeder del nivel app, `authz:catalog:sync` y el harness de la
+ * suite de contrato. El catálogo es metadata compartida entre drivers: un
+ * 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;
+    permission: string;
+}
+export interface CatalogDiff {
+    /** Permisos del spec que no existen en la base. */
+    missingPermissions: string[];
+    /** Roles del spec que no existen en la base. */
+    missingRoles: Array<{
+        slug: string;
+        scopeType: ScopeType;
+    }>;
+    /** Vínculos que el spec declara y la base no tiene. */
+    missingLinks: CatalogLinkRef[];
+    /** Vínculos que la base tiene, en roles DEL SPEC, y el spec ya no lista (privilegio zombi). */
+    extraLinks: CatalogLinkRef[];
+    /** Roles cuyo rank en la base difiere del spec. */
+    rankMismatches: Array<{
+        role: string;
+        scopeType: ScopeType;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Permisos del spec cuyo `assignableAt` en la base difiere (3B · B5):
+     * `null` = cualquier nivel. `corrupt: true` (3E · P5) es una fila que no
+     * se puede leer (`assignable_at` que no es JSON de niveles): cuenta como
+     * diferencia —el sync la repara— y el diff la nombra en vez de morir.
+     */
+    assignableAtMismatches: Array<{
+        permission: string;
+        expected: ScopeType[] | null;
+        actual: ScopeType[] | null;
+        corrupt?: boolean;
+    }>;
+    /**
+     * Roles LOCALES (3B): propios de un scope, definidos con `defineScopedRole`.
+     * Informativo: no son sobrantes ni faltantes (el spec solo declara
+     * globales) y no afectan a `catalogInSync`.
+     */
+    scopedRoles: Array<{
+        slug: string;
+        scopeType: ScopeType;
+        owner: string;
+    }>;
+    /**
+     * `(slug, nivel)` con MÁS DE UN rol visible desde una misma cadena que la
+     * AUTORIDAD no sabe ordenar (3D · M2 d; 3F · S3). Desde 3F, la pareja
+     * global+local va a `shadowedByGlobal` y la de ancestro+descendiente a
+     * `shadowedByAncestor` —las dos son el orden de autoridad funcionando, no
+     * deriva—, así que aquí solo queda lo que NINGUNA regla ordena: dos
+     * locales que se declaran ancestro el uno del otro (un `resolveChain` con
+     * un ciclo o que se contradice). Eso sí es deriva REAL —`catalogInSync` es
+     * `false` y el comando sale con código ≠ 0—: mientras dure, toda ruta por
+     * slug ahí responde 422 `E_AUTHZ_AMBIGUOUS_ROLE` (M1) y el operador tiene
+     * que PURGAR uno (un rol local no se renombra: 3E · Q1). Las parejas de
+     * locales solo se juzgan con `resolveChain` (el árbol es del consumidor):
+     * sin resolutor se dice en el informe.
+     */
+    ambiguousRoles: Array<{
+        slug: string;
+        scopeType: ScopeType;
+        owners: string[];
+    }>;
+    /**
+     * Roles LOCALES ensombrecidos por un rol GLOBAL homónimo: el del spec que
+     * el sync va a escribir (3E · P1 b) o uno que ya está en la base. **No es
+     * deriva** desde 3F · S3: es el orden de AUTORIDAD funcionando (global >
+     * local), igual que `shadowedByAncestor`. Se listan para que el operador
+     * los vea —mientras duren, ese slug es 422 `E_AUTHZ_AMBIGUOUS_ROLE` en la
+     * cadena de esos owners y se opera por `{ uuid }`—, pero no dejan el gate
+     * de CI en rojo: un tenant que ocupa un nombre no puede parar el deploy de
+     * la plataforma, ni siquiera por la vía del `exit 1` (auditor N1).
+     */
+    shadowedByGlobal: Array<{
+        slug: string;
+        scopeType: ScopeType;
+        owner: string;
+    }>;
+    /**
+     * Roles LOCALES ensombrecidos por otro LOCAL homónimo cuyo owner es un
+     * ANCESTRO suyo (3F · S3): el dueño del árbol definió el suyo y el del
+     * descendiente queda tapado dentro de su propio subárbol. Como
+     * `shadowedByGlobal`: se lista, no es deriva.
+     */
+    shadowedByAncestor: Array<{
+        slug: string;
+        scopeType: ScopeType;
+        owner: string;
+        shadowedBy: string;
+    }>;
+    /**
+     * Vínculos rol→permiso vivos que el `assignableAt` del spec ya no admite
+     * (3E · P6), en roles que el sync no toca (locales y globales de otro
+     * catálogo). El sync los reporta igual; el diff los dice antes.
+     */
+    assignableAtViolations: Array<{
+        role: string;
+        scopeType: ScopeType;
+        owner: string;
+        permission: string;
+    }>;
+}
+/**
+ * Compara un spec con lo que hay en `authz_*`, sin escribir. Igual que el
+ * sync, solo mira los roles del spec: lo ajeno (otro catálogo) no es una
+ * diferencia. Un diff limpio significa que `syncAuthzCatalog(spec)` sería un
+ * no-op.
+ */
+export declare function diffAuthzCatalog(catalog: CatalogSpec, options?: {
+    timeoutMs?: number;
+    resolveChain?: ScopeChainResolver;
+}): Promise<CatalogDiff>;
+export declare function catalogInSync(diff: CatalogDiff): boolean;
+/** Líneas legibles del diff (vacío si está en sync). */
+export declare function formatCatalogDiff(diff: CatalogDiff): string[];
+/** Líneas informativas del diff (no son diferencias): los roles locales, propios de un scope. */
+export declare function formatScopedRoles(diff: CatalogDiff): string[];
+/**
+ * Líneas informativas del diff (3F · S3): los roles locales ENSOMBRECIDOS
+ * por una definición más autorizada —un global, o un local de un ancestro—.
+ * No son deriva: es el orden de autoridad funcionando. Se listan porque
+ * 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: Pick<CatalogDiff, 'shadowedByGlobal' | 'shadowedByAncestor'>): string[];
+/** Fábricas de catálogo tal como se declaran en `config.catalogs`. */
+export type CatalogSource = () => Promise<CatalogSpec> | CatalogSpec;
+/**
+ * El diff de TODOS los catálogos del config. `inSync: false` ⇒ el comando
+ * sale con código ≠ 0 (para CI). Separado del comando para poder probarlo
+ * sin un kernel de ace.
+ */
+export declare function runCatalogDiff(catalogs: CatalogSource[], options?: {
+    resolveChain?: ScopeChainResolver;
+    failOnShadows?: boolean;
+}): Promise<{
+    inSync: boolean;
+    lines: string[];
+}>;
+/**
+ * Sincroniza todos los catálogos del config, en orden (lo que hace
+ * `authz:catalog:sync`). Devuelve cuántos y lo que hay que DECIR (3E · P1 b
+ * / P6): el comando lo imprime como aviso — reportar y seguir, nunca romper
+ * en silencio.
+ */
+export declare function syncCatalogs(catalogs: CatalogSource[], options?: SyncCatalogOptions): Promise<{
+    count: number;
+} & CatalogSyncReport>;
+//# sourceMappingURL=catalog.d.ts.map

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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"}