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

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

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

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

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

package/build/src/http/resource_access_middleware.js

@@ -0,0 +1,81 @@
+import { Exception } from '@adonisjs/core/exceptions';
+import authorization from '../../services/main.js';
+import { AuthorizationConfigError, RoleIsNotAccessError } from '../errors.js';
+/** Métodos HTTP seguros: usan `readPermission` si se declara. */
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+export default class ResourceAccessMiddleware {
+    async handle(ctx, next, options) {
+        // Config PRIMERO, antes de mirar si hay usuario: una ruta mal declarada
+        // tiene que saltar en el primer request de desarrollo, autenticado o no.
+        if (options && 'role' in options) {
+            throw new RoleIsNotAccessError(options.role);
+        }
+        if (!options?.permission) {
+            throw new AuthorizationConfigError("middleware.resourceAccess requiere `{ permission }` (p. ej. resourceAccess({ permission: 'documents:write', ... }))");
+        }
+        if (!options.param) {
+            throw new AuthorizationConfigError('middleware.resourceAccess requiere `{ param }` — el nombre del param de ruta con el id del recurso');
+        }
+        if (typeof options.load !== 'function') {
+            throw new AuthorizationConfigError('middleware.resourceAccess requiere `load(ctx, id)` — cómo cargar el recurso y en qué `{ scope }` vive');
+        }
+        if (!options.resource) {
+            throw new AuthorizationConfigError('middleware.resourceAccess requiere `{ resource }` — el nombre bajo el que se propaga el recurso al controlador');
+        }
+        // ── 1. 401 ────────────────────────────────────────────────────────────
+        const holder = ctx.auth?.user;
+        if (!holder) {
+            return ctx.response.unauthorized({ message: 'No autenticado', statusCode: 401, errors: [] });
+        }
+        // El holder tiene que ser un subject válido (mismos guards que appAccess).
+        // Son errores de programación (500), no de acceso: nunca degradan a 404.
+        const morph = holder.__morphMapName;
+        if (!morph) {
+            throw new Exception('El modelo autenticado no tiene @MorphMap — no es un holder válido', {
+                status: 500,
+            });
+        }
+        if (!holder.uuid) {
+            throw new Exception(`El holder '${morph}' no expone 'uuid' — el motor identifica a los holders por uuid, ` +
+                `no por la clave primaria del modelo.`, { status: 500 });
+        }
+        const subject = { type: morph, uuid: holder.uuid };
+        // ── 2. 403 gate del consumidor ────────────────────────────────────────
+        // Sin try/catch: si el gate lanza (backend caído), el 503 sube tal cual.
+        if (options.gate && !(await options.gate(ctx))) {
+            return ctx.response.forbidden({ message: 'Permiso insuficiente', statusCode: 403, errors: [] });
+        }
+        // El 404 del contenedor, del recurso ausente y del authorize negativo
+        // comparten EXACTAMENTE el mismo cuerpo: nada distingue los tres.
+        const notFound = () => ctx.response.notFound({ message: 'Recurso no encontrado', statusCode: 404, errors: [] });
+        // ── 3. 404 contenedor (ANTES que el recurso) ──────────────────────────
+        if (options.containerParam) {
+            const containerId = ctx.params?.[options.containerParam];
+            if (!containerId)
+                return notFound();
+        }
+        // ── 4. 404 recurso ────────────────────────────────────────────────────
+        const id = ctx.params?.[options.param];
+        if (!id)
+            return notFound();
+        // Un throw de `load` NO se atrapa: «no pude comprobar» (503) ≠ «no existe».
+        const loaded = await options.load(ctx, String(id));
+        if (!loaded)
+            return notFound();
+        // ── 5. authorize (UNA vez) sobre el scope del recurso ─────────────────
+        const method = String(ctx.request?.method?.() ?? 'GET').toUpperCase();
+        const permission = SAFE_METHODS.has(method) && options.readPermission
+            ? options.readPermission
+            : options.permission;
+        if (!(await authorization.authorize(subject, permission, loaded.scope))) {
+            // Negado ⇒ 404 con el MISMO cuerpo, NO 403: que no puedas verlo no
+            // revela que existe.
+            return notFound();
+        }
+        // El recurso cargado (con su scope) llega al controlador sin recargarlo.
+        ;
+        ctx[options.resource] = loaded;
+        return next();
+    }
+}
+//# sourceMappingURL=resource_access_middleware.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource_access_middleware.js","sourceRoot":"","sources":["../../../src/http/resource_access_middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,aAAa,MAAM,wBAAwB,CAAA;AAElD,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAoG7E,iEAAiE;AACjE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;AAE7C,MAAM,CAAC,OAAO,OAAO,wBAAwB;IAC3C,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,IAAY,EAAE,OAA8B;QACzE,wEAAwE;QACxE,yEAAyE;QACzE,IAAI,OAAO,IAAI,MAAM,IAAK,OAAkB,EAAE,CAAC;YAC7C,MAAM,IAAI,oBAAoB,CAAE,OAAe,CAAC,IAAI,CAAC,CAAA;QACvD,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,wBAAwB,CAChC,qHAAqH,CACtH,CAAA;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,wBAAwB,CAChC,oGAAoG,CACrG,CAAA;QACH,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvC,MAAM,IAAI,wBAAwB,CAChC,uGAAuG,CACxG,CAAA;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,wBAAwB,CAChC,gHAAgH,CACjH,CAAA;QACH,CAAC;QAED,yEAAyE;QACzE,MAAM,MAAM,GAAI,GAAW,CAAC,IAAI,EAAE,IAErB,CAAA;QACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9F,CAAC;QAED,2EAA2E;QAC3E,yEAAyE;QACzE,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAA;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,SAAS,CAAC,mEAAmE,EAAE;gBACvF,MAAM,EAAE,GAAG;aACZ,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,SAAS,CACjB,cAAc,KAAK,mEAAmE;gBACpF,sCAAsC,EACxC,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAA;QACH,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;QAElD,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC/C,OAAO,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QACjG,CAAC;QAED,sEAAsE;QACtE,kEAAkE;QAClE,MAAM,QAAQ,GAAG,GAAG,EAAE,CACpB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QAE1F,yEAAyE;QACzE,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,MAAM,WAAW,GAAI,GAAW,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,CAAA;YACjE,IAAI,CAAC,WAAW;gBAAE,OAAO,QAAQ,EAAE,CAAA;QACrC,CAAC;QAED,yEAAyE;QACzE,MAAM,EAAE,GAAI,GAAW,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC/C,IAAI,CAAC,EAAE;YAAE,OAAO,QAAQ,EAAE,CAAA;QAC1B,4EAA4E;QAC5E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;QAClD,IAAI,CAAC,MAAM;YAAE,OAAO,QAAQ,EAAE,CAAA;QAE9B,yEAAyE;QACzE,MAAM,MAAM,GAAG,MAAM,CAAE,GAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;QAC9E,MAAM,UAAU,GACd,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,cAAc;YAChD,CAAC,CAAC,OAAO,CAAC,cAAc;YACxB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAA;QAExB,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACxE,mEAAmE;YACnE,qBAAqB;YACrB,OAAO,QAAQ,EAAE,CAAA;QACnB,CAAC;QAED,yEAAyE;QACzE,CAAC;QAAC,GAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAA;QACxC,OAAO,IAAI,EAAE,CAAA;IACf,CAAC;CACF"}

package/build/src/identity.d.ts

@@ -0,0 +1,228 @@
+import type { NormalizedRoleQuery, RoleQuery, ScopeRef, SubjectRef } from './types.js';
+/**
+ * Validación de identidad del motor: holder, scope, rol y permiso.
+ *
+ * Vive en un solo sitio y la aplican el manager (una vez por llamada) Y los
+ * drivers (defensa en profundidad: el juez del contrato habla con el driver
+ * directamente, y un driver de terceros puede usarse sin manager). Nadie
+ * duplica la regla: se importa.
+ *
+ * Por qué es 422 y no "se acepta lo que venga":
+ *  - `uuid: undefined` en el driver openfga escribía `user:undefined`, y a
+ *    partir de ahí CUALQUIER holder sin uuid heredaba ese permiso (L0.5).
+ *  - `{ type: 'app', uuid: 'X' }` colapsaba a la raíz global en openfga y no
+ *    en database: escalada de tenant a plataforma en un driver y `false` en
+ *    el otro (L0.10).
+ *  - `#`, `:`, `|`, `~`, `*` y espacios son sintaxis de FGA o separadores de
+ *    los ids de binding: un componente que los contenga puede fabricar un
+ *    userset, un comodín o la clave de OTRO scope (L0.5, L0.8). Desde 3A
+ *    (2.2) el slug ya NO viaja en los ids de FGA (van por uuid de catálogo),
+ *    pero los tipos y uuids de scope sí, y los slugs serán relaciones del
+ *    modelo `facts` (3b): la lista blanca se mantiene entera.
+ *  - Las longitudes son las de las columnas `authz_*`: lo que no cabe se
+ *    truncaría o fallaría con un error de SQL ilegible.
+ */
+/**
+ * Longitudes de columna del esquema publicado (`stubs/migration.stub`) que
+ * la identidad aplica tal cual. El slug NO está aquí: su límite es
+ * `MAX_SLUG_LENGTH` (42), más estricto que la columna (100) para que el
+ * catálogo sea publicable en FGA (E2).
+ */
+export declare const IDENTITY_LIMITS: Readonly<{
+    holderType: 50;
+    scopeType: 20;
+    uuid: 36;
+}>;
+/**
+ * Centinela con el que el driver `database` almacena el uuid del scope `app`
+ * (NOT NULL + unique). Fuera de `app` sería una identidad de scope que
+ * colisiona con la raíz: se rechaza (L0.15).
+ */
+export declare const SENTINEL_UUID = "00000000-0000-0000-0000-000000000000";
+/** El uuid de un rol o permiso del catálogo (opcional en el spec): canónico y en minúsculas, o 422. */
+export declare function assertCatalogUuid(kind: string, value: unknown): asserts value is string;
+/** Versión booleana para caminos de LECTURA (ids que vienen del backend): no lanza. */
+export declare function isCatalogUuid(value: unknown): value is string;
+/** `SubjectRef` bien formado: type y uuid presentes, con formato y longitud. */
+export declare function assertSubject(subject: SubjectRef): void;
+/**
+ * `ScopeRef` bien formado. `app` es la raíz y NO admite uuid (L0.10): un
+ * `{ app, 'X' }` no es "otro app", es una identidad que un driver colapsaría
+ * a la global. Fuera de `app` el uuid es obligatorio y no puede ser el
+ * centinela con el que `database` representa la raíz (L0.15).
+ */
+export declare function assertScope(scope: ScopeRef): void;
+/** Tipo de scope suelto (el de `listRoleScopes`). */
+export declare function assertScopeType(scopeType: string): void;
+/**
+ * Longitud máxima del id de un objeto/holder de RELACIÓN (columna
+ * `varchar(64)` de `authz_relations`). Más ancha que `IDENTITY_LIMITS.uuid`
+ * (36): el `object.id` de ReBAC lo elige el consumidor y no tiene por qué ser
+ * un uuid.
+ */
+export declare const RELATION_ID_LIMIT = 64;
+/**
+ * **La gramática del id de un objeto de RELACIÓN** (R-16, Fase 4 · lote 4-7).
+ *
+ * Un `object.id` de relaciones va en la columna `varchar(64)` de
+ * `authz_relations` y, en el store compartido, en el id de objeto de FGA
+ * (`document:<partitionKey>|<object.id>`). El driver `database` ya lo validaba
+ * (`RELATION_ID_FORMAT`), pero ni el manager ni el driver `openfga` lo hacían:
+ * el `openfga` solo medía la LONGITUD. Un `object.id` con un `|` dentro
+ * (`'a|b'`) se ESCRIBÍA y `check` lo honraba, pero al parsear de vuelta (corte
+ * por el ÚLTIMO `|`) la partición salía mal, así que `listObjects` lo filtraba
+ * y `enumerateRelations` lo descartaba: una relación que concede y que NO se ve
+ * en la enumeración ni migra —pérdida SILENCIOSA en `reconcile`, justo lo que
+ * el driver promete que no pasa— y una divergencia con `database`, que lo
+ * rechaza con 422. Y los caracteres estructurales (`:`/`#`/espacio) salían como
+ * 503 mal clasificado, cuando por invariante 5 una entrada malformada es 422.
+ *
+ * Misma lista blanca que el resto de la identidad (`COMPONENT_FORMAT`):
+ * minúsculas, dígitos y `._-`; excluye `|`, `#`, `:`, `@`, `*`, `~`, espacios y
+ * control. La aplican el manager (una vez por llamada) Y cada driver (defensa
+ * en profundidad), como el resto de la gramática.
+ */
+export declare function assertRelationId(kind: string, value: unknown): asserts value is string;
+/** Versión booleana para caminos de LECTURA (ids que vienen del backend): no lanza. */
+export declare function isValidRelationId(value: unknown): value is string;
+/**
+ * Clave textual de un scope: `app` para la raíz, `<tipo>|<uuid>` para el
+ * resto (≤ 57 caracteres). Es la MISMA en todo el paquete: el id de los
+ * bindings de FGA (`role_binding:<scopeKey>|<roleUuid>`) y el owner de un
+ * rol local (`authz_roles.owner_scope_key`, 3B · B1). `|` es el separador:
+ * como ningún componente lo admite (`assertScope`), dos scopes distintos no
+ * pueden producir la misma clave, y la clave reservada `global` (el catálogo
+ * del config) no la produce ningún scope — la raíz da `app` y todo lo demás
+ * lleva `|`. Un scope mal formado (`{app, uuid}`, centinela, mayúsculas) es
+ * 422 aquí, antes de serializarse a nada.
+ */
+export declare function scopeKey(scope: ScopeRef): string;
+/**
+ * **Las ORTOGRAFÍAS de un scope con las que hay que limpiar cuando ya no hay
+ * cadena con la que canonizar** (3b-2h · 🟠 3, auditor R2).
+ *
+ * La identidad de un scope es la canónica que devuelve el resolutor
+ * (invariante 17) y el paquete la usa para TODOS los hechos… mientras la fila
+ * del consumidor existe. `scopes.detached` es justo la operación que admite
+ * que ya NO exista (3F · S1: se purga igual, con el scope tal cual), y ahí no
+ * hay con qué canonizar: se usa la ortografía del llamante. Medido contra
+ * PostgreSQL: el tipo `uuid` funde `01a0…-…` con el mismo uuid SIN guiones,
+ * así que el `DELETE` del controlador acierta con el alias, el `detached`
+ * llega con el alias, `purgeScope` demuestra cero sobre un objeto que no
+ * existe y el scope REAL conserva su `parent` y su `binding`: en modo
+ * `facts`, **concede para siempre**. En lectura el mismo alias es
+ * fail-closed; en escritura era fail-OPEN.
+ *
+ * La salida es no elegir: una purga sin cadena limpia la ortografía del
+ * llamante **y** la canónica de la que puede ser alias. Solo se expande el
+ * alias SIN guiones (32 hex ⇒ también la forma 8-4-4-4-12), que es la única
+ * que un motor produce fundiendo —PostgreSQL canoniza CON guiones; el alias
+ * por mayúsculas ya muere en la puerta (`assertScope`)—; así el consumidor
+ * que guarda sus uuids con guiones (el caso normal) no paga NADA, y el que
+ * los guarda sin guiones sigue purgando su clave y, además, una que nunca
+ * tiene hechos. Normalizar en vez de expandir no vale: sin la fila no se sabe
+ * cuál de las dos es la buena, y elegir mal deja los hechos vivos, que es el
+ * fallo que se está cerrando.
+ */
+export declare function scopeSpellings(scope: ScopeRef): ScopeRef[];
+/**
+ * La inversa de `scopeKey` para claves que vienen de la BASE (el owner de un
+ * rol): `app` ⇒ la raíz; `<tipo>|<uuid>` ⇒ el scope; cualquier otra forma
+ * (incluida `global`, que no es un scope) ⇒ `null`. No lanza: es camino de
+ * lectura, y una clave que no es un scope simplemente no resuelve.
+ */
+export declare function scopeFromKey(key: string): ScopeRef | null;
+/**
+ * Nombres que el modelo FGA del modo `facts` usa como relaciones propias
+ * (`scope#parent`, `role_binding#assignee`, `scope#denied_<P>`…). Un
+ * permiso llamado `parent` invalidaría el modelo entero (S14): se rechaza en
+ * el núcleo, para ambos drivers, no el día de la migración.
+ */
+export declare const RESERVED_SLUGS: ReadonlySet<string>;
+/**
+ * Familias de relaciones derivadas del modelo (`can_<P>`, `denied_<P>`,
+ * `permits_<P>`). Un slug que EMPIECE por una de ellas colisiona con la
+ * relación derivada de otro permiso y el generador la colapsaría en silencio
+ * (S4: `can_docs_write` anulaba el deny de `docs:write`).
+ */
+export declare const RESERVED_SLUG_PREFIXES: readonly string[];
+/**
+ * **Los TIPOS de objeto que el modelo `facts` (y el `group` de relaciones) YA
+ * declaran** (Fase 4 · ⚪4). Un tipo de objeto de relaciones que se llame como
+ * uno de estos DUPLICARÍA un tipo del store compartido: `role_binding` sobre
+ * todo —si el driver de relaciones pudiera declararlo, podría componer el id
+ * de un binding real y `relate` sería una escalada a `roles.authorize`—. Vive
+ * en `identity.ts` (la gramática compartida) porque lo consumen DOS módulos
+ * que la frontera de pureza mantiene disjuntos: el generador del modelo
+ * (`src/drivers/openfga_facts.ts`, que no puede depender de `relations/`) y
+ * `defineRelationsConfig` (`src/relations/`, que no puede depender de
+ * `drivers/`). `deny_binding` sigue reservado aunque el modelo (c2r) ya no lo
+ * emita: un catálogo migrado del modo `resolver` no puede resucitarlo.
+ */
+export declare const RESERVED_FACTS_TYPES: ReadonlySet<string>;
+/**
+ * Longitud máxima de un slug. Un nombre de relación en FGA admite 50
+ * caracteres y el modelo deriva `permits_<slug>` (el prefijo más largo, 8):
+ * 42 es lo que cabe con cualquier prefijo. Es más estricto que la columna
+ * (100) a propósito: un catálogo legal en `database` tiene que ser publicable
+ * en `openfga` (S13), o el cambio de driver no es una migración de hechos.
+ */
+export declare const MAX_SLUG_LENGTH: number;
+export type SlugKind = 'rol' | 'permiso';
+/** Slug de rol o permiso válido para AMBOS drivers (formato, longitud, reservados). */
+export declare function assertValidSlug(kind: SlugKind, slug: unknown): asserts slug is string;
+/**
+ * Cómo se proyecta un slug a un nombre de relación FGA (`:` → `_`). Dos slugs
+ * distintos con la misma proyección (`docs:write` / `docs_write`) serían UNA
+ * relación: el catálogo los rechaza juntos (L0.8a).
+ */
+export declare function slugAsRelation(slug: string): string;
+/** Ningún par de slugs del conjunto colisiona tras proyectarse a relación. */
+export declare function assertNoSlugCollisions(kind: SlugKind, slugs: Iterable<string>): void;
+/** Versiones booleanas para caminos de LECTURA que no deben lanzar (ids que vienen del backend). */
+export declare function isValidScope(scope: ScopeRef): boolean;
+export declare function isValidScopeType(scopeType: unknown): scopeType is string;
+export declare function isValidSlug(kind: SlugKind, slug: string): boolean;
+/**
+ * La pregunta de `hasRole`, validada: string ⇒ `{ slug }`; objeto ⇒
+ * `{ slug, scopeType }` (ambos con la gramática del motor).
+ */
+export declare function normalizeRoleQuery(role: RoleQuery): NormalizedRoleQuery;
+/**
+ * Las claves de la cadena desde cada nivel hacia la raíz (3B · B2; movida
+ * aquí en 3D · N5 para que exista UNA sola codificación de clave de scope):
+ * `keysFrom[i]` = `chain.slice(i).map(scopeKey)`. Un rol es visible en el
+ * nivel `i` si es global o su owner está en `keysFrom[i]` — el owner tiene
+ * que ser ancestro-o-igual del scope de la ASIGNACIÓN, no de la pregunta.
+ */
+export declare function chainKeysFrom(chain: ScopeRef[]): string[][];
+/**
+ * `expiresAt` de un `grant`, en sus tres estados legales: omitido, `null` o
+ * una `Date` válida. Una cadena, un número o un `Invalid Date` no son una
+ * caducidad: un driver lanzaba un TypeError al serializar y el otro persistía
+ * basura (D7). Se rechaza como identidad mal formada (422).
+ */
+export declare function assertExpiresAt(value: unknown): asserts value is Date | null | undefined;
+export interface IdentityParts {
+    subject?: SubjectRef;
+    scope?: ScopeRef;
+    scopeType?: string;
+    /** Pregunta de `hasRole`: string u objeto `{ slug, scopeType }`. */
+    role?: RoleQuery;
+    /**
+     * Slug de rol donde el contrato pide un string (`grant`, `revoke`,
+     * `listSubjects`): un `RoleQuery` objeto aquí es 422, no un 503 ni un
+     * TypeError (D11).
+     */
+    roleSlug?: unknown;
+    permission?: string;
+    /** Caducidad de un `grant`: `undefined` | `null` | `Date` válida. */
+    expiresAt?: unknown;
+}
+/**
+ * Valida en un solo paso los componentes que recibe una operación. Se llama
+ * ANTES de tocar catálogo, árbol o backend: una pregunta mal formada no
+ * cuesta una consulta ni deja rastro.
+ */
+export declare function assertIdentity(parts: IdentityParts): void;
+//# sourceMappingURL=identity.d.ts.map

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

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