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

package/build/src/catalog.d.ts

@@ -1,3 +1,250 @@
-import type { CatalogSpec } from './types.js';
-export declare function syncAuthzCatalog(catalog: CatalogSpec): Promise<void>;
+import type { 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;
+    }>;
+}
+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;
+}
+/**
+ * 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>;
+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: CatalogDiff): 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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA+B7C,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA8E1E"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"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"}