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

package/build/src/errors.js

@@ -32,4 +32,587 @@ export class AuthorizationBackendError extends Exception {
         super(`El backend de autorización '${driver}' no respondió (${operation})`, { cause });
     }
 }
+/**
+ * El backend respondió tarde: venció `timeoutMs`. Es un `AuthorizationBackendError`
+ * (503, se maneja igual) con código propio, porque para operaciones "no responde"
+ * y "responde lento" son incidentes distintos: el segundo suele ser saturación, no
+ * caída, y el remedio (subir el deadline, escalar el backend) es otro.
+ */
+export class AuthorizationBackendTimeoutError extends AuthorizationBackendError {
+    static code = 'E_AUTHZ_BACKEND_TIMEOUT';
+    constructor(driver, operation, timeoutMs, cause) {
+        super(driver, operation, cause);
+        this.message = `El backend de autorización '${driver}' no respondió en ${timeoutMs} ms (${operation})`;
+    }
+}
+/**
+ * El resolutor de ancestros del consumidor lanzó. Es una dependencia más de
+ * cada pregunta (el árbol de scopes), así que su caída se clasifica como la
+ * del backend: 503, nunca `false`, nunca el error crudo del consumidor.
+ */
+export class ScopeResolverError extends Exception {
+    static status = 503;
+    static code = 'E_AUTHZ_RESOLVER_FAILED';
+    constructor(operation, cause) {
+        super(`El resolutor de ancestros de scopes falló (${operation})`, { cause });
+    }
+}
+/**
+ * Un componente de identidad (holder, scope, rol, permiso) no cumple el formato
+ * del motor. Es una pregunta inválida (422), no un "sin permiso": aceptarla
+ * fundiría identidades distintas en una (`user:undefined`, `{app, uuid}` que
+ * colapsa a la raíz) o produciría ids que otro backend no puede representar.
+ */
+export class InvalidIdentityError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_INVALID_IDENTITY';
+}
+/**
+ * Un slug de rol/permiso no cumple la gramática del catálogo: formato,
+ * longitud, nombre reservado o familia de prefijos reservada. 422 porque es la
+ * pregunta la que está mal formada; el catálogo no se consulta.
+ */
+export class InvalidSlugError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_INVALID_SLUG';
+}
+/**
+ * La configuración del consumidor es contradictoria (p. ej. `holderTypes` no
+ * inyectivo). 500: la aplicación está mal construida, no hay pregunta que
+ * responder hasta que se arregle.
+ */
+export class AuthorizationConfigError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_CONFIG';
+}
+/**
+ * Invariante interno del motor violado (una escritura sin scopes, un batchCheck
+ * incompleto). 500: es un bug del paquete o de quien lo extiende, no del
+ * llamante ni del backend.
+ */
+export class AuthorizationInternalError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_INTERNAL';
+}
+/**
+ * El scope no existe para el consumidor (`resolveChain` devolvió `null`).
+ * En lectura el motor responde `false` sin más; en escritura es 422: conceder
+ * o denegar en un scope que nadie reconoce dejaría un hecho huérfano que
+ * ningún árbol volverá a alcanzar — o, peor, que resucitaría si el uuid se
+ * reutiliza (L0.3, N5).
+ */
+export class UnknownScopeError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_UNKNOWN_SCOPE';
+}
+/**
+ * Se preguntó por un scope que no es la raíz y el driver no tiene resolutor
+ * de ancestros. Antes el paquete suplía un default plano ("todo cuelga de
+ * app") que convertía cualquier scope inventado en descendiente de la raíz.
+ * 422 y no 500: la raíz sigue funcionando; lo que no existe en este
+ * despliegue son los niveles intermedios.
+ */
+export class NoScopeResolverError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_NO_SCOPE_RESOLVER';
+}
+/**
+ * Rol fuera del catálogo para ese nivel (pregunta inválida, 422). Con
+ * `scopeType` se buscó por `(slug, scopeType)`; sin él, por uuid (3B ·
+ * `purgeRole`, `updateScopedRole`, `deleteScopedRole`).
+ */
+export class UnknownRoleError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_UNKNOWN_ROLE';
+    constructor(slugOrUuid, scopeType) {
+        super(scopeType === undefined
+            ? `Rol con uuid '${slugOrUuid}' no existe en el catálogo`
+            : `Rol '${slugOrUuid}' no existe en el catálogo para el nivel '${scopeType}'`);
+    }
+}
+/**
+ * El rol existe pero es LOCAL a un scope que no está en la cadena del scope
+ * de la escritura (3B · B2): un rol de la organization A no existe en B ni
+ * en la raíz. 422 y nada escrito — es la barrera que impide asignar el rol
+ * de un tenant fuera de su contenedor. En lectura no hay error: el rol
+ * simplemente no concede ni es membresía fuera de su owner.
+ */
+export class RoleNotVisibleError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_ROLE_NOT_VISIBLE';
+}
+/**
+ * En la cadena del scope de la pregunta hay MÁS DE UN rol visible con ese
+ * `(slug, nivel)` (3D · M1): dos locales de owners distintos que un
+ * `scopes.moved` juntó, o un local que tapa a un global. El slug ya no
+ * identifica un rol y elegir uno («el owner más cercano gana») convertía un
+ * homónimo en una escalada de privilegios (auditor V1/V2/V3): la ambigüedad
+ * es un ERROR, no una regla de resolución. Toda ruta que direccione por slug
+ * —`grant`, `revoke` por uuid, `hasRole`, `listSubjects`— falla CERRADA con
+ * 422 nombrando los uuids y sus owners; la forma sin ambigüedad posible es
+ * `{ uuid }` (`RoleQuery`). `authorize` no pasa por aquí: no direcciona por
+ * slug (lo asignado concede lo que su rol vincula, invariante 1).
+ */
+export class AmbiguousRoleError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_AMBIGUOUS_ROLE';
+}
+/**
+ * El `scopeType` de un rol local no es el nivel de su owner ni uno que
+ * cuelgue de él (3E · P1, auditor A1). Un rol de nivel SUPERIOR al owner no
+ * es visible en ninguna parte —no concede, no es membresía, nadie lo puede
+ * asignar— pero OCUPA ese `(slug, nivel)`: bloqueaba el `defineScopedRole`
+ * del dueño del árbol y, hasta 3E, el `syncAuthzCatalog` entero de la
+ * plataforma. Es squatting con forma de spec, como `permissions: []` (3D ·
+ * N3): 422. Los niveles que cuelgan del owner los declara el consumidor con
+ * `scopes.descendantsOf`; sin él solo se admite el nivel del owner.
+ */
+export class RoleLevelAboveOwnerError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_ROLE_LEVEL_ABOVE_OWNER';
+}
+/**
+ * `updateScopedRole`/`deleteScopedRole` sobre un rol GLOBAL (3B · B3). Los
+ * roles del catálogo del config se cambian en el config y se sincronizan
+ * (`syncAuthzCatalog`); por la API de delegación son inmutables, o un
+ * administrador de tenant podría editar el catálogo de la plataforma.
+ */
+export class RoleImmutableError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_ROLE_IMMUTABLE';
+}
+/**
+ * Un rol de nivel L no puede llevar (o ser asignado llevando) un permiso
+ * cuyo `assignableAt` no incluye L (3B · B5). Es un control de COMPOSICIÓN
+ * —`syncAuthzCatalog`, `defineScopedRole`, `updateScopedRole` y, por defensa
+ * en profundidad, `grant`—, nunca de evaluación: lo ya asignado sigue
+ * concediendo (invariante 1).
+ */
+export class RoleNotAssignableAtError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_ROLE_NOT_ASSIGNABLE_AT';
+}
+/**
+ * `defineScopedRole`/`updateScopedRole` con un permiso que el actor no puede
+ * delegar (3B · B3): no está en `config.delegablePermissions` (lista blanca;
+ * vacía por defecto: nadie delega nada hasta declararla), no existe en el
+ * catálogo, o el actor no lo tiene EFECTIVO en el owner (no lo concede
+ * ningún rol suyo en la cadena, o lo tiene denegado — auditor C2: un deny
+ * no se lava componiendo un rol para un títere).
+ */
+export class PermissionNotDelegableError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_PERMISSION_NOT_DELEGABLE';
+}
+/**
+ * El `rank` de un rol local no cumple `0 < rank < min(rank del actor, rank
+ * máximo global)` (3B · B3), o el actor intenta tocar un rol de rango ≥ al
+ * suyo. Es policy de ESCRITURA (composición y delegación); el motor sigue sin
+ * evaluar `rank` en `authorize` (invariante 8).
+ */
+export class RankExceededError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_RANK_EXCEEDED';
+}
+/**
+ * Dos catálogos de `config.catalogs` declaran el mismo rol `(slug, scopeType)`
+ * o el mismo permiso. La identidad de un rol es ese par: compartirla es
+ * compartir el rol, y el prune del segundo sync borraría los vínculos del
+ * primero en silencio (D3). Un rol pertenece a exactamente un catálogo; se
+ * rechaza antes de tocar la base, en el sync y en el diff.
+ */
+export class CatalogConflictError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_CATALOG_CONFLICT';
+}
+/** Permiso fuera del catálogo (pregunta inválida en `deny`/catálogo, 422). */
+export class UnknownPermissionError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_UNKNOWN_PERMISSION';
+    constructor(slug) {
+        super(`Permiso '${slug}' no existe en el catálogo`);
+    }
+}
+/**
+ * `appAccess({ role })` se retiró (L0.6). `hasRole` es una consulta de
+ * MEMBRESÍA y el deny no la gobierna: un middleware sobre ella era un punto de
+ * decisión indenegable (un holder con todos sus permisos denegados seguía
+ * pasando). 500: es la ruta la que está mal declarada, y debe saltar en el
+ * primer request de desarrollo, no en producción.
+ */
+export class RoleIsNotAccessError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_ROLE_IS_NOT_ACCESS';
+    constructor(role) {
+        super(`appAccess({ role: ${JSON.stringify(role)} }) ya no existe: un rol es membresía, no acceso, ` +
+            `y el deny no lo gobierna. Receta: crea un permiso que represente ese acceso ` +
+            `(p. ej. 'admin:access'), vincúlalo al rol en el catálogo y protege la ruta con ` +
+            `appAccess({ permission: 'admin:access' }).`);
+    }
+}
+/**
+ * Colgar `child` de `parent` cerraría un ciclo (el padre desciende del hijo,
+ * o son el mismo). FGA no detecta ciclos de `parent`: los evalúa, y un grant
+ * en cualquier nodo del ciclo concede en todos, raíz incluida (S2). La única
+ * barrera es el paquete, antes de escribir nada.
+ */
+export class ScopeCycleError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_SCOPE_CYCLE';
+}
+/**
+ * `purgeScope` terminó y el backend todavía muestra hechos del scope. Un
+ * número parcial que no lanza deja grants huérfanos e indenegables (S6, B2);
+ * se lanza para que el consumidor NO confirme el borrado de su entidad.
+ */
+export class PurgeIncompleteError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_PURGE_INCOMPLETE';
+}
+/**
+ * Una escritura del driver `openfga` chocó una y otra vez con otra
+ * transacción sobre las MISMAS tuplas (3b-2f · R3). FGA responde
+ * `Aborted` (HTTP 409) cuando dos `Write` transaccionales tocan una tupla a
+ * la vez, y responde `write_failed_due_to_invalid_input` cuando la tupla ya
+ * existía: las dos dicen "otro escritor llegó antes", y el driver las trata
+ * releyendo y re-aplicando. Si tras varias vueltas el store sigue en
+ * conflicto, el llamante se entera con un **409** —el estado del destino no
+ * es el que esta escritura esperaba, y reintentar es lo correcto—, nunca con
+ * un 503 "el backend no respondió": respondió, y dijo exactamente qué pasa.
+ */
+export class WriteConflictError extends Exception {
+    static status = 409;
+    static code = 'E_AUTHZ_WRITE_CONFLICT';
+}
+/**
+ * `config.requireActor: true` y una escritura llegó sin `actor` (2.1, B7).
+ * 422 antes de tocar el driver: una auditoría que exige saber quién ordenó
+ * cada cambio no puede tener huecos, y el hueco no se descubre después.
+ */
+export class ActorRequiredError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_ACTOR_REQUIRED';
+}
+/**
+ * `within` no está en la cadena del scope de la escritura (2.1, B1): el
+ * call-site declaró "dentro de MI tenant" y el scope pertenece a otro. 422 y
+ * nada escrito: es la barrera contra el administrador de A que concede en
+ * una unit de B pasando un uuid ajeno. Vale para las SEIS escrituras del
+ * manager (2D · F2): quitar un deny ajeno es conceder, revocar un rol ajeno
+ * es sabotear, y purgar o recolgar un scope ajeno es lo mismo.
+ */
+export class NotWithinError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_NOT_WITHIN';
+}
+/**
+ * `config.requireWithin` (`true` o `'non-root'`) y una escritura llegó sin
+ * `within` (2.1, B1; las seis desde 2D · F2). 422 antes del driver: la
+ * contención opt-in (auditor E2) deja de serlo cuando el consumidor lo declara.
+ */
+export class WithinRequiredError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_WITHIN_REQUIRED';
+}
+/**
+ * `config.requireWithin: 'non-root'` y una escritura declaró `within: APP_SCOPE`
+ * (2.1, 2D · F2). La raíz contiene todo, así que como `within` no acota nada:
+ * era el comodín con el que un call-site de tenant satisfacía `requireWithin`
+ * sin decir de qué tenant es (auditor 9). 422 y nada escrito; la plataforma,
+ * que sí escribe en la raíz, usa `manager.driver()` o una config sin el flag.
+ */
+export class WithinRootForbiddenError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_WITHIN_ROOT_FORBIDDEN';
+}
+/**
+ * Una enumeración de scopes superó su cota (2.1, B2/B3): `authorizedScopes`
+ * por encima de `maxScopes`, o un `descendantsOf` que devolvió más de
+ * `maxNodes`. 422 y NUNCA una lista parcial: un listado truncado en silencio
+ * es la forma más discreta de fail-open/fail-closed. El llamante acota la
+ * pregunta o sube la cota a sabiendas.
+ */
+export class TooManyScopesError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_TOO_MANY_SCOPES';
+}
+/**
+ * `sqlDescendantsOf` sobre un dialecto sin observación (2.1, B2): hoy solo PG
+ * y SQLite corren la CTE en la suite; MySQL entra en 2.5 con harness propio.
+ * 500: config del consumidor, salta en la primera llamada.
+ */
+export class UnsupportedDialectError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_UNSUPPORTED_DIALECT';
+}
+/**
+ * `hierarchicalScopeResolver` superó `maxDepth` (2.1, B4). Truncar la cadena
+ * perdería la raíz —y con ella cualquier deny en `app`—: fail-open. 500 y no
+ * 503: el árbol del consumidor es más profundo de lo declarado, no hay
+ * reintento que lo arregle.
+ */
+export class ScopeTooDeepError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_SCOPE_TOO_DEEP';
+}
+/**
+ * Una primitiva de 2.1 necesita un método OPCIONAL del puerto que el driver
+ * activo no implementa (2.1, B5): se nombra el método y se lanza. 500 porque
+ * es el despliegue el que está incompleto; nunca se simula la respuesta —un
+ * `[]` en `listDenies` sería "sin denies", fail-open.
+ */
+export class UnsupportedOperationError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_UNSUPPORTED';
+    constructor(method, primitive, driver, hint) {
+        super(`${primitive} necesita '${method}' y el driver '${driver}' no lo implementa: es un método opcional del ` +
+            `puerto (2.1) que este driver tiene que añadir para usar esta primitiva.` + (hint ? ` ${hint}` : ''));
+    }
+}
+/**
+ * Una vista de `forRequest()` se usó para LEER después de `maxAgeMs` (2D ·
+ * F9, auditor 5). El memo de ancestros de la vista es correcto durante un
+ * request y peligroso guardado en un módulo: tras un `scopes.moved` serviría
+ * la cadena vieja para siempre (cruce de tenant). 500 y ruidoso: es un bug
+ * del consumidor (la vista sobrevivió a su request), no un "sin permiso".
+ */
+export class ViewExpiredError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_VIEW_EXPIRED';
+}
+/**
+ * `authorizedScopes` sin `scopes.descendantsOf` en el config (2.1, B3). 500
+ * y nunca `none`: un "ningún scope" sin haber mirado el árbol sería un
+ * fail-closed mentiroso que el consumidor tomaría por respuesta.
+ */
+export class NoDescendantsResolverError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_NO_DESCENDANTS_RESOLVER';
+}
+/**
+ * `pruneOrphanRoles({ force: true })` iba a purgar una fracción del catálogo
+ * local que solo tiene sentido si el ÁRBOL se ha quedado ciego (3b-0b · AA2,
+ * auditor 3b-0): TODOS los owners distintos huérfanos, o más del 50 % de los
+ * roles locales. Esa es exactamente la firma de un `resolveChain` filtrado
+ * por el tenant de la petición —patrón normal en multi-tenant— o corriendo
+ * sin contexto (un comando, una réplica atrasada): devuelve `null` para
+ * todo, así que TODO rol local parece huérfano y una pasada con `--force` se
+ * lleva el catálogo local de todos los tenants. 500 y no 422 porque el
+ * error está en el despliegue, no en la pregunta; el barrido legítimo de una
+ * poda grande de verdad pasa con `allowMassPurge: true`
+ * (`--allow-mass-purge`), que es una decisión humana, no un default.
+ */
+export class MassPurgeRefusedError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_MASS_PURGE_REFUSED';
+}
+/**
+ * Un `purgeRole` falló a mitad del barrido de `prune-orphans`.
+ *
+ * La purga NO es transaccional entre roles: cada `purgeRole` es atómico, pero
+ * si el tercero revienta, los dos primeros ya están borrados. El valor de
+ * retorno —que es donde vivía la lista— nunca llega a producirse, así que
+ * quien recoge el error necesita saber **qué se fue** y **qué queda**, o la
+ * frase del CHANGELOG es papel mojado (tester 3b-1 §6.2).
+ *
+ * Por eso este error lleva `purged` y `skipped` con la misma forma que el
+ * valor de retorno, y envuelve el error del driver como `cause` en vez de
+ * dejarlo escapar crudo: la abstracción no filtra.
+ *
+ * Recuperación: los `role_purged` ya notificados nombran lo mismo que
+ * `purged`, y la siguiente pasada recoge el resto (los huérfanos que quedan
+ * lo siguen siendo).
+ */
+export class PruneInterruptedError extends Exception {
+    purged;
+    skipped;
+    static status = 500;
+    static code = 'E_AUTHZ_PRUNE_INTERRUPTED';
+    constructor(message, purged, skipped, options) {
+        super(message, options);
+        this.purged = purged;
+        this.skipped = skipped;
+    }
+}
+/**
+ * `readLocalRoles()` (el barrido de `prune-orphans`) encontró más roles
+ * locales que su cota `maxLocalRoles` (3b-0b · AB2, auditor 3b-0 ⚪): la
+ * lectura es UNA consulta sin `LIMIT`, así que un catálogo local enorme la
+ * convierte en amplificación. 500 y nunca una lista parcial —truncar aquí
+ * sería decidir a ciegas qué se purga—: se sube la cota a sabiendas.
+ */
+export class TooManyLocalRolesError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_TOO_MANY_LOCAL_ROLES';
+}
+/**
+ * El catálogo no cabe en un authorization model de OpenFGA (3b-2a · A3): el
+ * modo `facts` publica cada permiso como cuatro relaciones del modelo y el
+ * servidor tiene un techo de 262.144 bytes. **Cuántos permisos son esos bytes
+ * depende de tu catálogo** (3b-4 · C3): ~450 con slugs realistas
+ * (`recurso:accion`) y tres holder types, 691 si los permisos se llaman
+ * `p0`…`pN`, 272 con slugs de 40 caracteres. La tabla y de qué depende están
+ * en `FACTS_MODEL_MAX_BYTES`; el mensaje del error dice los bytes REALES y
+ * cuántos permisos tenía el catálogo que se intentó publicar.
+ * Se comprueba en `syncAuthzCatalog` ANTES de escribir: si se escribiera
+ * primero, el catálogo quedaría en la base sin poder proyectarse nunca y el
+ * store sin poder regenerarse. 500 porque es config de despliegue —el techo
+ * del servidor es del pliego de infraestructura—, no una pregunta inválida.
+ */
+export class ModelTooLargeError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_MODEL_TOO_LARGE';
+}
+/**
+ * La config de relaciones ReBAC (Fase 4) no se puede FUSIONAR en el modelo
+ * `facts`. Es 422 (pregunta inválida del que declara la config), no 500: un
+ * tipo de objeto de relaciones que duplica un tipo o una familia de
+ * relaciones reservados del modelo `facts` (`scope`/`role`/`role_binding`/
+ * `deny_binding`/`group`, o `can_<P>`/`permits_<P>`/`denied_<P>`/`assignee`/
+ * `parent`/`rooted`), o una relación cuyo nombre choca con un permiso del
+ * catálogo (F-04), invalidaría el modelo compartido. Lo detecta el GENERADOR y
+ * lanza el PAQUETE —nunca el 400 opaco del servidor—, porque en el store
+ * compartido los ids de `facts` y los de relaciones viven en el mismo espacio
+ * (⚪4 del auditor, cierre por construcción del 🔴).
+ */
+export class RelationConfigError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_RELATION_CONFIG';
+}
+/**
+ * El árbol materializado del store no es un árbol (3b-2b, cruce 8). El
+ * paquete escribe UNA arista `scope:<hijo>#parent@scope:<padre>` por nodo y
+ * la sustituye entera en cada `moved`, así que encontrar dos padres para el
+ * mismo scope significa que alguien MÁS está escribiendo ahí. No se
+ * "arregla": con dos padres la herencia ya está trayendo hechos de otra rama
+ * y elegir uno de los dos sería adivinar cuál de las dos concesiones vivas es
+ * la buena. 500 y se denuncia; lo reconstruye `authz:reconcile`.
+ */
+export class ScopeTreeDriftError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_SCOPE_TREE_DRIFT';
+}
+/**
+ * El motor está CONGELADO por una operación de plataforma (`authz:reconcile`
+ * o la ventana de cutover de `authz:freeze`).
+ *
+ * Desde 3b-7 el freeze es DURABLE (la fila `id = 2` de
+ * `authz_catalog_version`): mientras está vivo, las ESCRITURAS del manager
+ * (`grant`/`revoke`/`deny`/`removeDeny`, las tres `scopes.*`, la API de
+ * delegación, el barrido de huérfanos y el relay) responden con este 503 **en
+ * todos los procesos que comparten esas tablas**, y las LECTURAS siguen
+ * funcionando: una migración que copia hechos de un backend a otro no puede
+ * competir con quien los está escribiendo —lo que entre entre la lectura del
+ * origen y la escritura del destino se pierde sin que nadie lo cuente— y
+ * dejar de leer sería tirar la aplicación entera por una operación de
+ * plataforma.
+ *
+ * **503 y REINTENTABLE** (`retryable: true`): no es una pregunta inválida ni
+ * un fallo del backend, es una ventana de mantenimiento acotada (por el
+ * lease, o por el `authz:unfreeze` del operador). El llamante puede
+ * reintentar tal cual; un 409 diría «tu estado no es el que esperaba» y un
+ * 422 «no vuelvas a intentarlo», y ninguna de las dos es cierta aquí.
+ */
+export class AuthorizationFrozenError extends Exception {
+    static status = 503;
+    static code = 'E_AUTHZ_FROZEN';
+    /** Reintentar tal cual es lo correcto en cuanto termine la ventana. */
+    retryable = true;
+}
+/**
+ * Ya hay un freeze VIVO de otro dueño (3b-7, auditor A1.3).
+ *
+ * `freeze()` no puede ser idempotente entre procesos: dos `authz:reconcile`
+ * simultáneos que compartieran la fila se levantarían la barrera el uno al
+ * otro al terminar el primero — dos pasadas pisándose con el README diciendo
+ * que no puede pasar. El segundo dueño recibe este 423 con el motivo y el
+ * holder del freeze vivo; la excepción a propósito es el freeze de OPERADOR,
+ * que `reconcile` reconoce como su propio contexto (el cutover, F6) en vez
+ * de chocar con él.
+ */
+export class FreezeHeldError extends Exception {
+    static status = 423;
+    static code = 'E_AUTHZ_FREEZE_HELD';
+}
+/**
+ * `authz:reconcile --prune` iba a borrar hechos del destino con un ORIGEN
+ * VACÍO (3b-3a; mismo patrón que `E_AUTHZ_MASS_PURGE_REFUSED`, 3b-0b · AA2).
+ *
+ * `--to=openfga` hace del store un espejo de `authz_assignments`/
+ * `authz_denies`, así que un origen sin una sola fila de hechos y un destino
+ * lleno significa casi siempre que **los hechos los está escribiendo el otro
+ * driver** (el store ES la fuente cuando `openfga` está activo) o que la
+ * conexión mira a la base equivocada. Con `--prune` eso se lleva por delante
+ * todo lo concedido, y sin manera de reconstruirlo. 500 antes de escribir
+ * nada, `allowMassDelete: true` (`--allow-mass-delete`) es la decisión
+ * humana, y `--dry-run` no lanza: lo marca en el reporte.
+ */
+export class MassReconcileRefusedError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_MASS_RECONCILE_REFUSED';
+}
+/**
+ * **El volcado del destino no cabe en la cota declarada** (3b-3b · B5).
+ *
+ * Reconciliar exige comparar contra el estado ENTERO del destino: sin esa
+ * foto no se puede saber qué sobra, y «lo que sobra» es la mitad del trabajo
+ * (las aristas que el consumidor ya no respalda, el nodo con dos padres, la
+ * basura de una versión anterior). El ORIGEN sí se lee por lotes con cursor;
+ * el destino no, y por eso hay una cota.
+ *
+ * Se declara en vez de esconderse: por encima de `maxTuples` la pasada se
+ * niega **antes de escribir nada**, con la cifra y la salida (subir la cota,
+ * o migrar por particiones, que hoy el paquete NO trae). Un OOM a mitad de
+ * migración deja el destino con las escrituras de MENOS que ya se aplicaron
+ * y sin reporte; esto no deja nada.
+ */
+export class ReconcileTooLargeError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_RECONCILE_TOO_LARGE';
+}
+/**
+ * El driver se ha pedido en `hierarchy: 'facts'` —el árbol vive en el store
+ * de FGA— sin `scopes.outbox` y sin aceptar el riesgo por escrito (3b-2d,
+ * cruce 4 · S5). En ese montaje el paquete escribe la arista en FGA dentro
+ * de la transacción del consumidor y un `rollback` posterior NO la deshace:
+ * SQL dice un padre y FGA otro, FGA es quien decide, y la aplicación —que
+ * lista y audita contra SQL— no puede ver la escalada. No es un mal uso: el
+ * uso correcto fuga, sin crash, con un simple rollback.
+ *
+ * 500 y al construir, no al escribir: un puerto opcional que nadie declara
+ * no mitiga nada, y descubrirlo en la primera escritura de un tenant es
+ * tarde. `acceptScopeDriftRisk: true` es la salida explícita para quien
+ * mueve el árbol solo desde la plataforma y lo asume por escrito.
+ */
+export class ScopeDriftUnguardedError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_SCOPE_DRIFT_UNGUARDED';
+}
+/**
+ * **F-05, la frontera de ESCRITURA de relaciones (Fase 4, cierre del 🔴 del
+ * auditor).** `relate`/`unrelate` recibieron un `object.type` que NO está
+ * declarado en `defineRelationsConfig`. Es 422 ANTES de tocar el driver: en el
+ * store COMPARTIDO los tipos de `facts` (`role_binding`, `scope`, `role`)
+ * viven en el MISMO espacio de ids, y la composición
+ * `<type>:<scopeKey(partition)>|<id>` reproduce byte a byte el id de un
+ * `role_binding` real. Sin este corte, `relate(evil, assignee,
+ * {type:'role_binding', id:<roleUuid>}, S)` escribía la tupla del binding y
+ * `check(evil, can_<P>, S)` devolvía `true` (escalada a `roles.authorize`,
+ * medida por el auditor). Junto con ⚪4 (un tipo reservado no se puede
+ * declarar) la colisión deja de existir en vez de vigilarse.
+ */
+export class RelationTypeUnknownError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_RELATION_TYPE_UNKNOWN';
+}
+/**
+ * **F-05, cara de la RELACIÓN.** El `object.type` está declarado, pero la
+ * `relation` no es una de las suyas en `defineRelationsConfig`. Mismo 422
+ * antes de tocar el driver: una relación no declarada podría, en un futuro
+ * modelo, mapear a una relación propia de `facts`.
+ */
+export class RelationUnknownError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_RELATION_UNKNOWN';
+}
 //# sourceMappingURL=errors.js.map

package/build/src/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,SAAS;IACtD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAA;IACnB,MAAM,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAE3C,YAAY,MAAc,EAAE,SAAiB,EAAE,KAAc;QAC3D,KAAK,CAAC,+BAA+B,MAAM,mBAAmB,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACxF,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}

package/build/src/expiry.d.ts

@@ -0,0 +1,27 @@
+import type { GrantOutcome } from './types.js';
+/**
+ * Semántica de `expiresAt` en un re-grant (L0.4), compartida por los drivers
+ * para que ambos respondan igual:
+ *
+ *   omitido (`undefined`) → no tocar una caducidad VIGENTE; si la asignación
+ *                            ya expiró, revive sin caducidad (es un grant nuevo)
+ *   `null`                → quitar la caducidad, explícitamente
+ *   `Date`                → fijarla (también a un instante pasado: expira)
+ *
+ * El defecto que cierra: "asegúrate de que tiene el rol" (grant sin opciones,
+ * idempotente por naturaleza) convertía un acceso temporal en permanente.
+ */
+export declare function resolveGrantExpiry(previous: Date | null, requested: Date | null | undefined, now?: Date): Date | null;
+/** Vigente: sin caducidad o con caducidad futura. */
+export declare function isActiveExpiry(expiresAt: Date | null, now?: Date): boolean;
+/**
+ * ¿Mismo instante? Compara el tiempo, no la referencia ni la cadena:
+ * `2026-01-01T00:00:00Z` y `…00.000Z` son el mismo momento y no justifican
+ * una reescritura (que en openfga es delete+write con ventana de denegación).
+ */
+export declare function sameInstant(a: Date | null | undefined, b: Date | null | undefined): boolean;
+/** Lo que devuelve el backend como caducidad (número, ISO, Date) → Date | null. */
+export declare function toExpiryDate(value: unknown): Date | null;
+/** ¿El outcome de un grant cambió la caducidad de una asignación que ya existía? */
+export declare function expiryChanged(outcome: GrantOutcome): boolean;
+//# sourceMappingURL=expiry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.d.ts","sourceRoot":"","sources":["../../src/expiry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,IAAI,GAAG,IAAI,EACrB,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,EAClC,GAAG,GAAE,IAAoB,GACxB,IAAI,GAAG,IAAI,CAGb;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,GAAE,IAAoB,GAAG,OAAO,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAI3F;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAKxD;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAM5D"}