@fiado/type-kit 3.136.0 → 3.138.0

package/src/platformRbac/enums/Permission.ts

@@ -1,482 +1,482 @@
-/**
- * Catálogo universal de permisos del sistema RBAC Fiado.
- *
- * Origen: componente 01 de Fase 0 SureKeep (spec maestro):
- *   surekeep/docs/5_fases/00_fase0_cognito_rbac_users_mfa/componentes/01_typekit-rbac-additions.md
- *
- * Copy-paste literal de los valores del spec (DEC-003).
- * Convención: `<category>.<resource>.<action>` (snake_case en action si multi-palabra).
- *
- * ⚠️ ESTE ES EL CATÁLOGO GLOBAL Y ÚNICO. Todo permiso del sistema vive acá. Los tenants
- * NO inventan permisos: cada `tenantType` arma su lista (techo) ELIGIENDO de este catálogo
- * (`TenantTypePermissionCatalog_GT` en platform-rbac-business, DEC-062), y cada tenant arma
- * sus roles combinando esos permisos. El vocabulario es global; lo que varía por tenant es
- * QUÉ permisos usa, no CUÁLES existen.
- *
- * ⚠️⚠️ AL AGREGAR / QUITAR / RENOMBRAR UN PERMISO — PROCEDIMIENTO OBLIGATORIO:
- *   1. Agregar el valor a ESTE enum.
- *   2. Agregarlo TAMBIÉN al FINAL de `PERMISSION_BIT_ORDER` (abajo) — append-only, NUNCA en
- *      el medio ni reordenando: ese array define el bit de cada permiso en el token (bitset).
- *      Reordenar/insertar en medio desalinea TODOS los tokens ya emitidos (escalada/pérdida
- *      de permisos silenciosa). Un permiso deprecado CONSERVA su posición (no se borra del array).
- *   3. Recién entonces un `tenantType` puede incluirlo en su lista. Un permiso que NO esté en
- *      este enum + bit-order NO tiene bit → no viaja en el token (el gateway-adapter no lo ve).
- *   4. `PERMS_VERSION` (hash del orden) cambia solo → bump minor del type-kit + redeploy de
- *      consumers (jwt-inyector-trigger, gateway-adapter, platform-rbac-business). Tokens viejos
- *      caen al fallback (resolver DDB) hasta refrescar — by-design, no rompe.
- *   El test `permissionBits.test.ts` falla si el enum y `PERMISSION_BIT_ORDER` se desincronizan.
- *
- * Coexiste con módulo `rbac/` oficial cuando yhonhansen publique componente 01 — TD-RBAC-002.
- */
-export enum Permission {
-    // ====================================================
-    // RBAC — gestión genérica del propio sistema RBAC
-    // ====================================================
-    RBAC_CATALOG_MANAGE = 'rbac.catalog.manage',
-
-    // ====================================================
-    // PLATFORM — operaciones a nivel meta-plataforma (Fiado equipo)
-    // ====================================================
-    PLATFORM_TENANT_CREATE = 'platform.tenant.create',
-    PLATFORM_TENANT_LIST = 'platform.tenant.list',
-    PLATFORM_TENANT_VIEW = 'platform.tenant.view',
-    PLATFORM_TENANT_UPDATE = 'platform.tenant.update',
-    PLATFORM_TENANT_SUSPEND = 'platform.tenant.suspend',
-    PLATFORM_TENANT_ACTIVATE = 'platform.tenant.activate',
-    PLATFORM_TENANT_ADMIN_REPLACE = 'platform.tenant.admin.replace',
-    PLATFORM_COGNITO_POOL_MANAGE = 'platform.cognito.pool.manage',
-    PLATFORM_COGNITO_POOL_LIST = 'platform.cognito.pool.list',
-    PLATFORM_USER_CREATE = 'platform.user.create',
-    PLATFORM_USER_LIST = 'platform.user.list',
-    PLATFORM_USER_VIEW = 'platform.user.view',
-    PLATFORM_USER_UPDATE = 'platform.user.update',
-    PLATFORM_USER_DISABLE = 'platform.user.disable',
-    PLATFORM_USER_ENABLE = 'platform.user.enable',
-    PLATFORM_USER_DELETE = 'platform.user.delete',
-    // Crear/asignar usuarios platform de TU MISMO nivel (platform_admin → platform_admin).
-    // Espejo de tenant.user.create.lateral / retail.user.create.lateral: habilita allowOwnLevel
-    // en ScopeValidationService.canAssign para scope PLATFORM. DEC-052.
-    PLATFORM_USER_CREATE_LATERAL = 'platform.user.create.lateral',
-    PLATFORM_ROLE_CREATE = 'platform.role.create',
-    PLATFORM_ROLE_LIST = 'platform.role.list',
-    PLATFORM_ROLE_UPDATE = 'platform.role.update',
-    PLATFORM_ROLE_DELETE = 'platform.role.delete',
-    PLATFORM_AUDIT_VIEW = 'platform.audit.view',
-    PLATFORM_TENANT_USERFIELDS_MANAGE = 'platform.tenant.userfields.manage',
-    // DEC-RBAC-050: edición del autoregistro self-service del tenant (allowlist anti-escalación
-    // centralizada/platform). Espejo EXACTO de PLATFORM_TENANT_USERFIELDS_MANAGE (scope PLATFORM).
-    PLATFORM_TENANT_AUTOREGISTER_MANAGE = 'platform.tenant.autoregister.manage',
-    // DEC-RBAC-036: gestión de aplicaciones (plantillas) — reemplaza el reuso de rbac.catalog.manage en /applications.
-    PLATFORM_APPLICATION_MANAGE = 'platform.application.manage',
-
-    // ====================================================
-    // TENANT — operaciones dentro del silo de un tenant
-    // ====================================================
-    TENANT_USER_CREATE = 'tenant.user.create',
-    // Crear/gestionar usuarios de TU MISMO nivel jerárquico (ej. tenant_admin → tenant_admin).
-    // Gobierna create + assign-role + update (no solo create). Sin el permiso: solo "para abajo".
-    TENANT_USER_CREATE_LATERAL = 'tenant.user.create.lateral',
-    // Merge de tenant.user.list + tenant.user.view (read unificado del listado y el detalle).
-    TENANT_USER_READ = 'tenant.user.read',
-    // Merge de tenant.user.disable + tenant.user.enable (cambio de estado activo/suspendido).
-    TENANT_USER_STATUS = 'tenant.user.status',
-    // Deprecados (NO borrar — compat): reemplazados por TENANT_USER_READ / TENANT_USER_STATUS.
-    TENANT_USER_LIST = 'tenant.user.list',
-    TENANT_USER_VIEW = 'tenant.user.view',
-    TENANT_USER_UPDATE = 'tenant.user.update',
-    TENANT_USER_DISABLE = 'tenant.user.disable',
-    TENANT_USER_ENABLE = 'tenant.user.enable',
-    TENANT_USER_DELETE = 'tenant.user.delete',
-    TENANT_USER_MFA_RESET = 'tenant.user.mfa.reset',
-    TENANT_USER_PASSWORD_RESET = 'tenant.user.password.reset',
-    TENANT_ROLE_CREATE = 'tenant.role.create',
-    TENANT_ROLE_LIST = 'tenant.role.list',
-    TENANT_ROLE_UPDATE = 'tenant.role.update',
-    TENANT_ROLE_DELETE = 'tenant.role.delete',
-    TENANT_ROLE_VIEW = 'tenant.role.view',
-    TENANT_ROLE_ASSIGN = 'tenant.role.assign',
-    TENANT_ROLE_REVOKE = 'tenant.role.revoke',
-    TENANT_SECURITY_POLICY_VIEW = 'tenant.security.policy.view',
-    TENANT_SECURITY_POLICY_MANAGE = 'tenant.security.policy.manage',
-    TENANT_BRANDING_MANAGE = 'tenant.branding.manage',
-    TENANT_AUDIT_VIEW = 'tenant.audit.view',
-    // DEC-RBAC-038: gestión de scope-entities de nivel genérico — crear/editar/borrar entidades del nivel inferior; scope-bound.
-    TENANT_LEVEL_MANAGE = 'tenant.level.manage',
-
-    // ====================================================
-    // RETAIL — catálogo + inventario + ventas
-    // ====================================================
-    // RETAIL user-management — espejo de tenant.user.* a nivel RETAILER. Los KEYS existen para que el
-    // catálogo + el picker los ofrezcan; sus endpoints/handlers los implementa el agente de retailer
-    // user-management (rbac TD-RBAC-049). create.lateral gobierna create + assign + update (igual que tenant).
-    RETAIL_USER_CREATE = 'retail.user.create',
-    RETAIL_USER_CREATE_LATERAL = 'retail.user.create.lateral',
-    RETAIL_USER_READ = 'retail.user.read',
-    RETAIL_USER_UPDATE = 'retail.user.update',
-    RETAIL_USER_STATUS = 'retail.user.status',
-    RETAIL_USER_DELETE = 'retail.user.delete',
-    RETAIL_USER_PASSWORD_RESET = 'retail.user.password.reset',
-    RETAIL_USER_MFA_RESET = 'retail.user.mfa.reset',
-    RETAIL_PRODUCT_CREATE = 'retail.product.create',
-    RETAIL_PRODUCT_LIST = 'retail.product.list',
-    RETAIL_PRODUCT_VIEW = 'retail.product.view',
-    RETAIL_PRODUCT_UPDATE = 'retail.product.update',
-    RETAIL_PRODUCT_DELETE = 'retail.product.delete',
-    /** @deprecated DEC-RBAC-061: se renombrará a 'retail.product.mdm.config' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
-    RETAIL_PRODUCT_MDM_CONFIG = 'retail.product.mdm_config',
-    RETAIL_INVENTORY_LIST = 'retail.inventory.list',
-    RETAIL_INVENTORY_VIEW = 'retail.inventory.view',
-    RETAIL_INVENTORY_UPDATE = 'retail.inventory.update',
-    RETAIL_SALE_CREATE = 'retail.sale.create',
-    RETAIL_SALE_LIST = 'retail.sale.list',
-    RETAIL_SALE_CANCEL = 'retail.sale.cancel',
-    RETAIL_STORE_MANAGE = 'retail.store.manage',
-    RETAIL_RETAILER_MANAGE = 'retail.retailer.manage',
-
-    // ====================================================
-    // LEND — créditos + cobranza
-    // ====================================================
-    LEND_CREDIT_CREATE = 'lend.credit.create',
-    LEND_CREDIT_LIST = 'lend.credit.list',
-    LEND_CREDIT_VIEW = 'lend.credit.view',
-    LEND_CREDIT_UPDATE = 'lend.credit.update',
-    LEND_CREDIT_LIQUIDATE = 'lend.credit.liquidate',
-    LEND_CREDIT_RESTRUCTURE = 'lend.credit.restructure',
-    LEND_PAYMENT_APPLY = 'lend.payment.apply',
-    LEND_PAYMENT_LIST = 'lend.payment.list',
-    LEND_PAYMENT_REVERSE = 'lend.payment.reverse',
-    LEND_INSTALLMENT_VIEW = 'lend.installment.view',
-
-    // ====================================================
-    // MDM — device management (subset especializado de LEND)
-    // ====================================================
-    MDM_DEVICE_ENROLL = 'mdm.device.enroll',
-    MDM_DEVICE_RELEASE = 'mdm.device.release',
-    MDM_DEVICE_ARCHIVE = 'mdm.device.archive',
-    MDM_DEVICE_DEACTIVATE = 'mdm.device.deactivate',
-    MDM_DEVICE_LOCK_MANUAL = 'mdm.device.lock.manual',
-    MDM_DEVICE_UNLOCK_MANUAL = 'mdm.device.unlock.manual',
-    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.device.pin.unlock' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
-    MDM_DEVICE_PIN_UNLOCK = 'mdm.device.pin_unlock',
-    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.device.extend.validity' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
-    MDM_DEVICE_EXTEND_VALIDITY = 'mdm.device.extend_validity',
-    MDM_DEVICE_NOTIFY = 'mdm.device.notify',
-    MDM_DEVICE_STATUS_VIEW = 'mdm.device.status.view',
-    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.operation.log.view' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
-    MDM_OPERATION_LOG_VIEW = 'mdm.operation_log.view',
-    MDM_TEST = 'mdm.test',
-
-    // ====================================================
-    // PAY — futuro FiadoPay (placeholder, no usado en MVP)
-    // ====================================================
-    PAY_TRANSACTION_VIEW = 'pay.transaction.view',
-
-    // ====================================================
-    // AGENTS — Fiado Agents (tenant type AGENTS, roles scope GROUP).
-    // Permisos de DOMINIO derivados de los endpoints/pantallas reales del webapp de agents
-    // (ver fiado-agents-webapp/docs/rbac/RBAC-agents.md §5.2). El aislamiento entre orgs lo da el
-    // scope GROUP del roleAssignment (scopeRef = Group_GT.id), no un permiso aparte.
-    // ====================================================
-    // Gate de ACCESO a la app web de Agents (gobernanza). Sin este permiso el usuario no
-    // entra a la app. Lo otorgan los 5 roles GROUP de agents (en su propio repo, no acá).
-    AGENTS_APP_ACCESS = 'agents.app.access',
-    AGENTS_AGENT_LIST = 'agents.agent.list',
-    AGENTS_AGENT_CREATE = 'agents.agent.create',
-    /** @deprecated DEC-RBAC-061: se renombrará a 'agents.agent.create.bulk' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
-    AGENTS_AGENT_CREATE_BULK = 'agents.agent.create_bulk',
-    AGENTS_AGENT_MOVE = 'agents.agent.move',
-    AGENTS_AGENT_DELETE = 'agents.agent.delete',
-    AGENTS_REFERRAL_VIEW = 'agents.referral.view',
-    AGENTS_RANKING_VIEW = 'agents.ranking.view',
-    AGENTS_PRODUCTION_VIEW = 'agents.production.view',
-    AGENTS_PERSON_SEARCH = 'agents.person.search',
-    AGENTS_PERSON_VIEW = 'agents.person.view',
-    AGENTS_PERSON_UPDATE = 'agents.person.update',
-    AGENTS_PERSON_CREATE = 'agents.person.create',
-    AGENTS_DOCUMENT_VIEW = 'agents.document.view',
-    AGENTS_DOCUMENT_UPLOAD = 'agents.document.upload',
-    AGENTS_ADDRESS_VIEW = 'agents.address.view',
-    AGENTS_ADDRESS_MANAGE = 'agents.address.manage',
-    AGENTS_BENEFICIARY_VIEW = 'agents.beneficiary.view',
-    AGENTS_BENEFICIARY_MANAGE = 'agents.beneficiary.manage',
-    AGENTS_CARD_ISSUE = 'agents.card.issue',
-    AGENTS_CHAT_VIEW = 'agents.chat.view',
-    AGENTS_CHAT_SEND = 'agents.chat.send',
-    AGENTS_NOTIFICATION_SEND = 'agents.notification.send',
-    AGENTS_EXPORT_RUN = 'agents.export.run',
-    AGENTS_CATALOG_VIEW = 'agents.catalog.view',
-    // Gestión de grupos del tenant AGENTS (scope TENANT — el operador). Espejo de retail.retailer.manage.
-    AGENTS_GROUP_MANAGE = 'agents.group.manage',
-    // Gestión de usuarios DENTRO de un grupo (scope GROUP — el group_owner/admin sobre su grupo; el
-    // operador la cubre por TENANT). Crea usuarios + asigna roles group_* acotado al groupId. DEC-102.
-    AGENTS_GROUP_USER_MANAGE = 'agents.group.user.manage',
-
-    // ====================================================
-    // LEVEL{1,2,3} — primitivas RBAC genéricas por nivel (DEC-RBAC-063, ADITIVO)
-    // Permisos básicos auto-sembrables por nivel genérico (data-driven). Coexisten con los
-    // legacy retail.*/agents.* (categorías @deprecated), NO los reemplazan en la línea 3.x.
-    // ====================================================
-    LEVEL1_USER_CREATE = 'level1.user.create',
-    LEVEL1_USER_READ = 'level1.user.read',
-    LEVEL1_USER_UPDATE = 'level1.user.update',
-    LEVEL1_USER_DELETE = 'level1.user.delete',
-    LEVEL1_ROLE_CREATE = 'level1.role.create',
-    LEVEL1_ROLE_LIST = 'level1.role.list',
-    LEVEL1_ROLE_VIEW = 'level1.role.view',
-    LEVEL1_ROLE_UPDATE = 'level1.role.update',
-    LEVEL1_ROLE_DELETE = 'level1.role.delete',
-    LEVEL1_ROLE_ASSIGN = 'level1.role.assign',
-    LEVEL1_ROLE_REVOKE = 'level1.role.revoke',
-    LEVEL1_AUDIT_VIEW = 'level1.audit.view',
-    LEVEL2_USER_CREATE = 'level2.user.create',
-    LEVEL2_USER_READ = 'level2.user.read',
-    LEVEL2_USER_UPDATE = 'level2.user.update',
-    LEVEL2_USER_DELETE = 'level2.user.delete',
-    LEVEL2_ROLE_CREATE = 'level2.role.create',
-    LEVEL2_ROLE_LIST = 'level2.role.list',
-    LEVEL2_ROLE_VIEW = 'level2.role.view',
-    LEVEL2_ROLE_UPDATE = 'level2.role.update',
-    LEVEL2_ROLE_DELETE = 'level2.role.delete',
-    LEVEL2_ROLE_ASSIGN = 'level2.role.assign',
-    LEVEL2_ROLE_REVOKE = 'level2.role.revoke',
-    LEVEL2_AUDIT_VIEW = 'level2.audit.view',
-    LEVEL3_USER_CREATE = 'level3.user.create',
-    LEVEL3_USER_READ = 'level3.user.read',
-    LEVEL3_USER_UPDATE = 'level3.user.update',
-    LEVEL3_USER_DELETE = 'level3.user.delete',
-    LEVEL3_ROLE_CREATE = 'level3.role.create',
-    LEVEL3_ROLE_LIST = 'level3.role.list',
-    LEVEL3_ROLE_VIEW = 'level3.role.view',
-    LEVEL3_ROLE_UPDATE = 'level3.role.update',
-    LEVEL3_ROLE_DELETE = 'level3.role.delete',
-    LEVEL3_ROLE_ASSIGN = 'level3.role.assign',
-    LEVEL3_ROLE_REVOKE = 'level3.role.revoke',
-    LEVEL3_AUDIT_VIEW = 'level3.audit.view',
-}
-
-/**
- * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.
- * Índice de cada permiso = su posición de bit. NUNCA reordenar ni borrar:
- * deprecados CONSERVAN su posición; los nuevos van SIEMPRE al final.
- * Derivado explícitamente (no Object.values, frágil ante edición del enum).
- *
- * ⚠️ Si agregás un permiso al enum `Permission` (arriba), agregalo TAMBIÉN acá, AL FINAL.
- * Ver el procedimiento completo en el JSDoc del enum `Permission`. El test
- * `permissionBits.test.ts` rompe si esto y el enum no coinciden, y el snapshot del orden
- * completo rompe si reordenás (guard anti-desalineamiento de tokens emitidos).
- */
-export const PERMISSION_BIT_ORDER: readonly Permission[] = [
-    Permission.RBAC_CATALOG_MANAGE,
-    Permission.PLATFORM_TENANT_CREATE,
-    Permission.PLATFORM_TENANT_LIST,
-    Permission.PLATFORM_TENANT_VIEW,
-    Permission.PLATFORM_TENANT_UPDATE,
-    Permission.PLATFORM_TENANT_SUSPEND,
-    Permission.PLATFORM_TENANT_ACTIVATE,
-    Permission.PLATFORM_TENANT_ADMIN_REPLACE,
-    Permission.PLATFORM_COGNITO_POOL_MANAGE,
-    Permission.PLATFORM_COGNITO_POOL_LIST,
-    Permission.PLATFORM_USER_CREATE,
-    Permission.PLATFORM_USER_LIST,
-    Permission.PLATFORM_USER_VIEW,
-    Permission.PLATFORM_USER_UPDATE,
-    Permission.PLATFORM_USER_DISABLE,
-    Permission.PLATFORM_USER_ENABLE,
-    Permission.PLATFORM_USER_DELETE,
-    Permission.PLATFORM_ROLE_CREATE,
-    Permission.PLATFORM_ROLE_LIST,
-    Permission.PLATFORM_ROLE_UPDATE,
-    Permission.PLATFORM_ROLE_DELETE,
-    Permission.PLATFORM_AUDIT_VIEW,
-    Permission.TENANT_USER_CREATE,
-    Permission.TENANT_USER_CREATE_LATERAL,
-    Permission.TENANT_USER_READ,
-    Permission.TENANT_USER_STATUS,
-    Permission.TENANT_USER_LIST,
-    Permission.TENANT_USER_VIEW,
-    Permission.TENANT_USER_UPDATE,
-    Permission.TENANT_USER_DISABLE,
-    Permission.TENANT_USER_ENABLE,
-    Permission.TENANT_USER_DELETE,
-    Permission.TENANT_USER_MFA_RESET,
-    Permission.TENANT_USER_PASSWORD_RESET,
-    Permission.TENANT_ROLE_CREATE,
-    Permission.TENANT_ROLE_LIST,
-    Permission.TENANT_ROLE_UPDATE,
-    Permission.TENANT_ROLE_DELETE,
-    Permission.TENANT_ROLE_VIEW,
-    Permission.TENANT_ROLE_ASSIGN,
-    Permission.TENANT_ROLE_REVOKE,
-    Permission.TENANT_SECURITY_POLICY_VIEW,
-    Permission.TENANT_SECURITY_POLICY_MANAGE,
-    Permission.TENANT_BRANDING_MANAGE,
-    Permission.TENANT_AUDIT_VIEW,
-    Permission.RETAIL_USER_CREATE,
-    Permission.RETAIL_USER_CREATE_LATERAL,
-    Permission.RETAIL_USER_READ,
-    Permission.RETAIL_USER_UPDATE,
-    Permission.RETAIL_USER_STATUS,
-    Permission.RETAIL_USER_DELETE,
-    Permission.RETAIL_USER_PASSWORD_RESET,
-    Permission.RETAIL_USER_MFA_RESET,
-    Permission.RETAIL_PRODUCT_CREATE,
-    Permission.RETAIL_PRODUCT_LIST,
-    Permission.RETAIL_PRODUCT_VIEW,
-    Permission.RETAIL_PRODUCT_UPDATE,
-    Permission.RETAIL_PRODUCT_DELETE,
-    Permission.RETAIL_PRODUCT_MDM_CONFIG,
-    Permission.RETAIL_INVENTORY_LIST,
-    Permission.RETAIL_INVENTORY_VIEW,
-    Permission.RETAIL_INVENTORY_UPDATE,
-    Permission.RETAIL_SALE_CREATE,
-    Permission.RETAIL_SALE_LIST,
-    Permission.RETAIL_SALE_CANCEL,
-    Permission.RETAIL_STORE_MANAGE,
-    Permission.RETAIL_RETAILER_MANAGE,
-    Permission.LEND_CREDIT_CREATE,
-    Permission.LEND_CREDIT_LIST,
-    Permission.LEND_CREDIT_VIEW,
-    Permission.LEND_CREDIT_UPDATE,
-    Permission.LEND_CREDIT_LIQUIDATE,
-    Permission.LEND_CREDIT_RESTRUCTURE,
-    Permission.LEND_PAYMENT_APPLY,
-    Permission.LEND_PAYMENT_LIST,
-    Permission.LEND_PAYMENT_REVERSE,
-    Permission.LEND_INSTALLMENT_VIEW,
-    Permission.MDM_DEVICE_ENROLL,
-    Permission.MDM_DEVICE_RELEASE,
-    Permission.MDM_DEVICE_ARCHIVE,
-    Permission.MDM_DEVICE_DEACTIVATE,
-    Permission.MDM_DEVICE_LOCK_MANUAL,
-    Permission.MDM_DEVICE_UNLOCK_MANUAL,
-    Permission.MDM_DEVICE_PIN_UNLOCK,
-    Permission.MDM_DEVICE_EXTEND_VALIDITY,
-    Permission.MDM_DEVICE_NOTIFY,
-    Permission.MDM_DEVICE_STATUS_VIEW,
-    Permission.MDM_OPERATION_LOG_VIEW,
-    Permission.MDM_TEST,
-    Permission.PAY_TRANSACTION_VIEW,
-    // AGENTS (append-only) — Fiado Agents domain perms.
-    Permission.AGENTS_AGENT_LIST,
-    Permission.AGENTS_AGENT_CREATE,
-    Permission.AGENTS_AGENT_CREATE_BULK,
-    Permission.AGENTS_AGENT_MOVE,
-    Permission.AGENTS_AGENT_DELETE,
-    Permission.AGENTS_REFERRAL_VIEW,
-    Permission.AGENTS_RANKING_VIEW,
-    Permission.AGENTS_PRODUCTION_VIEW,
-    Permission.AGENTS_PERSON_SEARCH,
-    Permission.AGENTS_PERSON_VIEW,
-    Permission.AGENTS_PERSON_UPDATE,
-    Permission.AGENTS_DOCUMENT_VIEW,
-    Permission.AGENTS_DOCUMENT_UPLOAD,
-    Permission.AGENTS_ADDRESS_VIEW,
-    Permission.AGENTS_ADDRESS_MANAGE,
-    Permission.AGENTS_BENEFICIARY_VIEW,
-    Permission.AGENTS_BENEFICIARY_MANAGE,
-    Permission.AGENTS_CARD_ISSUE,
-    Permission.AGENTS_CHAT_VIEW,
-    Permission.AGENTS_CHAT_SEND,
-    Permission.AGENTS_NOTIFICATION_SEND,
-    Permission.AGENTS_EXPORT_RUN,
-    Permission.AGENTS_CATALOG_VIEW,
-    Permission.AGENTS_GROUP_MANAGE,
-    Permission.AGENTS_GROUP_USER_MANAGE,
-    // Append-only: nuevo permiso agregado 2026-06-18 (DEC-A2-02). Va al FINAL para no correr los bits
-    // existentes (PERMS_VERSION cambia, pero los índices previos se conservan).
-    Permission.AGENTS_PERSON_CREATE,
-    // Append-only 2026-06-18 (DEC-RBAC-017): catálogo de campos personalizados por tenant. Al FINAL para
-    // no correr bits existentes. (El bitset está deprecado por token-flaco, pero el orden se mantiene
-    // sincronizado con el enum para que el test de bits no rompa.)
-    Permission.PLATFORM_TENANT_USERFIELDS_MANAGE,
-    // Append-only 2026-06-21: gate de acceso a la app web de Agents (gobernanza). Al FINAL para no
-    // correr bits existentes (PERMS_VERSION cambia, pero los índices previos se conservan).
-    Permission.AGENTS_APP_ACCESS,
-    // Append-only 2026-06-19: lateral platform (platform_super_admin asigna roles scope PLATFORM).
-    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
-    Permission.PLATFORM_USER_CREATE_LATERAL,
-    // Append-only 2026-06-24 (DEC-RBAC-036): gate dedicada de gestión de aplicaciones (plantillas).
-    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
-    Permission.PLATFORM_APPLICATION_MANAGE,
-    // Append-only 2026-06-24 (DEC-RBAC-038): gestión de scope-entities de nivel genérico (scope-bound).
-    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
-    Permission.TENANT_LEVEL_MANAGE,
-    // Append-only 2026-06-25 (DEC-RBAC-050): edición del autoregistro self-service del tenant (allowlist
-    // anti-escalación). Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
-    Permission.PLATFORM_TENANT_AUTOREGISTER_MANAGE,
-    // Append-only 2026-06-28 (DEC-RBAC-063): 36 primitivas RBAC por nivel genérico. Al FINAL para no
-    // correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
-    Permission.LEVEL1_USER_CREATE,
-    Permission.LEVEL1_USER_READ,
-    Permission.LEVEL1_USER_UPDATE,
-    Permission.LEVEL1_USER_DELETE,
-    Permission.LEVEL1_ROLE_CREATE,
-    Permission.LEVEL1_ROLE_LIST,
-    Permission.LEVEL1_ROLE_VIEW,
-    Permission.LEVEL1_ROLE_UPDATE,
-    Permission.LEVEL1_ROLE_DELETE,
-    Permission.LEVEL1_ROLE_ASSIGN,
-    Permission.LEVEL1_ROLE_REVOKE,
-    Permission.LEVEL1_AUDIT_VIEW,
-    Permission.LEVEL2_USER_CREATE,
-    Permission.LEVEL2_USER_READ,
-    Permission.LEVEL2_USER_UPDATE,
-    Permission.LEVEL2_USER_DELETE,
-    Permission.LEVEL2_ROLE_CREATE,
-    Permission.LEVEL2_ROLE_LIST,
-    Permission.LEVEL2_ROLE_VIEW,
-    Permission.LEVEL2_ROLE_UPDATE,
-    Permission.LEVEL2_ROLE_DELETE,
-    Permission.LEVEL2_ROLE_ASSIGN,
-    Permission.LEVEL2_ROLE_REVOKE,
-    Permission.LEVEL2_AUDIT_VIEW,
-    Permission.LEVEL3_USER_CREATE,
-    Permission.LEVEL3_USER_READ,
-    Permission.LEVEL3_USER_UPDATE,
-    Permission.LEVEL3_USER_DELETE,
-    Permission.LEVEL3_ROLE_CREATE,
-    Permission.LEVEL3_ROLE_LIST,
-    Permission.LEVEL3_ROLE_VIEW,
-    Permission.LEVEL3_ROLE_UPDATE,
-    Permission.LEVEL3_ROLE_DELETE,
-    Permission.LEVEL3_ROLE_ASSIGN,
-    Permission.LEVEL3_ROLE_REVOKE,
-    Permission.LEVEL3_AUDIT_VIEW,
-] as const;
-
-function djb2(input: string): number {
-    let h = 5381;
-    for (let i = 0; i < input.length; i++) h = ((h << 5) + h + input.charCodeAt(i)) >>> 0;
-    return h;
-}
-/** Versión del catálogo = hash del orden. Cambia solo si el orden cambia. */
-export const PERMS_VERSION: number = djb2(PERMISSION_BIT_ORDER.join('|'));
-
-const BIT_INDEX: ReadonlyMap<Permission, number> = new Map(PERMISSION_BIT_ORDER.map((p, i) => [p, i]));
-
-/** Comprime un set de permisos a bitset base64url. */
-export function permissionsToBits(perms: readonly Permission[]): string {
-    const bytes = new Uint8Array(Math.ceil(PERMISSION_BIT_ORDER.length / 8));
-    for (const p of perms) {
-        const idx = BIT_INDEX.get(p);
-        if (idx === undefined) continue;
-        bytes[idx >> 3] |= 1 << (idx & 7);
-    }
-    return Buffer.from(bytes).toString('base64url');
-}
-/** Decodifica un bitset base64url a la lista de permisos. Tolerante a basura → []. */
-export function bitsToPermissions(bits: string): Permission[] {
-    if (typeof bits !== 'string' || bits.length === 0) return [];
-    let bytes: Buffer;
-    try {
-        bytes = Buffer.from(bits, 'base64url');
-    } catch {
-        return [];
-    }
-    const out: Permission[] = [];
-    for (let i = 0; i < PERMISSION_BIT_ORDER.length; i++) {
-        const byte = bytes[i >> 3] ?? 0;
-        if (byte & (1 << (i & 7))) out.push(PERMISSION_BIT_ORDER[i]);
-    }
-    return out;
-}
+/**
+ * Catálogo universal de permisos del sistema RBAC Fiado.
+ *
+ * Origen: componente 01 de Fase 0 SureKeep (spec maestro):
+ *   surekeep/docs/5_fases/00_fase0_cognito_rbac_users_mfa/componentes/01_typekit-rbac-additions.md
+ *
+ * Copy-paste literal de los valores del spec (DEC-003).
+ * Convención: `<category>.<resource>.<action>` (snake_case en action si multi-palabra).
+ *
+ * ⚠️ ESTE ES EL CATÁLOGO GLOBAL Y ÚNICO. Todo permiso del sistema vive acá. Los tenants
+ * NO inventan permisos: cada `tenantType` arma su lista (techo) ELIGIENDO de este catálogo
+ * (`TenantTypePermissionCatalog_GT` en platform-rbac-business, DEC-062), y cada tenant arma
+ * sus roles combinando esos permisos. El vocabulario es global; lo que varía por tenant es
+ * QUÉ permisos usa, no CUÁLES existen.
+ *
+ * ⚠️⚠️ AL AGREGAR / QUITAR / RENOMBRAR UN PERMISO — PROCEDIMIENTO OBLIGATORIO:
+ *   1. Agregar el valor a ESTE enum.
+ *   2. Agregarlo TAMBIÉN al FINAL de `PERMISSION_BIT_ORDER` (abajo) — append-only, NUNCA en
+ *      el medio ni reordenando: ese array define el bit de cada permiso en el token (bitset).
+ *      Reordenar/insertar en medio desalinea TODOS los tokens ya emitidos (escalada/pérdida
+ *      de permisos silenciosa). Un permiso deprecado CONSERVA su posición (no se borra del array).
+ *   3. Recién entonces un `tenantType` puede incluirlo en su lista. Un permiso que NO esté en
+ *      este enum + bit-order NO tiene bit → no viaja en el token (el gateway-adapter no lo ve).
+ *   4. `PERMS_VERSION` (hash del orden) cambia solo → bump minor del type-kit + redeploy de
+ *      consumers (jwt-inyector-trigger, gateway-adapter, platform-rbac-business). Tokens viejos
+ *      caen al fallback (resolver DDB) hasta refrescar — by-design, no rompe.
+ *   El test `permissionBits.test.ts` falla si el enum y `PERMISSION_BIT_ORDER` se desincronizan.
+ *
+ * Coexiste con módulo `rbac/` oficial cuando yhonhansen publique componente 01 — TD-RBAC-002.
+ */
+export enum Permission {
+    // ====================================================
+    // RBAC — gestión genérica del propio sistema RBAC
+    // ====================================================
+    RBAC_CATALOG_MANAGE = 'rbac.catalog.manage',
+
+    // ====================================================
+    // PLATFORM — operaciones a nivel meta-plataforma (Fiado equipo)
+    // ====================================================
+    PLATFORM_TENANT_CREATE = 'platform.tenant.create',
+    PLATFORM_TENANT_LIST = 'platform.tenant.list',
+    PLATFORM_TENANT_VIEW = 'platform.tenant.view',
+    PLATFORM_TENANT_UPDATE = 'platform.tenant.update',
+    PLATFORM_TENANT_SUSPEND = 'platform.tenant.suspend',
+    PLATFORM_TENANT_ACTIVATE = 'platform.tenant.activate',
+    PLATFORM_TENANT_ADMIN_REPLACE = 'platform.tenant.admin.replace',
+    PLATFORM_COGNITO_POOL_MANAGE = 'platform.cognito.pool.manage',
+    PLATFORM_COGNITO_POOL_LIST = 'platform.cognito.pool.list',
+    PLATFORM_USER_CREATE = 'platform.user.create',
+    PLATFORM_USER_LIST = 'platform.user.list',
+    PLATFORM_USER_VIEW = 'platform.user.view',
+    PLATFORM_USER_UPDATE = 'platform.user.update',
+    PLATFORM_USER_DISABLE = 'platform.user.disable',
+    PLATFORM_USER_ENABLE = 'platform.user.enable',
+    PLATFORM_USER_DELETE = 'platform.user.delete',
+    // Crear/asignar usuarios platform de TU MISMO nivel (platform_admin → platform_admin).
+    // Espejo de tenant.user.create.lateral / retail.user.create.lateral: habilita allowOwnLevel
+    // en ScopeValidationService.canAssign para scope PLATFORM. DEC-052.
+    PLATFORM_USER_CREATE_LATERAL = 'platform.user.create.lateral',
+    PLATFORM_ROLE_CREATE = 'platform.role.create',
+    PLATFORM_ROLE_LIST = 'platform.role.list',
+    PLATFORM_ROLE_UPDATE = 'platform.role.update',
+    PLATFORM_ROLE_DELETE = 'platform.role.delete',
+    PLATFORM_AUDIT_VIEW = 'platform.audit.view',
+    PLATFORM_TENANT_USERFIELDS_MANAGE = 'platform.tenant.userfields.manage',
+    // DEC-RBAC-050: edición del autoregistro self-service del tenant (allowlist anti-escalación
+    // centralizada/platform). Espejo EXACTO de PLATFORM_TENANT_USERFIELDS_MANAGE (scope PLATFORM).
+    PLATFORM_TENANT_AUTOREGISTER_MANAGE = 'platform.tenant.autoregister.manage',
+    // DEC-RBAC-036: gestión de aplicaciones (plantillas) — reemplaza el reuso de rbac.catalog.manage en /applications.
+    PLATFORM_APPLICATION_MANAGE = 'platform.application.manage',
+
+    // ====================================================
+    // TENANT — operaciones dentro del silo de un tenant
+    // ====================================================
+    TENANT_USER_CREATE = 'tenant.user.create',
+    // Crear/gestionar usuarios de TU MISMO nivel jerárquico (ej. tenant_admin → tenant_admin).
+    // Gobierna create + assign-role + update (no solo create). Sin el permiso: solo "para abajo".
+    TENANT_USER_CREATE_LATERAL = 'tenant.user.create.lateral',
+    // Merge de tenant.user.list + tenant.user.view (read unificado del listado y el detalle).
+    TENANT_USER_READ = 'tenant.user.read',
+    // Merge de tenant.user.disable + tenant.user.enable (cambio de estado activo/suspendido).
+    TENANT_USER_STATUS = 'tenant.user.status',
+    // Deprecados (NO borrar — compat): reemplazados por TENANT_USER_READ / TENANT_USER_STATUS.
+    TENANT_USER_LIST = 'tenant.user.list',
+    TENANT_USER_VIEW = 'tenant.user.view',
+    TENANT_USER_UPDATE = 'tenant.user.update',
+    TENANT_USER_DISABLE = 'tenant.user.disable',
+    TENANT_USER_ENABLE = 'tenant.user.enable',
+    TENANT_USER_DELETE = 'tenant.user.delete',
+    TENANT_USER_MFA_RESET = 'tenant.user.mfa.reset',
+    TENANT_USER_PASSWORD_RESET = 'tenant.user.password.reset',
+    TENANT_ROLE_CREATE = 'tenant.role.create',
+    TENANT_ROLE_LIST = 'tenant.role.list',
+    TENANT_ROLE_UPDATE = 'tenant.role.update',
+    TENANT_ROLE_DELETE = 'tenant.role.delete',
+    TENANT_ROLE_VIEW = 'tenant.role.view',
+    TENANT_ROLE_ASSIGN = 'tenant.role.assign',
+    TENANT_ROLE_REVOKE = 'tenant.role.revoke',
+    TENANT_SECURITY_POLICY_VIEW = 'tenant.security.policy.view',
+    TENANT_SECURITY_POLICY_MANAGE = 'tenant.security.policy.manage',
+    TENANT_BRANDING_MANAGE = 'tenant.branding.manage',
+    TENANT_AUDIT_VIEW = 'tenant.audit.view',
+    // DEC-RBAC-038: gestión de scope-entities de nivel genérico — crear/editar/borrar entidades del nivel inferior; scope-bound.
+    TENANT_LEVEL_MANAGE = 'tenant.level.manage',
+
+    // ====================================================
+    // RETAIL — catálogo + inventario + ventas
+    // ====================================================
+    // RETAIL user-management — espejo de tenant.user.* a nivel RETAILER. Los KEYS existen para que el
+    // catálogo + el picker los ofrezcan; sus endpoints/handlers los implementa el agente de retailer
+    // user-management (rbac TD-RBAC-049). create.lateral gobierna create + assign + update (igual que tenant).
+    RETAIL_USER_CREATE = 'retail.user.create',
+    RETAIL_USER_CREATE_LATERAL = 'retail.user.create.lateral',
+    RETAIL_USER_READ = 'retail.user.read',
+    RETAIL_USER_UPDATE = 'retail.user.update',
+    RETAIL_USER_STATUS = 'retail.user.status',
+    RETAIL_USER_DELETE = 'retail.user.delete',
+    RETAIL_USER_PASSWORD_RESET = 'retail.user.password.reset',
+    RETAIL_USER_MFA_RESET = 'retail.user.mfa.reset',
+    RETAIL_PRODUCT_CREATE = 'retail.product.create',
+    RETAIL_PRODUCT_LIST = 'retail.product.list',
+    RETAIL_PRODUCT_VIEW = 'retail.product.view',
+    RETAIL_PRODUCT_UPDATE = 'retail.product.update',
+    RETAIL_PRODUCT_DELETE = 'retail.product.delete',
+    /** @deprecated DEC-RBAC-061: se renombrará a 'retail.product.mdm.config' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
+    RETAIL_PRODUCT_MDM_CONFIG = 'retail.product.mdm_config',
+    RETAIL_INVENTORY_LIST = 'retail.inventory.list',
+    RETAIL_INVENTORY_VIEW = 'retail.inventory.view',
+    RETAIL_INVENTORY_UPDATE = 'retail.inventory.update',
+    RETAIL_SALE_CREATE = 'retail.sale.create',
+    RETAIL_SALE_LIST = 'retail.sale.list',
+    RETAIL_SALE_CANCEL = 'retail.sale.cancel',
+    RETAIL_STORE_MANAGE = 'retail.store.manage',
+    RETAIL_RETAILER_MANAGE = 'retail.retailer.manage',
+
+    // ====================================================
+    // LEND — créditos + cobranza
+    // ====================================================
+    LEND_CREDIT_CREATE = 'lend.credit.create',
+    LEND_CREDIT_LIST = 'lend.credit.list',
+    LEND_CREDIT_VIEW = 'lend.credit.view',
+    LEND_CREDIT_UPDATE = 'lend.credit.update',
+    LEND_CREDIT_LIQUIDATE = 'lend.credit.liquidate',
+    LEND_CREDIT_RESTRUCTURE = 'lend.credit.restructure',
+    LEND_PAYMENT_APPLY = 'lend.payment.apply',
+    LEND_PAYMENT_LIST = 'lend.payment.list',
+    LEND_PAYMENT_REVERSE = 'lend.payment.reverse',
+    LEND_INSTALLMENT_VIEW = 'lend.installment.view',
+
+    // ====================================================
+    // MDM — device management (subset especializado de LEND)
+    // ====================================================
+    MDM_DEVICE_ENROLL = 'mdm.device.enroll',
+    MDM_DEVICE_RELEASE = 'mdm.device.release',
+    MDM_DEVICE_ARCHIVE = 'mdm.device.archive',
+    MDM_DEVICE_DEACTIVATE = 'mdm.device.deactivate',
+    MDM_DEVICE_LOCK_MANUAL = 'mdm.device.lock.manual',
+    MDM_DEVICE_UNLOCK_MANUAL = 'mdm.device.unlock.manual',
+    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.device.pin.unlock' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
+    MDM_DEVICE_PIN_UNLOCK = 'mdm.device.pin_unlock',
+    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.device.extend.validity' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
+    MDM_DEVICE_EXTEND_VALIDITY = 'mdm.device.extend_validity',
+    MDM_DEVICE_NOTIFY = 'mdm.device.notify',
+    MDM_DEVICE_STATUS_VIEW = 'mdm.device.status.view',
+    /** @deprecated DEC-RBAC-061: se renombrará a 'mdm.operation.log.view' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
+    MDM_OPERATION_LOG_VIEW = 'mdm.operation_log.view',
+    MDM_TEST = 'mdm.test',
+
+    // ====================================================
+    // PAY — futuro FiadoPay (placeholder, no usado en MVP)
+    // ====================================================
+    PAY_TRANSACTION_VIEW = 'pay.transaction.view',
+
+    // ====================================================
+    // AGENTS — Fiado Agents (tenant type AGENTS, roles scope GROUP).
+    // Permisos de DOMINIO derivados de los endpoints/pantallas reales del webapp de agents
+    // (ver fiado-agents-webapp/docs/rbac/RBAC-agents.md §5.2). El aislamiento entre orgs lo da el
+    // scope GROUP del roleAssignment (scopeRef = Group_GT.id), no un permiso aparte.
+    // ====================================================
+    // Gate de ACCESO a la app web de Agents (gobernanza). Sin este permiso el usuario no
+    // entra a la app. Lo otorgan los 5 roles GROUP de agents (en su propio repo, no acá).
+    AGENTS_APP_ACCESS = 'agents.app.access',
+    AGENTS_AGENT_LIST = 'agents.agent.list',
+    AGENTS_AGENT_CREATE = 'agents.agent.create',
+    /** @deprecated DEC-RBAC-061: se renombrará a 'agents.agent.create.bulk' (naming con puntos). Migración de datos coordinada por backend pendiente; no usar en código nuevo. */
+    AGENTS_AGENT_CREATE_BULK = 'agents.agent.create_bulk',
+    AGENTS_AGENT_MOVE = 'agents.agent.move',
+    AGENTS_AGENT_DELETE = 'agents.agent.delete',
+    AGENTS_REFERRAL_VIEW = 'agents.referral.view',
+    AGENTS_RANKING_VIEW = 'agents.ranking.view',
+    AGENTS_PRODUCTION_VIEW = 'agents.production.view',
+    AGENTS_PERSON_SEARCH = 'agents.person.search',
+    AGENTS_PERSON_VIEW = 'agents.person.view',
+    AGENTS_PERSON_UPDATE = 'agents.person.update',
+    AGENTS_PERSON_CREATE = 'agents.person.create',
+    AGENTS_DOCUMENT_VIEW = 'agents.document.view',
+    AGENTS_DOCUMENT_UPLOAD = 'agents.document.upload',
+    AGENTS_ADDRESS_VIEW = 'agents.address.view',
+    AGENTS_ADDRESS_MANAGE = 'agents.address.manage',
+    AGENTS_BENEFICIARY_VIEW = 'agents.beneficiary.view',
+    AGENTS_BENEFICIARY_MANAGE = 'agents.beneficiary.manage',
+    AGENTS_CARD_ISSUE = 'agents.card.issue',
+    AGENTS_CHAT_VIEW = 'agents.chat.view',
+    AGENTS_CHAT_SEND = 'agents.chat.send',
+    AGENTS_NOTIFICATION_SEND = 'agents.notification.send',
+    AGENTS_EXPORT_RUN = 'agents.export.run',
+    AGENTS_CATALOG_VIEW = 'agents.catalog.view',
+    // Gestión de grupos del tenant AGENTS (scope TENANT — el operador). Espejo de retail.retailer.manage.
+    AGENTS_GROUP_MANAGE = 'agents.group.manage',
+    // Gestión de usuarios DENTRO de un grupo (scope GROUP — el group_owner/admin sobre su grupo; el
+    // operador la cubre por TENANT). Crea usuarios + asigna roles group_* acotado al groupId. DEC-102.
+    AGENTS_GROUP_USER_MANAGE = 'agents.group.user.manage',
+
+    // ====================================================
+    // LEVEL{1,2,3} — primitivas RBAC genéricas por nivel (DEC-RBAC-063, ADITIVO)
+    // Permisos básicos auto-sembrables por nivel genérico (data-driven). Coexisten con los
+    // legacy retail.*/agents.* (categorías @deprecated), NO los reemplazan en la línea 3.x.
+    // ====================================================
+    LEVEL1_USER_CREATE = 'level1.user.create',
+    LEVEL1_USER_READ = 'level1.user.read',
+    LEVEL1_USER_UPDATE = 'level1.user.update',
+    LEVEL1_USER_DELETE = 'level1.user.delete',
+    LEVEL1_ROLE_CREATE = 'level1.role.create',
+    LEVEL1_ROLE_LIST = 'level1.role.list',
+    LEVEL1_ROLE_VIEW = 'level1.role.view',
+    LEVEL1_ROLE_UPDATE = 'level1.role.update',
+    LEVEL1_ROLE_DELETE = 'level1.role.delete',
+    LEVEL1_ROLE_ASSIGN = 'level1.role.assign',
+    LEVEL1_ROLE_REVOKE = 'level1.role.revoke',
+    LEVEL1_AUDIT_VIEW = 'level1.audit.view',
+    LEVEL2_USER_CREATE = 'level2.user.create',
+    LEVEL2_USER_READ = 'level2.user.read',
+    LEVEL2_USER_UPDATE = 'level2.user.update',
+    LEVEL2_USER_DELETE = 'level2.user.delete',
+    LEVEL2_ROLE_CREATE = 'level2.role.create',
+    LEVEL2_ROLE_LIST = 'level2.role.list',
+    LEVEL2_ROLE_VIEW = 'level2.role.view',
+    LEVEL2_ROLE_UPDATE = 'level2.role.update',
+    LEVEL2_ROLE_DELETE = 'level2.role.delete',
+    LEVEL2_ROLE_ASSIGN = 'level2.role.assign',
+    LEVEL2_ROLE_REVOKE = 'level2.role.revoke',
+    LEVEL2_AUDIT_VIEW = 'level2.audit.view',
+    LEVEL3_USER_CREATE = 'level3.user.create',
+    LEVEL3_USER_READ = 'level3.user.read',
+    LEVEL3_USER_UPDATE = 'level3.user.update',
+    LEVEL3_USER_DELETE = 'level3.user.delete',
+    LEVEL3_ROLE_CREATE = 'level3.role.create',
+    LEVEL3_ROLE_LIST = 'level3.role.list',
+    LEVEL3_ROLE_VIEW = 'level3.role.view',
+    LEVEL3_ROLE_UPDATE = 'level3.role.update',
+    LEVEL3_ROLE_DELETE = 'level3.role.delete',
+    LEVEL3_ROLE_ASSIGN = 'level3.role.assign',
+    LEVEL3_ROLE_REVOKE = 'level3.role.revoke',
+    LEVEL3_AUDIT_VIEW = 'level3.audit.view',
+}
+
+/**
+ * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.
+ * Índice de cada permiso = su posición de bit. NUNCA reordenar ni borrar:
+ * deprecados CONSERVAN su posición; los nuevos van SIEMPRE al final.
+ * Derivado explícitamente (no Object.values, frágil ante edición del enum).
+ *
+ * ⚠️ Si agregás un permiso al enum `Permission` (arriba), agregalo TAMBIÉN acá, AL FINAL.
+ * Ver el procedimiento completo en el JSDoc del enum `Permission`. El test
+ * `permissionBits.test.ts` rompe si esto y el enum no coinciden, y el snapshot del orden
+ * completo rompe si reordenás (guard anti-desalineamiento de tokens emitidos).
+ */
+export const PERMISSION_BIT_ORDER: readonly Permission[] = [
+    Permission.RBAC_CATALOG_MANAGE,
+    Permission.PLATFORM_TENANT_CREATE,
+    Permission.PLATFORM_TENANT_LIST,
+    Permission.PLATFORM_TENANT_VIEW,
+    Permission.PLATFORM_TENANT_UPDATE,
+    Permission.PLATFORM_TENANT_SUSPEND,
+    Permission.PLATFORM_TENANT_ACTIVATE,
+    Permission.PLATFORM_TENANT_ADMIN_REPLACE,
+    Permission.PLATFORM_COGNITO_POOL_MANAGE,
+    Permission.PLATFORM_COGNITO_POOL_LIST,
+    Permission.PLATFORM_USER_CREATE,
+    Permission.PLATFORM_USER_LIST,
+    Permission.PLATFORM_USER_VIEW,
+    Permission.PLATFORM_USER_UPDATE,
+    Permission.PLATFORM_USER_DISABLE,
+    Permission.PLATFORM_USER_ENABLE,
+    Permission.PLATFORM_USER_DELETE,
+    Permission.PLATFORM_ROLE_CREATE,
+    Permission.PLATFORM_ROLE_LIST,
+    Permission.PLATFORM_ROLE_UPDATE,
+    Permission.PLATFORM_ROLE_DELETE,
+    Permission.PLATFORM_AUDIT_VIEW,
+    Permission.TENANT_USER_CREATE,
+    Permission.TENANT_USER_CREATE_LATERAL,
+    Permission.TENANT_USER_READ,
+    Permission.TENANT_USER_STATUS,
+    Permission.TENANT_USER_LIST,
+    Permission.TENANT_USER_VIEW,
+    Permission.TENANT_USER_UPDATE,
+    Permission.TENANT_USER_DISABLE,
+    Permission.TENANT_USER_ENABLE,
+    Permission.TENANT_USER_DELETE,
+    Permission.TENANT_USER_MFA_RESET,
+    Permission.TENANT_USER_PASSWORD_RESET,
+    Permission.TENANT_ROLE_CREATE,
+    Permission.TENANT_ROLE_LIST,
+    Permission.TENANT_ROLE_UPDATE,
+    Permission.TENANT_ROLE_DELETE,
+    Permission.TENANT_ROLE_VIEW,
+    Permission.TENANT_ROLE_ASSIGN,
+    Permission.TENANT_ROLE_REVOKE,
+    Permission.TENANT_SECURITY_POLICY_VIEW,
+    Permission.TENANT_SECURITY_POLICY_MANAGE,
+    Permission.TENANT_BRANDING_MANAGE,
+    Permission.TENANT_AUDIT_VIEW,
+    Permission.RETAIL_USER_CREATE,
+    Permission.RETAIL_USER_CREATE_LATERAL,
+    Permission.RETAIL_USER_READ,
+    Permission.RETAIL_USER_UPDATE,
+    Permission.RETAIL_USER_STATUS,
+    Permission.RETAIL_USER_DELETE,
+    Permission.RETAIL_USER_PASSWORD_RESET,
+    Permission.RETAIL_USER_MFA_RESET,
+    Permission.RETAIL_PRODUCT_CREATE,
+    Permission.RETAIL_PRODUCT_LIST,
+    Permission.RETAIL_PRODUCT_VIEW,
+    Permission.RETAIL_PRODUCT_UPDATE,
+    Permission.RETAIL_PRODUCT_DELETE,
+    Permission.RETAIL_PRODUCT_MDM_CONFIG,
+    Permission.RETAIL_INVENTORY_LIST,
+    Permission.RETAIL_INVENTORY_VIEW,
+    Permission.RETAIL_INVENTORY_UPDATE,
+    Permission.RETAIL_SALE_CREATE,
+    Permission.RETAIL_SALE_LIST,
+    Permission.RETAIL_SALE_CANCEL,
+    Permission.RETAIL_STORE_MANAGE,
+    Permission.RETAIL_RETAILER_MANAGE,
+    Permission.LEND_CREDIT_CREATE,
+    Permission.LEND_CREDIT_LIST,
+    Permission.LEND_CREDIT_VIEW,
+    Permission.LEND_CREDIT_UPDATE,
+    Permission.LEND_CREDIT_LIQUIDATE,
+    Permission.LEND_CREDIT_RESTRUCTURE,
+    Permission.LEND_PAYMENT_APPLY,
+    Permission.LEND_PAYMENT_LIST,
+    Permission.LEND_PAYMENT_REVERSE,
+    Permission.LEND_INSTALLMENT_VIEW,
+    Permission.MDM_DEVICE_ENROLL,
+    Permission.MDM_DEVICE_RELEASE,
+    Permission.MDM_DEVICE_ARCHIVE,
+    Permission.MDM_DEVICE_DEACTIVATE,
+    Permission.MDM_DEVICE_LOCK_MANUAL,
+    Permission.MDM_DEVICE_UNLOCK_MANUAL,
+    Permission.MDM_DEVICE_PIN_UNLOCK,
+    Permission.MDM_DEVICE_EXTEND_VALIDITY,
+    Permission.MDM_DEVICE_NOTIFY,
+    Permission.MDM_DEVICE_STATUS_VIEW,
+    Permission.MDM_OPERATION_LOG_VIEW,
+    Permission.MDM_TEST,
+    Permission.PAY_TRANSACTION_VIEW,
+    // AGENTS (append-only) — Fiado Agents domain perms.
+    Permission.AGENTS_AGENT_LIST,
+    Permission.AGENTS_AGENT_CREATE,
+    Permission.AGENTS_AGENT_CREATE_BULK,
+    Permission.AGENTS_AGENT_MOVE,
+    Permission.AGENTS_AGENT_DELETE,
+    Permission.AGENTS_REFERRAL_VIEW,
+    Permission.AGENTS_RANKING_VIEW,
+    Permission.AGENTS_PRODUCTION_VIEW,
+    Permission.AGENTS_PERSON_SEARCH,
+    Permission.AGENTS_PERSON_VIEW,
+    Permission.AGENTS_PERSON_UPDATE,
+    Permission.AGENTS_DOCUMENT_VIEW,
+    Permission.AGENTS_DOCUMENT_UPLOAD,
+    Permission.AGENTS_ADDRESS_VIEW,
+    Permission.AGENTS_ADDRESS_MANAGE,
+    Permission.AGENTS_BENEFICIARY_VIEW,
+    Permission.AGENTS_BENEFICIARY_MANAGE,
+    Permission.AGENTS_CARD_ISSUE,
+    Permission.AGENTS_CHAT_VIEW,
+    Permission.AGENTS_CHAT_SEND,
+    Permission.AGENTS_NOTIFICATION_SEND,
+    Permission.AGENTS_EXPORT_RUN,
+    Permission.AGENTS_CATALOG_VIEW,
+    Permission.AGENTS_GROUP_MANAGE,
+    Permission.AGENTS_GROUP_USER_MANAGE,
+    // Append-only: nuevo permiso agregado 2026-06-18 (DEC-A2-02). Va al FINAL para no correr los bits
+    // existentes (PERMS_VERSION cambia, pero los índices previos se conservan).
+    Permission.AGENTS_PERSON_CREATE,
+    // Append-only 2026-06-18 (DEC-RBAC-017): catálogo de campos personalizados por tenant. Al FINAL para
+    // no correr bits existentes. (El bitset está deprecado por token-flaco, pero el orden se mantiene
+    // sincronizado con el enum para que el test de bits no rompa.)
+    Permission.PLATFORM_TENANT_USERFIELDS_MANAGE,
+    // Append-only 2026-06-21: gate de acceso a la app web de Agents (gobernanza). Al FINAL para no
+    // correr bits existentes (PERMS_VERSION cambia, pero los índices previos se conservan).
+    Permission.AGENTS_APP_ACCESS,
+    // Append-only 2026-06-19: lateral platform (platform_super_admin asigna roles scope PLATFORM).
+    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
+    Permission.PLATFORM_USER_CREATE_LATERAL,
+    // Append-only 2026-06-24 (DEC-RBAC-036): gate dedicada de gestión de aplicaciones (plantillas).
+    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
+    Permission.PLATFORM_APPLICATION_MANAGE,
+    // Append-only 2026-06-24 (DEC-RBAC-038): gestión de scope-entities de nivel genérico (scope-bound).
+    // Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
+    Permission.TENANT_LEVEL_MANAGE,
+    // Append-only 2026-06-25 (DEC-RBAC-050): edición del autoregistro self-service del tenant (allowlist
+    // anti-escalación). Al FINAL para no correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
+    Permission.PLATFORM_TENANT_AUTOREGISTER_MANAGE,
+    // Append-only 2026-06-28 (DEC-RBAC-063): 36 primitivas RBAC por nivel genérico. Al FINAL para no
+    // correr bits existentes (PERMS_VERSION cambia, índices previos se conservan).
+    Permission.LEVEL1_USER_CREATE,
+    Permission.LEVEL1_USER_READ,
+    Permission.LEVEL1_USER_UPDATE,
+    Permission.LEVEL1_USER_DELETE,
+    Permission.LEVEL1_ROLE_CREATE,
+    Permission.LEVEL1_ROLE_LIST,
+    Permission.LEVEL1_ROLE_VIEW,
+    Permission.LEVEL1_ROLE_UPDATE,
+    Permission.LEVEL1_ROLE_DELETE,
+    Permission.LEVEL1_ROLE_ASSIGN,
+    Permission.LEVEL1_ROLE_REVOKE,
+    Permission.LEVEL1_AUDIT_VIEW,
+    Permission.LEVEL2_USER_CREATE,
+    Permission.LEVEL2_USER_READ,
+    Permission.LEVEL2_USER_UPDATE,
+    Permission.LEVEL2_USER_DELETE,
+    Permission.LEVEL2_ROLE_CREATE,
+    Permission.LEVEL2_ROLE_LIST,
+    Permission.LEVEL2_ROLE_VIEW,
+    Permission.LEVEL2_ROLE_UPDATE,
+    Permission.LEVEL2_ROLE_DELETE,
+    Permission.LEVEL2_ROLE_ASSIGN,
+    Permission.LEVEL2_ROLE_REVOKE,
+    Permission.LEVEL2_AUDIT_VIEW,
+    Permission.LEVEL3_USER_CREATE,
+    Permission.LEVEL3_USER_READ,
+    Permission.LEVEL3_USER_UPDATE,
+    Permission.LEVEL3_USER_DELETE,
+    Permission.LEVEL3_ROLE_CREATE,
+    Permission.LEVEL3_ROLE_LIST,
+    Permission.LEVEL3_ROLE_VIEW,
+    Permission.LEVEL3_ROLE_UPDATE,
+    Permission.LEVEL3_ROLE_DELETE,
+    Permission.LEVEL3_ROLE_ASSIGN,
+    Permission.LEVEL3_ROLE_REVOKE,
+    Permission.LEVEL3_AUDIT_VIEW,
+] as const;
+
+function djb2(input: string): number {
+    let h = 5381;
+    for (let i = 0; i < input.length; i++) h = ((h << 5) + h + input.charCodeAt(i)) >>> 0;
+    return h;
+}
+/** Versión del catálogo = hash del orden. Cambia solo si el orden cambia. */
+export const PERMS_VERSION: number = djb2(PERMISSION_BIT_ORDER.join('|'));
+
+const BIT_INDEX: ReadonlyMap<Permission, number> = new Map(PERMISSION_BIT_ORDER.map((p, i) => [p, i]));
+
+/** Comprime un set de permisos a bitset base64url. */
+export function permissionsToBits(perms: readonly Permission[]): string {
+    const bytes = new Uint8Array(Math.ceil(PERMISSION_BIT_ORDER.length / 8));
+    for (const p of perms) {
+        const idx = BIT_INDEX.get(p);
+        if (idx === undefined) continue;
+        bytes[idx >> 3] |= 1 << (idx & 7);
+    }
+    return Buffer.from(bytes).toString('base64url');
+}
+/** Decodifica un bitset base64url a la lista de permisos. Tolerante a basura → []. */
+export function bitsToPermissions(bits: string): Permission[] {
+    if (typeof bits !== 'string' || bits.length === 0) return [];
+    let bytes: Buffer;
+    try {
+        bytes = Buffer.from(bits, 'base64url');
+    } catch {
+        return [];
+    }
+    const out: Permission[] = [];
+    for (let i = 0; i < PERMISSION_BIT_ORDER.length; i++) {
+        const byte = bytes[i >> 3] ?? 0;
+        if (byte & (1 << (i & 7))) out.push(PERMISSION_BIT_ORDER[i]);
+    }
+    return out;
+}