@jantstack/adonis-authz 2.5.0-alpha.4 → 2.5.0-rc.2

package/build/src/scope_outbox.js

@@ -85,7 +85,9 @@ const MYSQL_LOCK_NAME_MAX = 64;
  * coincidieran en los primeros 64 COMPARTÍAN lease y se excluían para siempre
  * — y el modo de fallo era `busy: true`, que no lanza: el relay de uno de los
  * dos no corría nunca, en silencio. Desde alpha.5 el nombre es un hash
- * ESTABLE del nombre completo (`current`, 59 caracteres), que no colisiona.
+ * ESTABLE del nombre completo (`current`, 59 caracteres), que no colisiona entre
+ * TABLAS — entre BASES del mismo servidor sí: el «nombre completo» no llevaba la
+ * base (rotación 2 · R2-01, abajo).
  *
  * **Transición**: `sqlScopeOutbox.acquire()` toma el lock viejo (`legacy`, el
  * recortado) Y el nuevo durante alpha.5, porque en un rolling deploy un
@@ -114,13 +116,47 @@ export const SCOPE_OUTBOX_LEGACY_LOCK_UNTIL = '2.4.0-alpha.6';
  * desde ≤ alpha.4 en MySQL exige parada completa del relay, no despliegue rodante.
  */
 export const SCOPE_OUTBOX_TAKES_LEGACY_LOCK = false;
-export function scopeOutboxLockNames(connection, table) {
+/**
+ * **La identidad de la BASE en el nombre del lease** (rotación 2 de M4 · R2-01, decisión del dueño 2026-10-22 (1)).
+ * `GET_LOCK` es un cerrojo de SERVIDOR, y hasta 2.5.0-alpha.4 el nombre era `<conexión>:<tabla>`: dos despliegues en
+ * BASES distintas del mismo MySQL con la conexión por defecto de Adonis y la tabla del stub calculaban el MISMO nombre y
+ * se excluían (`busy`, exit 0) — el síntoma que R6 de alpha.5 daba por cerrado nunca lo estuvo, porque el «nombre
+ * completo» no llevaba la base. Desde este cierre `current` lleva la base que la PROPIA conexión que sostiene el lease
+ * lee con `DATABASE()` (no la del config: es la base contra la que esa sesión resuelve la tabla sin cualificar, o sea la
+ * identidad real de la cola; un alias de host o una URL distinta que apunte a la misma base dan el mismo nombre).
+ *
+ * En MINÚSCULAS a propósito: los dos errores posibles no cuestan lo mismo. Fundir `App` y `app` (dos bases distintas en
+ * un servidor sensible a mayúsculas) solo hace que esos dos despliegues compartan lease —vivacidad, `busy`—; separar la
+ * misma base escrita de dos formas por dos procesos del MISMO despliegue serían dos escritores —seguridad—. Se elige el
+ * error barato. `DATABASE()` `NULL` (sesión sin base por defecto: la tabla tiene que ir cualificada) entra como cadena
+ * vacía: los procesos de ese despliegue siguen calculando el mismo nombre.
+ *
+ * Los tres nombres: `legacy` (el recortado a 64 de ≤ alpha.4, retirado en alpha.7, se conserva para el caso que lo
+ * fija), `unscoped` (el sha1 sin base de 2.4.0-alpha.5..2.5.0-alpha.4) y `current` (el sha1 con base). Sin `database`
+ * —quien no ha abierto conexión: los casos de identidad pura— `current` es `unscoped`.
+ */
+export function scopeOutboxLockNames(connection, table, database) {
     const full = `authz_scope_outbox:${connection ?? 'default'}:${table}`;
+    const sha = (value) => `authz_scope_outbox:${createHash('sha1').update(value).digest('hex')}`;
+    const unscoped = sha(full);
     return {
         legacy: full.slice(0, MYSQL_LOCK_NAME_MAX),
-        current: `authz_scope_outbox:${createHash('sha1').update(full).digest('hex')}`,
+        unscoped,
+        current: database === undefined ? unscoped : sha(`${full}@db:${String(database ?? '').toLowerCase()}`),
     };
 }
+/**
+ * **La transición del nombre sin base** (rotación 2 · R2-01, firmada: «como alpha.5»). En 2.5.x `acquire()` toma el
+ * nombre VIEJO (`unscoped`, el de 2.4.0-alpha.5..2.5.0-alpha.4) y DESPUÉS el nuevo (`current`, con la base), y suelta
+ * los dos: en un despliegue rodante un proceso de alpha.4 solo conoce el viejo, y los dos tienen que seguir
+ * excluyéndose. **El precio, declarado**: mientras se tome el viejo, dos despliegues en bases distintas del mismo
+ * servidor SIGUEN compartiéndolo — R2-01 queda abierto en 2.5.x y se cierra al retirarlo en 2.6 (README «Limits»,
+ * `relay.mysql-unscoped-lease`; backlog 2.6). Atado a la versión como en alpha.6: `tests/rotacion2_cierre.spec.ts` exige
+ * que valga exactamente «`package.json` < `SCOPE_OUTBOX_UNSCOPED_LOCK_RETIRED_IN`» (`2.6.0-alpha.0`: toda 2.6, sus
+ * prereleases incluidas), así que el bump a 2.6 pone la suite en rojo hasta retirarlo.
+ */
+export const SCOPE_OUTBOX_UNSCOPED_LOCK_RETIRED_IN = '2.6.0-alpha.0';
+export const SCOPE_OUTBOX_TAKES_UNSCOPED_LOCK = true;
 /** Hash de 32 bits con signo (lo que acepta `pg_try_advisory_xact_lock`). */
 function hash32(value) {
     let hash = 0;
@@ -374,7 +410,6 @@ export function sqlScopeOutbox(options = {}, database = db) {
          * pasada, que es el precio de que dos pasadas no se pisen.
          */
         async acquire() {
-            const names = scopeOutboxLockNames(connection, table);
             /** El nombre del cerrojo de PROCESO y del advisory de PG: el completo (allí no hay recorte). */
             const name = `authz_scope_outbox:${connection ?? 'default'}:${table}`;
             const client = lockClientOf(database, connection);
@@ -397,11 +432,17 @@ export function sqlScopeOutbox(options = {}, database = db) {
                     return { release: async () => void (await trx.rollback()) };
                 }
                 if (dialect.startsWith('mysql')) {
-                    // **Los DOS locks** (alpha.5 · R6, transición): el nuevo —hash
-                    // estable, sin colisión— y el viejo —el recortado a 64 de alpha.4—,
-                    // para que un rolling deploy con las dos versiones siga siendo
-                    // escritor único. Si cualquiera de los dos falla, se sueltan los que
-                    // se tomaron y es `busy`. El viejo se retira en 2.5.
+                    // **La base en el nombre** (rotación 2 · R2-01): la lee la MISMA sesión que va a sostener el cerrojo.
+                    const database = firstValue(await query('acquire', () => trx.rawQuery('select database() as db')), 'db');
+                    const names = scopeOutboxLockNames(connection, table, database === null || database === undefined ? null : String(database));
+                    // **Transición** (2.5.x): el VIEJO (sin base) primero y el NUEVO después; si cualquiera falla se sueltan los
+                    // ya tomados y es `busy`. Un proceso de alpha.4 solo toma el viejo: los dos siguen excluyéndose.
+                    // (El recortado de ≤ alpha.4 sigue retirado: `SCOPE_OUTBOX_TAKES_LEGACY_LOCK` es `false` desde alpha.7.)
+                    const order = [
+                        ...(SCOPE_OUTBOX_TAKES_UNSCOPED_LOCK ? [names.unscoped] : []),
+                        names.current,
+                        ...(SCOPE_OUTBOX_TAKES_LEGACY_LOCK ? [names.legacy] : []),
+                    ];
                     const taken = [];
                     const take = async (lockName) => {
                         const result = await query('acquire', () => trx.rawQuery('select get_lock(?, 0) as taken', [lockName]));
@@ -410,18 +451,38 @@ export function sqlScopeOutbox(options = {}, database = db) {
                             taken.push(lockName);
                         return ok;
                     };
+                    // `GET_LOCK` es de SESIÓN, no de la transacción: revertir no lo suelta, y una conexión que vuelve al pool
+                    // con el cerrojo puesto deja la cola `busy` para siempre. Se sueltan TODOS los tomados (en orden inverso)
+                    // aunque uno falle, y la transacción se revierte al final pase lo que pase.
+                    let released = false;
                     const releaseAll = async () => {
-                        try {
-                            for (const lockName of taken.reverse())
+                        if (released)
+                            return;
+                        released = true;
+                        let failure;
+                        for (const lockName of [...taken].reverse()) {
+                            try {
                                 await trx.rawQuery('select release_lock(?)', [lockName]);
+                            }
+                            catch (error) {
+                                failure ??= error;
+                            }
                         }
-                        finally {
-                            await trx.rollback();
-                        }
+                        await trx.rollback();
+                        if (failure !== undefined)
+                            throw failure;
                     };
-                    if (!(await take(names.current)) || (SCOPE_OUTBOX_TAKES_LEGACY_LOCK && !(await take(names.legacy)))) {
-                        await releaseAll();
-                        return null;
+                    try {
+                        for (const lockName of order) {
+                            if (!(await take(lockName))) {
+                                await releaseAll();
+                                return null;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        await releaseAll().catch(() => { });
+                        throw error;
                     }
                     return { release: releaseAll };
                 }

package/build/src/shared/sql_expiry.d.ts

@@ -26,7 +26,7 @@ export interface ExpiryCodec {
     bind(at: Date): unknown;
     /** Expresión de SELECT que devuelve la columna de forma que `fromDb` la lea sin depender del cliente. */
     select(column: string, alias?: string): unknown;
-    /** Lo que devuelve el SELECT de `select(...)` → `Date | null`. */
+    /** Lo que devuelve el SELECT de `select(...)` → `Date | null` (`null` = columna NULL); presente e ilegible LANZA (RR-2). */
     fromDb(value: unknown): Date | null;
 }
 /** ¿Es MySQL? (el mismo conjunto que decide el codec). */
@@ -44,8 +44,12 @@ export declare function dialectOf(connection: any): string;
 export declare function isSqliteDialect(connection: any): boolean;
 /** `2030-06-15T12:00:00.000Z` → `2030-06-15 12:00:00.000` (UTC, con milisegundos). */
 export declare function formatUtcDatetime(at: Date): string;
-/** `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`, o `null` si no es una fecha. */
-export declare function parseUtcDatetime(value: string): Date | null;
+/**
+ * `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`. Lo que no es una fecha REAL lanza
+ * `unreadableExpiry` (RR-2): la fecha cero, un mes 13, un 31 de febrero o un `24:00:00` (que `Date` desbordaría en
+ * silencio al día o al mes siguiente) no se leen como nada.
+ */
+export declare function parseUtcDatetime(value: string): Date;
 /**
  * El codec para una conexión de Lucid (default: la primaria). Se decide por
  * dialecto una vez por driver; MySQL es el único que necesita algo distinto

package/build/src/shared/sql_expiry.js

@@ -26,20 +26,54 @@ export function isSqliteDialect(connection) {
 export function formatUtcDatetime(at) {
     return at.toISOString().slice(0, 23).replace('T', ' ');
 }
-/** `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`, o `null` si no es una fecha. */
+/**
+ * Una caducidad PRESENTE que no se puede leer (rotación 3 · cierre 2, RR-2 del re-ataque): es un error, nunca «sin
+ * caducidad». Hasta aquí `parseUtcDatetime` y el codec identidad devolvían `null` para una fecha que no lo es —la fecha
+ * cero `0000-00-00` que MySQL deja con un `sql_mode` no estricto, un `-infinity` de PostgreSQL, un texto en SQLite—, y
+ * `null` es PERMANENTE para quien lo consume: el re-grant la conservaba como «sin caducidad», `reconcile --to=openfga`
+ * y el export de `relations:reconcile` escribían una tupla permanente para una fila que en SQL ya no concede. Ahora es
+ * 500 `E_AUTHZ_INTERNAL` en la lectura: lo que lee la caducidad para reescribirla o migrarla se para antes de escribir
+ * (`reconcile --to=database` incluido, que antes la reescribía con la del origen: E1, declarado en «Limits»). La DECISIÓN
+ * de SQL (`expires_at > now`) NO pasa por aquí y no es fail-closed para todo valor (re-ataque 2 · C1, corregido): no
+ * concede con la fecha cero de MySQL ni con `-infinity`, pero SÍ concede —para siempre— con `+infinity` en PostgreSQL y
+ * con un TEXTO en SQLite (`TEXT > INTEGER` es verdadero), aunque sea una fecha pasada. El paquete nunca escribe esos
+ * valores; está declarado en «Limits» con su receta (revoke + grant) y el arreglo de fondo va a 2.6. `null`/`undefined` siguen siendo «sin
+ * caducidad»: es lo que guarda una columna NULL.
+ */
+function unreadableExpiry(value) {
+    const shown = value instanceof Date ? 'Invalid Date' : JSON.stringify(typeof value === 'string' ? value.slice(0, 40) : String(value));
+    return new AuthorizationInternalError(`expires_at ilegible (${shown}): una caducidad presente que no es un instante es un error, nunca «sin caducidad». ` +
+        'Corrige la fila (o bórrala) antes de releerla, migrarla o reescribirla.');
+}
+/**
+ * `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`. Lo que no es una fecha REAL lanza
+ * `unreadableExpiry` (RR-2): la fecha cero, un mes 13, un 31 de febrero o un `24:00:00` (que `Date` desbordaría en
+ * silencio al día o al mes siguiente) no se leen como nada.
+ */
 export function parseUtcDatetime(value) {
-    const match = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(?:\.(\d{1,6}))?$/.exec(value.trim());
+    const match = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?$/.exec(value.trim());
     if (!match)
-        return null;
-    const millis = (match[3] ?? '').padEnd(3, '0').slice(0, 3);
-    const date = new Date(`${match[1]}T${match[2]}.${millis}Z`);
-    return Number.isNaN(date.getTime()) ? null : date;
+        throw unreadableExpiry(value);
+    const [, year, month, day, hour, minute, second, fraction] = match;
+    const wall = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+    const date = new Date(`${wall}.${(fraction ?? '').padEnd(3, '0').slice(0, 3)}Z`);
+    // Ida y vuelta: `Date` acepta `2030-02-31` (⇒ 3 de marzo) y `24:00:00` (⇒ día siguiente); una fecha real vuelve igual.
+    if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 19) !== wall)
+        throw unreadableExpiry(value);
+    return date;
 }
 const identityCodec = {
     toDb: (expiresAt) => expiresAt,
     bind: (at) => at,
     select: (column, alias) => (alias && alias !== column ? `${column} as ${alias}` : column),
-    fromDb: toExpiryDate,
+    // RR-2: `toExpiryDate` da `null` para lo que no es fecha (y deja pasar un `Date` inválido); aquí eso es un error.
+    fromDb: (value) => {
+        const date = toExpiryDate(value);
+        if (date === null ? !(value === null || value === undefined || value === '') : Number.isNaN(date.getTime())) {
+            throw unreadableExpiry(value);
+        }
+        return date;
+    },
 };
 function mysqlCodec(connection) {
     const raw = (sql, bindings) => typeof connection?.raw === 'function' ? connection.raw(sql, bindings) : db.raw(sql, bindings);

package/build/src/testing/contract.d.ts

@@ -37,6 +37,10 @@ import type { ContractScopeTree } from './scope_tree.js';
  * `truncationSignal: false` (con `exhaustiveLists`) y `hierarchyFacts: false`;
  * los demás llegan con su fase, y mientras tanto declararlos `true` hace que
  * la suite lance al registrarse: una promesa sin juez no pasa.
+ *
+ * Las claves OPCIONALES (`?:`, regla D15) se pueden omitir: entonces la cara
+ * la elige la declaración normalizada del DRIVER (`isOmittedOptionalCapability`);
+ * declararlas fija la cara y el juez exige que el driver diga lo mismo.
  */
 export interface DriverCapabilities {
     /** El driver materializa el árbol como hechos propios (Fase 3b). */
@@ -132,8 +136,10 @@ export interface DriverCapabilities {
      * y MySQL, y es la promesa que el README hace.
      *
      * Con `false` (SQLite, que serializa bloqueando la BASE ENTERA) el juez
-     * solo puede exigir lo innegociable: nunca dos ganadores y el perdedor no
-     * escribe — su transacción puede morir con `SQLITE_BUSY`, que es un 503
+     * solo puede exigir lo innegociable: nunca dos ganadores con el MISMO owner
+     * (el del ancestro puede ensombrecer al del descendiente: los dos finales
+     * legales de 3G · Y1, también en esta cara desde la rotación 2) y el
+     * perdedor no escribe — su transacción puede morir con `SQLITE_BUSY`, que es un 503
      * legítimo. Declararlo `true` en un motor así convierte un flake en un
      * fallo; declararlo `false` en PG/MySQL deja pasar un mutante que
      * convierte la colisión en 503. Solo tiene casos en `level: '2.2'`.
@@ -202,12 +208,39 @@ export interface DriverCapabilities {
     enumerateFacts: boolean;
     /**
      * **El driver es EXPERIMENTAL** (estrategia 2.5.0, firma 4; `AuthorizationDriverCapabilities.experimental`). Opcional
-     * (regla D15: un harness publicado de 2.4/2.5 sin la clave sigue valiendo y cuenta como `false`). Con `true` el juez fija
-     * que el driver lo declara y que `authorization.capabilities()` lo publica; con `false` (o ausente), que el driver NO lo
+     * (regla D15): si el harness la OMITE, el juez juzga la cara que el DRIVER declara (su declaración normalizada; ensayo
+     * rc.1 de COGNITIV) y un harness publicado sin la clave sigue valiendo; si la declara, manda el harness. Con `true` el
+     * juez fija que el driver lo declara y que `authorization.capabilities()` lo publica; con `false`, que el driver NO lo
      * declara y la copia normalizada dice `false`. No apaga ningún caso. `openfga` = `true` en 2.5.x; `database` = `false`.
      */
     experimental?: boolean;
+    /**
+     * **Toda decisión que combina concesión y deny se lee en UNA foto** (rotación 2 · cierre 3, L12;
+     * `AuthorizationDriverCapabilities.snapshotDecisions`). Opcional (regla D15): si el harness la OMITE, el juez juzga la
+     * cara que el DRIVER declara —el `database` del paquete declara `true`, así que un harness de alpha.4 que lo registra
+     * sin la clave se juzga en la cara `true` (ensayo rc.1 de COGNITIV)—; si la declara, manda el harness y contradecir al
+     * driver es rojo. Solo tiene casos en `level: '2.1'` o superior (necesita `listDenies`). Con `true`
+     * el juez fija que el driver trae `readSnapshot`, que cada lectura pedida es EXACTAMENTE la del método homónimo (y lo
+     * no pedido no viene), que una pregunta mal formada es 422, y que el manager compone `effectivePermissions`,
+     * `authorizedScopes` y la policy de `defineScopedRole` con UNA llamada a `readSnapshot` y ninguna a
+     * `rolesInChain`/`listScopes`/`listDenies` (el espía cuenta solo las llamadas del MANAGER: lo que `readSnapshot` llame
+     * por dentro no cuenta). Con `false`, que el manager NO llama a `readSnapshot` —aunque el driver traiga un método con
+     * ese nombre: decide la capacidad— y compone como antes restando los denies (el hueco declarado de un driver sin la
+     * capacidad); sin `listDenies` la cara se queda en la declaración y su título lo dice. Que la foto sea de verdad UNA no lo puede
+     * observar un juez genérico sin meterse en el backend: en `database` lo fijan los casos de entrelazado forzado y la
+     * guardia `database.decision.snapshot` del paquete.
+     */
+    snapshotDecisions?: boolean;
 }
+/**
+ * **Clave D15 OMITIDA ⇒ la declaración del driver** (ensayo rc.1 de COGNITIV, día 1, hallazgo 1; firma del dueño
+ * 2026-10-23). Una clave opcional que el harness no declara (`undefined`) no es `false`: el juez la toma de la
+ * declaración NORMALIZADA del driver (`normalizeAuthorizationCapabilities`) y juzga ESA cara. Si el harness la declara,
+ * manda el harness (y contradecir al driver sigue siendo rojo). Un harness publicado antes de que la clave existiera no
+ * puede declararla: tratarla como `false` ponía rojo a un harness verde contra un driver que la declara `true` (el propio
+ * `database` con `snapshotDecisions`), que es lo que D15 prohíbe.
+ */
+export declare function isOmittedOptionalCapability(capabilities: DriverCapabilities, capability: keyof DriverCapabilities): boolean;
 export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
     name: string;