@fiado/type-kit 3.37.0 → 3.39.0

package/src/cognitoBackofficeConnector/enums/CognitoUserStatus.ts

@@ -0,0 +1,29 @@
+/**
+ * Estados posibles de un usuario en un Cognito User Pool, según el tipo
+ * `UserStatusType` del SDK `@aws-sdk/client-cognito-identity-provider`.
+ *
+ * El SDK no expone enum value `DISABLED` — el equivalente operativo en Cognito
+ * es el flag boolean `enabled` del usuario (ver `CreateUserResponse.enabled`
+ * y `UserDetailResponse.enabled`), que es independiente del `status`.
+ *
+ * `EXTERNAL_PROVIDER` (federación SAML / OIDC) no se incluye porque el
+ * proyecto NO usa federación — el backoffice solo administra usuarios nativos
+ * del pool.
+ *
+ *  - `UNCONFIRMED` — el usuario fue creado pero no completó la verificación de email.
+ *  - `CONFIRMED` — usuario verificado, puede operar (sujeto a MFA si aplica).
+ *  - `ARCHIVED` — usuario archivado por Cognito (no puede operar, no se borra).
+ *  - `COMPROMISED` — flag de Cognito Advanced Security: credencial comprometida.
+ *  - `UNKNOWN` — Cognito no determinó el estado (raro).
+ *  - `RESET_REQUIRED` — el usuario debe resetear password antes del próximo login.
+ *  - `FORCE_CHANGE_PASSWORD` — temp password vigente, requiere `NEW_PASSWORD_REQUIRED`.
+ */
+export enum CognitoUserStatus {
+    UNCONFIRMED = 'UNCONFIRMED',
+    CONFIRMED = 'CONFIRMED',
+    ARCHIVED = 'ARCHIVED',
+    COMPROMISED = 'COMPROMISED',
+    UNKNOWN = 'UNKNOWN',
+    RESET_REQUIRED = 'RESET_REQUIRED',
+    FORCE_CHANGE_PASSWORD = 'FORCE_CHANGE_PASSWORD',
+}

package/src/cognitoBackofficeConnector/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Módulo `cognitoBackofficeConnector` — DTOs, enums y validators para el Lambda
+ * `cognito-backoffice-connector` (backoffice multi-tenant Fiado).
+ *
+ * Es un módulo NUEVO y SEPARADO del módulo `cognitoConnector/` legacy que pertenece
+ * a otro Lambda Cognito Fiado (mantenido por yhonhansen). No reusar tipos del
+ * legacy aquí ni viceversa — los dominios divergieron y mezclarlos arrastraría
+ * acoplamiento histórico.
+ */
+export * from './enums/CognitoChallengeType';
+export * from './enums/CognitoUserStatus';
+export * from './validators/NoTenantIdInCustomAttrs';
+export * from './validators/MfaTypesRequiresOne';
+export * from './dtos/CreateUserRequest';
+export * from './dtos/CreateUserResponse';
+export * from './dtos/UpdateUserAttributesRequest';
+export * from './dtos/UserActionRequest';
+export * from './dtos/DeleteUserRequest';
+export * from './dtos/ResendInvitationRequest';
+export * from './dtos/UserDetailResponse';
+export * from './dtos/AuthEventsRequest';
+export * from './dtos/AuthEventResponse';
+export * from './dtos/AuthTokensResponse';
+export * from './dtos/InitiateAuthRequest';
+export * from './dtos/InitiateAuthResponse';
+export * from './dtos/RespondToChallengeRequest';
+export * from './dtos/RespondToChallengeResponse';
+export * from './dtos/RefreshTokensRequest';
+export * from './dtos/RefreshTokensResponse';
+export * from './dtos/ForgotPasswordRequest';
+export * from './dtos/ConfirmForgotPasswordRequest';
+export * from './dtos/ResendConfirmationRequest';
+export * from './dtos/ChangePasswordRequest';
+export * from './dtos/TotpBeginRequest';
+export * from './dtos/TotpBeginResponse';
+export * from './dtos/TotpVerifyRequest';
+export * from './dtos/MfaVerifyResponse';
+export * from './dtos/SetMfaPreferenceRequest';
+export * from './dtos/MfaResetRequest';
+export * from './dtos/UpdateEmailRequest';
+export * from './dtos/VerifyEmailRequest';
+export * from './dtos/UpdateProfileRequest';
+export * from './dtos/HealthcheckResponse';
+export * from './dtos/MfaPoolConfig';
+export * from './dtos/PasswordPolicyConfig';
+export * from './dtos/CustomAttributeSpec';
+export * from './dtos/AppClientConfig';
+export * from './dtos/CreatePoolRequest';
+export * from './dtos/CreatePoolResponse';
+export * from './dtos/DeletePoolRequest';

package/src/cognitoBackofficeConnector/validators/MfaTypesRequiresOne.ts

@@ -0,0 +1,29 @@
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+/**
+ * Cross-field validator: si `requireMfa: true`, entonces `mfaTypes` debe tener
+ * al menos 1 elemento. Si `requireMfa: false`, `mfaTypes` puede ser vacío.
+ *
+ * Razón: cuando el pool nace con MFA habilitado, el connector llama
+ * `SetUserPoolMfaConfigCommand` con la lista de tipos del DTO. Si el array
+ * llega vacío con `requireMfa: true`, el SDK rechaza con InvalidParameterException
+ * y el pool queda en estado inconsistente (MfaConfiguration:'ON' sin tipos).
+ * Mejor rechazar en validación del DTO antes de tocar AWS.
+ *
+ * Ver pivote v1.4.1 TD-017 cerrado + spec doc §1 R3.
+ */
+@ValidatorConstraint({ name: 'MfaTypesRequiresOneWhenMfaRequired', async: false })
+export class MfaTypesRequiresOne implements ValidatorConstraintInterface {
+    validate(mfaTypes: unknown, args: ValidationArguments): boolean {
+        const obj = args.object as { requireMfa?: boolean };
+        if (obj.requireMfa === true) {
+            return Array.isArray(mfaTypes) && mfaTypes.length >= 1;
+        }
+        // requireMfa: false → cualquier mfaTypes pasa.
+        return true;
+    }
+
+    defaultMessage(): string {
+        return 'mfaTypes requiere al menos un tipo cuando requireMfa=true';
+    }
+}

package/src/cognitoBackofficeConnector/validators/NoTenantIdInCustomAttrs.ts

@@ -0,0 +1,36 @@
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+/**
+ * Bloquea que el cliente del backoffice envíe `tenantId` dentro del map
+ * `customAttributes` al actualizar atributos de un usuario Cognito (decisión D3
+ * del spec del proyecto `cognito-backoffice-connector`).
+ *
+ * Razón: el `tenantId` se determina por el pool donde vive el usuario y por
+ * el rol del caller — permitir overridearlo desde `customAttributes` habilitaría
+ * "tenant reassignment" por la puerta de atrás (escalación de privilegios
+ * cross-tenant).
+ *
+ * Acepta:
+ *  - `undefined` / `null` (el campo es opcional).
+ *  - Objeto vacío `{}`.
+ *  - Cualquier objeto que NO contenga la key `tenantId`.
+ *
+ * Rechaza:
+ *  - Objetos con la key `tenantId` presente (con cualquier valor).
+ *  - Valores que no son objeto (string, number, array, etc.).
+ *
+ * Uso en DTOs: `@Validate(NoTenantIdInCustomAttrs)` sobre el campo
+ * `customAttributes`.
+ */
+@ValidatorConstraint({ name: 'NoTenantIdInCustomAttrs', async: false })
+export class NoTenantIdInCustomAttrs implements ValidatorConstraintInterface {
+    validate(value: unknown, _args: ValidationArguments): boolean {
+        if (value === undefined || value === null) return true;
+        if (typeof value !== 'object' || Array.isArray(value)) return false;
+        return !Object.prototype.hasOwnProperty.call(value, 'tenantId');
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        return `${args.property} must not contain a 'tenantId' key — tenant reassignment via customAttributes is forbidden`;
+    }
+}

package/src/index.ts

@@ -73,5 +73,13 @@ export * as CirculoCredito from './circuloCredito';
 export * as MilestoneBusiness from './milestone-business';
 export * as Mdm from './mdm';
 export * as MessagesConnector from './messagesConnector';
+export * as CognitoBackofficeConnector from './cognitoBackofficeConnector';
+export * as Rbac from './rbac';
+// PlatformRbac: módulo del lambda platform-rbac-business (Fase 0 SureKeep).
+// Contiene Permission enum + AuthContext + RoleAssignmentInfo + PermissionScope +
+// PermissionCategory + PermissionMeta + (futuro Fase 1.B) DTOs propios del rbac-business.
+// Coexiste con `Rbac` oficial cuando yhonhansen publique componente 01.
+// Cleanup del `Rbac` viejo planeado en bloque 13 post-gate (TD-RBAC en platform-rbac-business).
+export * as PlatformRbac from './platformRbac';
 export * as Remittance from './remittance';
 export * from './messaging';

package/src/platformRbac/dtos/AuthContext.ts

@@ -0,0 +1,22 @@
+import type { Permission } from '../enums/Permission';
+import type { RoleAssignmentInfo } from './RoleAssignmentInfo';
+
+/**
+ * Shape DESERIALIZADO del authorizer context.
+ * El authorizer Lambda (componente 07) lo construye + serializa; el helper
+ * `extractTenantContext` lo deserializa para los handlers business.
+ *
+ * En API Gateway authorizer.context todos los valores son strings:
+ * - `permissions` viaja como CSV (`"a.b.c,d.e.f,..."`).
+ * - `roleAssignments` viaja como JSON string.
+ * Este interface es la forma ya parseada.
+ */
+export interface AuthContext {
+    cognitoSub: string;
+    tenantId: string;
+    email: string;
+    roleAssignments: RoleAssignmentInfo[];
+    permissions: Permission[];
+    resolvedAt: string;
+    issuer?: string;
+}

package/src/platformRbac/dtos/PermissionMeta.ts

@@ -0,0 +1,20 @@
+import type { Permission } from '../enums/Permission';
+import type { PermissionScope } from '../enums/PermissionScope';
+import type { PermissionCategory } from '../enums/PermissionCategory';
+
+/**
+ * Metadata enriquecida de una permission del catálogo.
+ * Usado para:
+ * - Sync del enum a DDB `PlatformPermission_GT` al deploy.
+ * - UI del módulo rbac-admin: selector de permissions agrupado.
+ * - Reporting / docs.
+ */
+export interface PermissionMeta {
+    permissionKey: Permission;
+    displayName: string;
+    description: string;
+    category: PermissionCategory;
+    scope: PermissionScope;
+    platforms: string[];
+    isDeprecated?: boolean;
+}

package/src/platformRbac/dtos/RoleAssignmentInfo.ts

@@ -0,0 +1,12 @@
+import type { PermissionScope } from '../enums/PermissionScope';
+
+/**
+ * Una asignación de role a un user con scope específico.
+ * Shape que el authorizer Lambda (componente 07) serializa como JSON string
+ * dentro del API Gateway authorizer context.
+ */
+export interface RoleAssignmentInfo {
+    roleId: string;
+    scope: PermissionScope;
+    scopeRef: string;
+}

package/src/platformRbac/enums/Permission.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 78 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.
+ *
+ * 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',
+    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',
+
+    // ====================================================
+    // TENANT — operaciones dentro del silo de un tenant
+    // ====================================================
+    TENANT_USER_CREATE = 'tenant.user.create',
+    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',
+
+    // ====================================================
+    // RETAIL — catálogo + inventario + ventas
+    // ====================================================
+    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',
+    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',
+    MDM_DEVICE_PIN_UNLOCK = 'mdm.device.pin_unlock',
+    MDM_DEVICE_EXTEND_VALIDITY = 'mdm.device.extend_validity',
+    MDM_DEVICE_NOTIFY = 'mdm.device.notify',
+    MDM_DEVICE_STATUS_VIEW = 'mdm.device.status.view',
+    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',
+}

package/src/platformRbac/enums/PermissionCategory.ts

@@ -0,0 +1,14 @@
+/**
+ * Categorías del catálogo de permissions (componente 01).
+ * TD-RBAC-005: `AUDIT` category sin permissions `audit.*` asociadas — drift consciente.
+ */
+export enum PermissionCategory {
+    RBAC = 'rbac',
+    PLATFORM = 'platform',
+    TENANT = 'tenant',
+    RETAIL = 'retail',
+    LEND = 'lend',
+    MDM = 'mdm',
+    AUDIT = 'audit',
+    PAY = 'pay',
+}

package/src/platformRbac/enums/PermissionScope.ts

@@ -0,0 +1,10 @@
+/**
+ * Jerarquía: PLATFORM > TENANT > RETAILER > STORE.
+ * Componente 01 spec — copia exacta.
+ */
+export enum PermissionScope {
+    PLATFORM = 'PLATFORM',
+    TENANT = 'TENANT',
+    RETAILER = 'RETAILER',
+    STORE = 'STORE',
+}

package/src/platformRbac/index.ts

@@ -0,0 +1,17 @@
+// platformRbac — módulo del lambda platform-rbac-business (Fase 0 SureKeep).
+//
+// Coexiste con `Rbac` oficial cuando yhonhansen publique componente 01 — TD-RBAC-002
+// del platform-rbac-business documenta la migración futura de los 4 símbolos cross-cutting
+// (Permission, PermissionScope, AuthContext, RoleAssignmentInfo) de aquí a `rbac/`.
+//
+// En Fase 1.A los DTOs propios del rbac-business (CreateTenantRequest, AssignRoleRequest,
+// EffectivePermissionsResponse, etc.) NO viven en este módulo todavía — se agregan en
+// Fase 1.B cuando los managers que los consumen se implementen.
+
+export { Permission } from './enums/Permission';
+export { PermissionScope } from './enums/PermissionScope';
+export { PermissionCategory } from './enums/PermissionCategory';
+
+export type { AuthContext } from './dtos/AuthContext';
+export type { RoleAssignmentInfo } from './dtos/RoleAssignmentInfo';
+export type { PermissionMeta } from './dtos/PermissionMeta';

package/src/rbac/enums/PoolKind.ts

@@ -0,0 +1,16 @@
+/**
+ * Tipo de User Pool de Cognito desde la perspectiva del modelo RBAC Fiado.
+ *
+ * Origen: spec del proyecto `cognito-backoffice-connector` (Fase 0, componente 01
+ * documento `docs/superpowers/specs/2026-05-26-cognito-connector-decisiones-pendientes-design.md`).
+ *
+ * Decisión (TD-003): el proyecto converge en estos 2 valores. El documento componente 03
+ * lista 3 valores (incluyendo una variante adicional) pero queda como outlier — la
+ * decisión vigente en los 6 docs restantes y en el plan de implementación es 2 valores:
+ *  - BACKOFFICE_PLATFORM — pool del backoffice de plataforma (cross-tenant)
+ *  - BACKOFFICE_TENANT — pool por tenant (multi-tenant isolation)
+ */
+export enum PoolKind {
+    BACKOFFICE_PLATFORM = 'BACKOFFICE_PLATFORM',
+    BACKOFFICE_TENANT = 'BACKOFFICE_TENANT',
+}

package/src/rbac/index.ts

@@ -0,0 +1 @@
+export * from './enums/PoolKind';