@fiado/type-kit 3.71.0 → 3.73.0

package/docs/superpowers/specs/2026-05-22-inversify-v8-migration-design.md

@@ -0,0 +1,191 @@
+# Migración a inversify v8 (última) con soporte gradual de lambdas en v6
+
+Fecha: 2026-05-22
+Estado: diseño aprobado (estrategia), pendiente de revisión del spec
+Versión objetivo: inversify **8.x** (la última, hoy 8.1.0). Se salta v7; se va de v6 directo a v8.
+
+## 1. Contexto y objetivo
+
+Las libs compartidas (`@fiado/api-invoker`, `@fiado/gateway-adapter`,
+`@fiado/http-client`) dependen hoy de `inversify ^6.x` como dependencia normal.
+122 repos de lambdas las consumen y todos declaran `inversify` directamente,
+repartidos entre el major 1 (~80 repos, `^1.x`) y el major 3 (~30, `^3.x`).
+Las libs se publican a npm público (`registry.npmjs.org`).
+
+**Objetivo:** subir las libs a inversify 8 y migrar las 122 lambdas **de forma
+gradual**, manteniendo las lambdas no migradas funcionando en inversify 6,
+incluyendo la capacidad de sacar hotfixes a las libs para esas lambdas v6.
+
+## 2. Restricciones técnicas (la causa raíz)
+
+- **La DI cruza la frontera lib↔lambda.** Cada lambda hace
+  `const c = new Container(); c.load(gatewayAdapterBindings); c.load(apiInvokerBindings)`
+  y además `c.bind("IHttpRequest").to(AxiosHttpRequest)`. Los `ContainerModule`
+  y las clases `@injectable` viajan desde la lib al container de la lambda.
+- **Consecuencia:** el `ContainerModule`/decoradores producidos por la lib y el
+  `Container` de la lambda **deben ser de la misma versión de inversify**.
+  inversify 6 y 8 no se pueden mezclar en un mismo container (cambian la firma
+  del callback de `ContainerModule`, se elimina el namespace `interfaces`, y
+  cambian APIs de binding). Por eso **no existe una sola versión de lib que
+  sirva para ambos** sin un shim frágil.
+- **Atomicidad de la migración por lambda:** una lambda no puede mezclar
+  `gateway-adapter` v6 con `api-invoker` v8. Debe subir **en un solo PR**:
+  `inversify` 6→8 + el set completo de libs que tocan su container
+  (`api-invoker`, `gateway-adapter`, `http-client`).
+- **Ciclo entre libs:** `gateway-adapter` depende de `api-invoker` y
+  `api-invoker` depende de `gateway-adapter`. No se pueden publicar "uno a la
+  vez"; sus majors nuevos se publican coordinados (ver §5).
+- **Libs sin inversify:** `logger` y `type-kit` no usan el container ni
+  decoradores → **no se tocan** en esta migración.
+
+## 3. Estrategia elegida: majors paralelos (dual-track)
+
+Sacar un **major nuevo** de cada lib del set, construido sobre inversify 8.
+Los majors v6 actuales quedan como **línea de mantenimiento** para backports.
+Cada lambda migra cuando le toca, en un PR atómico. Cada container en runtime
+ve **una sola** versión de inversify.
+
+Líneas resultantes por lib (los majors de NUESTRAS libs son independientes del
+número de versión de inversify):
+
+| Lib            | Línea v6 (mantenimiento) | Línea v8 (nueva)     |
+|----------------|--------------------------|----------------------|
+| http-client    | 1.x                      | 2.0.0                |
+| gateway-adapter| 1.x                      | 2.0.0                |
+| api-invoker    | 3.x                      | 4.0.0                |
+| logger         | —  (sin cambio)          | —                    |
+| type-kit       | —  (sin cambio)          | —                    |
+
+(Estrategias descartadas: desacoplar las libs de inversify por completo —
+refactor enorme incompatible con "gradual"; peerDependency + shim dual-API —
+frágil por las diferencias de API entre v6 y v8.)
+
+## 4. Breaking changes confirmados (v6 → v8)
+
+Verificado contra las guías oficiales ([migrating-from-v6](https://inversify.io/docs/guides/migrating-from-v6/)
+y [migrating-from-v7](https://inversify.io/docs/guides/migrating-from-v7/)).
+Lo que toca este código:
+
+1. **`ContainerModule`**: el callback recibe ahora un objeto
+   `ContainerModuleLoadOptions`; se usa `options.bind(...)`. Afecta
+   `apiInvokerBindings` y `gatewayAdapterBindings`.
+   ```ts
+   // v6
+   export const apiInvokerBindings = new ContainerModule((bind: interfaces.Bind) => {
+     bind<IDirectoryApi>("IDirectoryApi").to(DirectoryApi);
+   });
+   // v8
+   export const apiInvokerBindings = new ContainerModule((options) => {
+     options.bind<IDirectoryApi>("IDirectoryApi").to(DirectoryApi);
+   });
+   ```
+2. **Namespace `interfaces` eliminado**: importar los tipos directamente.
+   `interfaces.Context → ResolutionContext`, `interfaces.Factory → Factory`,
+   `interfaces.Newable → Newable`, `interfaces.Request → BindingConstraints`.
+   Afecta `import { ContainerModule, interfaces } from "inversify"`.
+3. **`toAutoFactory` eliminado** → reescribir con `toFactory`:
+   ```ts
+   // v6 (auth-business)
+   .toAutoFactory("EventBridgeMessageSubscriber")
+   // v8
+   .toFactory((ctx) => () => ctx.get("EventBridgeMessageSubscriber"))
+   ```
+   También: `toProvider → toFactory` (con función async),
+   `toConstructor → toConstantValue`, `toFunction → toConstantValue`.
+4. **`container.load()` SIGUE SIENDO SÍNCRONO en v8** (convención "sync-first":
+   el nombre por defecto es sync, el async es `loadAsync()`). Como nuestros
+   módulos de binding son síncronos, **el patrón `const container = new
+   Container(); container.load(...); export { container }` se conserva** — NO
+   hay que volverlo async. (En v7 sí era async; v8 lo revirtió, a nuestro favor.)
+   `container.get()` también sigue síncrono.
+5. **Opciones del `Container`**: `autoBindInjectable → autobind`;
+   `container.createChild()` → `new Container({ parent })`. Revisar usos.
+6. **`@injectable`/`@inject` sin cambios**; nuevo `@injectFromBase` solo si una
+   clase hereda de una base injectable (revisar herencia).
+7. **inversify 8 es ESM-only**, pero proyectos CommonJS lo consumen vía
+   `require(esm)` en **Node 20+**. ⇒ todas las lambdas deben correr en runtime
+   **Node 20.x o superior**. Verificar el runtime de cada lambda antes de migrar.
+
+Entregable de esta fase: un **codemod / guía** reproducible para
+`container.config.ts` (reescritura de `toAutoFactory`, import de `interfaces`,
+firma de `ContainerModule`), ya que el patrón se repite en las 122 lambdas.
+
+## 5. Orden de trabajo en las libs (un proyecto a la vez)
+
+Para cada lib, antes de tocar: `git checkout develop && git pull`.
+
+1. **http-client** (hoja, solo `@injectable` en `AxiosHttpRequest`):
+   migrar a v8, publicar **2.0.0**. dist-tag `latest` → 2.x, `legacy-v6` → 1.x.
+2. **gateway-adapter + api-invoker** (ciclo): migrar el código de ambos a v8 en
+   ramas, desarrollando con enlaces locales (`npm link` / `file:`) para que
+   compilen uno contra otro. Publicar coordinado con prerelease:
+   - `gateway-adapter@2.0.0-rc.0` con dep `@fiado/api-invoker@^4.0.0-rc`
+   - `api-invoker@4.0.0-rc.0` con dep `@fiado/gateway-adapter@^2.0.0-rc`
+   - validar en 1 lambda piloto, luego promover a `2.0.0` / `4.0.0` finales.
+3. **logger / type-kit**: sin cambios.
+
+> **Publicación en espera:** no se publica ninguna lib a npm hasta terminar los
+> cambios y tener el visto bueno explícito del usuario.
+
+## 6. Política de branching y backport (soporte v6)
+
+- Cortar una rama de mantenimiento por línea v6 en el último release v6:
+  `release/3.x` en api-invoker (desde 3.18.0), `release/1.x` en
+  gateway-adapter y http-client. `develop` pasa a ser la línea v8.
+- **Hotfix que toca una lib mientras una lambda sigue en v6:**
+  1. El fix se hace en la línea natural y se hace `git cherry-pick` a la otra.
+     La mayoría de hotfixes (lógica de negocio, no inversify) tienen archivos
+     idénticos entre líneas → cherry-pick limpio.
+  2. Publicar patch en la línea v6 (ej. `3.18.1`) y, si aplica, en la nueva.
+  3. La lambda v6 (pineada `^3.x`) hace `npm update` y recibe el fix: cero
+     cambio de inversify, cero cambio en su `container.config.ts`.
+- **Disciplina clave:** mantener el major nuevo como un **diff quirúrgico** sobre
+  v6 (tocar solo archivos que tocan inversify) para que los cherry-picks no
+  choquen.
+- **Ventana de soporte:** se backportea **solo al último major v6** (api-invoker
+  3.x). Las ~80 lambdas aún en `^1.x` deben consolidarse a `^3` como parte de
+  (o antes de) la migración, porque hoy ya no pueden recibir fixes limpios.
+
+## 7. Playbook de migración por lambda (gradual)
+
+Por cada lambda, en un PR atómico:
+
+1. `inversify` 6→8 y `reflect-metadata` a la versión alineada.
+2. Subir el set de libs nuevas: `api-invoker` `^4`, `gateway-adapter` `^2`,
+   `http-client` `^2`.
+3. Aplicar el codemod/guía a `container.config.ts`: reescribir `toAutoFactory`
+   → `toFactory`, ajustar imports del namespace `interfaces`. El patrón
+   síncrono `export { container }` **no cambia** (load/get siguen sync en v8).
+4. Verificar que el runtime de la lambda sea **Node ≥20** (inversify 8 ESM-only).
+5. Correr tests + smoke test del handler. Merge y deploy.
+
+Las lambdas no migradas siguen en v6 sin cambios.
+
+## 8. Riesgos
+
+- **Divergencia de líneas v6/v8** si el major nuevo refactoriza de más →
+  mitigado con el "diff quirúrgico".
+- **Ciclo api-invoker↔gateway-adapter** en el publish → mitigado con prerelease
+  rc + dist-tags.
+- **Cola de migración larga** (122 lambdas) → mantener línea v6 viva y priorizar
+  consolidar los `^1.x` a `^3.x`.
+- **Runtime Node <20**: inversify 8 es ESM-only; lambdas en Node 18 o menor no
+  podrán hacer `require(esm)`. Mitigación: auditar y subir a Node 20+ el runtime
+  de cada lambda como prerrequisito de su PR de migración.
+- **Saltar v7→v8 directo** acumula breaking changes; mitigado validando lib por
+  lib con su smoke test antes de avanzar. (El cambio más riesgoso de v7 —`load`
+  async— quedó revertido en v8, así que el bootstrap síncrono se conserva.)
+
+## 9. Criterios de éxito
+
+- http-client@2, gateway-adapter@2, api-invoker@4 construidos sobre inversify 8
+  y validados en 1 lambda piloto (publicación pendiente de visto bueno).
+- Línea v6 (`release/*`) capaz de recibir y publicar un hotfix backporteado.
+- Guía/codemod de `container.config.ts` documentada y reutilizable.
+- Lambdas no migradas siguen desplegando sin cambios.
+
+## Seguridad (fuera de alcance, pero a atender)
+
+`fiado-api-invoker/.npmrc` contiene un token de publicación de npm en texto
+plano. Si está versionado, debe **revocarse/rotarse** en npmjs.com y moverse a
+una variable de entorno / secret de CI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.71.0",
+  "version": "3.73.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/platformRbac/dtos/CreateTenantRequest.ts

@@ -1,5 +1,6 @@
 import { Expose } from 'class-transformer';
-import { IsBoolean, IsEmail, IsInt, IsOptional, IsString, Matches, Min } from 'class-validator';
+import { IsBoolean, IsEmail, IsEnum, IsInt, IsOptional, IsString, Matches, Min } from 'class-validator';
+import { TokenValidationMode } from '../enums/TokenValidationMode';
 
 /**
  * Input del POST backoffice de creación de tenant (F-11 — onboarding de tenant en SureKeep).
@@ -17,4 +18,5 @@ export class CreateTenantRequest {
     @Expose() @IsString() region!: string;
     @Expose() @IsOptional() @IsBoolean() mfaRequired?: boolean;
     @Expose() @IsOptional() @IsInt() @Min(8) passwordMinLength?: number;
+    @Expose() @IsOptional() @IsEnum(TokenValidationMode) tokenValidationMode?: TokenValidationMode;
 }

package/src/platformRbac/enums/Permission.ts

@@ -6,7 +6,25 @@
  *
  * Copy-paste literal de los valores del spec (DEC-003).
  * Convención: `<category>.<resource>.<action>` (snake_case en action si multi-palabra).
- * Cualquier cambio aquí requiere PR + bump minor + redeploy de consumers.
+ *
+ * ⚠️ 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.
  */
@@ -143,6 +161,11 @@ export enum Permission {
  * Í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,

package/src/platformRbac/enums/TokenValidationMode.ts

@@ -0,0 +1,13 @@
+/**
+ * Modo de validación de tokens por tenant (DEC-RBAC-002 del rbac-authorizer-trigger).
+ * Persistido como atributo no-key en PlatformTenantConfig_GT. Los valores string SON el
+ * contrato: el authorizer los espeja con un tipo local (no depende de type-kit, DT-7).
+ * - OFFLINE: solo firma (JWKS) + permsEpoch. Default. No pega a Cognito.
+ * - ONLINE_PREFERRED: AdminGetUser; negativo definitivo → Deny; fallo de infra → cae a offline.
+ * - ONLINE_STRICT: AdminGetUser; negativo definitivo O fallo de infra → Deny (fail-closed, regulado).
+ */
+export enum TokenValidationMode {
+    OFFLINE = 'offline',
+    ONLINE_PREFERRED = 'online_preferred',
+    ONLINE_STRICT = 'online_strict',
+}

package/src/platformRbac/index.ts

@@ -26,6 +26,7 @@ export type { EffectivePermissionsResponse } from './dtos/EffectivePermissionsRe
 // Fase 1 — Custom Auth Challenge (Email OTP + TOTP) + MFA self-service.
 // Class values (no type-only) — los DTOs llevan decoradores class-validator y se hidratan con plainToInstance en runtime.
 export * from './enums/MfaMethodEnum';
+export * from './enums/TokenValidationMode';
 export * from './enums/ChallengeNameEnum';
 export * from './auth/DefineNextChallengeRequest';
 export * from './auth/DefineNextChallengeResponse';

package/src/riskProfile/dtos/TransactionAlarmQueueMessage.ts

@@ -1,5 +1,6 @@
 import { IsNotEmpty, IsNumber, IsOptional, IsString } from "class-validator";
 import { OperationEnum } from "../../transaction";
+import { ProductSubtypeEnum } from "../../productCatalog";
 
 
 
@@ -37,6 +38,10 @@ export class TransactionAlarmQueueMessage {
     @IsNotEmpty()
     transactionType: string
 
+    @IsString()
+    @IsOptional()
+    subType?: ProductSubtypeEnum
+
     @IsString()
     @IsNotEmpty()
     id: string