@jantstack/adonis-authz 2.0.0-alpha.1 → 2.4.0-alpha.10

package/build/src/freeze.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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 barrera se lee SIEMPRE por la conexión del motor, nunca por un
+ * cliente del llamante** (L-1 · 🟠 8, dictamen del juez del panel `{trx}`).
+ * Hasta L-1 `readFreezeRow` aceptaba `client` —la transacción del consumidor,
+ * «para no interbloquear un pool de 1»— y eso convertía la AUTORIDAD en una
+ * decisión del llamante: un cliente que responde «no congelado», o el
+ * snapshot REPEATABLE READ de una transacción abierta ANTES del freeze, dejaba
+ * entrar la escritura (medido: auditor C1 en SQLite; MySQL/PG en
+ * `freeze.spec.ts`). La regla: *la escritura va por tu transacción; la
+ * autoridad que decide si puedes escribir, nunca*. El precio, decidido por el
+ * dueño: `{ transaction }` exige pool ≥ 2 — con pool 1 la lectura de la
+ * barrera espera una conexión que el llamante sostiene y sale **503
+ * `E_AUTHZ_BACKEND_TIMEOUT` al vencer SU deadline** (`withDeadline`, porque
+ * el `timeout()` de knex NO cubre la espera del pool: medido, 60 s), jamás
+ * un cuelgue ni un bypass.
+ */
+/** 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 TOTAL de cada consulta (default 5000), espera del pool incluida:
+     * vencido ⇒ 503 `E_AUTHZ_BACKEND_TIMEOUT`. No hay opción para leer por otro
+     * cliente: la barrera es autoridad y va por la conexión del motor (L-1).
+     */
+    timeoutMs?: number;
+}
+/**
+ * Lee la fila del freeze **por la conexión del motor** (503 clasificado si la
+ * base no responde o el pool no da una conexión en `timeoutMs`; 503 «migración
+ * no aplicada» si no existe). No acepta cliente: es la autoridad (L-1 · 🟠 8).
+ */
+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;
+export interface FreezeBarrierOptions extends FreezeSqlOptions {
+    /** Milisegundos de PARED del reloj del config (el mismo que decide caducidades). */
+    nowMs: number;
+}
+/**
+ * **La barrera del freeze**, la MISMA para los dos motores (roles y
+ * relations, L-1 · J1): lee la fila por la conexión del motor y lanza 503
+ * `E_AUTHZ_FROZEN` (reintentable) si hay un freeze vivo en `nowMs`. Va
+ * delante de TODA escritura, antes de validar identidades o tocar el driver:
+ * durante una ventana una escritura no se valida a medias, se rechaza entera.
+ * Nunca recibe un cliente del llamante — ver el docblock del módulo.
+ */
+export declare function assertNotFrozenRow(operation: string, options: FreezeBarrierOptions): Promise<void>;
+/** El holder con el que se publica una fila con motivo y SIN holder (legada o a mano); también es su token. */
+export declare const UNKNOWN_HOLDER = "?";
+/** Prefijo del holder de la ventana del OPERADOR (`freeze()` con `kind: 'operator'`). */
+export declare const OPERATOR_HOLDER_PREFIX = "operator:";
+/**
+ * `isOperatorHolder` en SQL, por motor (cierre-2 de alpha.10 · C3): los
+ * `OPERATOR_HOLDER_PREFIX.length` primeros CARACTERES de `freeze_holder` igual a
+ * `operator:`, sensible a mayúsculas y acentos. SQLite: `substr()` no hereda
+ * collation ⇒ `BINARY`. PostgreSQL: `COLLATE "C"` (byte a byte aunque la base
+ * declare otra). MySQL: la collation de la columna es la de la tabla (`_ai_ci` por
+ * defecto: `OPERATOR:` y `opérator:` serían iguales), así que se compara como
+ * BINARIO. El prefijo es ASCII, así que «9 caracteres» y «9 unidades UTF-16» (JS)
+ * coinciden siempre que la comparación sea verdadera. Sin `LIKE`: ni comodines ni
+ * collation. Cualquier otro dialecto ⇒ 500 `E_AUTHZ_UNSUPPORTED_DIALECT` ANTES de
+ * tocar la fila (re-ataque del cierre-2 · ⚪ 3: el `substr` de SQLite en MSSQL
+ * sería un error del motor envuelto como 503, que invita a reintentar para siempre).
+ */
+export declare function operatorHolderSql(connection?: any): {
+    sql: string;
+    bindings: unknown[];
+};
+/**
+ * Qué pasó al intentar tomar el freeze: `acquired` (con el token), `held` (hay
+ * un freeze VIVO de otro dueño) o `expired-operator` (la fila es una ventana de
+ * OPERADOR con el lease vencido, que no se pisa). `row` es la fila releída para
+ * REDACTAR el error; la decisión ya la tomó el UPDATE.
+ */
+export type FreezeAcquireOutcome = {
+    status: 'acquired';
+    token: FreezeToken;
+} | {
+    status: 'held';
+    row: FreezeRow;
+} | {
+    status: 'expired-operator';
+    row: FreezeRow;
+};
+/**
+ * Toma el freeze si NADIE lo sostiene vivo (condicional y atómico: dos
+ * `acquire` a la vez acaban en exactamente uno). Una fila con el lease VENCIDO
+ * se toma encima (el dueño murió: la flota vuelve sola) **salvo que sea una
+ * ventana de OPERADOR** (cierre del auditor de alpha.10 · R2): esa exclusión va
+ * DENTRO del `WHERE` del mismo `UPDATE`, en los tres motores. Hasta el cierre
+ * vivía en `freeze()` como «leo la fila, compruebo, tomo», y con un reloj que
+ * cruzaba el vencimiento entre la comprobación y el UPDATE la pasada pisaba la
+ * ventana del operador sin 503 — el TOCTOU que el atómico existe para cerrar.
+ */
+export declare function acquireFreezeOutcome(input: {
+    reason: string;
+    holder: string;
+    untilMs: number | null;
+    nowMs: number;
+}, options?: FreezeSqlOptions, attempt?: number): Promise<FreezeAcquireOutcome>;
+/** `acquireFreezeOutcome` reducido a «el token o `null`» (lo usan los casos que siembran una fila ajena). */
+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;
+}>;
+/**
+ * **La regla ÚNICA del prefijo de operador** (cierre-2 de alpha.10 · C3): los
+ * `OPERATOR_HOLDER_PREFIX.length` primeros caracteres del holder son EXACTAMENTE
+ * `operator:` — sensible a mayúsculas y a acentos, sin comodines. La MISMA
+ * comparación va en el `WHERE` de `acquireFreezeOutcome` (`operatorHolderSql`) y
+ * aquí; hasta el cierre-2 el SQL usaba `LIKE` (insensible a mayúsculas en SQLite y
+ * en MySQL `_ci`) y JS partía por `:`, así que un holder `OPERATOR:…` caducado era
+ * «de operador» para el UPDATE y `unknown` para JS ⇒ 423 «VIVO» sobre una fila
+ * caducada, distinto por motor.
+ */
+export declare function isOperatorHolder(holder: string | null): boolean;
+/** El `kind` que el holder lleva escrito (`operator:123:ab…` → `operator`); el de operador, por `isOperatorHolder`. */
+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":"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"}

package/build/src/freeze.js

@@ -0,0 +1,306 @@
+import db from '@adonisjs/lucid/services/db';
+import { guardSql, withDeadline } from './shared/backend_guard.js';
+import { AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationFrozenError, UnsupportedDialectError, } from './errors.js';
+import { CATALOG_VERSION_TABLE } from './catalog/catalog_cache.js';
+import { dialectOf, isMysqlDialect, isSqliteDialect } from './shared/sql_expiry.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 barrera se lee SIEMPRE por la conexión del motor, nunca por un
+ * cliente del llamante** (L-1 · 🟠 8, dictamen del juez del panel `{trx}`).
+ * Hasta L-1 `readFreezeRow` aceptaba `client` —la transacción del consumidor,
+ * «para no interbloquear un pool de 1»— y eso convertía la AUTORIDAD en una
+ * decisión del llamante: un cliente que responde «no congelado», o el
+ * snapshot REPEATABLE READ de una transacción abierta ANTES del freeze, dejaba
+ * entrar la escritura (medido: auditor C1 en SQLite; MySQL/PG en
+ * `freeze.spec.ts`). La regla: *la escritura va por tu transacción; la
+ * autoridad que decide si puedes escribir, nunca*. El precio, decidido por el
+ * dueño: `{ transaction }` exige pool ≥ 2 — con pool 1 la lectura de la
+ * barrera espera una conexión que el llamante sostiene y sale **503
+ * `E_AUTHZ_BACKEND_TIMEOUT` al vencer SU deadline** (`withDeadline`, porque
+ * el `timeout()` de knex NO cubre la espera del pool: medido, 60 s), jamás
+ * un cuelgue ni un bypass.
+ */
+/** 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 };
+}
+/**
+ * Una consulta del freeze con deadline TOTAL. `guardSql` fija el `timeout()`
+ * de knex, que solo cuenta desde que la consulta tiene conexión: si el pool
+ * está agotado (el llamante sostiene la única conexión de `:memory:`), la
+ * espera la gobierna `acquireConnectionTimeout` (60 s por defecto) — medido,
+ * L-1. `withDeadline` cubre también esa espera, así que con pool 1 la
+ * barrera responde 503 en `timeoutMs`, no en un minuto.
+ */
+function freezeSql(driver, operation, timeoutMs, fn) {
+    return withDeadline(guardSql(driver, operation, timeoutMs, fn), timeoutMs, () => new AuthorizationBackendTimeoutError(driver, operation, timeoutMs));
+}
+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 **por la conexión del motor** (503 clasificado si la
+ * base no responde o el pool no da una conexión en `timeoutMs`; 503 «migración
+ * no aplicada» si no existe). No acepta cliente: es la autoridad (L-1 · 🟠 8).
+ */
+export async function readFreezeRow(options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const rows = await freezeSql(driver, 'freeze.read', timeoutMs, () => db
+        .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;
+}
+/**
+ * **La barrera del freeze**, la MISMA para los dos motores (roles y
+ * relations, L-1 · J1): lee la fila por la conexión del motor y lanza 503
+ * `E_AUTHZ_FROZEN` (reintentable) si hay un freeze vivo en `nowMs`. Va
+ * delante de TODA escritura, antes de validar identidades o tocar el driver:
+ * durante una ventana una escritura no se valida a medias, se rechaza entera.
+ * Nunca recibe un cliente del llamante — ver el docblock del módulo.
+ */
+export async function assertNotFrozenRow(operation, options) {
+    const row = await readFreezeRow(options);
+    if (!freezeIsLive(row, options.nowMs))
+        return;
+    const lift = freezeKindOf(row.holder) === 'operator' ? ' (la levanta authz:unfreeze)' : '';
+    throw new AuthorizationFrozenError(`${operation}: el motor de autorización está congelado (${row.reason})${lift} y no acepta escrituras. ` +
+        `Las lecturas siguen funcionando; reintenta esta escritura cuando la ventana termine.`);
+}
+/** El holder con el que se publica una fila con motivo y SIN holder (legada o a mano); también es su token. */
+export const UNKNOWN_HOLDER = '?';
+/** Prefijo del holder de la ventana del OPERADOR (`freeze()` con `kind: 'operator'`). */
+export const OPERATOR_HOLDER_PREFIX = 'operator:';
+/**
+ * `isOperatorHolder` en SQL, por motor (cierre-2 de alpha.10 · C3): los
+ * `OPERATOR_HOLDER_PREFIX.length` primeros CARACTERES de `freeze_holder` igual a
+ * `operator:`, sensible a mayúsculas y acentos. SQLite: `substr()` no hereda
+ * collation ⇒ `BINARY`. PostgreSQL: `COLLATE "C"` (byte a byte aunque la base
+ * declare otra). MySQL: la collation de la columna es la de la tabla (`_ai_ci` por
+ * defecto: `OPERATOR:` y `opérator:` serían iguales), así que se compara como
+ * BINARIO. El prefijo es ASCII, así que «9 caracteres» y «9 unidades UTF-16» (JS)
+ * coinciden siempre que la comparación sea verdadera. Sin `LIKE`: ni comodines ni
+ * collation. Cualquier otro dialecto ⇒ 500 `E_AUTHZ_UNSUPPORTED_DIALECT` ANTES de
+ * tocar la fila (re-ataque del cierre-2 · ⚪ 3: el `substr` de SQLite en MSSQL
+ * sería un error del motor envuelto como 503, que invita a reintentar para siempre).
+ */
+export function operatorHolderSql(connection = db.connection()) {
+    const length = OPERATOR_HOLDER_PREFIX.length;
+    if (isMysqlDialect(connection)) {
+        return { sql: `CAST(SUBSTRING(freeze_holder, 1, ${length}) AS BINARY) = CAST(? AS BINARY)`, bindings: [OPERATOR_HOLDER_PREFIX] };
+    }
+    if (dialectOf(connection).startsWith('postgres')) {
+        return { sql: `substr(freeze_holder, 1, ${length}) COLLATE "C" = ?`, bindings: [OPERATOR_HOLDER_PREFIX] };
+    }
+    if (isSqliteDialect(connection)) {
+        return { sql: `substr(freeze_holder, 1, ${length}) = ?`, bindings: [OPERATOR_HOLDER_PREFIX] };
+    }
+    throw new UnsupportedDialectError(`freeze: dialecto '${dialectOf(connection)}' sin observación en la suite (hoy: PostgreSQL, MySQL 8 y SQLite)`);
+}
+/**
+ * Toma el freeze si NADIE lo sostiene vivo (condicional y atómico: dos
+ * `acquire` a la vez acaban en exactamente uno). Una fila con el lease VENCIDO
+ * se toma encima (el dueño murió: la flota vuelve sola) **salvo que sea una
+ * ventana de OPERADOR** (cierre del auditor de alpha.10 · R2): esa exclusión va
+ * DENTRO del `WHERE` del mismo `UPDATE`, en los tres motores. Hasta el cierre
+ * vivía en `freeze()` como «leo la fila, compruebo, tomo», y con un reloj que
+ * cruzaba el vencimiento entre la comprobación y el UPDATE la pasada pisaba la
+ * ventana del operador sin 503 — el TOCTOU que el atómico existe para cerrar.
+ */
+export async function acquireFreezeOutcome(input, options = {}, attempt = 0) {
+    const { driver, timeoutMs } = opts(options);
+    // Fuera de `freezeSql`: un dialecto no soportado es config (500), no un backend caído (503).
+    const operator = operatorHolderSql();
+    const updated = await freezeSql(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)
+                // …salvo la ventana del OPERADOR vencida: es evidencia, no espacio libre (R2).
+                .andWhere((notOperator) => {
+                // La regla ÚNICA (`isOperatorHolder`), sin `LIKE`: comparación EXACTA de prefijo (cierre-2 · C3).
+                notOperator.whereNull('freeze_holder').orWhereRaw(`NOT (${operator.sql})`, operator.bindings);
+            });
+        });
+    })
+        .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 una ventana de operador vencida, o la fila no existe: distinguirlo es leerla.
+        const row = await readFreezeRow(options);
+        if (freezeIsLive(row, input.nowMs))
+            return { status: 'held', row };
+        if (row.reason !== null && freezeKindOf(row.holder) === 'operator')
+            return { status: 'expired-operator', row };
+        // Carrera minúscula (se liberó entre el UPDATE y el SELECT): reintenta UNA vez.
+        // Cierre-2 · C3: tras el reintento, una fila que NO está viva no es `held` (su
+        // letra dice «VIVO»). Con la regla única del prefijo esta rama solo la alcanza
+        // una fila que cambió dos veces entre UPDATE y SELECT: 503 reintentable que lo dice.
+        if (attempt >= 1) {
+            const error = new AuthorizationBackendError(driver, 'freeze.acquire', new Error('la fila del freeze cambió entre el UPDATE condicional y su relectura dos veces seguidas'));
+            error.message =
+                `${driver}: no se pudo tomar el freeze: la fila (${row.holder ?? 'sin holder'}, fence ${row.fence}) NO está viva ` +
+                    `y aun así el UPDATE condicional no casó dos veces seguidas — otro proceso la está cambiando a la vez ` +
+                    `(rama «contención tras reintento», no «freeze VIVO»). Reintenta.`;
+            throw error;
+        }
+        return acquireFreezeOutcome(input, options, attempt + 1);
+    }
+    const row = await readFreezeRow(options);
+    // Otro acquire ganó justo después (no debería: el nuestro dejó la fila viva).
+    if (row.holder !== input.holder)
+        return { status: 'held', row };
+    return { status: 'acquired', token: { fence: row.fence, holder: input.holder } };
+}
+/** `acquireFreezeOutcome` reducido a «el token o `null`» (lo usan los casos que siembran una fila ajena). */
+export async function acquireFreeze(input, options = {}) {
+    const outcome = await acquireFreezeOutcome(input, options);
+    return outcome.status === 'acquired' ? outcome.token : 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 async function renewFreeze(token, input, options = {}) {
+    const { driver, timeoutMs } = opts(options);
+    const updated = await freezeSql(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);
+    // La fila SIN holder (legada o escrita a mano) se publica como `UNKNOWN_HOLDER`
+    // en `freezeStatus()`/`lastFreezeStatus()`, así que ese es su token: sin esto
+    // `authz:unfreeze` no casaba nunca y repetía su aviso para siempre (cierre del
+    // auditor de alpha.10 · ⚪ 5). `freeze()` jamás escribe ese holder.
+    // Cierre-2 · C4: `'?'` publica DOS filas —holder NULL y holder LITERAL `'?'` (a
+    // mano)—, así que el token casa las dos (`IS NULL OR = '?'`); casar solo NULL
+    // dejaba la literal sin salida y `authz:unfreeze` en bucle con exit 1. Sigue
+    // atado al fence y nunca casa un holder real.
+    const unknownHolder = token.holder === UNKNOWN_HOLDER;
+    const mine = row.fence === token.fence && (unknownHolder ? row.holder === null || row.holder === UNKNOWN_HOLDER : row.holder === token.holder);
+    const lapsed = !mine || (row.untilMs !== null && row.untilMs <= input.nowMs);
+    if (!mine)
+        return { released: false, lapsed };
+    const updated = await freezeSql(driver, 'freeze.release', timeoutMs, () => db
+        .from(CATALOG_VERSION_TABLE)
+        .where('id', FREEZE_ROW_ID)
+        .where('freeze_fence', token.fence)
+        .where((q) => unknownHolder ? q.whereNull('freeze_holder').orWhere('freeze_holder', UNKNOWN_HOLDER) : q.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 };
+}
+/**
+ * **La regla ÚNICA del prefijo de operador** (cierre-2 de alpha.10 · C3): los
+ * `OPERATOR_HOLDER_PREFIX.length` primeros caracteres del holder son EXACTAMENTE
+ * `operator:` — sensible a mayúsculas y a acentos, sin comodines. La MISMA
+ * comparación va en el `WHERE` de `acquireFreezeOutcome` (`operatorHolderSql`) y
+ * aquí; hasta el cierre-2 el SQL usaba `LIKE` (insensible a mayúsculas en SQLite y
+ * en MySQL `_ci`) y JS partía por `:`, así que un holder `OPERATOR:…` caducado era
+ * «de operador» para el UPDATE y `unknown` para JS ⇒ 423 «VIVO» sobre una fila
+ * caducada, distinto por motor.
+ */
+export function isOperatorHolder(holder) {
+    return typeof holder === 'string' && holder.slice(0, OPERATOR_HOLDER_PREFIX.length) === OPERATOR_HOLDER_PREFIX;
+}
+/** El `kind` que el holder lleva escrito (`operator:123:ab…` → `operator`); el de operador, por `isOperatorHolder`. */
+export function freezeKindOf(holder) {
+    if (isOperatorHolder(holder))
+        return 'operator';
+    if (typeof holder !== 'string' || !holder.includes(':'))
+        return 'unknown';
+    const prefix = holder.slice(0, holder.indexOf(':'));
+    return 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/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/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"}

package/build/src/http/resource_access_middleware.d.ts

@@ -0,0 +1,105 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+import type { ScopeRef } from '../types.js';
+/**
+ * Enforcement de acceso A UN RECURSO concreto. COMPONE el `authorize` que ya
+ * existe: el consumidor dice CÓMO cargar el recurso (`load(ctx, id)`) y en qué
+ * `{ scope }` vive, y el middleware pregunta al motor sobre ese scope. No es un
+ * modelo ni un driver nuevo: es el borde HTTP del scope de un recurso.
+ *
+ * El ORDEN de las respuestas ES la propiedad de seguridad — un 403 donde
+ * debería ir un 404 filtra qué recursos existen (enumeración):
+ *
+ *   1. 401  si no hay usuario autenticado (antes de nada).
+ *   2. 403  si el `gate(ctx)` del consumidor (una ability previa, p. ej.
+ *           «es admin del tenant») lo niega.
+ *   3. 404  si el CONTENEDOR no existe (`containerParam`, cuando se declara).
+ *   4. 404  si el RECURSO no existe (`load` ⇒ null) — MISMO cuerpo que el 404
+ *           del contenedor, para no distinguir «no existe» de «no es tuyo».
+ *   5. authorize sobre el `{ scope }` que devolvió `load`, con `permission`
+ *           (o `readPermission` en métodos seguros): un `false` aquí también
+ *           es 404 con el MISMO cuerpo, NO un 403 — que no puedas verlo no
+ *           revela que existe.
+ *
+ * Invariantes que NO se negocian:
+ *  - `AuthorizationBackendError` (503) NUNCA se disfraza de 404/403: si el
+ *    backend cae (`gate`/`load`/`authorize` lanzan), el error sube tal cual.
+ *    Es lo que distingue «denegado» de «no pude comprobar». El middleware NO
+ *    envuelve estas llamadas en try/catch a propósito.
+ *  - Prohibido `role`: como `appAccess`, solo acepta `permission`/
+ *    `readPermission`. `{ role }` es 500 con receta (membresía no es acceso, y
+ *    el deny no la gobierna: toda decisión pasa por `authorize`).
+ *  - Sin segundo `authorize`: se llama UNA sola vez. No re-autoriza.
+ *
+ * Limitación conocida — canal de TEMPORIZACIÓN (auditor Fase 5, ⚪): el status
+ * y el cuerpo de «no existe» y «existe pero no es tuyo» son idénticos, pero el
+ * TIEMPO no: un id inexistente responde 404 sin round-trip a `authorize`; uno
+ * ajeno responde el mismo 404 tras esa llamada. Es inherente a load→authorize
+ * (no se puede autorizar el scope de algo que no se ha cargado), no un defecto;
+ * quien necesite cerrar el canal iguala el tiempo en su capa (delay constante),
+ * no en el middleware.
+ *
+ * Pureza: el middleware NO importa aliases del consumidor; `load`/`gate` llegan
+ * INYECTADOS en las opciones de la ruta.
+ *
+ * Uso:
+ *   router
+ *     .get('/orgs/:orgId/documents/:id', [DocumentsController, 'show'])
+ *     .use(middleware.resourceAccess({
+ *       resource: 'document',
+ *       param: 'id',
+ *       containerParam: 'orgId',
+ *       permission: 'documents:write',
+ *       readPermission: 'documents:read',
+ *       load: (ctx, id) => Document.query().where('id', id).first(),
+ *       gate: (ctx) => ctx.auth.user!.isMemberOf(ctx.params.orgId),
+ *     }))
+ */
+export interface ResourceAccessOptions {
+    /**
+     * Nombre del recurso. Es la clave bajo la que el recurso cargado (con su
+     * scope) se PROPAGA al `ctx` para el controlador (`ctx[resource]`), así que
+     * dos `resourceAccess` anidados no se pisan.
+     */
+    resource: string;
+    /** Nombre del param de ruta que trae el id del recurso (`ctx.params[param]`). */
+    param: string;
+    /**
+     * Nombre del param de ruta del contenedor (p. ej. el tenant de una ruta
+     * anidada). Cuando se declara, un contenedor ausente en la ruta es 404 —el
+     * MISMO cuerpo que un recurso ausente— y se comprueba ANTES de cargar el
+     * recurso. La pertenencia real del recurso al contenedor la comprueba
+     * `load` (que ve `ctx.params`): devolver `null` allí es el mismo 404, así que
+     * «no existe» y «no está en este contenedor» son indistinguibles.
+     */
+    containerParam?: string;
+    /** Permiso requerido (métodos que mutan, y lectura si no hay `readPermission`). */
+    permission: string;
+    /**
+     * Permiso requerido en métodos SEGUROS (GET/HEAD). Si se omite, una lectura
+     * exige `permission` — nunca es gratis. Suele ser el permiso MENOS
+     * privilegiado (ver vs escribir).
+     */
+    readPermission?: string;
+    /**
+     * Carga el recurso por su id y devuelve dónde vive (`{ scope }`) o `null` si
+     * no existe / no es visible. Del consumidor: ve el `ctx` entero (params,
+     * usuario). Un throw es «no pude comprobar» (sube como 503), NO un 404.
+     */
+    load: (ctx: HttpContext, id: string) => Promise<{
+        scope: ScopeRef;
+    } | null> | {
+        scope: ScopeRef;
+    } | null;
+    /**
+     * Ability previa del consumidor (p. ej. «es admin del tenant»). Opcional; si
+     * se declara y devuelve `false`, es 403 —una restricción ADICIONAL, evaluada
+     * antes de tocar el recurso—. Si se omite, no hay pre-check: la seguridad la
+     * da igualmente `authorize`.
+     */
+    gate?: (ctx: HttpContext) => Promise<boolean> | boolean;
+}
+export default class ResourceAccessMiddleware {
+    handle(ctx: HttpContext, next: NextFn, options: ResourceAccessOptions): Promise<any>;
+}
+//# sourceMappingURL=resource_access_middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource_access_middleware.d.ts","sourceRoot":"","sources":["../../../src/http/resource_access_middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAGvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,IAAI,EAAE,CACJ,GAAG,EAAE,WAAW,EAChB,EAAE,EAAE,MAAM,KACP,OAAO,CAAC;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC,GAAG;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAA;IACrE;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CACxD;AAKD,MAAM,CAAC,OAAO,OAAO,wBAAwB;IACrC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB;CA6F5E"}