@fiado/type-kit 3.293.0 → 3.295.0

package/_test_/unit/platformRbac/enums/__snapshots__/permissionBits.test.ts.snap

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`PERMISSION_BIT_ORDER PERMS_VERSION es número estable 1`] = `1018014330`;
+exports[`PERMISSION_BIT_ORDER PERMS_VERSION es número estable 1`] = `3833769424`;
 
 exports[`PERMISSION_BIT_ORDER append-only: snapshot del ORDEN COMPLETO (rompe ante cualquier reorden/inserción) 1`] = `
 [
@@ -90,5 +90,10 @@ exports[`PERMISSION_BIT_ORDER append-only: snapshot del ORDEN COMPLETO (rompe an
   "level3.role.assign",
   "level3.role.revoke",
   "level3.audit.view",
+  "platform.integration.view",
+  "platform.integration.manage",
+  "platform.integration.key.issue",
+  "platform.integration.key.revoke",
+  "tenant.integration.diagnostic",
 ]
 `;

package/bin/emailVerification/dtos/internal/EmailStartByDirectoryRequest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Request interno (api-invoker) para registrar un email y disparar su verificación.
+ * `directoryId` es @IsString (cognitoSub UUID v7 — no usar @IsUUID).
+ */
+export declare class EmailStartByDirectoryRequest {
+    directoryId: string;
+    email: string;
+    /** Nombre para el saludo del correo. Default "Cliente". */
+    name?: string;
+}

package/bin/emailVerification/dtos/internal/EmailStartByDirectoryRequest.js

@@ -0,0 +1,37 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailStartByDirectoryRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Request interno (api-invoker) para registrar un email y disparar su verificación.
+ * `directoryId` es @IsString (cognitoSub UUID v7 — no usar @IsUUID).
+ */
+class EmailStartByDirectoryRequest {
+}
+exports.EmailStartByDirectoryRequest = EmailStartByDirectoryRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryRequest.prototype, "directoryId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryRequest.prototype, "email", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryRequest.prototype, "name", void 0);

package/bin/emailVerification/dtos/internal/EmailStartByDirectoryResponse.d.ts

@@ -0,0 +1,9 @@
+import { EmailVerificationStatusEnum } from '../../enums/EmailVerificationStatusEnum';
+/**
+ * Response interno del alta + disparo de verificación de un email por directorio.
+ */
+export declare class EmailStartByDirectoryResponse {
+    email: string;
+    verificationId: string;
+    status: EmailVerificationStatusEnum;
+}

package/bin/emailVerification/dtos/internal/EmailStartByDirectoryResponse.js

@@ -0,0 +1,32 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailStartByDirectoryResponse = void 0;
+const class_transformer_1 = require("class-transformer");
+const EmailVerificationStatusEnum_1 = require("../../enums/EmailVerificationStatusEnum");
+/**
+ * Response interno del alta + disparo de verificación de un email por directorio.
+ */
+class EmailStartByDirectoryResponse {
+}
+exports.EmailStartByDirectoryResponse = EmailStartByDirectoryResponse;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryResponse.prototype, "email", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryResponse.prototype, "verificationId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    __metadata("design:type", String)
+], EmailStartByDirectoryResponse.prototype, "status", void 0);

package/bin/emailVerification/index.d.ts

@@ -17,3 +17,5 @@ export * from './dtos/internal/PrimaryEmailByDirectoryRequest';
 export * from './dtos/internal/PrimaryEmailResponse';
 export * from './dtos/internal/EmailsByDirectoryRequest';
 export * from './dtos/internal/EmailsByDirectoryResponse';
+export * from './dtos/internal/EmailStartByDirectoryRequest';
+export * from './dtos/internal/EmailStartByDirectoryResponse';

package/bin/emailVerification/index.js

@@ -33,3 +33,5 @@ __exportStar(require("./dtos/internal/PrimaryEmailByDirectoryRequest"), exports)
 __exportStar(require("./dtos/internal/PrimaryEmailResponse"), exports);
 __exportStar(require("./dtos/internal/EmailsByDirectoryRequest"), exports);
 __exportStar(require("./dtos/internal/EmailsByDirectoryResponse"), exports);
+__exportStar(require("./dtos/internal/EmailStartByDirectoryRequest"), exports);
+__exportStar(require("./dtos/internal/EmailStartByDirectoryResponse"), exports);

package/bin/platformRbac/dtos/CreateIntegrationRequest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Body del POST /platform/tenants/{tenantId}/integrations. `tenantId` viaja en el path.
+ *
+ * Da de alta una integración M2M con un socio externo (DEC-RBAC-120/121). Los datos son del tenant
+ * pero **solo un usuario de plataforma** puede crearla.
+ *
+ * `roleId` es un rol del silo del tenant, elegido de los que ya existen — no se siembra uno
+ * especial. Está sujeto a las guardas anti-escalada: no puede contener permisos de administración
+ * de integraciones ni calcular scope PLATFORM (DEC-RBAC-122/126).
+ *
+ * `ipAllowlist` es OPCIONAL y su semántica es permisiva (spec §5): ausente, vacía o `['*']` ⇒ sin
+ * restricción de IP. Que se pueda apagar es deliberado; que se apague en silencio, no — por eso la
+ * pantalla marca las integraciones sin restricción.
+ */
+export declare class CreateIntegrationRequest {
+    displayName: string;
+    roleId: string;
+    ipAllowlist?: string[];
+    /** cognitoSub del operador real (audit + grantedBy del assignment). */
+    createdBy: string;
+}

package/bin/platformRbac/dtos/CreateIntegrationRequest.js

@@ -0,0 +1,57 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateIntegrationRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Body del POST /platform/tenants/{tenantId}/integrations. `tenantId` viaja en el path.
+ *
+ * Da de alta una integración M2M con un socio externo (DEC-RBAC-120/121). Los datos son del tenant
+ * pero **solo un usuario de plataforma** puede crearla.
+ *
+ * `roleId` es un rol del silo del tenant, elegido de los que ya existen — no se siembra uno
+ * especial. Está sujeto a las guardas anti-escalada: no puede contener permisos de administración
+ * de integraciones ni calcular scope PLATFORM (DEC-RBAC-122/126).
+ *
+ * `ipAllowlist` es OPCIONAL y su semántica es permisiva (spec §5): ausente, vacía o `['*']` ⇒ sin
+ * restricción de IP. Que se pueda apagar es deliberado; que se apague en silencio, no — por eso la
+ * pantalla marca las integraciones sin restricción.
+ */
+class CreateIntegrationRequest {
+}
+exports.CreateIntegrationRequest = CreateIntegrationRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateIntegrationRequest.prototype, "displayName", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateIntegrationRequest.prototype, "roleId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsString)({ each: true }),
+    __metadata("design:type", Array)
+], CreateIntegrationRequest.prototype, "ipAllowlist", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateIntegrationRequest.prototype, "createdBy", void 0);

package/bin/platformRbac/dtos/IntegrationKeyResponse.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Estado de una llave. NO existe `ROTATING`: rotar es emitir una segunda llave y revocar la vieja,
+ * con las dos activas mientras dura la migración del socio.
+ */
+export type IntegrationKeyStatusValue = 'ACTIVE' | 'REVOKED';
+/**
+ * Una llave, tal como la devuelve el listado.
+ *
+ * 🔴 **NUNCA lleva el secreto ni el `secretHash`.** El secreto en claro se devuelve exactamente una
+ * vez, en la respuesta del POST que lo emite (`IssueIntegrationKeyResponse`), y no existe ningún
+ * endpoint que lo lea de vuelta.
+ *
+ * `lastUsedAt` y `lastUsedIp` los escribe el authorizer W5, con throttle: sirven para detectar una
+ * integración que dejó de llamar, que es uno de los dos incidentes clásicos de un canal M2M.
+ */
+export interface IntegrationKeyResponse {
+    keyId: string;
+    integrationId: string;
+    status: IntegrationKeyStatusValue;
+    /** epoch ms. Ausente = no vence. */
+    expiresAt?: number;
+    lastUsedAt?: number;
+    lastUsedIp?: string;
+    createdAt: number;
+    createdBy?: string;
+    revokedAt?: number;
+    revokedBy?: string;
+}
+/**
+ * Respuesta del POST que emite una llave. **El único lugar de todo el sistema donde el secreto
+ * viaja en claro.**
+ *
+ * Quien lo consuma tiene que mostrarlo una sola vez y no persistirlo: no hay forma de recuperarlo
+ * después, porque en base solo queda su hash. Si se pierde, se emite otra llave.
+ */
+export interface IssueIntegrationKeyResponse extends IntegrationKeyResponse {
+    /** `fdo_sk.<keyId>.<secreto>` — se muestra UNA vez y no se vuelve a poder leer. */
+    token: string;
+}

package/bin/platformRbac/dtos/IntegrationKeyResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/platformRbac/dtos/IntegrationResponse.d.ts

@@ -0,0 +1,25 @@
+/** Estado de una integración. Suspender corta TODAS sus llaves de una. */
+export type IntegrationStatusValue = 'ACTIVE' | 'SUSPENDED';
+/**
+ * Una integración, tal como la devuelven el GET de detalle y el listado.
+ *
+ * NO lleva nada del secreto de sus llaves — ni el valor ni el hash. Para eso está
+ * `IntegrationKeyResponse`, que tampoco los lleva.
+ */
+export interface IntegrationResponse {
+    integrationId: string;
+    tenantId: string;
+    displayName: string;
+    status: IntegrationStatusValue;
+    /** Rol del silo que porta esta integración. */
+    roleId: string;
+    /**
+     * CIDRs permitidos. Vacío o `['*']` ⇒ **sin restricción de IP** (spec §5).
+     * El front lo marca visiblemente en la lista: la protección se puede apagar, pero no en silencio.
+     */
+    ipAllowlist: string[];
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+    updatedBy?: string;
+}

package/bin/platformRbac/dtos/IntegrationResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/platformRbac/dtos/IntegrationWhoamiResponse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Respuesta del endpoint de diagnóstico del authorizer W5.
+ *
+ * Devuelve **el principal ya resuelto**, no un "ok". Eso es lo que lo hace útil como prueba de la
+ * cadena completa: no verifica que el request pase, sino que haya resuelto como quien debía —
+ * con el tenant correcto y con los permisos que su rol otorga.
+ *
+ * 🔴 Endpoint TEMPORAL, solo dev: expone la lista de permisos del principal. Se saca antes de
+ * producción (el permiso `tenant.integration.diagnostic` en cambio se queda, marcado deprecado:
+ * quitarlo del enum rompería la cobertura bidireccional del catálogo y dejaría
+ * `UnknownPermissionError` en cualquier rol ya sembrado con él).
+ */
+export interface IntegrationWhoamiResponse {
+    principalType: 'INTEGRATION';
+    /** Con prefijo `INT#`. */
+    principalId: string;
+    integrationId: string;
+    tenantId: string;
+    /** Los permisos que resolvió el RBAC para este principal — el punto de la prueba. */
+    permissions: string[];
+}

package/bin/platformRbac/dtos/IntegrationWhoamiResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/platformRbac/dtos/UpdateIntegrationRequest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Body del PUT /platform/tenants/{tenantId}/integrations/{integrationId}.
+ *
+ * ⚠️ **Semántica de MERGE, no de reemplazo**: solo se actualiza lo que venga. Un campo ausente se
+ * deja como está, NO se borra.
+ *
+ * Es PUT y no PATCH porque `PATCH` no existe en este stack — el enum `HttpMethod` del
+ * `@fiado/gateway-adapter` tiene GET/POST/PUT/DELETE, y el CORS y los `GatewayResponses` tampoco lo
+ * listan. Mismo precedente que `backofficeUpdateTenantUserField`.
+ *
+ * El merge no es cosmético: con reemplazo total, un body que omitiera `ipAllowlist` la borraría, y
+ * eso apagaría el filtro por IP de la integración sin que nadie lo pidiera.
+ */
+export declare class UpdateIntegrationRequest {
+    displayName?: string;
+    ipAllowlist?: string[];
+    updatedBy: string;
+}

package/bin/platformRbac/dtos/UpdateIntegrationRequest.js

@@ -0,0 +1,51 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateIntegrationRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Body del PUT /platform/tenants/{tenantId}/integrations/{integrationId}.
+ *
+ * ⚠️ **Semántica de MERGE, no de reemplazo**: solo se actualiza lo que venga. Un campo ausente se
+ * deja como está, NO se borra.
+ *
+ * Es PUT y no PATCH porque `PATCH` no existe en este stack — el enum `HttpMethod` del
+ * `@fiado/gateway-adapter` tiene GET/POST/PUT/DELETE, y el CORS y los `GatewayResponses` tampoco lo
+ * listan. Mismo precedente que `backofficeUpdateTenantUserField`.
+ *
+ * El merge no es cosmético: con reemplazo total, un body que omitiera `ipAllowlist` la borraría, y
+ * eso apagaría el filtro por IP de la integración sin que nadie lo pidiera.
+ */
+class UpdateIntegrationRequest {
+}
+exports.UpdateIntegrationRequest = UpdateIntegrationRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpdateIntegrationRequest.prototype, "displayName", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsString)({ each: true }),
+    __metadata("design:type", Array)
+], UpdateIntegrationRequest.prototype, "ipAllowlist", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpdateIntegrationRequest.prototype, "updatedBy", void 0);

package/bin/platformRbac/enums/Permission.d.ts

@@ -114,7 +114,12 @@ export declare enum Permission {
     LEVEL3_ROLE_DELETE = "level3.role.delete",
     LEVEL3_ROLE_ASSIGN = "level3.role.assign",
     LEVEL3_ROLE_REVOKE = "level3.role.revoke",
-    LEVEL3_AUDIT_VIEW = "level3.audit.view"
+    LEVEL3_AUDIT_VIEW = "level3.audit.view",
+    PLATFORM_INTEGRATION_VIEW = "platform.integration.view",
+    PLATFORM_INTEGRATION_MANAGE = "platform.integration.manage",
+    PLATFORM_INTEGRATION_KEY_ISSUE = "platform.integration.key.issue",
+    PLATFORM_INTEGRATION_KEY_REVOKE = "platform.integration.key.revoke",
+    TENANT_INTEGRATION_DIAGNOSTIC = "tenant.integration.diagnostic"
 }
 /**
  * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.

package/bin/platformRbac/enums/Permission.js

@@ -149,6 +149,21 @@ var Permission;
     Permission["LEVEL3_ROLE_ASSIGN"] = "level3.role.assign";
     Permission["LEVEL3_ROLE_REVOKE"] = "level3.role.revoke";
     Permission["LEVEL3_AUDIT_VIEW"] = "level3.audit.view";
+    // Append-only 2026-08-10 (DEC-RBAC-120/121/126): integraciones M2M con socios externos.
+    // Los cuatro de ADMINISTRACIÓN son scope PLATFORM: los datos de la integración son del tenant,
+    // pero solo un usuario de plataforma la crea, rota o revoca. Son además el set exacto que la
+    // guarda 1 prohíbe asignarle a un principal `INT#` — una integración jamás puede administrarse
+    // a sí misma.
+    Permission["PLATFORM_INTEGRATION_VIEW"] = "platform.integration.view";
+    Permission["PLATFORM_INTEGRATION_MANAGE"] = "platform.integration.manage";
+    Permission["PLATFORM_INTEGRATION_KEY_ISSUE"] = "platform.integration.key.issue";
+    Permission["PLATFORM_INTEGRATION_KEY_REVOKE"] = "platform.integration.key.revoke";
+    // DEC-RBAC-126: el endpoint de diagnóstico del authorizer W5 lo llama la INTEGRACIÓN, no un
+    // humano — y una integración NUNCA puede portar permisos de scope PLATFORM (computeRoleScope
+    // toma el MAX de los scopes del rol, así que uno solo lo volvería PLATFORM con scopeRef '*').
+    // Por eso este es TENANT-scoped. Y por eso NO entra en el set de la guarda 1: no administra
+    // nada, solo devuelve quién sos.
+    Permission["TENANT_INTEGRATION_DIAGNOSTIC"] = "tenant.integration.diagnostic";
 })(Permission || (exports.Permission = Permission = {}));
 /**
  * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.
@@ -261,6 +276,13 @@ exports.PERMISSION_BIT_ORDER = [
     Permission.LEVEL3_ROLE_ASSIGN,
     Permission.LEVEL3_ROLE_REVOKE,
     Permission.LEVEL3_AUDIT_VIEW,
+    // Append-only 2026-08-10 (DEC-RBAC-120/126): integraciones M2M. Van AL FINAL y en este orden,
+    // nunca intercalados: reordenar desalinearía los bits de los tokens ya emitidos.
+    Permission.PLATFORM_INTEGRATION_VIEW,
+    Permission.PLATFORM_INTEGRATION_MANAGE,
+    Permission.PLATFORM_INTEGRATION_KEY_ISSUE,
+    Permission.PLATFORM_INTEGRATION_KEY_REVOKE,
+    Permission.TENANT_INTEGRATION_DIAGNOSTIC,
 ];
 function djb2(input) {
     let h = 5381;

package/bin/platformRbac/index.d.ts

@@ -55,3 +55,8 @@ export * from './dtos/CreateLevelEntityRequest';
 export type { CreateLevelEntityResponse } from './dtos/CreateLevelEntityResponse';
 export * from './dtos/CreateTenantUserRequest';
 export type { CreateTenantUserResponse } from './dtos/CreateTenantUserResponse';
+export * from './dtos/CreateIntegrationRequest';
+export * from './dtos/UpdateIntegrationRequest';
+export type { IntegrationResponse, IntegrationStatusValue } from './dtos/IntegrationResponse';
+export type { IntegrationKeyResponse, IntegrationKeyStatusValue, IssueIntegrationKeyResponse, } from './dtos/IntegrationKeyResponse';
+export type { IntegrationWhoamiResponse } from './dtos/IntegrationWhoamiResponse';

package/bin/platformRbac/index.js

@@ -111,3 +111,7 @@ __exportStar(require("./dtos/SelfRegisterCompleteRequest"), exports);
 // Response son interfaces plain → type-only. Consumidos por retail-org vía api-invoker (Publisher).
 __exportStar(require("./dtos/CreateLevelEntityRequest"), exports);
 __exportStar(require("./dtos/CreateTenantUserRequest"), exports);
+// DEC-RBAC-120/121/126: integraciones M2M con socios externos (API keys como principal del RBAC).
+// Los requests van como clase (class-validator); las responses como tipo.
+__exportStar(require("./dtos/CreateIntegrationRequest"), exports);
+__exportStar(require("./dtos/UpdateIntegrationRequest"), exports);

package/package.json

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

package/src/emailVerification/dtos/internal/EmailStartByDirectoryRequest.ts

@@ -0,0 +1,22 @@
+import { Expose } from 'class-transformer';
+import { IsEmail, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Request interno (api-invoker) para registrar un email y disparar su verificación.
+ * `directoryId` es @IsString (cognitoSub UUID v7 — no usar @IsUUID).
+ */
+export class EmailStartByDirectoryRequest {
+    @Expose()
+    @IsString()
+    directoryId!: string;
+
+    @Expose()
+    @IsEmail()
+    email!: string;
+
+    /** Nombre para el saludo del correo. Default "Cliente". */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    name?: string;
+}

package/src/emailVerification/dtos/internal/EmailStartByDirectoryResponse.ts

@@ -0,0 +1,16 @@
+import { Expose } from 'class-transformer';
+import { EmailVerificationStatusEnum } from '../../enums/EmailVerificationStatusEnum';
+
+/**
+ * Response interno del alta + disparo de verificación de un email por directorio.
+ */
+export class EmailStartByDirectoryResponse {
+    @Expose()
+    email!: string;
+
+    @Expose()
+    verificationId!: string;
+
+    @Expose()
+    status!: EmailVerificationStatusEnum;
+}

package/src/emailVerification/index.ts

@@ -17,3 +17,5 @@ export * from './dtos/internal/PrimaryEmailByDirectoryRequest';
 export * from './dtos/internal/PrimaryEmailResponse';
 export * from './dtos/internal/EmailsByDirectoryRequest';
 export * from './dtos/internal/EmailsByDirectoryResponse';
+export * from './dtos/internal/EmailStartByDirectoryRequest';
+export * from './dtos/internal/EmailStartByDirectoryResponse';

package/src/platformRbac/dtos/CreateIntegrationRequest.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { ArrayNotEmpty, IsArray, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Body del POST /platform/tenants/{tenantId}/integrations. `tenantId` viaja en el path.
+ *
+ * Da de alta una integración M2M con un socio externo (DEC-RBAC-120/121). Los datos son del tenant
+ * pero **solo un usuario de plataforma** puede crearla.
+ *
+ * `roleId` es un rol del silo del tenant, elegido de los que ya existen — no se siembra uno
+ * especial. Está sujeto a las guardas anti-escalada: no puede contener permisos de administración
+ * de integraciones ni calcular scope PLATFORM (DEC-RBAC-122/126).
+ *
+ * `ipAllowlist` es OPCIONAL y su semántica es permisiva (spec §5): ausente, vacía o `['*']` ⇒ sin
+ * restricción de IP. Que se pueda apagar es deliberado; que se apague en silencio, no — por eso la
+ * pantalla marca las integraciones sin restricción.
+ */
+export class CreateIntegrationRequest {
+    @Expose() @IsString() @IsNotEmpty() displayName!: string;
+    @Expose() @IsString() @IsNotEmpty() roleId!: string;
+    @Expose() @IsOptional() @IsArray() @ArrayNotEmpty() @IsString({ each: true }) ipAllowlist?: string[];
+    /** cognitoSub del operador real (audit + grantedBy del assignment). */
+    @Expose() @IsString() @IsNotEmpty() createdBy!: string;
+}

package/src/platformRbac/dtos/IntegrationKeyResponse.ts

@@ -0,0 +1,41 @@
+/**
+ * Estado de una llave. NO existe `ROTATING`: rotar es emitir una segunda llave y revocar la vieja,
+ * con las dos activas mientras dura la migración del socio.
+ */
+export type IntegrationKeyStatusValue = 'ACTIVE' | 'REVOKED';
+
+/**
+ * Una llave, tal como la devuelve el listado.
+ *
+ * 🔴 **NUNCA lleva el secreto ni el `secretHash`.** El secreto en claro se devuelve exactamente una
+ * vez, en la respuesta del POST que lo emite (`IssueIntegrationKeyResponse`), y no existe ningún
+ * endpoint que lo lea de vuelta.
+ *
+ * `lastUsedAt` y `lastUsedIp` los escribe el authorizer W5, con throttle: sirven para detectar una
+ * integración que dejó de llamar, que es uno de los dos incidentes clásicos de un canal M2M.
+ */
+export interface IntegrationKeyResponse {
+    keyId: string;
+    integrationId: string;
+    status: IntegrationKeyStatusValue;
+    /** epoch ms. Ausente = no vence. */
+    expiresAt?: number;
+    lastUsedAt?: number;
+    lastUsedIp?: string;
+    createdAt: number;
+    createdBy?: string;
+    revokedAt?: number;
+    revokedBy?: string;
+}
+
+/**
+ * Respuesta del POST que emite una llave. **El único lugar de todo el sistema donde el secreto
+ * viaja en claro.**
+ *
+ * Quien lo consuma tiene que mostrarlo una sola vez y no persistirlo: no hay forma de recuperarlo
+ * después, porque en base solo queda su hash. Si se pierde, se emite otra llave.
+ */
+export interface IssueIntegrationKeyResponse extends IntegrationKeyResponse {
+    /** `fdo_sk.<keyId>.<secreto>` — se muestra UNA vez y no se vuelve a poder leer. */
+    token: string;
+}

package/src/platformRbac/dtos/IntegrationResponse.ts

@@ -0,0 +1,26 @@
+/** Estado de una integración. Suspender corta TODAS sus llaves de una. */
+export type IntegrationStatusValue = 'ACTIVE' | 'SUSPENDED';
+
+/**
+ * Una integración, tal como la devuelven el GET de detalle y el listado.
+ *
+ * NO lleva nada del secreto de sus llaves — ni el valor ni el hash. Para eso está
+ * `IntegrationKeyResponse`, que tampoco los lleva.
+ */
+export interface IntegrationResponse {
+    integrationId: string;
+    tenantId: string;
+    displayName: string;
+    status: IntegrationStatusValue;
+    /** Rol del silo que porta esta integración. */
+    roleId: string;
+    /**
+     * CIDRs permitidos. Vacío o `['*']` ⇒ **sin restricción de IP** (spec §5).
+     * El front lo marca visiblemente en la lista: la protección se puede apagar, pero no en silencio.
+     */
+    ipAllowlist: string[];
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+    updatedBy?: string;
+}

package/src/platformRbac/dtos/IntegrationWhoamiResponse.ts

@@ -0,0 +1,21 @@
+/**
+ * Respuesta del endpoint de diagnóstico del authorizer W5.
+ *
+ * Devuelve **el principal ya resuelto**, no un "ok". Eso es lo que lo hace útil como prueba de la
+ * cadena completa: no verifica que el request pase, sino que haya resuelto como quien debía —
+ * con el tenant correcto y con los permisos que su rol otorga.
+ *
+ * 🔴 Endpoint TEMPORAL, solo dev: expone la lista de permisos del principal. Se saca antes de
+ * producción (el permiso `tenant.integration.diagnostic` en cambio se queda, marcado deprecado:
+ * quitarlo del enum rompería la cobertura bidireccional del catálogo y dejaría
+ * `UnknownPermissionError` en cualquier rol ya sembrado con él).
+ */
+export interface IntegrationWhoamiResponse {
+    principalType: 'INTEGRATION';
+    /** Con prefijo `INT#`. */
+    principalId: string;
+    integrationId: string;
+    tenantId: string;
+    /** Los permisos que resolvió el RBAC para este principal — el punto de la prueba. */
+    permissions: string[];
+}

package/src/platformRbac/dtos/UpdateIntegrationRequest.ts

@@ -0,0 +1,21 @@
+import { Expose } from 'class-transformer';
+import { ArrayNotEmpty, IsArray, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Body del PUT /platform/tenants/{tenantId}/integrations/{integrationId}.
+ *
+ * ⚠️ **Semántica de MERGE, no de reemplazo**: solo se actualiza lo que venga. Un campo ausente se
+ * deja como está, NO se borra.
+ *
+ * Es PUT y no PATCH porque `PATCH` no existe en este stack — el enum `HttpMethod` del
+ * `@fiado/gateway-adapter` tiene GET/POST/PUT/DELETE, y el CORS y los `GatewayResponses` tampoco lo
+ * listan. Mismo precedente que `backofficeUpdateTenantUserField`.
+ *
+ * El merge no es cosmético: con reemplazo total, un body que omitiera `ipAllowlist` la borraría, y
+ * eso apagaría el filtro por IP de la integración sin que nadie lo pidiera.
+ */
+export class UpdateIntegrationRequest {
+    @Expose() @IsOptional() @IsString() @IsNotEmpty() displayName?: string;
+    @Expose() @IsOptional() @IsArray() @ArrayNotEmpty() @IsString({ each: true }) ipAllowlist?: string[];
+    @Expose() @IsString() @IsNotEmpty() updatedBy!: string;
+}

package/src/platformRbac/enums/Permission.ts

@@ -146,6 +146,23 @@ export enum Permission {
     LEVEL3_ROLE_ASSIGN = 'level3.role.assign',
     LEVEL3_ROLE_REVOKE = 'level3.role.revoke',
     LEVEL3_AUDIT_VIEW = 'level3.audit.view',
+
+    // Append-only 2026-08-10 (DEC-RBAC-120/121/126): integraciones M2M con socios externos.
+    // Los cuatro de ADMINISTRACIÓN son scope PLATFORM: los datos de la integración son del tenant,
+    // pero solo un usuario de plataforma la crea, rota o revoca. Son además el set exacto que la
+    // guarda 1 prohíbe asignarle a un principal `INT#` — una integración jamás puede administrarse
+    // a sí misma.
+    PLATFORM_INTEGRATION_VIEW = 'platform.integration.view',
+    PLATFORM_INTEGRATION_MANAGE = 'platform.integration.manage',
+    PLATFORM_INTEGRATION_KEY_ISSUE = 'platform.integration.key.issue',
+    PLATFORM_INTEGRATION_KEY_REVOKE = 'platform.integration.key.revoke',
+
+    // DEC-RBAC-126: el endpoint de diagnóstico del authorizer W5 lo llama la INTEGRACIÓN, no un
+    // humano — y una integración NUNCA puede portar permisos de scope PLATFORM (computeRoleScope
+    // toma el MAX de los scopes del rol, así que uno solo lo volvería PLATFORM con scopeRef '*').
+    // Por eso este es TENANT-scoped. Y por eso NO entra en el set de la guarda 1: no administra
+    // nada, solo devuelve quién sos.
+    TENANT_INTEGRATION_DIAGNOSTIC = 'tenant.integration.diagnostic',
 }
 
 /**
@@ -259,6 +276,13 @@ export const PERMISSION_BIT_ORDER: readonly Permission[] = [
     Permission.LEVEL3_ROLE_ASSIGN,
     Permission.LEVEL3_ROLE_REVOKE,
     Permission.LEVEL3_AUDIT_VIEW,
+    // Append-only 2026-08-10 (DEC-RBAC-120/126): integraciones M2M. Van AL FINAL y en este orden,
+    // nunca intercalados: reordenar desalinearía los bits de los tokens ya emitidos.
+    Permission.PLATFORM_INTEGRATION_VIEW,
+    Permission.PLATFORM_INTEGRATION_MANAGE,
+    Permission.PLATFORM_INTEGRATION_KEY_ISSUE,
+    Permission.PLATFORM_INTEGRATION_KEY_REVOKE,
+    Permission.TENANT_INTEGRATION_DIAGNOSTIC,
 ] as const;
 
 function djb2(input: string): number {

package/src/platformRbac/index.ts

@@ -138,3 +138,15 @@ export * from './dtos/CreateLevelEntityRequest';
 export type { CreateLevelEntityResponse } from './dtos/CreateLevelEntityResponse';
 export * from './dtos/CreateTenantUserRequest';
 export type { CreateTenantUserResponse } from './dtos/CreateTenantUserResponse';
+
+// DEC-RBAC-120/121/126: integraciones M2M con socios externos (API keys como principal del RBAC).
+// Los requests van como clase (class-validator); las responses como tipo.
+export * from './dtos/CreateIntegrationRequest';
+export * from './dtos/UpdateIntegrationRequest';
+export type { IntegrationResponse, IntegrationStatusValue } from './dtos/IntegrationResponse';
+export type {
+    IntegrationKeyResponse,
+    IntegrationKeyStatusValue,
+    IssueIntegrationKeyResponse,
+} from './dtos/IntegrationKeyResponse';
+export type { IntegrationWhoamiResponse } from './dtos/IntegrationWhoamiResponse';