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

package/build/src/drivers/openfga_relations_driver.js

@@ -0,0 +1,724 @@
+/**
+ * Driver `openfga` del puerto `RelationsDriver` — ReBAC sobre el MISMO store y
+ * `modelId` que el driver `facts` de roles (Fase 4, lote 4-4).
+ *
+ * Store COMPARTIDO (decisión del dueño / juez §2): las relaciones ReBAC viven
+ * en el modelo FUSIONADO (`facts` + `group` + los tipos de objeto del
+ * consumidor), así que `relate`/`unrelate` son `Write`/delete de tuplas del
+ * mismo store, `check` es UN solo `Check` (el modelo resuelve includes +
+ * usersets del lado del servidor) y `list*` van por `ListObjects`/`Read`.
+ *
+ * **La partición va en el ID del objeto y del userset**, no en el modelo:
+ * `document:<scopeKey(partition)>|<uuid>`, `group:<scopeKey(partition)>|<uuid>#member`.
+ * El cruce de particiones se corta por comparación de string —aquí NO hay
+ * trigger como en `database`, así que F-05 (en el manager) + la comparación de
+ * string son la ÚNICA defensa de tenant—. El id lleva DOS `|` cuando la
+ * partición es un scope no-raíz (`document:unit|<partUuid>|<objUuid>`), así que
+ * el parseo es CANÓNICO desde la DERECHA (⚪5, el mismo cuidado que
+ * `parseBindingId`): partición = todo menos el ÚLTIMO segmento; el id del
+ * objeto es el último y no contiene `|`.
+ *
+ * **La frontera del 🔴 (F-05) NO vive aquí**: la cierra el `RelationsManager`
+ * ANTES de tocar el driver (un `object.type` no declarado ⇒ 422) junto con ⚪4
+ * (un tipo reservado no se puede declarar). Si a este driver se le llama en
+ * DIRECTO con `object.type: 'role_binding'` (la salida `manager.driver()`, de
+ * plataforma), compondría el id de un binding real y escalaría — por eso el
+ * caso-exploit del auditor se cierra en el manager, y el runner publica el
+ * caso para que un driver de terceros que no lo cumpla NO pase el contrato.
+ *
+ * Pureza: vive detrás del subpath `@jantstack/adonis-authz/openfga`
+ * (`src/openfga.ts`), como el driver `facts` de roles: es lo único que puede
+ * tocar `@openfga/sdk` (peer opcional). La abstracción no filtra: ningún error
+ * del SDK escapa (todo va por `#guard`, que clasifica a 503/timeout).
+ */
+import { OpenFgaClient, ConsistencyPreference, ClientWriteRequestOnMissingDeletes, ClientWriteRequestOnDuplicateWrites, } from '@openfga/sdk';
+import { AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationConfigError, InvalidIdentityError, PurgeIncompleteError, UnsupportedOperationError, markPartialWrite, } from '../errors.js';
+import { assertScope, assertSubject, assertRelationId, assertExpiresAt, scopeKey, scopeSpellings } from '../identity.js';
+import { isClock, systemClock } from '../clock.js';
+import { resolveGrantExpiry, sameInstant, toExpiryDate } from '../expiry.js';
+import { isRelUserset } from '../types.js';
+import { assertFgaObjectId, FACTS_EXPIRY_CONDITION, FACTS_GROUP_TYPE, } from './openfga_facts.js';
+import { assertRelationDeclared, assertObjectTypeDeclared } from '../relations/define_relations_config.js';
+import { isTimeoutLike, withDeadline } from '../shared/backend_guard.js';
+export const DEFAULT_TIMEOUT_MS = 5_000;
+/** Tope de operaciones por `Write` en FGA (`exceeded_entity_limit` a partir de 100). */
+const WRITE_BATCH_SIZE = 100;
+/** Tamaño de página de `Read` (máximo del servidor). */
+const READ_PAGE_SIZE = 100;
+/**
+ * Cota de páginas de una enumeración por `Read`. Un `continuation_token` que
+ * no avanza (servidor roto, proxy, caché) sería un bucle que ningún deadline
+ * corta (el deadline es por llamada). Mismo patrón que el driver de roles.
+ */
+const MAX_READ_PAGES = 10_000;
+/**
+ * El tope de `ListObjects` del servidor por defecto (`OPENFGA_LIST_OBJECTS_MAX_RESULTS`).
+ * `ListObjects` NO devuelve señal de truncado ni `continuation_token`: corta al
+ * tope y calla. La única forma honesta de detectar el corte es comparar el
+ * número de resultados con el tope CONFIGURADO del servidor —de ahí la opción
+ * `listObjectsMaxResults`—: si vuelven `>= tope`, no se puede prometer que la
+ * lista esté completa ⇒ `truncated: true` (lección S16/L0.7: nunca una lista
+ * parcial MUDA). Ponerlo por debajo del tope real del servidor daría un
+ * truncado FALSO (el servidor devolvió todo); por encima, se perdería el corte.
+ */
+const DEFAULT_LIST_OBJECTS_MAX = 1_000;
+/**
+ * Ignora duplicados en el `Write` de una tupla que NO estaba (idempotencia de
+ * dos `relate` concurrentes idénticos). Cambiar la caducidad de una que SÍ
+ * está es delete+write (R-15): FGA no admite reescribir la condición de una
+ * tupla existente y un `Ignore` la dejaría con la caducidad vieja en silencio.
+ */
+const IGNORE_DUPLICATE_WRITES = {
+    conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
+};
+/** Ignora deletes de tuplas ya ausentes (re-unrelate no-op seguro, invariante 6). */
+const IGNORE_MISSING_DELETES = {
+    conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
+};
+export class OpenFgaRelationsDriver {
+    /**
+     * Lo que declara (cada valor tiene su cara en `runRelationsDriverContract`):
+     *  - `singleCheckRelations: true`: `check` es UN solo `Check` (el modelo
+     *    resuelve includes + usersets del lado del servidor).
+     *  - `listObjectsInherited: false`: `list*` no abren el subárbol de
+     *    particiones (invariante 7); `ListObjects` sí resuelve la derivación del
+     *    modelo (includes/usersets), que es «directos + derivados», no herencia
+     *    de scopes.
+     *  - `usersetSubjects: true`: `listSubjects` (`Read`) trae los usersets
+     *    directos (`group#member`) junto con los holders.
+     *  - `membersOfNative: false`: la membresía TRANSITIVA sería `ListUsers`, que
+     *    trunca al tope del servidor; se declara 500 `E_AUTHZ_UNSUPPORTED`, jamás
+     *    un userset enumerado a medias (par de `purgeRole` de la 3b).
+     *  - `enumerateRelations: true` (4-5): es ORIGEN de `authz:reconcile` de
+     *    relaciones — lee el store ENTERO (`Read({})`, la única forma de ver todo
+     *    sin filtro por user u objeto: un `Read` por tipo-solo sin user es un 400)
+     *    y devuelve SOLO las tuplas de relación de la partición (tipo declarado o
+     *    `group`), descartando las de `facts` (scope/role/role_binding).
+     *  - `listObjectsTruncation: true`: `ListObjects` trunca al tope del servidor
+     *    y este driver lo SEÑALA (medido contra el `:8103` de tope 3).
+     *  - `injectableClock: true` (R-15): `withClock(now)` fija el reloj que viaja
+     *    como `current_time` y filtra `listSubjects`, como el driver de roles.
+     */
+    capabilities = Object.freeze({
+        singleCheckRelations: true,
+        listObjectsInherited: false,
+        usersetSubjects: true,
+        membersOfNative: false,
+        enumerateRelations: true,
+        listObjectsTruncation: true,
+        injectableClock: true,
+        // L-2/L-5 (panel `{trx}`, (C)): `false` EXPLÍCITO, y no puede ser otra
+        // cosa — una tupla no entra en una transacción SQL: el store es otro
+        // servicio y no hay 2PC, así que «los dos o ninguno» con la transacción
+        // del consumidor es una promesa que este driver no puede hacer, y no la
+        // hace. `{ transaction }` es 500 `E_AUTHZ_UNSUPPORTED` por llamada, en el
+        // `RelationsManager` (puerta 1) Y en el driver (`#rejectTransaction`,
+        // para quien entre por `manager.driver()` o por `reconcileRelations`),
+        // con CERO llamadas al store (L-5 lo fija contra el `:8101` con espía
+        // sobre el cliente). La alternativa que SÍ existe es para el ÁRBOL de
+        // scopes: `scopes.outbox` encola en tu transacción y `authz:scopes:relay`
+        // aplica. Para las RELACIONES no hay outbox (el panel la descartó:
+        // fail-open medido durante el lag); el consumidor lee esta capacidad y
+        // ajusta (usa `database` para lo que tenga que ir en su transacción, o
+        // `requireTransactionalWrites` para fallar al arrancar).
+        transactionalWrites: false,
+    });
+    client;
+    #config;
+    #options;
+    #now;
+    #holderTypes;
+    #fgaToMorph;
+    #timeoutMs;
+    #consistency;
+    #listObjectsMax;
+    #logger;
+    diagnostics = { unparseableTuples: 0 };
+    constructor(config, options) {
+        this.#config = config;
+        this.#options = options;
+        this.#now = options.now ?? systemClock;
+        this.#holderTypes = options.holderTypes;
+        this.#fgaToMorph = Object.fromEntries(Object.entries(options.holderTypes).map(([morph, fga]) => [fga, morph]));
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#consistency =
+            options.consistency === 'minimize_latency'
+                ? ConsistencyPreference.MinimizeLatency
+                : ConsistencyPreference.HigherConsistency;
+        this.#listObjectsMax = options.listObjectsMaxResults ?? DEFAULT_LIST_OBJECTS_MAX;
+        this.#logger = options.logger ?? console;
+        this.client = new OpenFgaClient({
+            apiUrl: options.apiUrl,
+            storeId: options.storeId,
+            authorizationModelId: options.modelId,
+            baseOptions: { timeout: this.#timeoutMs },
+            retryParams: { maxRetry: 0 },
+        });
+    }
+    /**
+     * Vista de este driver con OTRO reloj de pared (R-15, paridad con
+     * `AuthorizationDriver.withClock`): MISMO cliente (store, modelo, deadline),
+     * solo cambia el `now` que decide la caducidad. Se construye una instancia
+     * nueva y se le presta el cliente (el espía de «1 Check» envuelve
+     * `client.check` de la instancia base y tiene que seguir viéndolo).
+     */
+    withClock(now) {
+        if (!isClock(now)) {
+            throw new AuthorizationConfigError(`withClock: now debe ser una función () => Date (llegó ${typeof now})`);
+        }
+        const view = new OpenFgaRelationsDriver(this.#config, { ...this.#options, now });
+        view.client = this.client;
+        return view;
+    }
+    /** El `context` de todo `Check`/`ListObjects`: la condición `not_expired` se evalúa contra este instante (un `now` por operación). */
+    #checkContext(at) {
+        return { current_time: at.toISOString() };
+    }
+    /* ── Clasificación de fallos (la abstracción no filtra) ─────────────────── */
+    /**
+     * **El MISMO criterio que el driver de roles** (`guardBackendErrors`,
+     * `openfga_driver.ts`; cierre-2 de alpha.3, ⚪ 5 del re-ataque): un
+     * deadline TOTAL PROPIO por llamada (`withDeadline`, `timeoutMs`) que es lo
+     * que dice «venció el deadline» —503 `E_AUTHZ_BACKEND_TIMEOUT`, indeterminado—,
+     * y para lo que el cliente lanza por su cuenta el `isTimeoutLike` ESTRICTO
+     * de `backend_guard.ts` (`ECONNABORTED`/`ETIMEDOUT`/`.timeout` numérico/
+     * `KnexTimeoutError`, por la cadena de `cause`). Hasta el cierre-2 este
+     * driver duplicaba la función con una rama por SUBSTRING del mensaje
+     * (`/timeout/i`): un error que decía «no es timeout» salía como timeout con
+     * `indeterminate: true` sin haber borrado nada, y el docblock afirmaba en
+     * falso «mismo criterio que roles».
+     */
+    async #guard(operation, fn) {
+        const fail = (error) => {
+            // Un error del paquete (422/500 ya clasificado) se propaga tal cual.
+            if (error instanceof InvalidIdentityError || error instanceof PurgeIncompleteError)
+                return error;
+            if (isTimeoutLike(error)) {
+                return new AuthorizationBackendTimeoutError('openfga-relations', operation, this.#timeoutMs, error);
+            }
+            return new AuthorizationBackendError('openfga-relations', operation, error);
+        };
+        let pending;
+        try {
+            pending = fn();
+        }
+        catch (error) {
+            throw fail(error);
+        }
+        return withDeadline(pending.catch((error) => {
+            throw fail(error);
+        }), this.#timeoutMs, () => new AuthorizationBackendTimeoutError('openfga-relations', operation, this.#timeoutMs));
+    }
+    /* ── Composición y parseo de ids (⚪5: partición por string en el id) ────── */
+    /** `<type>:<scopeKey(partition)>|<objectUuid>`. */
+    #objectId(objectType, partitionKey, objectUuid) {
+        // R-16 (defensa en profundidad, paridad con `database`): el `object.id` con
+        // la gramática estricta ANTES de componer. Un `|`/`#`/`:`/espacio dentro se
+        // escribía (solo se medía la longitud) y luego se perdía en el parseo por
+        // el último `|` —invisible en enumeración y `reconcile`—. `manager.driver()`
+        // salta el manager, así que el driver aplica la MISMA regla que él.
+        assertRelationId(`el id del objeto '${objectType}'`, objectUuid);
+        const id = `${objectType}:${partitionKey}|${objectUuid}`;
+        assertFgaObjectId(objectType, id);
+        return id;
+    }
+    /**
+     * El `user` FGA de un sujeto: holder ⇒ `<fgaType>:<uuid>`; userset ⇒
+     * `<type>:<scopeKey(partition)>|<objUuid>#<relation>`. El userset comparte la
+     * partición de la tupla (el manager lo exige).
+     */
+    #subjectUser(subject, partitionKey) {
+        if (isRelUserset(subject)) {
+            // alpha.3 · F-05 también en el USERSET del sujeto (la misma función que
+            // el manager): `role_binding:<key>|<R>#role` como `user` de un `Read`/
+            // `Check`/`Write` no se compone nunca.
+            assertRelationDeclared(this.#config, subject.object, subject.relation);
+            const object = this.#objectId(subject.object.type, partitionKey, subject.object.id);
+            return `${object}#${subject.relation}`;
+        }
+        const fgaType = this.#holderTypes[subject.type];
+        if (!fgaType) {
+            throw new InvalidIdentityError(`Holder type '${subject.type}' no está en holderTypes del driver openfga de relaciones ` +
+                `(declarados: ${Object.keys(this.#holderTypes).join(', ') || 'ninguno'}).`);
+        }
+        return `${fgaType}:${subject.uuid}`;
+    }
+    /**
+     * **Parseo CANÓNICO del id de un objeto de relación** (⚪5): a partir de
+     * `<type>:<scopeKey>|<objUuid>`, separa `type` (antes del primer `:`),
+     * `partitionKey` (todo menos el ÚLTIMO segmento tras el `:`) y `objectUuid`
+     * (el último segmento, que no contiene `|`). Es el MISMO parseo-desde-la-
+     * derecha que `parseBindingId`: `lastIndexOf('|')` corta el objeto de la
+     * clave de partición (que tiene 1 parte `app` o 2 `<tipo>|<uuid>`). `null` si
+     * el id no tiene la forma que este driver escribe.
+     */
+    #parseObjectId(fullId) {
+        const colon = fullId.indexOf(':');
+        if (colon <= 0)
+            return null;
+        const type = fullId.slice(0, colon);
+        const rest = fullId.slice(colon + 1);
+        const cut = rest.lastIndexOf('|');
+        if (cut < 0)
+            return null;
+        const partitionKey = rest.slice(0, cut);
+        const objectUuid = rest.slice(cut + 1);
+        if (!partitionKey || !objectUuid)
+            return null;
+        return { type, partitionKey, objectUuid };
+    }
+    /** Un `user` del store de vuelta a `RelSubject`: userset (`…#rel`) o holder (`<fga>:<uuid>`). */
+    #userToSubject(user) {
+        const hash = user.indexOf('#');
+        if (hash >= 0) {
+            const parsed = this.#parseObjectId(user.slice(0, hash));
+            const relation = user.slice(hash + 1);
+            if (!parsed || !relation)
+                return null;
+            return { object: { type: parsed.type, id: parsed.objectUuid }, relation };
+        }
+        const colon = user.indexOf(':');
+        if (colon <= 0)
+            return null;
+        const morph = this.#fgaToMorph[user.slice(0, colon)];
+        const uuid = user.slice(colon + 1);
+        if (!morph || !uuid || uuid === '*' || uuid.includes('|'))
+            return null;
+        return { type: morph, uuid };
+    }
+    /* ── Escrituras ─────────────────────────────────────────────────────────── */
+    /**
+     * `relate` con los tres estados de `expiresAt` (R-15, invariante 10). Se LEE
+     * primero la tupla exacta (un `Read` por clave, como `grant` de roles):
+     *  - ausente ⇒ un `Write` (con la condición `not_expired` si caduca);
+     *  - presente con la caducidad que toca ⇒ no-op (idempotente, invariante 6);
+     *  - presente con OTRA ⇒ delete + write en DOS llamadas (FGA no admite
+     *    delete+write de la misma clave en un `Write`, ni reescribir su
+     *    condición): entre ambas hay un instante en el que `check` responde
+     *    `false` —fail-closed, la misma ventana que el `grant` de roles—.
+     */
+    /**
+     * **`{ transaction }` se rechaza también AQUÍ** (L-5, defensa en
+     * profundidad como F-05 en L-0): la puerta 1 vive en el `RelationsManager`,
+     * pero `manager.driver()` y `reconcileRelations` entran por el driver; sin
+     * esta guarda un `{ transaction }` por ahí escribiría la tupla en el store
+     * IGNORANDO la transacción — una escritura que finge ir en tu transacción y
+     * que tu rollback no deshace, que es exactamente el fail-open que
+     * `transactionalWrites: false` declara no poder evitar. Primera línea de
+     * las cuatro escrituras, antes de F-05, del `Read` y del `Write`: CERO
+     * llamadas al cliente.
+     */
+    #rejectTransaction(operation, options) {
+        if (options?.transaction === undefined || options.transaction === null)
+            return;
+        throw UnsupportedOperationError.transactionalDriver(`relations.${operation}`, 'openfga', 'relations');
+    }
+    async relate(subject, relation, object, partition, options) {
+        this.#rejectTransaction('relate', options);
+        // L-0 · F-05 en el DRIVER (defensa en profundidad, la MISMA función que el
+        // manager): `manager.driver()` y `reconcileRelations` entran por aquí, y en
+        // el store COMPARTIDO un tipo no declarado (`role_binding`) compondría el
+        // id exacto de un binding de roles. Corta ANTES del `Read` y del `Write`.
+        assertRelationDeclared(this.#config, object, relation);
+        assertScope(partition);
+        assertExpiresAt(options?.expiresAt);
+        const partitionKey = scopeKey(partition);
+        const objectId = this.#objectId(object.type, partitionKey, object.id);
+        const user = this.#subjectUser(subject, partitionKey);
+        const key = { user, relation, object: objectId };
+        const now = this.#now();
+        const current = await this.#readTuple('relate', key);
+        const previous = current ? current.validUntil : null;
+        const expiresAt = resolveGrantExpiry(previous, options?.expiresAt, now);
+        if (current && sameInstant(previous, expiresAt))
+            return;
+        const tuple = expiresAt
+            ? { ...key, condition: { name: FACTS_EXPIRY_CONDITION, context: { valid_until: expiresAt.toISOString() } } }
+            : key;
+        if (current) {
+            await this.#guard('relate', () => this.client.write({ deletes: [key] }, IGNORE_MISSING_DELETES));
+        }
+        await this.#guard('relate', () => this.client.write({ writes: [tuple] }, IGNORE_DUPLICATE_WRITES));
+    }
+    /** La tupla EXACTA de una clave (un `Read` por clave completa), con su caducidad si la lleva. */
+    async #readTuple(operation, key) {
+        const response = await this.#guard(operation, () => this.client.read(key, { consistency: this.#consistency }));
+        const found = (response.tuples ?? []).map((t) => t.key).find((k) => k?.user === key.user && k?.relation === key.relation && k?.object === key.object);
+        if (!found)
+            return null;
+        return { ...key, validUntil: toExpiryDate(found.condition?.context?.valid_until) };
+    }
+    async unrelate(subject, relation, object, partition, options) {
+        this.#rejectTransaction('unrelate', options);
+        // L-0 · F-05 también al RETIRAR: un `unrelate(alice, assignee, role_binding)`
+        // sería un revoke de roles por la puerta de relaciones.
+        assertRelationDeclared(this.#config, object, relation);
+        assertScope(partition);
+        const partitionKey = scopeKey(partition);
+        const objectId = this.#objectId(object.type, partitionKey, object.id);
+        const user = this.#subjectUser(subject, partitionKey);
+        await this.#guard('unrelate', () => 
+        // Re-unrelate no-op seguro: borrar una tupla ausente se ignora.
+        this.client.write({ deletes: [{ user, relation, object: objectId }] }, IGNORE_MISSING_DELETES));
+    }
+    /* ── Lecturas ───────────────────────────────────────────────────────────── */
+    /**
+     * **F-05 en las LECTURAS y las PURGAS del driver** (2.4.0-alpha.3, cierre
+     * del 🔴 1 / 🟠 2 del auditor; la MISMA función y la misma posición que
+     * L-0 en `relate`/`unrelate` y que L-5 con `{ transaction }`): PRIMERA
+     * línea (tras `#rejectTransaction` en las purgas), CERO llamadas al
+     * cliente. Reproducido contra el `:8101` en el store compartido:
+     * `purgeObject({ type: 'role_binding', id: R }, S)` componía
+     * `role_binding:<scopeKey>|<R>` —byte a byte el binding real— y
+     * `#purgeByFilter` lo borraba con demostración de cero (`authorize` de
+     * `true` a `false`); `listSubjects('assignee', role_binding)` enumeraba sus
+     * asignados. `check`/`listSubjects` validan el par; `listObjects`/
+     * `purgeObject` el tipo; `purgeSubject` el userset.
+     */
+    /** `check` = UN solo `Check` (el modelo resuelve includes + usersets). */
+    async check(subject, relation, object, partition) {
+        assertRelationDeclared(this.#config, object, relation);
+        assertScope(partition);
+        const partitionKey = scopeKey(partition);
+        const objectId = this.#objectId(object.type, partitionKey, object.id);
+        const user = this.#subjectUser(subject, partitionKey);
+        const context = this.#checkContext(this.#now());
+        const response = await this.#guard('check', () => this.client.check({ user, relation, object: objectId, context }, { consistency: this.#consistency }));
+        return response.allowed === true;
+    }
+    /**
+     * `listObjects` = `ListObjects` (resuelve includes + usersets del lado del
+     * servidor) + FILTRO por partición + señal de TRUNCADO. `ListObjects` corta
+     * al tope del servidor sin `continuation_token` ni bandera, así que el
+     * truncado se detecta comparando el número de resultados CRUDOS con el tope
+     * configurado (`listObjectsMaxResults`): `>= tope` ⇒ no se puede prometer la
+     * lista completa ⇒ `truncated: true`. El filtro por partición se aplica
+     * DESPUÉS (los ids llevan la partición), así que en un store con varias
+     * particiones el tope se consume entre todas — otra razón para señalar el
+     * truncado y no callar (documentado en el README).
+     */
+    async listObjects(subject, relation, objectType, partition, _page) {
+        assertRelationDeclared(this.#config, { type: objectType }, relation);
+        assertScope(partition);
+        const partitionKey = scopeKey(partition);
+        const user = this.#subjectUser(subject, partitionKey);
+        const context = this.#checkContext(this.#now());
+        const response = await this.#guard('listObjects', () => this.client.listObjects({ user, relation, type: objectType, context }, { consistency: this.#consistency }));
+        const raw = response.objects ?? [];
+        const truncated = raw.length >= this.#listObjectsMax;
+        const objects = [];
+        for (const full of raw) {
+            const parsed = this.#parseObjectId(full);
+            if (!parsed || parsed.type !== objectType) {
+                this.#warnUnparseable('listObjects', full);
+                continue;
+            }
+            if (parsed.partitionKey !== partitionKey)
+                continue; // otra partición: no cruza
+            objects.push({ type: objectType, id: parsed.objectUuid });
+        }
+        objects.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return truncated ? { objects, truncated: true } : { objects };
+    }
+    /**
+     * `listSubjects` = `Read` por `(object, relation)` — hechos DIRECTOS del
+     * relation EXACTO (invariante 7): ni transitivo (eso es `membersOf`) ni
+     * derivado por includes. `usersetSubjects: true` ⇒ los usersets
+     * (`group#member`) salen junto con los holders.
+     */
+    async listSubjects(relation, object, partition, _page) {
+        assertRelationDeclared(this.#config, object, relation);
+        assertScope(partition);
+        const partitionKey = scopeKey(partition);
+        const objectId = this.#objectId(object.type, partitionKey, object.id);
+        // `Read` devuelve tuplas ESCRITAS, no evaluadas: la caducidad se filtra en
+        // cliente con el MISMO reloj del driver (R-15, estricta: la que vence en
+        // `now` ya no cuenta), como las enumeraciones del driver de roles.
+        const now = this.#now();
+        const tuples = await this.#readAll('listSubjects', { object: objectId, relation });
+        const subjects = [];
+        for (const t of tuples) {
+            if (t.validUntil && t.validUntil.getTime() <= now.getTime())
+                continue;
+            const subject = this.#userToSubject(t.user);
+            if (subject)
+                subjects.push(subject);
+            else
+                this.#warnUnparseable('listSubjects', t.user);
+        }
+        return { subjects };
+    }
+    /**
+     * **`membersOf` ⇒ 500 `E_AUTHZ_UNSUPPORTED`** (cara `whenFalse`): la
+     * membresía TRANSITIVA de un grupo sería `ListUsers`, que trunca al tope del
+     * servidor sin señal fiable. No hay userset transitivo enumerable aquí; se
+     * dice con 500 nombrándolo, jamás un userset a medias. Es el análogo del par
+     * `purgeRole` de la 3b. (El método existe en el prototipo para que el manager
+     * lo despache, pero la capacidad `membersOfNative: false` lo corta antes.)
+     */
+    async membersOf() {
+        throw new UnsupportedOperationError('membersOf', 'la membresía transitiva de un grupo', 'openfga', `En 'openfga' la transitiva sería 'ListUsers', que trunca al tope del servidor sin señal fiable. ` +
+            `Usa el driver 'database' (CTE recursiva) o 'listSubjects' para los hechos directos.`);
+    }
+    /* ── ORIGEN de reconcile (4-5): las tuplas de relación de la partición ──── */
+    /**
+     * **`enumerateRelations` — el ORIGEN de `authz:reconcile` de relaciones**
+     * (4-5). Lee el store ENTERO (`Read({})`) —la única forma de ver todo sin un
+     * filtro por `user` u `object`, que un `Read` por tipo-solo sin user
+     * rechazaría con 400— y devuelve SOLO las tuplas de relación de la partición
+     * pedida: tipo `group` o un tipo declarado en la config, DESCARTANDO las de
+     * `facts` (`scope`/`role`/`role_binding`, que no llevan la partición en el id
+     * con la forma `<key>|<uuid>` de relaciones —o cuyo tipo no está declarado—).
+     *
+     * `truncated`/paginación: `enumerateRelations` agota el `Read` (exhaustivo,
+     * como `listSubjects`/`purge*`), así que devuelve TODO en una página sin
+     * cursor —el reconcile itera hasta que no hay cursor—. Es el ORIGEN de una
+     * migración: una tupla que no llegara aquí desaparecería sin rastro — por eso
+     * la CADUCADA también llega, con su `expiresAt` (R-15), para que el destino
+     * la cuente en `skipped`.
+     *
+     * **Coste: O(tuplas del store) por PASADA** (2.4.0-alpha.6): es un barrido
+     * entero por llamada, sea cual sea el tamaño de la partición (medido: 5 000
+     * tuplas ⇒ 50 páginas ≈ 170 ms; 15 000 ⇒ 151 páginas ≈ 0,5 s). Para K
+     * particiones usa `enumerateRelationsMany`: UN barrido en vez de K.
+     */
+    async enumerateRelations(partition, _page) {
+        assertScope(partition);
+        return this.#sweep([partition], 'enumerateRelations');
+    }
+    /**
+     * **`enumerateRelationsMany` — K particiones en UN barrido** (2.4.0-alpha.6;
+     * panel relay, analista §3: con 3 particiones 1,4 s → 0,46 s). MISMA
+     * semántica que `enumerateRelations` por cada partición pedida —exhaustiva,
+     * sin filtrar la caducada, todo en una página sin cursor— y cada tupla
+     * viene con SU `partition` (la referencia que pasó el llamante, casada por
+     * `scopeKey` ENTERA), de modo que el llamante reparte por `partition`.
+     * Reparte un solo `Read({})` paginado del store entero.
+     *
+     * **Lo que este método NO hace, a propósito: un `Read` por PREFIJO de id.**
+     * OpenFGA no tiene prefix-match: `Read({ object: 'document:unit|<uuid>|' })`
+     * responde **200 con cero tuplas** (medido por el panel, auditor 🔴 3) — en
+     * el ORIGEN de una migración eso es «esta partición está vacía» en silencio,
+     * y en una purga, «demostrado cero» sin haber borrado nada. El único filtro
+     * legal es `{}`; la partición se decide comparando la CLAVE entera del id
+     * parseado desde la derecha (`#parseObjectId`), así que `app` no arrastra a
+     * `appliance|…`, `org|U` no arrastra a `organization|U` y cada ortografía del
+     * uuid es su propia partición. La suite espía el FILTRO de cada `read`.
+     *
+     * **Exhaustivo o ruidoso**: una página con cero tuplas y token de
+     * continuación NO es el fin; un token que se repite, más de
+     * `MAX_READ_PAGES` páginas o una respuesta sin `tuples` son 503
+     * `E_AUTHZ_BACKEND_UNAVAILABLE` (`#readAll`); una tupla que no se entiende
+     * se cuenta en `diagnostics.unparseableTuples` y se avisa. Sin particiones
+     * es 500 `E_AUTHZ_CONFIG` con cero lecturas: no hay «éxito vacío».
+     */
+    async enumerateRelationsMany(partitions, _page) {
+        if (!Array.isArray(partitions) || partitions.length === 0) {
+            throw new AuthorizationConfigError('enumerateRelationsMany: sin particiones no hay nada que enumerar (y un barrido del store para nadie no es un éxito vacío). ' +
+                'Pasa al menos una partición.');
+        }
+        for (const partition of partitions)
+            assertScope(partition);
+        return this.#sweep(partitions, 'enumerateRelationsMany');
+    }
+    /** El barrido: UN `Read({})` paginado del store entero, repartido por la clave ENTERA de partición. */
+    async #sweep(partitions, operation) {
+        // La primera referencia de cada clave es la que viaja en `tuple.partition`
+        // (dos ortografías del mismo uuid son dos claves, como en `enumerateRelations`).
+        const wanted = new Map();
+        for (const partition of partitions) {
+            const key = scopeKey(partition);
+            if (!wanted.has(key))
+                wanted.set(key, partition);
+        }
+        const relationTypes = new Set([FACTS_GROUP_TYPE, ...this.#config.objectTypes.map((t) => t.type)]);
+        const all = await this.#readAll(operation, {});
+        const tuples = [];
+        for (const key of all) {
+            const parsed = this.#parseObjectId(key.object);
+            // No es una tupla de relación (facts: scope/role/role_binding, o un tipo
+            // no declarado): no la migra este puerto.
+            if (!parsed || !relationTypes.has(parsed.type))
+                continue;
+            const partition = wanted.get(parsed.partitionKey);
+            if (partition === undefined)
+                continue; // otra partición: no cruza (clave ENTERA, nunca prefijo)
+            const subject = this.#userToSubject(key.user);
+            if (!subject) {
+                this.#warnUnparseable(operation, key.user);
+                continue;
+            }
+            tuples.push({
+                subject,
+                relation: key.relation,
+                object: { type: parsed.type, id: parsed.objectUuid },
+                partition,
+                expiresAt: key.validUntil,
+            });
+        }
+        return { tuples };
+    }
+    /* ── Purga (invariante 11): borra y DEMUESTRA cero, o lanza ─────────────── */
+    /**
+     * Borra TODAS las tuplas del objeto (cualquier relación) y demuestra cero.
+     * Barre las DOS ortografías del uuid de partición (🟡2, paridad con
+     * `database`): un motor que funda `aaa…` con `aaa-…` dejaría la fila del
+     * alias concediendo tras una purga «exitosa». Si tras borrar quedan tuplas
+     * ⇒ 500 `E_AUTHZ_PURGE_INCOMPLETE`.
+     */
+    async purgeObject(object, partition, options) {
+        this.#rejectTransaction('purgeObject', options);
+        // alpha.3 · F-05 (solo el TIPO: una purga no nombra relación), antes de componer el id.
+        // Cierre-2: la función de TIPO, no la estricta con relación opcional.
+        assertObjectTypeDeclared(this.#config, object);
+        assertScope(partition);
+        const objectIds = this.#partitionSpellings(partition).map((key) => this.#objectId(object.type, key, object.id));
+        const progress = { deleted: 0 };
+        try {
+            for (const objectId of objectIds) {
+                await this.#purgeByFilter('purgeObject', { object: objectId }, `objeto ${objectId}`, progress);
+            }
+        }
+        catch (error) {
+            throw this.#partialIfDeleted(error, progress);
+        }
+    }
+    /**
+     * Borra TODAS las tuplas cuyo SUJETO es este subject en la partición, en
+     * cualquier tipo de objeto declarado, y demuestra cero. `Read` exige un
+     * filtro de objeto (un `Read` solo por `user` es un 400 del servidor), así
+     * que se recorre cada tipo declarado (`group` + los del consumidor) con
+     * `Read({ user, object: '<type>:' })`.
+     */
+    async purgeSubject(subject, partition, options) {
+        this.#rejectTransaction('purgeSubject', options);
+        // alpha.3 · F-05 del USERSET (una purga por sujeto no nombra objeto), antes de nada.
+        if (isRelUserset(subject))
+            assertRelationDeclared(this.#config, subject.object, subject.relation);
+        assertScope(partition);
+        if (!isRelUserset(subject))
+            assertSubject(subject);
+        const partitionKeys = this.#partitionSpellings(partition);
+        const types = [FACTS_GROUP_TYPE, ...this.#config.objectTypes.map((t) => t.type)];
+        const progress = { deleted: 0 };
+        try {
+            for (const partitionKey of partitionKeys) {
+                const user = this.#subjectUser(subject, partitionKey);
+                for (const type of types) {
+                    await this.#purgeByFilter('purgeSubject', { user, object: `${type}:` }, `sujeto ${user} en '${type}'`, progress);
+                }
+            }
+        }
+        catch (error) {
+            throw this.#partialIfDeleted(error, progress);
+        }
+    }
+    /**
+     * **Una purga que muere a MEDIAS es indeterminada** (invariante 13,
+     * 2.4.0-alpha.3, cierre del 🟡 6 del auditor). La purga NO es un `Write`:
+     * son N `Read`+`deleteTuples` (ortografías × tipos, y lotes de
+     * `WRITE_BATCH_SIZE`), y un 503 que no es timeout —o el 500
+     * `E_AUTHZ_PURGE_INCOMPLETE` de la demostración de cero— puede llegar
+     * después de haber borrado parte. Si YA se borró al menos una tupla, el
+     * error se marca (`markPartialWrite`, `src/errors.ts`: una propiedad, la
+     * clase y el `code` no cambian) y el `RelationsManager` notifica
+     * `onRelationWrite` con `indeterminate: true` ANTES de propagarlo — «puede
+     * haber ocurrido», como con el deadline. Si no se borró nada, el error va
+     * tal cual: «esa escritura no ocurrió» sigue siendo verdad. En `database`
+     * la purga es UN `DELETE` y no necesita la marca.
+     */
+    #partialIfDeleted(error, progress) {
+        if (progress.deleted > 0 && error !== null && typeof error === 'object')
+            return markPartialWrite(error);
+        return error;
+    }
+    /** Lee por filtro, borra en lotes, y RE-LEE para demostrar cero (o lanza). `progress.deleted` cuenta lo que YA se borró (un lote que falla no borró nada: el `Write` de FGA es transaccional). */
+    async #purgeByFilter(operation, filter, what, progress) {
+        const keys = await this.#readAll(operation, filter);
+        for (let i = 0; i < keys.length; i += WRITE_BATCH_SIZE) {
+            const batch = keys.slice(i, i + WRITE_BATCH_SIZE);
+            await this.#guard(operation, () => this.client.deleteTuples(batch.map((k) => ({ user: k.user, relation: k.relation, object: k.object })), IGNORE_MISSING_DELETES));
+            progress.deleted += batch.length;
+        }
+        if (keys.length === 0)
+            return;
+        // Demostración de cero: re-lee tras borrar (invariante 11).
+        const residue = await this.#readAll(operation, filter);
+        if (residue.length > 0) {
+            throw new PurgeIncompleteError(`${operation}: quedan ${residue.length} tuplas de ${what} tras el borrado ` +
+                `(${residue.slice(0, 3).map((k) => `${k.user}#${k.relation}@${k.object}`).join('; ')}). ` +
+                `No se confirma la purga.`);
+        }
+    }
+    /* ── Helpers ────────────────────────────────────────────────────────────── */
+    /** Las dos ortografías del uuid de partición, como claves de scope (🟡2). */
+    #partitionSpellings(partition) {
+        return [...new Set(scopeSpellings(partition).map((s) => scopeKey(s)))];
+    }
+    /**
+     * TODAS las tuplas que casan con el filtro, paginando `Read` hasta agotar el
+     * `continuation_token`. `Read` no tiene tope de resultados (a diferencia de
+     * `ListObjects`), así que es exhaustivo — por eso las purgas y `listSubjects`
+     * van por aquí, no por `ListObjects`.
+     */
+    async #readAll(operation, filter) {
+        const keys = [];
+        let continuationToken;
+        const seenTokens = new Set();
+        let pages = 0;
+        do {
+            const response = await this.#guard(operation, () => this.client.read(filter, {
+                pageSize: READ_PAGE_SIZE,
+                continuationToken,
+                consistency: this.#consistency,
+            }));
+            pages += 1;
+            // «Exhaustivo o ruidoso» (alpha.6): una respuesta que no trae `tuples`
+            // no se entiende — no es una página vacía. Un 200 sin forma en el ORIGEN
+            // de una migración sería «no hay nada» en silencio.
+            if (!Array.isArray(response?.tuples)) {
+                throw new AuthorizationBackendError('openfga-relations', operation, new Error(`la respuesta del Read (página ${pages}) no trae 'tuples'; no se toma por vacía`));
+            }
+            for (const tuple of response.tuples) {
+                const key = tuple?.key;
+                if (!key?.user || !key?.relation || !key?.object) {
+                    this.#warnUnparseable(operation, JSON.stringify(key ?? null));
+                    continue;
+                }
+                // Con su caducidad (R-15): quien la lee decide si filtra (`listSubjects`),
+                // la emite (`enumerateRelations`) o la ignora (`purge*` borra TODO).
+                keys.push({
+                    user: key.user,
+                    relation: key.relation,
+                    object: key.object,
+                    validUntil: toExpiryDate(key.condition?.context?.valid_until),
+                });
+            }
+            continuationToken = response.continuation_token || undefined;
+            if (continuationToken) {
+                if (seenTokens.has(continuationToken)) {
+                    throw new AuthorizationBackendError('openfga-relations', operation, new Error(`el continuation_token se repite (página ${pages}); el servidor no avanza`));
+                }
+                if (pages >= MAX_READ_PAGES) {
+                    throw new AuthorizationBackendError('openfga-relations', operation, new Error(`más de ${MAX_READ_PAGES} páginas sin agotar el Read`));
+                }
+                seenTokens.add(continuationToken);
+            }
+        } while (continuationToken);
+        return keys;
+    }
+    #warnUnparseable(operation, detail) {
+        this.diagnostics.unparseableTuples += 1;
+        this.#logger.warn(`authz(openfga-relations): tupla no parseable en ${operation} (${detail}); ` +
+            `se ignora en la enumeración (total: ${this.diagnostics.unparseableTuples})`);
+    }
+}
+// Cierre-2 de alpha.3 (⚪ 5 del re-ataque): la clasificación de timeout es la
+// de `src/shared/backend_guard.ts` —`isTimeoutLike`: `KnexTimeoutError`,
+// `.timeout` numérico, `ECONNABORTED`/`ETIMEDOUT`, por la cadena de `cause`—,
+// la MISMA que importa el driver de roles. Hasta el cierre-2 este fichero
+// duplicaba la función con una rama por SUBSTRING del mensaje (`/timeout/i`),
+// de modo que un 400 de validación de FGA o el cuerpo de un 502 que mencionara
+// la palabra salía como 503 `E_AUTHZ_BACKEND_TIMEOUT` con `indeterminate: true`
+// sin haber borrado nada (medido por el auditor: `alpha3-cierre-parcial.ts` B).
+//# sourceMappingURL=openfga_relations_driver.js.map