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

package/build/src/expiry.js

@@ -0,0 +1,50 @@
+import { systemClock } from './clock.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 function resolveGrantExpiry(previous, requested, now = systemClock()) {
+    if (requested !== undefined)
+        return requested;
+    return isActiveExpiry(previous, now) ? previous : null;
+}
+/** Vigente: sin caducidad o con caducidad futura. */
+export function isActiveExpiry(expiresAt, now = systemClock()) {
+    return expiresAt === null || expiresAt.getTime() > now.getTime();
+}
+/**
+ * ¿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 function sameInstant(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.getTime() === b.getTime();
+}
+/** Lo que devuelve el backend como caducidad (número, ISO, Date) → Date | null. */
+export function toExpiryDate(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (value instanceof Date)
+        return value;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** ¿El outcome de un grant cambió la caducidad de una asignación que ya existía? */
+export function expiryChanged(outcome) {
+    return (outcome.existed &&
+        outcome.previousExpiresAt !== undefined &&
+        !sameInstant(outcome.previousExpiresAt, outcome.expiresAt));
+}
+//# sourceMappingURL=expiry.js.map

package/build/src/expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.js","sourceRoot":"","sources":["../../src/expiry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAqB,EACrB,SAAkC,EAClC,MAAY,WAAW,EAAE;IAEzB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC7C,OAAO,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAA;AACxD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,SAAsB,EAAE,MAAY,WAAW,EAAE;IAC9E,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAA;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAA0B,EAAE,CAA0B;IAChF,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAC1B,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAA;AACpC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IACtE,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAA;IACvC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAY,CAAC,CAAA;IACnC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,OAAO,CACL,OAAO,CAAC,OAAO;QACf,OAAO,CAAC,iBAAiB,KAAK,SAAS;QACvC,CAAC,WAAW,CAAC,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,SAAS,CAAC,CAC3D,CAAA;AACH,CAAC"}

package/build/src/freeze.d.ts

@@ -0,0 +1,120 @@
+/**
+ * El **freeze DURABLE** (3b-7; decisión del dueño del 2026-08-31 (3b):
+ * B + E-analista). Primitivas SQL puras; la policy (quién congela, el
+ * anidado, el contexto del operador) vive en el manager.
+ *
+ * El freeze cuelga de la fila `id = 2` de `authz_catalog_version` — la señal
+ * entre procesos que el paquete ya usa (invariante 14). La colocación está
+ * MEDIDA (panel 3, analista §4.1): en la fila `id = 1` la renovación del
+ * lease espera al `FOR UPDATE` de `withAuthzCatalogWrite` (816 ms en PG /
+ * 805 en MySQL con un sync de 800 ms); en su propia fila, 10-12 ms. Y la
+ * consulta de la barrera es PROPIA y sin memo (juez C2): colgarse del memo
+ * del catálogo haría del freeze «una ventana acotada de freeze que todavía
+ * no aplica» con `catalogRevalidate: { everyMs }`. El coste que se publica
+ * es el medido: +0,14 ms p50 por escritura (PG; +0,11 MySQL), 0 por
+ * `authorize`.
+ *
+ * Las tres reglas del protocolo:
+ *  - **Token de dueño** (`fence` + `holder`): `acquire` sube el fence y solo
+ *    hay UN freeze vivo a la vez; `release`/`renew` son condicionales por
+ *    token, así que un `unfreeze` ajeno o rezagado es un no-op (auditor
+ *    A1.3: el `finally` de una ventana interior ya no puede levantar la
+ *    barrera de otra).
+ *  - **Lease**: `untilMs` en ms de PARED (el reloj del config, el mismo que
+ *    decide caducidades). Vencido ⇒ el freeze deja de estar vivo y la flota
+ *    vuelve a escribir SOLA — tras un `SIGKILL` nadie limpia nada (medido:
+ *    2 527 ms con lease de 3 000). `untilMs: null` = sin caducidad (la
+ *    ventana del operador).
+ *  - **Fence publicado**: la renovación exige `freeze_until_ms > now`; una
+ *    renovación que toca 0 filas significa que el lease se PERDIÓ a mitad
+ *    (pausa de GC, base caída más tiempo que el lease) y quien lo sostiene
+ *    lo marca `lapsed` — la pasada no se certifica (juez C4).
+ *
+ * La fila ausente (o las columnas: una base migrada con el stub < 2.3) es
+ * **503 «migración 2.0 no aplicada»** en toda escritura, jamás «no
+ * congelado»: el mismo patrón que la fila `id = 1` del memo. Un upsert
+ * perezoso desde la barrera sería una escritura en el camino de lectura,
+ * fuera de `withAuthzCatalogWrite`, y una carrera gratis.
+ */
+/** La fila del freeze durable (la `id = 1` es la versión del catálogo). */
+export declare const FREEZE_ROW_ID = 2;
+/** Lease por defecto (analista §2.3): 15 s renovados cada 5 s cubren cualquier pausa razonable y acotan la parada tras un `SIGKILL`. */
+export declare const DEFAULT_FREEZE_LEASE_MS = 15000;
+/** Quién congela: el dueño va escrito en la fila (`<kind>:<pid>:<hex>`). */
+export type FreezeKind = 'operator' | 'reconcile' | 'platform';
+/** El token del dueño: lo devuelve `freeze()` y es lo ÚNICO que levanta o renueva ese freeze. */
+export interface FreezeToken {
+    /** Número de generación: sube en cada `acquire`, nunca se reutiliza. */
+    fence: number;
+    /** `<kind>:<pid>:<hex>`: identifica al proceso que congeló. */
+    holder: string;
+}
+/** La fila del freeze, tal como está en la base. */
+export interface FreezeRow {
+    reason: string | null;
+    holder: string | null;
+    untilMs: number | null;
+    fence: number;
+}
+export interface FreezeSqlOptions {
+    /** Etiqueta del driver en los errores 503 (default `freeze`). */
+    driver?: string;
+    /** Deadline de cada consulta (default 5000): vencido ⇒ 503. */
+    timeoutMs?: number;
+    /**
+     * Cliente sobre el que leer (la TRANSACCIÓN del llamante, si la escritura
+     * llegó con una — `ScopeTreeWriteOptions.transaction`). Sin esto, la
+     * barrera necesitaría una SEGUNDA conexión del pool mientras el consumidor
+     * sostiene la suya, y con un pool de 1 (SQLite `:memory:`) eso es un
+     * interbloqueo, no una lectura. El precio, declarado: en un motor cuyo
+     * aislamiento por defecto congela la foto de las lecturas (InnoDB
+     * REPEATABLE READ), un freeze puesto DESPUÉS de abrir esa transacción
+     * puede no verse desde dentro — la misma ventana que una escritura que ya
+     * pasó su barrera (tester A4), y por eso la promesa publicada es «otro
+     * proceso recibe 503», no «ninguna escritura entra».
+     */
+    client?: {
+        from: (table: string) => any;
+    };
+}
+/** Lee la fila del freeze (503 clasificado si la base no responde; 503 «migración no aplicada» si no existe). */
+export declare function readFreezeRow(options?: FreezeSqlOptions): Promise<FreezeRow>;
+/** ¿Está VIVO este freeze en el instante `nowMs`? (motivo puesto y lease sin vencer; `untilMs: null` no vence). */
+export declare function freezeIsLive(row: FreezeRow, nowMs: number): boolean;
+/**
+ * Toma el freeze si NADIE lo sostiene vivo (condicional y atómico: dos
+ * `acquire` a la vez acaban en exactamente uno). Devuelve el token, o `null`
+ * si hay un freeze vivo de otro dueño (el llamante decide si eso es 423 o un
+ * contexto que reconoce).
+ */
+export declare function acquireFreeze(input: {
+    reason: string;
+    holder: string;
+    untilMs: number | null;
+    nowMs: number;
+}, options?: FreezeSqlOptions): Promise<FreezeToken | null>;
+/**
+ * Renueva el lease, CONDICIONAL por token y solo si aún no venció
+ * (`freeze_until_ms > now`). `false` = el lease se PERDIÓ (caducó a mitad, o
+ * otro dueño tomó el freeze): el llamante lo marca `lapsed` y deja de
+ * renovar — nunca «recupera» un freeze que ya no es suyo.
+ */
+export declare function renewFreeze(token: FreezeToken, input: {
+    untilMs: number;
+    nowMs: number;
+}, options?: FreezeSqlOptions): Promise<boolean>;
+/**
+ * Levanta el freeze de ESTE token (condicional: uno ajeno o rezagado no toca
+ * nada). Devuelve además `lapsed`: si en el instante de cerrar el lease ya
+ * estaba vencido o el token ya no era el de la fila, hubo una ventana en la
+ * que otros procesos pudieron escribir — es lo que el reporte publica.
+ */
+export declare function releaseFreeze(token: FreezeToken, input: {
+    nowMs: number;
+}, options?: FreezeSqlOptions): Promise<{
+    released: boolean;
+    lapsed: boolean;
+}>;
+/** El `kind` que el holder lleva escrito (`operator:123:ab…` → `operator`). */
+export declare function freezeKindOf(holder: string | null): FreezeKind | 'unknown';
+//# sourceMappingURL=freeze.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/freeze.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,aAAa,IAAI,CAAA;AAE9B,wIAAwI;AACxI,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAI7C,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAA;AAE9D,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;CACf;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAA;KAAE,CAAA;CAC1C;AAyBD,iHAAiH;AACjH,wBAAsB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmBtF;AAED,mHAAmH;AACnH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAChF,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8B7B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACzC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAejD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,SAAS,CAG1E"}

package/build/src/freeze.js

@@ -0,0 +1,172 @@
+import db from '@adonisjs/lucid/services/db';
+import { guardSql } from './shared/backend_guard.js';
+import { AuthorizationBackendError } from './errors.js';
+import { CATALOG_VERSION_TABLE } from './catalog/catalog_cache.js';
+/**
+ * El **freeze DURABLE** (3b-7; decisión del dueño del 2026-08-31 (3b):
+ * B + E-analista). Primitivas SQL puras; la policy (quién congela, el
+ * anidado, el contexto del operador) vive en el manager.
+ *
+ * El freeze cuelga de la fila `id = 2` de `authz_catalog_version` — la señal
+ * entre procesos que el paquete ya usa (invariante 14). La colocación está
+ * MEDIDA (panel 3, analista §4.1): en la fila `id = 1` la renovación del
+ * lease espera al `FOR UPDATE` de `withAuthzCatalogWrite` (816 ms en PG /
+ * 805 en MySQL con un sync de 800 ms); en su propia fila, 10-12 ms. Y la
+ * consulta de la barrera es PROPIA y sin memo (juez C2): colgarse del memo
+ * del catálogo haría del freeze «una ventana acotada de freeze que todavía
+ * no aplica» con `catalogRevalidate: { everyMs }`. El coste que se publica
+ * es el medido: +0,14 ms p50 por escritura (PG; +0,11 MySQL), 0 por
+ * `authorize`.
+ *
+ * Las tres reglas del protocolo:
+ *  - **Token de dueño** (`fence` + `holder`): `acquire` sube el fence y solo
+ *    hay UN freeze vivo a la vez; `release`/`renew` son condicionales por
+ *    token, así que un `unfreeze` ajeno o rezagado es un no-op (auditor
+ *    A1.3: el `finally` de una ventana interior ya no puede levantar la
+ *    barrera de otra).
+ *  - **Lease**: `untilMs` en ms de PARED (el reloj del config, el mismo que
+ *    decide caducidades). Vencido ⇒ el freeze deja de estar vivo y la flota
+ *    vuelve a escribir SOLA — tras un `SIGKILL` nadie limpia nada (medido:
+ *    2 527 ms con lease de 3 000). `untilMs: null` = sin caducidad (la
+ *    ventana del operador).
+ *  - **Fence publicado**: la renovación exige `freeze_until_ms > now`; una
+ *    renovación que toca 0 filas significa que el lease se PERDIÓ a mitad
+ *    (pausa de GC, base caída más tiempo que el lease) y quien lo sostiene
+ *    lo marca `lapsed` — la pasada no se certifica (juez C4).
+ *
+ * La fila ausente (o las columnas: una base migrada con el stub < 2.3) es
+ * **503 «migración 2.0 no aplicada»** en toda escritura, jamás «no
+ * congelado»: el mismo patrón que la fila `id = 1` del memo. Un upsert
+ * perezoso desde la barrera sería una escritura en el camino de lectura,
+ * fuera de `withAuthzCatalogWrite`, y una carrera gratis.
+ */
+/** La fila del freeze durable (la `id = 1` es la versión del catálogo). */
+export const FREEZE_ROW_ID = 2;
+/** Lease por defecto (analista §2.3): 15 s renovados cada 5 s cubren cualquier pausa razonable y acotan la parada tras un `SIGKILL`. */
+export const DEFAULT_FREEZE_LEASE_MS = 15_000;
+const DEFAULT_FREEZE_TIMEOUT_MS = 5_000;
+function opts(options) {
+    return { driver: options.driver ?? 'freeze', timeoutMs: options.timeoutMs ?? DEFAULT_FREEZE_TIMEOUT_MS };
+}
+function missingRow(driver) {
+    const error = new AuthorizationBackendError(driver, 'freeze.row', new Error(`no hay fila id = ${FREEZE_ROW_ID} en ${CATALOG_VERSION_TABLE}`));
+    error.message =
+        `${driver}: no se puede leer el freeze compartido (${CATALOG_VERSION_TABLE}, id = ${FREEZE_ROW_ID}). ` +
+            `Probablemente la migración 2.0 no está aplicada (la siembra el stub publicado; la receta está en el CHANGELOG). ` +
+            `Sin la fila las escrituras NO proceden: tratarla como «no congelado» sería fail-open.`;
+    return error;
+}
+function toMs(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const value = typeof raw === 'number' ? raw : Number(raw);
+    return Number.isFinite(value) ? value : null;
+}
+/** Lee la fila del freeze (503 clasificado si la base no responde; 503 «migración no aplicada» si no existe). */
+export async function readFreezeRow(options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const client = options.client ?? db;
+    const rows = await guardSql(driver, 'freeze.read', timeoutMs, () => client
+        .from(CATALOG_VERSION_TABLE)
+        .where('id', FREEZE_ROW_ID)
+        .select('freeze_reason', 'freeze_holder', 'freeze_until_ms', 'freeze_fence'));
+    if (rows.length === 0)
+        throw missingRow(driver);
+    const row = rows[0];
+    const fence = toMs(row.freeze_fence);
+    if (fence === null)
+        throw missingRow(driver);
+    return {
+        reason: row.freeze_reason === null || row.freeze_reason === undefined ? null : String(row.freeze_reason),
+        holder: row.freeze_holder === null || row.freeze_holder === undefined ? null : String(row.freeze_holder),
+        untilMs: toMs(row.freeze_until_ms),
+        fence,
+    };
+}
+/** ¿Está VIVO este freeze en el instante `nowMs`? (motivo puesto y lease sin vencer; `untilMs: null` no vence). */
+export function freezeIsLive(row, nowMs) {
+    if (row.reason === null)
+        return false;
+    return row.untilMs === null || row.untilMs > nowMs;
+}
+/**
+ * Toma el freeze si NADIE lo sostiene vivo (condicional y atómico: dos
+ * `acquire` a la vez acaban en exactamente uno). Devuelve el token, o `null`
+ * si hay un freeze vivo de otro dueño (el llamante decide si eso es 423 o un
+ * contexto que reconoce).
+ */
+export async function acquireFreeze(input, options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const updated = await guardSql(driver, 'freeze.acquire', timeoutMs, () => db
+        .from(CATALOG_VERSION_TABLE)
+        .where('id', FREEZE_ROW_ID)
+        .where((q) => {
+        // Libre, o con el lease VENCIDO (un dueño muerto no bloquea la toma).
+        q.whereNull('freeze_reason').orWhere((expired) => {
+            expired.whereNotNull('freeze_until_ms').andWhere('freeze_until_ms', '<=', input.nowMs);
+        });
+    })
+        .update({
+        freeze_reason: input.reason,
+        freeze_holder: input.holder,
+        freeze_until_ms: input.untilMs,
+        freeze_fence: db.raw('freeze_fence + 1'),
+        updated_at: new Date(input.nowMs),
+    }));
+    if (Number(updated) === 0) {
+        // O hay un freeze vivo, o la fila no existe: distinguirlo es leerla.
+        const row = await readFreezeRow(options);
+        if (freezeIsLive(row, input.nowMs))
+            return null;
+        // Carrera minúscula (se liberó entre el UPDATE y el SELECT): reintenta una vez.
+        return acquireFreeze(input, options);
+    }
+    const row = await readFreezeRow(options);
+    if (row.holder !== input.holder)
+        return null; // otro acquire ganó justo después (no debería: el nuestro dejó la fila viva)
+    return { fence: row.fence, holder: input.holder };
+}
+/**
+ * Renueva el lease, CONDICIONAL por token y solo si aún no venció
+ * (`freeze_until_ms > now`). `false` = el lease se PERDIÓ (caducó a mitad, o
+ * otro dueño tomó el freeze): el llamante lo marca `lapsed` y deja de
+ * renovar — nunca «recupera» un freeze que ya no es suyo.
+ */
+export async function renewFreeze(token, input, options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const updated = await guardSql(driver, 'freeze.renew', timeoutMs, () => db
+        .from(CATALOG_VERSION_TABLE)
+        .where('id', FREEZE_ROW_ID)
+        .where('freeze_fence', token.fence)
+        .where('freeze_holder', token.holder)
+        .where('freeze_until_ms', '>', input.nowMs)
+        .update({ freeze_until_ms: input.untilMs, updated_at: new Date(input.nowMs) }));
+    return Number(updated) > 0;
+}
+/**
+ * Levanta el freeze de ESTE token (condicional: uno ajeno o rezagado no toca
+ * nada). Devuelve además `lapsed`: si en el instante de cerrar el lease ya
+ * estaba vencido o el token ya no era el de la fila, hubo una ventana en la
+ * que otros procesos pudieron escribir — es lo que el reporte publica.
+ */
+export async function releaseFreeze(token, input, options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const row = await readFreezeRow(options);
+    const mine = row.fence === token.fence && row.holder === token.holder;
+    const lapsed = !mine || (row.untilMs !== null && row.untilMs <= input.nowMs);
+    if (!mine)
+        return { released: false, lapsed };
+    const updated = await guardSql(driver, 'freeze.release', timeoutMs, () => db
+        .from(CATALOG_VERSION_TABLE)
+        .where('id', FREEZE_ROW_ID)
+        .where('freeze_fence', token.fence)
+        .where('freeze_holder', token.holder)
+        .update({ freeze_reason: null, freeze_holder: null, freeze_until_ms: null, updated_at: new Date(input.nowMs) }));
+    return { released: Number(updated) > 0, lapsed };
+}
+/** El `kind` que el holder lleva escrito (`operator:123:ab…` → `operator`). */
+export function freezeKindOf(holder) {
+    const prefix = holder?.split(':', 1)[0];
+    return prefix === 'operator' || prefix === 'reconcile' || prefix === 'platform' ? prefix : 'unknown';
+}
+//# sourceMappingURL=freeze.js.map

package/build/src/freeze.js.map

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

package/build/src/hierarchical_resolver.d.ts

@@ -0,0 +1,56 @@
+import type { ScopeChainResolver, ScopeRef } from './types.js';
+/**
+ * Un nodo del árbol del consumidor, tal como está en SU tabla (2.5-B · K1):
+ *  - `self`: el propio scope CANÓNICO (la fila leída: su `type` y su `uuid`
+ *    tal como están guardados, no tal como llegó la pregunta);
+ *  - `parent`: el padre directo (`ScopeRef`; si es `app`, la cadena termina
+ *    ahí), o `null` si el nodo es de primer nivel ⇒ cuelga de `app`.
+ */
+export interface ScopeNode {
+    self: ScopeRef;
+    parent: ScopeRef | null;
+}
+/**
+ * `nodeOf` del consumidor: la fila de un scope.
+ *  - `ScopeNode`: el nodo existe; `self` es su identidad canónica y `parent`
+ *    su padre (`null` = primer nivel);
+ *  - `undefined`: el scope NO existe ⇒ el resolutor devuelve `null` y el
+ *    motor deniega/rechaza escribir (L0.3). Vale también a mitad de cadena:
+ *    un hijo cuyo padre ya no existe es un árbol roto, no un nodo de `app`.
+ * Si lanza, el error se propaga tal cual y el driver lo clasifica como 503
+ * `E_AUTHZ_RESOLVER_FAILED` (nunca `[]`, nunca `false`). Un `self` o un
+ * padre mal formado (`{app, uuid}`, tipo en mayúsculas…) es 503
+ * `E_AUTHZ_RESOLVER_FAILED` del propio resolutor (F6): nunca se normaliza en
+ * silencio. Un `self` que no sea el scope preguntado (otro tipo, o un uuid
+ * que no es el mismo id salvo mayúsculas/guiones) también es 503: la fila
+ * que devuelves tiene que ser la del scope que se te pidió.
+ *
+ * Por qué devuelve el nodo entero y no solo el padre (`parentOf` de 2.1): con
+ * el tipo `uuid` de PostgreSQL o una collation `*_ci`, `SELECT … WHERE uuid =
+ * ?` encuentra la fila para un ALIAS del id (mayúsculas, sin guiones); si el
+ * resolutor solo devolvía el padre, la cadena se construía con el alias del
+ * llamante y los hechos —guardados canónicos— no casaban (el deny se evadía).
+ */
+export type NodeOf = (scope: ScopeRef) => Promise<ScopeNode | undefined>;
+export interface HierarchicalResolverOptions {
+    nodeOf: NodeOf;
+    /**
+     * Número máximo de ANCESTROS (`app` incluida; el propio scope no cuenta).
+     * Default 64. Superado ⇒ lanza 500 `E_AUTHZ_SCOPE_TOO_DEEP`: truncar
+     * devolvería una cadena sin la raíz y el deny de `app` dejaría de verse
+     * (fail-open).
+     */
+    maxDepth?: number;
+}
+/**
+ * Construye un `ScopeChainResolver` a partir de un `nodeOf` (2.1, B4; 2.5-B ·
+ * K1): lee el nodo (canónico), sube padre a padre hasta `app`, con conjunto
+ * de visitados (un ciclo lanza 422 `E_AUTHZ_SCOPE_CYCLE`: FGA evaluaría el
+ * ciclo y un grant en cualquier nodo concedería en la raíz, S2) y cota de
+ * profundidad que lanza. Cuesta una llamada a `nodeOf` por nivel: envuélvelo
+ * con `memoizeAncestors` (o usa `forRequest()`) para que una request no lo
+ * pague por cada pregunta. La cadena que devuelve es `[self canónico,
+ * ...padres canónicos, APP_SCOPE]`: cada nivel es la fila leída.
+ */
+export declare function hierarchicalScopeResolver(options: HierarchicalResolverOptions): ScopeChainResolver;
+//# sourceMappingURL=hierarchical_resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical_resolver.d.ts","sourceRoot":"","sources":["../../src/hierarchical_resolver.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;AAExE,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,2BAA2B,GAAG,kBAAkB,CA8ElG"}

package/build/src/hierarchical_resolver.js

@@ -0,0 +1,87 @@
+import { ScopeCycleError, ScopeResolverError, ScopeTooDeepError } from './errors.js';
+import { assertScope } from './identity.js';
+import { APP_SCOPE, APP_SCOPE_TYPE } from './types.js';
+/**
+ * Construye un `ScopeChainResolver` a partir de un `nodeOf` (2.1, B4; 2.5-B ·
+ * K1): lee el nodo (canónico), sube padre a padre hasta `app`, con conjunto
+ * de visitados (un ciclo lanza 422 `E_AUTHZ_SCOPE_CYCLE`: FGA evaluaría el
+ * ciclo y un grant en cualquier nodo concedería en la raíz, S2) y cota de
+ * profundidad que lanza. Cuesta una llamada a `nodeOf` por nivel: envuélvelo
+ * con `memoizeAncestors` (o usa `forRequest()`) para que una request no lo
+ * pague por cada pregunta. La cadena que devuelve es `[self canónico,
+ * ...padres canónicos, APP_SCOPE]`: cada nivel es la fila leída.
+ */
+export function hierarchicalScopeResolver(options) {
+    const { nodeOf } = options;
+    const maxDepth = options.maxDepth ?? 64;
+    if (typeof nodeOf !== 'function') {
+        throw new TypeError('hierarchicalScopeResolver: nodeOf debe ser una función');
+    }
+    if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+        throw new TypeError(`hierarchicalScopeResolver: maxDepth debe ser un entero >= 1 (llegó ${String(maxDepth)})`);
+    }
+    // Separador no imprimible, escrito como escape (nunca como carácter
+    // literal): sin él `org`+`a-1` y `o`+`rga-1` colisionaban y un árbol
+    // legítimo era un 422 falso de ciclo (F6, CR4).
+    const key = (s) => `${s.type}\u001f${s.uuid ?? ''}`;
+    const fold = (uuid) => (uuid ?? '').toLowerCase().replaceAll('-', '');
+    return async (scope) => {
+        if (scope.type === APP_SCOPE_TYPE)
+            return [APP_SCOPE];
+        const label = `hierarchicalScopeResolver(${scope.type}:${scope.uuid ?? ''})`;
+        const chain = [];
+        const visited = new Set();
+        let asked = scope;
+        for (;;) {
+            const node = await nodeOf(asked);
+            if (node === undefined)
+                return null;
+            // La RESPUESTA del árbol se valida (D13, F6, K1): un `self` o un padre
+            // mal formado no es un nodo, es un fallo de la dependencia ⇒ 503 con la
+            // causa; y `self` tiene que ser la fila del scope que se pidió.
+            if (!node || typeof node !== 'object' || !('self' in node) || !('parent' in node)) {
+                throw new ScopeResolverError(label, new TypeError(`nodeOf devolvió ${typeof node} en vez de { self, parent } | undefined`));
+            }
+            try {
+                assertScope(node.self);
+            }
+            catch (error) {
+                throw new ScopeResolverError(label, error);
+            }
+            if (node.self.type !== asked.type || fold(node.self.uuid) !== fold(asked.uuid)) {
+                throw new ScopeResolverError(label, new TypeError(`nodeOf(${asked.type}:${asked.uuid ?? ''}) devolvió self = ${node.self.type}:${node.self.uuid ?? ''}: no es la fila del scope pedido`));
+            }
+            const self = node.self;
+            const k = key(self);
+            if (visited.has(k)) {
+                throw new ScopeCycleError(`hierarchicalScopeResolver: ciclo al resolver ${scope.type}:${scope.uuid} — ` +
+                    `${self.type}:${self.uuid} ya está en la cadena (${chain.map((s) => `${s.type}:${s.uuid}`).join(' → ') || 'vacía'})`);
+            }
+            visited.add(k);
+            chain.push(self);
+            // Los ancestros serán (nodos leídos − 1) + `app` = nodos leídos: si ya
+            // superan la cota, se lanza ahora — nunca se devuelve una cadena corta.
+            if (chain.length > maxDepth) {
+                throw new ScopeTooDeepError(`hierarchicalScopeResolver: la cadena de ${scope.type}:${scope.uuid} supera maxDepth=${maxDepth} ` +
+                    `(truncarla dejaría fuera la raíz y sus denies)`);
+            }
+            const parent = node.parent;
+            if (parent === null) {
+                chain.push(APP_SCOPE);
+                return chain;
+            }
+            try {
+                assertScope(parent);
+            }
+            catch (error) {
+                throw new ScopeResolverError(label, error);
+            }
+            if (parent.type === APP_SCOPE_TYPE) {
+                chain.push(APP_SCOPE);
+                return chain;
+            }
+            asked = parent;
+        }
+    };
+}
+//# sourceMappingURL=hierarchical_resolver.js.map

package/build/src/hierarchical_resolver.js.map

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

package/build/src/{middleware → http}/app_access_middleware.d.ts

@@ -7,17 +7,19 @@ import type { NextFn } from '@adonisjs/core/types/http';
  *
  * Reglas:
  *  - No autenticado → 401.
- *  - Holder sin el rol/permiso requerido a nivel app → 403.
+ *  - Holder sin el permiso requerido a nivel app → 403.
  *  - El ACL decide por IDENTIDAD; el scope del token lo acota
  *    middleware.ability() aparte (el token nunca amplía, solo restringe).
+ *  - Solo `permission`. `{ role }` se retiró (L0.6): `hasRole` es membresía
+ *    y el deny no la gobierna, así que un PEP sobre un rol era indenegable.
+ *    Toda decisión de acceso pasa por `authorize`.
  *
  * Uso: middleware.appAccess({ permission: 'audit:read' })
- *      middleware.appAccess({ role: 'superadmin' })
  */
+export interface AppAccessOptions {
+    permission: string;
+}
 export default class AppAccessMiddleware {
-    handle(ctx: HttpContext, next: NextFn, options?: {
-        permission?: string;
-        role?: string;
-    }): Promise<any>;
+    handle(ctx: HttpContext, next: NextFn, options: AppAccessOptions): Promise<any>;
 }
 //# sourceMappingURL=app_access_middleware.d.ts.map

package/build/src/http/app_access_middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_access_middleware.d.ts","sourceRoot":"","sources":["../../../src/http/app_access_middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAMvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB;CAgDvE"}

package/build/src/{middleware → http}/app_access_middleware.js

@@ -1,24 +1,16 @@
 import { Exception } from '@adonisjs/core/exceptions';
 import authorization from '../../services/main.js';
 import { APP_SCOPE } from '../types.js';
-/**
- * Enforcement del ACL de NIVEL APP (gemelo de orgAccess para el scope
- * global). Debe ir DESPUÉS de `middleware.auth(...)` — típicamente con el
- * guard `admins`, aunque funciona con cualquier holder con morph name.
- *
- * Reglas:
- *  - No autenticado → 401.
- *  - Holder sin el rol/permiso requerido a nivel app → 403.
- *  - El ACL decide por IDENTIDAD; el scope del token lo acota
- *    middleware.ability() aparte (el token nunca amplía, solo restringe).
- *
- * Uso: middleware.appAccess({ permission: 'audit:read' })
- *      middleware.appAccess({ role: 'superadmin' })
- */
+import { AuthorizationConfigError, RoleIsNotAccessError } from '../errors.js';
 export default class AppAccessMiddleware {
-    async handle(ctx, next, options = {}) {
-        if (!options.permission && !options.role) {
-            throw new Exception('middleware.appAccess requiere `permission` o `role`', { status: 500 });
+    async handle(ctx, next, options) {
+        // Antes de mirar si hay usuario: una ruta mal declarada tiene que saltar
+        // en el primer request de desarrollo, autenticado o no.
+        if (options && 'role' in options) {
+            throw new RoleIsNotAccessError(options.role);
+        }
+        if (!options?.permission) {
+            throw new AuthorizationConfigError("middleware.appAccess requiere `{ permission }` (p. ej. appAccess({ permission: 'audit:read' }))");
         }
         const holder = ctx.auth?.user;
         if (!holder) {
@@ -39,15 +31,7 @@ export default class AppAccessMiddleware {
                 `no por la clave primaria del modelo.`, { status: 500 });
         }
         const subject = { type: morph, uuid: holder.uuid };
-        if (options.role && !(await authorization.hasRole(subject, options.role, APP_SCOPE))) {
-            return ctx.response.forbidden({
-                message: 'Permiso insuficiente',
-                statusCode: 403,
-                errors: [],
-            });
-        }
-        if (options.permission &&
-            !(await authorization.authorize(subject, options.permission, APP_SCOPE))) {
+        if (!(await authorization.authorize(subject, options.permission, APP_SCOPE))) {
             return ctx.response.forbidden({
                 message: 'Permiso insuficiente',
                 statusCode: 403,

package/build/src/http/app_access_middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_access_middleware.js","sourceRoot":"","sources":["../../../src/http/app_access_middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,aAAa,MAAM,wBAAwB,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAsB7E,MAAM,CAAC,OAAO,OAAO,mBAAmB;IACtC,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,IAAY,EAAE,OAAyB;QACpE,yEAAyE;QACzE,wDAAwD;QACxD,IAAI,OAAO,IAAI,MAAM,IAAK,OAAkB,EAAE,CAAC;YAC7C,MAAM,IAAI,oBAAoB,CAAE,OAAe,CAAC,IAAI,CAAC,CAAA;QACvD,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,wBAAwB,CAChC,iGAAiG,CAClG,CAAA;QACH,CAAC;QAED,MAAM,MAAM,GAAI,GAAW,CAAC,IAAI,EAAE,IAA6D,CAAA;QAC/F,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9F,CAAC;QAED,mEAAmE;QACnE,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAA;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,SAAS,CAAC,mEAAmE,EAAE;gBACvF,MAAM,EAAE,GAAG;aACZ,CAAC,CAAA;QACJ,CAAC;QAED,kEAAkE;QAClE,wEAAwE;QACxE,yEAAyE;QACzE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,SAAS,CACjB,cAAc,KAAK,mEAAmE;gBACpF,sCAAsC,EACxC,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAA;QACH,CAAC;QAED,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;QAElD,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;YAC7E,OAAO,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAC5B,OAAO,EAAE,sBAAsB;gBAC/B,UAAU,EAAE,GAAG;gBACf,MAAM,EAAE,EAAE;aACX,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,IAAI,EAAE,CAAA;IACf,CAAC;CACF"}