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

package/build/src/relations/manager.js

@@ -0,0 +1,156 @@
+/**
+ * `RelationsManager` — la fachada de ReBAC (Fase 4, lote 4-2).
+ *
+ * Es el análogo de `AuthorizationManager` para el puerto `RelationsDriver`:
+ * aplica la POLICY antes de tocar el driver y despacha la auditoría después.
+ * Lo que fija este lote:
+ *
+ *  - **F-05 (cierre del 🔴 del auditor)**: `relate`/`unrelate` con un
+ *    `object.type` o una `relation` que NO estén declarados en
+ *    `defineRelationsConfig` ⇒ 422 ANTES de llamar al driver. Junto con ⚪4
+ *    (un tipo reservado no se puede declarar) hace IMPOSIBLE que un `relate`
+ *    componga el id de un `role_binding` real y escale a `roles.authorize`.
+ *  - **R-13**: `assertWrite` PURO (obligatorio aquí, a diferencia de
+ *    `roles/`): si rechaza, nada toca el driver.
+ *  - `actor` en `onRelationWrite` (auditoría del consumidor sin
+ *    `AsyncLocalStorage`).
+ *  - `membersOf` como método OPCIONAL DISTINTO de `listSubjects`: si el driver
+ *    no lo trae (`membersOfNative: false`) ⇒ 500 `E_AUTHZ_UNSUPPORTED`
+ *    nombrándolo, jamás un `skip`.
+ *
+ * Pureza (regla 2): solo depende del puerto, los errores, la gramática
+ * compartida y `defineRelationsConfig`. Nada de `manager`/`drivers/*`.
+ */
+import { ActorRequiredError, RelationTypeUnknownError, RelationUnknownError, UnsupportedOperationError, } from '../errors.js';
+import { assertScope, assertSubject, assertRelationId } from '../identity.js';
+import { isRelUserset } from '../types.js';
+export class RelationsManager {
+    #driver;
+    #config;
+    #options;
+    constructor(driver, config, options = {}) {
+        this.#driver = driver;
+        this.#config = config;
+        this.#options = options;
+    }
+    /** El driver crudo — salida documentada de las barreras (plataforma y tests). */
+    driver() {
+        return this.#driver;
+    }
+    /**
+     * **F-05**: rechaza un tipo/relación no declarado ANTES de tocar el driver.
+     * La gramática de identidad no basta: `role_binding`/`assignee` son
+     * gramaticalmente válidos y en el store compartido componen el id de un
+     * binding real.
+     */
+    #assertDeclared(object, relation) {
+        if (!object || typeof object !== 'object' || typeof object.type !== 'string') {
+            throw new RelationTypeUnknownError(`Objeto de relación inválido: se esperaba { type, id } y llegó ${JSON.stringify(object)}.`);
+        }
+        if (!this.#config.hasType(object.type)) {
+            throw new RelationTypeUnknownError(`El tipo de objeto '${object.type}' no está declarado en defineRelationsConfig (F-05): ` +
+                `relate/unrelate solo aceptan tipos declarados. En el store compartido un tipo no declarado ` +
+                `podría componer el id de un 'role_binding' real y escalar a roles.authorize.`);
+        }
+        if (!this.#config.isDeclared(object.type, relation)) {
+            throw new RelationUnknownError(`La relación '${relation}' no está declarada para el tipo '${object.type}' en ` +
+                `defineRelationsConfig (F-05).`);
+        }
+    }
+    /**
+     * **R-16**: el `object.id` con la gramática estricta de relaciones ANTES del
+     * driver ⇒ 422 `E_AUTHZ_INVALID_IDENTITY`. `#assertDeclared` solo valida el
+     * TIPO (F-05): un `object.id` con un `|`/`#`/`:`/espacio se colaba y en
+     * `openfga` se ESCRIBÍA (invisibilidad de enumeración y pérdida en
+     * `reconcile`) o salía como 503 mal clasificado. Se valida aquí (una vez) y
+     * en cada driver (defensa en profundidad).
+     */
+    #assertObjectId(object) {
+        assertRelationId(`el id del objeto '${object?.type}'`, object?.id);
+    }
+    #assertActor(options) {
+        if (this.#options.requireActor && !options?.actor) {
+            throw new ActorRequiredError(`Escritura de relación sin 'actor' y la config exige uno (requireActor).`);
+        }
+    }
+    async relate(subject, relation, object, partition, options) {
+        this.#assertDeclared(object, relation);
+        this.#assertObjectId(object);
+        this.#assertActor(options);
+        assertScope(partition);
+        this.#assertSubject(subject, partition);
+        const ref = { operation: 'relate', subject, relation, object, partition };
+        this.#options.assertWrite?.(ref);
+        await this.#driver.relate(subject, relation, object, partition, options);
+        this.#options.onRelationWrite?.({ ...ref, actor: options?.actor });
+    }
+    async unrelate(subject, relation, object, partition, options) {
+        this.#assertDeclared(object, relation);
+        this.#assertObjectId(object);
+        this.#assertActor(options);
+        assertScope(partition);
+        this.#assertSubject(subject, partition);
+        const ref = { operation: 'unrelate', subject, relation, object, partition };
+        this.#options.assertWrite?.(ref);
+        await this.#driver.unrelate(subject, relation, object, partition, options);
+        this.#options.onRelationWrite?.({ ...ref, actor: options?.actor });
+    }
+    async check(subject, relation, object, partition) {
+        assertScope(partition);
+        this.#assertObjectId(object);
+        return this.#driver.check(subject, relation, object, partition);
+    }
+    async listObjects(subject, relation, objectType, partition, page) {
+        assertScope(partition);
+        return this.#driver.listObjects(subject, relation, objectType, partition, page);
+    }
+    async listSubjects(relation, object, partition, page) {
+        assertScope(partition);
+        this.#assertObjectId(object);
+        return this.#driver.listSubjects(relation, object, partition, page);
+    }
+    async purgeObject(object, partition) {
+        assertScope(partition);
+        this.#assertObjectId(object);
+        return this.#driver.purgeObject(object, partition);
+    }
+    async purgeSubject(subject, partition) {
+        assertScope(partition);
+        return this.#driver.purgeSubject(subject, partition);
+    }
+    /**
+     * Membresía TRANSITIVA de un grupo (a través de usersets anidados) —
+     * DISTINTA de `listSubjects`, que da los hechos DIRECTOS. Solo la trae el
+     * driver `database` (`membersOfNative: true`); en `openfga` es 500
+     * `E_AUTHZ_UNSUPPORTED` nombrándola (la transitiva sería `ListUsers`, que
+     * trunca), jamás un `skip`.
+     */
+    async membersOf(object, relation, partition, page) {
+        assertScope(partition);
+        if (!this.#driver.membersOf || !this.#driver.capabilities?.membersOfNative) {
+            throw new UnsupportedOperationError('membersOf', 'la membresía transitiva de un grupo', 'relations', `Solo el driver 'database' la resuelve (CTE recursiva); en 'openfga' la transitiva sería ` +
+                `'ListUsers', que trunca. Usa 'listSubjects' para los hechos directos.`);
+        }
+        return this.#driver.membersOf(object, relation, partition, page);
+    }
+    /** ORIGEN de `authz:reconcile` de relaciones. 500 `E_AUTHZ_UNSUPPORTED` si el driver no lo trae. */
+    async enumerateRelations(partition, page) {
+        assertScope(partition);
+        if (!this.#driver.enumerateRelations || !this.#driver.capabilities?.enumerateRelations) {
+            throw new UnsupportedOperationError('enumerateRelations', 'ser origen de authz:reconcile de relaciones', 'relations');
+        }
+        return this.#driver.enumerateRelations(partition, page);
+    }
+    #assertSubject(subject, partition) {
+        if (isRelUserset(subject)) {
+            // El userset (`group:g#member`) también se ancla a la partición; su
+            // objeto se valida como cualquier otro objeto declarado (tipo + id, R-16).
+            this.#assertDeclared(subject.object, subject.relation);
+            this.#assertObjectId(subject.object);
+            assertScope(partition);
+            return;
+        }
+        assertSubject(subject);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/build/src/relations/manager.js.map

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

package/build/src/relations/reconcile.d.ts

@@ -0,0 +1,62 @@
+import type { RelationsDriver, ScopeRef } from '../types.js';
+import type { RelationsConfig } from './define_relations_config.js';
+export interface RelationsReconcileOptions {
+    /** El driver del que se LEEN las tuplas (origen). Necesita `enumerateRelations`. */
+    from: RelationsDriver;
+    /** El driver al que se ESCRIBEN (destino). Necesita `enumerateRelations` para ver lo que sobra. */
+    to: RelationsDriver;
+    /** La partición a migrar (mono-tenant: `APP_SCOPE`). El reconcile es POR partición. */
+    partition: ScopeRef;
+    /** Solo reporta lo que HARÍA; cero escrituras (read-only por contrato, como el de roles). */
+    dryRun?: boolean;
+    /** Borra del destino las tuplas que el origen ya no respalda. Sin él, solo añade. */
+    prune?: boolean;
+    /**
+     * **El seguro de borrado masivo** (R-17): con `prune` y un ORIGEN sin una
+     * sola tupla utilizable, borrar TODO el destino es 500
+     * `E_AUTHZ_MASS_RECONCILE_REFUSED` (la firma de un `--from` equivocado o de un
+     * store vacío). `allowMassDelete: true` (`--allow-mass-delete`) es la decisión
+     * humana de vaciarlo de verdad; `--dry-run` no lanza, lo marca en `massDelete`.
+     * Paridad con el seguro de `authz:reconcile` de roles.
+     */
+    allowMassDelete?: boolean;
+    /**
+     * La config del DESTINO, para vigilar la deriva del modelo fusionado en
+     * `--dry-run`: un tipo de relación presente en el origen que el destino NO
+     * declara no cabría en su modelo fusionado (se reporta en `modelDrift`).
+     */
+    toConfig?: RelationsConfig;
+}
+export interface RelationsReconcileReport {
+    /** ¿Fue `--dry-run` (sin escrituras)? */
+    dryRun: boolean;
+    /** Tuplas nuevas escritas en el destino (o que se escribirían, en `--dry-run`). */
+    written: number;
+    /** Tuplas que sobraban en el destino y se borraron (solo con `prune`; o que se borrarían). */
+    deleted: number;
+    /** Tuplas que ya estaban exactamente igual. */
+    unchanged: number;
+    /**
+     * Tuplas del destino que el origen ya no respalda y que NO se borraron por
+     * no pasar `--prune` (deriva recuperable; con `prune` pasan a `deleted`).
+     */
+    extra: number;
+    /**
+     * Deriva del modelo fusionado del destino (`--dry-run`): tipos de relación
+     * del origen que la config del destino no declara. Vacío si no aplica.
+     */
+    modelDrift: string[];
+    /**
+     * **El seguro de borrado masivo se disparó** (R-17): `prune` iba a borrar
+     * tuplas y el ORIGEN no aportó ni una utilizable. En una pasada real es 500
+     * (salvo `allowMassDelete`); en `--dry-run` NO lanza y esto lo marca.
+     */
+    massDelete: boolean;
+}
+/**
+ * Migra las tuplas de relación de `from` a `to` en `partition`. Idempotente
+ * (una segunda pasada no escribe nada) y bidireccional (funciona en cualquier
+ * sentido). Nunca silenciosa: devuelve `written`/`deleted`/`unchanged`/`extra`.
+ */
+export declare function reconcileRelations(options: RelationsReconcileOptions): Promise<RelationsReconcileReport>;
+//# sourceMappingURL=reconcile.d.ts.map

package/build/src/relations/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/relations/reconcile.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAA6B,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAkBnE,MAAM,WAAW,yBAAyB;IACxC,oFAAoF;IACpF,IAAI,EAAE,eAAe,CAAA;IACrB,mGAAmG;IACnG,EAAE,EAAE,eAAe,CAAA;IACnB,uFAAuF;IACvF,SAAS,EAAE,QAAQ,CAAA;IACnB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;IACf,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAA;IACf,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAA;CACpB;AA8BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAyE9G"}

package/build/src/relations/reconcile.js

@@ -0,0 +1,138 @@
+/**
+ * **`authz:reconcile` de relaciones** (Fase 4, lote 4-5) — migra las tuplas de
+ * relación de un `RelationsDriver` a otro, idempotente y bidireccional, nunca
+ * silenciosa. Es el análogo de `manager.reconcile` de roles, pero para el
+ * puerto `RelationsDriver`: solo hay HECHOS de relación (no árbol ni catálogo),
+ * así que es más simple —lee el ORIGEN por `enumerateRelations`, lee el DESTINO
+ * ENTERO (la única forma de ver lo que SOBRA), y aplica writes y —con
+ * `prune`— deletes—.
+ *
+ * **La lección M1/M3/T4 de la 3b** (el agujero del 3b-4·C1): un contrato que
+ * solo cruza `report.skipped` se pasa PERDIENDO datos. El verificador de
+ * verdad es el CENSO (`src/testing/relations_reconcile_contract.ts`): busca
+ * cada hecho sembrado en el destino UNO A UNO por el camino DIRECTO
+ * (`listSubjects`), no le pregunta al origen lleno. Un tramo omisivo o una
+ * pérdida de `subject_relation` (un userset migrado como holder) o de
+ * partición se ve ROJA ahí, no en los contadores.
+ *
+ * Pureza (regla 2): este módulo vive en `src/relations/` y solo depende del
+ * puerto (`../types.js`), los errores y la config de relaciones. NO importa
+ * `manager` ni `drivers/*`: los drivers concretos los inyecta el llamante (la
+ * plataforma), como `manager.reconcile` recibe el destino por su clave.
+ */
+import { MassReconcileRefusedError, UnsupportedOperationError } from '../errors.js';
+import { isRelUserset } from '../types.js';
+/** La clave estable de una tupla de relación (partición + objeto + relación + sujeto). */
+function subjectKey(subject) {
+    if (isRelUserset(subject))
+        return `${subject.object.type}:${subject.object.id}#${subject.relation}`;
+    return `${subject.type}:${subject.uuid}`;
+}
+function scopeKeyOf(scope) {
+    return scope.type === 'app' ? 'app' : `${scope.type}|${scope.uuid}`;
+}
+function tupleKey(tuple) {
+    return `${scopeKeyOf(tuple.partition)}|${tuple.object.type}:${tuple.object.id}#${tuple.relation}@${subjectKey(tuple.subject)}`;
+}
+/** Enumera TODAS las tuplas de una partición de un driver (paginando el cursor). */
+async function enumerateAll(driver, partition, role) {
+    if (!driver.enumerateRelations || !driver.capabilities?.enumerateRelations) {
+        throw new UnsupportedOperationError('enumerateRelations', `ser ${role} de authz:reconcile de relaciones`, 'relations', `El driver ${role} no sabe enumerar sus tuplas (capacidad 'enumerateRelations': false). ` +
+            `Sin poder leer ${role === 'destino' ? 'el destino no se ve qué sobra' : 'el origen no hay nada que migrar'}.`);
+    }
+    const out = [];
+    const seen = new Set();
+    let after;
+    let pages = 0;
+    do {
+        const page = await driver.enumerateRelations(partition, after ? { after } : undefined);
+        out.push(...page.tuples);
+        after = page.cursor || undefined;
+        if (after) {
+            if (seen.has(after))
+                throw new Error(`enumerateRelations (${role}): el cursor '${after}' se repite; no avanza`);
+            seen.add(after);
+            if (++pages > 100_000)
+                throw new Error(`enumerateRelations (${role}): más de 100000 páginas sin agotar`);
+        }
+    } while (after);
+    return out;
+}
+/**
+ * Migra las tuplas de relación de `from` a `to` en `partition`. Idempotente
+ * (una segunda pasada no escribe nada) y bidireccional (funciona en cualquier
+ * sentido). Nunca silenciosa: devuelve `written`/`deleted`/`unchanged`/`extra`.
+ */
+export async function reconcileRelations(options) {
+    const { from, to, partition, dryRun = false, prune = false, allowMassDelete = false, toConfig } = options;
+    const sourceTuples = await enumerateAll(from, partition, 'origen');
+    const destTuples = await enumerateAll(to, partition, 'destino');
+    const sourceByKey = new Map();
+    for (const tuple of sourceTuples)
+        sourceByKey.set(tupleKey(tuple), tuple);
+    const destKeys = new Set(destTuples.map((tuple) => tupleKey(tuple)));
+    const toWrite = [];
+    let unchanged = 0;
+    for (const [key, tuple] of sourceByKey) {
+        if (destKeys.has(key))
+            unchanged += 1;
+        else
+            toWrite.push(tuple);
+    }
+    const toDelete = destTuples.filter((tuple) => !sourceByKey.has(tupleKey(tuple)));
+    // Deriva del modelo fusionado del destino (--dry-run): tipos del origen que
+    // el destino no declara. `group` es built-in (el generador lo emite siempre).
+    const modelDrift = [];
+    if (toConfig) {
+        const declared = new Set(['group', ...toConfig.objectTypes.map((t) => t.type)]);
+        const seenDrift = new Set();
+        for (const tuple of sourceTuples) {
+            if (!declared.has(tuple.object.type) && !seenDrift.has(tuple.object.type)) {
+                seenDrift.add(tuple.object.type);
+                modelDrift.push(tuple.object.type);
+            }
+        }
+    }
+    // **El seguro de borrado masivo** (R-17, paridad con `authz:reconcile` de
+    // roles / AA2). `prune` + un ORIGEN sin una sola tupla utilizable + un destino
+    // con tuplas que borrar es la firma de un `--from` equivocado o de un store
+    // vacío: vaciar el destino entero se rechaza con 500 antes de tocar nada,
+    // salvo `allowMassDelete`. En `--dry-run` no lanza, lo marca. «Utilizable» =
+    // una tupla del origen cuyo tipo cabe en el modelo del destino (los tipos que
+    // `modelDrift` recoge no migrarían, así que no cuentan como respaldo).
+    const usableSource = toConfig
+        ? sourceTuples.filter((tuple) => declaredIn(toConfig, tuple.object.type)).length
+        : sourceTuples.length;
+    const massDelete = prune && toDelete.length > 0 && usableSource === 0;
+    if (massDelete && !dryRun && !allowMassDelete) {
+        throw new MassReconcileRefusedError(`authz:relations:reconcile --prune borraría ${toDelete.length} tupla(s) de relación del destino y el ` +
+            `ORIGEN no ha aportado NI UNA utilizable (${sourceTuples.length} leídas` +
+            `${toConfig ? ', todas de tipos que el destino no declara' : ''}). Eso es la firma de un --from ` +
+            `equivocado o de un store vacío, no de un destino que sobra: esta pasada dejaría la partición sin ` +
+            `una sola relación. Comprueba el --from y el store; si de verdad quieres vaciarlo, --allow-mass-delete.`);
+    }
+    if (!dryRun) {
+        for (const tuple of toWrite) {
+            await to.relate(tuple.subject, tuple.relation, tuple.object, tuple.partition);
+        }
+        if (prune) {
+            for (const tuple of toDelete) {
+                await to.unrelate(tuple.subject, tuple.relation, tuple.object, tuple.partition);
+            }
+        }
+    }
+    return {
+        dryRun,
+        written: toWrite.length,
+        deleted: prune ? toDelete.length : 0,
+        unchanged,
+        extra: prune ? 0 : toDelete.length,
+        modelDrift,
+        massDelete,
+    };
+}
+/** ¿El tipo de objeto cabe en el modelo fusionado del destino? (`group` es built-in.) */
+function declaredIn(config, objectType) {
+    return objectType === 'group' || config.objectTypes.some((t) => t.type === objectType);
+}
+//# sourceMappingURL=reconcile.js.map

package/build/src/relations/reconcile.js.map

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

package/build/src/relations_config_store.d.ts

@@ -0,0 +1,22 @@
+import type { RelationsConfig, RelationsConfigSpec } from './relations/define_relations_config.js';
+export interface RelationsConfigStoreOptions {
+    connection?: string;
+    timeoutMs?: number;
+}
+/**
+ * **Guarda (persiste) la config de relaciones** bajo el gate de versión: la
+ * valida (⚪4/F-05 de config), la serializa a JSON y hace UPSERT de la fila
+ * `id=1` dentro de `withAuthzCatalogWrite` —que sube la versión compartida como
+ * última sentencia (invariante 14): un sync en otro proceso la ve en la
+ * siguiente pregunta—. Devuelve la config congelada.
+ */
+export declare function saveRelationsConfig(spec: RelationsConfigSpec, options?: RelationsConfigStoreOptions): Promise<RelationsConfig>;
+/** Lee el spec persistido (o `null` si no hay relaciones declaradas — opt-in). */
+export declare function readRelationsConfigSpec(options?: RelationsConfigStoreOptions): Promise<RelationsConfigSpec | null>;
+/**
+ * Lee la config persistida ya VALIDADA (o `null`). Es lo que hace 🟡3: un
+ * proceso SIN `defineRelationsConfig` en memoria recupera aquí los tipos de
+ * relación de la base, así que el modelo que republique los lleva.
+ */
+export declare function readRelationsConfig(options?: RelationsConfigStoreOptions): Promise<RelationsConfig | null>;
+//# sourceMappingURL=relations_config_store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relations_config_store.d.ts","sourceRoot":"","sources":["../../src/relations_config_store.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAA;AAMlG,MAAM,WAAW,2BAA2B;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,eAAe,CAAC,CAc1B;AAED,kFAAkF;AAClF,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAMrC;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAGjC"}

package/build/src/relations_config_store.js

@@ -0,0 +1,74 @@
+/**
+ * **La config de relaciones PERSISTIDA** (Fase 4, lote 4-5 · 🟡3) — vive en la
+ * tabla `authz_relations_config`, bajo el gate de versión (invariante 14), como
+ * el catálogo. Es la copia de la config de relaciones en la BASE, para que
+ * cualquier proceso —también uno SIN `defineRelationsConfig` en memoria— lea
+ * los tipos declarados. Hoy la CONSUME `authz:relations:reconcile` (la config
+ * del DESTINO, para vigilar la deriva del modelo fusionado en `--dry-run`).
+ *
+ * Este módulo vive en `src/` (NO en `src/relations/`, que la regla 2 de pureza
+ * mantiene aislado del `db`): es la ruta que TOCA la base, como `catalog.ts`.
+ * Importa el TIPO y el validador de `src/relations/` (la dirección permitida:
+ * `relations/` no importa hacia afuera; los demás sí importan de él).
+ *
+ * **Nota (Fase 4-8):** el modelo fusionado del store lo publica
+ * `openfga:provision` leyendo los tipos de relación del CONFIG estático
+ * (`relations.config`, como `permissions` sale de `catalogs`), no de esta
+ * tabla: el comando es `startApp: false` (bootstrap del appliance, sin base) y
+ * no puede leer la base. Por eso el antiguo `republishFusedModel` —el
+ * republicador basado en esta tabla, con CAS sobre `model_id`— se retiró en
+ * 4-8: no tenía llamador de producción (la carrera que protegía no ocurre;
+ * republicar el modelo es un paso manual de operador, escritor único). Ver el
+ * informe 4-8. La columna `model_id` queda sin uso (cleanup futuro).
+ */
+import { systemClock } from './clock.js';
+import { guardSql } from './shared/backend_guard.js';
+import db from '@adonisjs/lucid/services/db';
+import { invalidateAuthzCatalog, withAuthzCatalogWrite } from './catalog/catalog_cache.js';
+import { defineRelationsConfig } from './relations/define_relations_config.js';
+const TABLE = 'authz_relations_config';
+const ROW_ID = 1;
+const DEFAULT_TIMEOUT_MS = 5_000;
+function connectionOf(options) {
+    return options?.connection ? db.connection(options.connection) : db;
+}
+/**
+ * **Guarda (persiste) la config de relaciones** bajo el gate de versión: la
+ * valida (⚪4/F-05 de config), la serializa a JSON y hace UPSERT de la fila
+ * `id=1` dentro de `withAuthzCatalogWrite` —que sube la versión compartida como
+ * última sentencia (invariante 14): un sync en otro proceso la ve en la
+ * siguiente pregunta—. Devuelve la config congelada.
+ */
+export async function saveRelationsConfig(spec, options = {}) {
+    // Valida ANTES de escribir: una config inválida no ensucia la tabla.
+    const config = defineRelationsConfig(spec);
+    const json = JSON.stringify(spec);
+    await withAuthzCatalogWrite(async (trx) => {
+        const existing = await trx.from(TABLE).where('id', ROW_ID).first();
+        if (existing) {
+            await trx.from(TABLE).where('id', ROW_ID).update({ spec: json, updated_at: systemClock() });
+        }
+        else {
+            await trx.table(TABLE).insert({ id: ROW_ID, spec: json, model_id: null, updated_at: systemClock() });
+        }
+    }, options);
+    invalidateAuthzCatalog();
+    return config;
+}
+/** Lee el spec persistido (o `null` si no hay relaciones declaradas — opt-in). */
+export async function readRelationsConfigSpec(options = {}) {
+    const row = await guardSql('relations-config', 'read', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, () => connectionOf(options).from(TABLE).where('id', ROW_ID).first());
+    if (!row?.spec)
+        return null;
+    return JSON.parse(String(row.spec));
+}
+/**
+ * Lee la config persistida ya VALIDADA (o `null`). Es lo que hace 🟡3: un
+ * proceso SIN `defineRelationsConfig` en memoria recupera aquí los tipos de
+ * relación de la base, así que el modelo que republique los lleva.
+ */
+export async function readRelationsConfig(options = {}) {
+    const spec = await readRelationsConfigSpec(options);
+    return spec ? defineRelationsConfig(spec) : null;
+}
+//# sourceMappingURL=relations_config_store.js.map

package/build/src/relations_config_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations_config_store.js","sourceRoot":"","sources":["../../src/relations_config_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,EAAE,MAAM,6BAA6B,CAAA;AAC5C,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAC1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAA;AAG9E,MAAM,KAAK,GAAG,wBAAwB,CAAA;AACtC,MAAM,MAAM,GAAG,CAAC,CAAA;AAChB,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAOhC,SAAS,YAAY,CAAC,OAAqC;IACzD,OAAO,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAyB,EACzB,UAAuC,EAAE;IAEzC,qEAAqE;IACrE,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,qBAAqB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACxC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAA;QAClE,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,CAAC,CAAA;QAC7F,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,CAAC,CAAA;QACtG,CAAC;IACH,CAAC,EAAE,OAAO,CAAC,CAAA;IACX,sBAAsB,EAAE,CAAA;IACxB,OAAO,MAAM,CAAA;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAAuC,EAAE;IAEzC,MAAM,GAAG,GAAQ,MAAM,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB,EAAE,GAAG,EAAE,CACxG,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAC9D,CAAA;IACD,IAAI,CAAC,GAAG,EAAE,IAAI;QAAE,OAAO,IAAI,CAAA;IAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAwB,CAAA;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAuC,EAAE;IAEzC,MAAM,IAAI,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,CAAA;IACnD,OAAO,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAClD,CAAC"}

package/build/src/scope_outbox.d.ts

@@ -0,0 +1,69 @@
+/**
+ * **La outbox del árbol sobre Lucid** (3b-2d; panel 2, cruce 4 · S5).
+ *
+ * El puerto es `ScopeOutbox` (`src/types.ts`) y el paquete NO impone tabla:
+ * cualquier implementación vale. Esta es la que se publica para quien no
+ * quiera escribir la suya, junto con su migración
+ * (`stubs/scopes_outbox_migration.stub`, que hay que COPIAR al proyecto:
+ * `configure` no la publica sola porque la outbox es opt-in).
+ *
+ *   import { sqlScopeOutbox } from '@jantstack/adonis-authz'
+ *
+ *   const outbox = sqlScopeOutbox()
+ *   export default defineConfig({
+ *     scopes: { resolveChain, outbox },
+ *     ...
+ *   })
+ *
+ *   // y en el sitio donde mueves tu árbol:
+ *   await db.transaction(async (trx) => {
+ *     await authorization.scopes.moved(unit, nuevaOrg, { within, actor, transaction: trx })
+ *     await unit.useTransaction(trx).merge({ organizationId: nuevaOrg.uuid }).save()
+ *   })
+ *
+ * Lo único que tiene que cumplir una implementación del puerto es que
+ * `enqueue` escriba DENTRO de la transacción que le pasan: es lo que hace
+ * que el cambio del árbol y su propagación al backend confirmen —o se vayan—
+ * juntos. Todo lo demás (nombres de columna, si las filas aplicadas se
+ * borran o se marcan, si hay reintento con backoff) es del consumidor.
+ *
+ * Aquí las filas aplicadas se MARCAN (`applied_at`), no se borran: la cola
+ * es también el registro de lo que se propagó y cuándo, y `authz:scopes:relay`
+ * no puede ser silencioso.
+ */
+import type { Clock } from './clock.js';
+import type { ScopeOutbox } from './types.js';
+export interface SqlScopeOutboxOptions {
+    /** Tabla de la cola (default `authz_scope_outbox`, la del stub). */
+    table?: string;
+    /** Nombre de la conexión Lucid (default: la primaria). */
+    connection?: string;
+    /** Deadline de cada consulta en ms (default 5000): vencido ⇒ 503. */
+    timeoutMs?: number;
+    /**
+     * Reloj de pared con el que se sellan `created_at` y `applied_at`
+     * (2.5 · J1). Default `() => new Date()`; inyectable para fijar el
+     * instante en tests.
+     */
+    now?: Clock;
+    /**
+     * **Cuántas veces se reintenta una entrada antes de APARCARLA** (3b-2h ·
+     * 🔴 2; default 5). Alcanzado el tope, `pending()` deja de ofrecerla y sale
+     * por `dead()`: hay entradas que no se pueden aplicar NUNCA —el scope padre
+     * del `attached` encolado lo borró el tenant antes del relevo y no va a
+     * volver— y sin tope esa fila se reintenta en todas las pasadas para
+     * siempre. Aparcar no es olvidar: el relay la reporta en cada pasada y el
+     * comando sale ≠ 0 mientras haya alguna, porque el árbol del backend queda
+     * permanentemente divergente en ese nodo (lo reconcilia `authz:reconcile`,
+     * 3b-3, o un `scopes.detached`/`attached` nuevo del consumidor).
+     */
+    maxAttempts?: number;
+}
+/** Lo que se necesita del `db` de Lucid; inyectable para probar sin servidor. */
+interface DatabaseLike {
+    from(table: string): any;
+    table(table: string): any;
+}
+export declare function sqlScopeOutbox(options?: SqlScopeOutboxOptions, database?: DatabaseLike): ScopeOutbox;
+export {};
+//# sourceMappingURL=scope_outbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope_outbox.d.ts","sourceRoot":"","sources":["../../src/scope_outbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAKvC,OAAO,KAAK,EAEV,WAAW,EAKZ,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,GAAG,CAAC,EAAE,KAAK,CAAA;IACX;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAgBD,iFAAiF;AACjF,UAAU,YAAY;IACpB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAA;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAA;CAC1B;AAuFD,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,EACnC,QAAQ,GAAE,YAA4C,GACrD,WAAW,CAsLb"}