@jantstack/adonis-authz 2.5.0-alpha.3 → 2.5.0-rc.1

package/build/src/identity.d.ts

@@ -1,4 +1,4 @@
-import type { NormalizedRoleQuery, RoleQuery, ScopeRef, SubjectRef } from './types.js';
+import type { NormalizedRoleQuery, RoleQuery, ScopeRef, SnapshotReads, SubjectRef } from './types.js';
 /**
  * Validación de identidad del motor: holder, scope, rol y permiso.
  *
@@ -173,6 +173,8 @@ export declare function scopeSpellings(scope: ScopeRef): ScopeRef[];
 export declare function isDashlessUuid(value: unknown): value is string;
 /** La forma 8-4-4-4-12 de un uuid de 32 hex (la ortografía CANÓNICA). */
 export declare function dashedUuid(dashless: string): string;
+/** ¿Es un uuid en su ortografía CANÓNICA (8-4-4-4-12, minúsculas)? (7.4: la forma del cursor de `enumerate*` de `database`.) */
+export declare function isCanonicalUuid(value: unknown): value is string;
 /**
  * **¿Es una ortografía NO canónica de un uuid?** (D4 + cierre 🟠 A2 del
  * auditor del lote A, decisión del dueño 2026-10-15): todo valor que, sin
@@ -336,4 +338,9 @@ export interface IdentityParts {
  * cuesta una consulta ni deja rastro.
  */
 export declare function assertIdentity(parts: IdentityParts): void;
-//# sourceMappingURL=identity.d.ts.map
+/**
+ * La forma de una pregunta a `readSnapshot` (rotación 2 · cierre 3): al menos una de las tres claves y ninguna más;
+ * `rolesInChain` un array de scopes válidos, `listScopes` un slug de permiso, `listDenies` exactamente `true`. Lo
+ * demás es 422 `E_AUTHZ_INVALID_IDENTITY` antes de tocar el backend. Devuelve la pregunta con las claves presentes.
+ */
+export declare function assertSnapshotReads(reads: unknown): SnapshotReads;

package/build/src/identity.js

@@ -306,6 +306,10 @@ export function dashedUuid(dashless) {
 /* ── Partición de RELACIONES (D4, plan 2.5 · lote A) ───────────────────── */
 /** La ortografía CANÓNICA de un uuid: exactamente 8-4-4-4-12, minúsculas. */
 const CANONICAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** ¿Es un uuid en su ortografía CANÓNICA (8-4-4-4-12, minúsculas)? (7.4: la forma del cursor de `enumerate*` de `database`.) */
+export function isCanonicalUuid(value) {
+    return typeof value === 'string' && CANONICAL_UUID.test(value);
+}
 /**
  * **¿Es una ortografía NO canónica de un uuid?** (D4 + cierre 🟠 A2 del
  * auditor del lote A, decisión del dueño 2026-10-15): todo valor que, sin
@@ -606,4 +610,32 @@ export function assertIdentity(parts) {
     if ('expiresAt' in parts)
         assertExpiresAt(parts.expiresAt);
 }
-//# sourceMappingURL=identity.js.map
+/**
+ * La forma de una pregunta a `readSnapshot` (rotación 2 · cierre 3): al menos una de las tres claves y ninguna más;
+ * `rolesInChain` un array de scopes válidos, `listScopes` un slug de permiso, `listDenies` exactamente `true`. Lo
+ * demás es 422 `E_AUTHZ_INVALID_IDENTITY` antes de tocar el backend. Devuelve la pregunta con las claves presentes.
+ */
+export function assertSnapshotReads(reads) {
+    if (reads === null || typeof reads !== 'object' || Array.isArray(reads)) {
+        throw new InvalidIdentityError(`readSnapshot: se esperaba un objeto { rolesInChain?, listScopes?, listDenies? } y llegó ${Array.isArray(reads) ? 'un array' : typeof reads}`);
+    }
+    const known = new Set(['rolesInChain', 'listScopes', 'listDenies']);
+    const present = Object.keys(reads).filter((key) => reads[key] !== undefined);
+    const unknown = present.filter((key) => !known.has(key));
+    if (unknown.length)
+        throw new InvalidIdentityError(`readSnapshot: clave desconocida ${unknown.map((k) => `'${k}'`).join(', ')}`);
+    if (present.length === 0)
+        throw new InvalidIdentityError('readSnapshot: no se pidió ninguna lectura');
+    const { rolesInChain, listScopes, listDenies } = reads;
+    if (rolesInChain !== undefined) {
+        if (!Array.isArray(rolesInChain))
+            throw new InvalidIdentityError('readSnapshot: rolesInChain tiene que ser un array de scopes');
+        for (const scope of rolesInChain)
+            assertScope(scope);
+    }
+    if (listScopes !== undefined)
+        assertIdentity({ permission: listScopes });
+    if (listDenies !== undefined && listDenies !== true)
+        throw new InvalidIdentityError('readSnapshot: listDenies solo admite true');
+    return { rolesInChain, listScopes, listDenies };
+}

package/build/src/manager.d.ts

@@ -71,6 +71,12 @@ export declare const RELAY_LEASE_POLL_MS = 25;
  * reloj de pared: con `config.clock` fijo el sondeo por reloj no terminaba nunca.
  */
 export declare const RELAY_WAIT_LEASE_MAX_MS = 60000;
+/**
+ * Por qué una pasada de `pruneOrphanRoles` tiene la firma de un resolutor ciego (3b-0b · AA2 + rotación 2 · R2-02):
+ * todos los owners huérfanos, más del 50 % de los roles locales, o huérfanos de más de un owner con alguno que todavía
+ * concede (o no se sabe).
+ */
+export type MassPurgeReason = 'all-owners' | 'proportion' | 'granting-across-owners';
 export interface ForRequestOptions {
     /**
      * Milisegundos durante los que la vista puede LEER (default 30 000).
@@ -700,6 +706,21 @@ export declare class AuthorizationManager {
      *    antes de su `purgeRole`; si ha vuelto, el rol se salta y se cuenta en
      *    `skipped` con `reason: 'owner-came-back'`.
      *
+     * **Tercer disparador del seguro** (rotación 2 de M4 · R2-02, decisión del dueño 2026-10-22 (2)): la
+     *    proporción la controla un TENANT —con la API de delegación legítima infla su catálogo local hasta que los
+     *    huérfanos de los demás bajan del 50 %—, y la variante realista del resolutor ciego no es «`null` para todo»
+     *    sino un contexto de tenant COLADO en el job de plataforma, que solo deja vivo a ese tenant. Así que, con
+     *    `force`, si los huérfanos son de MÁS DE UN owner y ALGUNO todavía concede (`stillGranting === true`) o no se
+     *    sabe (`undefined`: el driver no cuenta), también es 500 `E_AUTHZ_MASS_PURGE_REFUSED` antes de borrar nada,
+     *    salvo `allowMassPurge`. Un solo owner huérfano con asignaciones vivas sigue pasando (es el caso normal de un
+     *    tenant que se va, y el listado lo marca aparte). El `--dry-run` no lanza: lo marca en `massPurge` y dice por
+     *    qué en `massPurgeReasons` (`'all-owners' | 'proportion' | 'granting-across-owners'`).
+     *  - **Cota de lectura** (R2-04): `maxLocalRoles` (default `DEFAULT_MAX_LOCAL_ROLES`, `--max-local-roles` en el
+     *    comando) acota la lectura del catálogo local; pasarla es 500 `E_AUTHZ_TOO_MANY_LOCAL_ROLES`, nunca una lista
+     *    parcial. Hasta este cierre la opción no existía y el mensaje pedía «subir la cota» sin mando: un tenant con
+     *    10 001 roles locales dejaba `prune-orphans` muerto para todos. Un valor que no es un entero ≥ 1 es 500
+     *    `E_AUTHZ_CONFIG` antes de leer nada.
+     *
      * Coste: una lectura del catálogo local + un `resolveChain` por OWNER
      * DISTINTO (memoizado) + UNA llamada a `countRoleAssignments` con los
      * uuids de los huérfanos (ninguna si no hay) + un `resolveChain` más por
@@ -710,6 +731,7 @@ export declare class AuthorizationManager {
     pruneOrphanRoles(options?: {
         force?: boolean;
         allowMassPurge?: boolean;
+        maxLocalRoles?: number;
     }): Promise<{
         orphans: Array<{
             role: CatalogRole;
@@ -725,6 +747,8 @@ export declare class AuthorizationManager {
         }>;
         /** ¿La pasada tiene la firma de un resolutor ciego? Con `force` exige `allowMassPurge`. */
         massPurge: boolean;
+        /** Qué disparó `massPurge` (vacío si no saltó): todos los owners, la proporción, o huérfanos de > 1 owner que conceden (R2-02). */
+        massPurgeReasons: MassPurgeReason[];
         dryRun: boolean;
     }>;
     /**
@@ -787,4 +811,3 @@ export declare class AuthorizationManager {
         maxScopes?: number;
     }): Promise<ScopeRef[]>;
 }
-//# sourceMappingURL=manager.d.ts.map