@fiado/type-kit 3.252.0 → 3.254.0

package/_test_/unit/biometrics/BiometricVerificationChangedV1.test.ts

@@ -0,0 +1,96 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  BiometricVerificationChangedV1,
+  BiometricEventTypeEnum,
+  BiometricProviderEnum,
+  BiometricResultEnum,
+} from '../../../src/biometrics/index';
+
+/** Base válida de un evento; cada caso pisa solo el campo que está probando. */
+const base = {
+  eventId: 'evt-1',
+  biometricVerificationId: 'bio-1',
+  provider: 'METAMAP',
+  eventType: 'STEP_COMPLETED',
+  occurredAt: '2026-07-26T10:05:00.000Z',
+};
+
+const instancia = (raw: Record<string, unknown>): BiometricVerificationChangedV1 =>
+  plainToInstance(BiometricVerificationChangedV1, raw, { excludeExtraneousValues: true });
+
+describe('BiometricVerificationChangedV1', () => {
+  it('valida el shape que publica el webhook desde un step_completed', async () => {
+    const dto = instancia({ ...base, result: 'MATCH', score: 92, providerRef: 'mm-abc' });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.eventType).toBe(BiometricEventTypeEnum.STEP_COMPLETED);
+    expect(dto.provider).toBe(BiometricProviderEnum.METAMAP);
+    expect(dto.result).toBe(BiometricResultEnum.MATCH);
+  });
+
+  it('valida sin result ni score (VERIFICATION_STARTED no los trae)', async () => {
+    const dto = instancia({ ...base, eventType: 'VERIFICATION_STARTED' });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.result).toBeUndefined();
+    expect(dto.score).toBeUndefined();
+  });
+
+  describe('eventId — la clave de deduplicación', () => {
+    it('rechaza el evento sin eventId', async () => {
+      const { eventId: _omitido, ...sinEventId } = base;
+      const errores = await validate(instancia(sinEventId) as object);
+
+      expect(errores.map((e) => e.property)).toContain('eventId');
+    });
+
+    it('rechaza eventId vacío: pasaría el boundary y no deduplicaría nada', async () => {
+      const errores = await validate(instancia({ ...base, eventId: '' }) as object);
+
+      expect(errores.map((e) => e.property)).toContain('eventId');
+    });
+  });
+
+  describe('occurredAt — el candado es LÉXICO, así que exige Z sin offset', () => {
+    it('acepta UTC con Z', async () => {
+      expect(await validate(instancia({ ...base, occurredAt: '2026-07-26T10:05:00.000Z' }) as object)).toHaveLength(0);
+    });
+
+    it('acepta UTC con Z sin milisegundos', async () => {
+      expect(await validate(instancia({ ...base, occurredAt: '2026-07-26T10:05:00Z' }) as object)).toHaveLength(0);
+    });
+
+    /**
+     * 🔴 El caso que hace daño de verdad. `+05:00` son las 10:05 UTC, pero comparado como TEXTO es
+     * mayor que un `T10:06:00Z` posterior: el consumer lo leería como más nuevo, descartaría el
+     * evento real y la transición no se aplicaría nunca — sin un solo error en los logs.
+     */
+    it('RECHAZA un offset, aunque sea ISO-8601 válido', async () => {
+      const errores = await validate(instancia({ ...base, occurredAt: '2026-07-26T15:05:00+05:00' }) as object);
+
+      expect(errores.map((e) => e.property)).toContain('occurredAt');
+    });
+
+    it('rechaza una fecha sin hora (@IsISO8601 sola la aceptaría)', async () => {
+      const errores = await validate(instancia({ ...base, occurredAt: '2026-07-26' }) as object);
+
+      expect(errores.map((e) => e.property)).toContain('occurredAt');
+    });
+  });
+
+  describe('score', () => {
+    it('rechaza un score fuera de 0–100', async () => {
+      const errores = await validate(instancia({ ...base, score: 101 }) as object);
+
+      expect(errores.map((e) => e.property)).toContain('score');
+    });
+  });
+
+  it('rechaza un eventType que no está en el vocabulario nuestro', async () => {
+    const errores = await validate(instancia({ ...base, eventType: 'verification_started' }) as object);
+
+    expect(errores.map((e) => e.property)).toContain('eventType');
+  });
+});

package/_test_/unit/biometrics/CreateBiometricVerificationRequest.test.ts

@@ -0,0 +1,109 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  CreateBiometricVerificationRequest,
+  BiometricProviderEnum,
+  BiometricTypeEnum,
+} from '../../../src/biometrics/index';
+
+/** El request mínimo válido: los 4 campos obligatorios. */
+const base = {
+  type: 'FACEMATCH',
+  provider: 'METAMAP',
+  directoryId: 'dir-1',
+  requestedBy: 'surekeep-wizard',
+};
+
+const instancia = (raw: Record<string, unknown>): CreateBiometricVerificationRequest =>
+  plainToInstance(CreateBiometricVerificationRequest, raw, { excludeExtraneousValues: true });
+
+const propiedadesConError = async (raw: Record<string, unknown>): Promise<string[]> =>
+  (await validate(instancia(raw) as object)).map((e) => e.property);
+
+describe('CreateBiometricVerificationRequest', () => {
+  it('valida con solo los 4 obligatorios', async () => {
+    const dto = instancia(base);
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.type).toBe(BiometricTypeEnum.FACEMATCH);
+    expect(dto.provider).toBe(BiometricProviderEnum.METAMAP);
+  });
+
+  it('valida el request completo', async () => {
+    const dto = instancia({
+      ...base,
+      subject: { peopleId: 'ppl-1', countryId: '484', phoneNumber: '+521234567890' },
+      referenceImageUrl: 'https://cdn.fiado.test/ref/abc.jpg',
+      ttlSeconds: 3600,
+      callerContext: 'sesion-42',
+    });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.subject?.countryId).toBe('484');
+  });
+
+  describe('los 4 obligatorios', () => {
+    it.each(['type', 'provider', 'directoryId', 'requestedBy'])('rechaza sin %s', async (campo) => {
+      const { [campo]: _omitido, ...incompleto } = base as Record<string, unknown>;
+
+      expect(await propiedadesConError(incompleto)).toContain(campo);
+    });
+
+    /**
+     * `@IsNotEmpty()` y no solo `@IsString()`: un `''` pasaría el boundary y fallaría tres pasos río
+     * abajo, contra identity, con un error que no apunta a nada.
+     */
+    it('rechaza directoryId vacío', async () => {
+      expect(await propiedadesConError({ ...base, directoryId: '' })).toContain('directoryId');
+    });
+  });
+
+  describe('provider es obligatorio — DEC-004', () => {
+    it('rechaza un provider fuera del enum', async () => {
+      expect(await propiedadesConError({ ...base, provider: 'FACETEC' })).toContain('provider');
+    });
+
+    /**
+     * APPLE es un valor VÁLIDO del enum aunque no esté implementado: el rechazo por "no soportado"
+     * es del manager (`BIOMETRIC_NOT_SUPPORTED`, 422), no del DTO. Si el DTO lo rechazara, el caller
+     * recibiría un 400 de validación en vez de un 422 accionable.
+     */
+    it('acepta APPLE en el DTO — el "no soportado" lo decide el manager, no la validación', async () => {
+      expect(await propiedadesConError({ ...base, provider: 'APPLE' })).toHaveLength(0);
+    });
+  });
+
+  describe('subject.phoneNumber exige E.164 — la normalización es del caller', () => {
+    it('acepta E.164', async () => {
+      expect(await propiedadesConError({ ...base, subject: { phoneNumber: '+521234567890' } })).toHaveLength(0);
+    });
+
+    /**
+     * El wizard guarda 10 dígitos crudos en su sesión y solo los convierte al cruzar hacia el
+     * proveedor. Mandarlos pelados acá produciría una metadata que el proveedor acepta y que después
+     * nadie puede reconciliar.
+     */
+    it('RECHAZA 10 dígitos pelados', async () => {
+      expect(await propiedadesConError({ ...base, subject: { phoneNumber: '1234567890' } })).toContain('subject');
+    });
+
+    it('rechaza un teléfono con espacios', async () => {
+      expect(await propiedadesConError({ ...base, subject: { phoneNumber: '+52 123 456 7890' } })).toContain('subject');
+    });
+  });
+
+  describe('ttlSeconds', () => {
+    it('rechaza un TTL mayor a 24 h: lo que se entrega es una identidad abierta', async () => {
+      expect(await propiedadesConError({ ...base, ttlSeconds: 86401 })).toContain('ttlSeconds');
+    });
+
+    it('rechaza un TTL menor a 60 s', async () => {
+      expect(await propiedadesConError({ ...base, ttlSeconds: 59 })).toContain('ttlSeconds');
+    });
+  });
+
+  it('rechaza un callerContext de más de 256 caracteres', async () => {
+    expect(await propiedadesConError({ ...base, callerContext: 'x'.repeat(257) })).toContain('callerContext');
+  });
+});

package/bin/biometrics/dtos/BiometricDelivery.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Lo que el caller necesita para que el biométrico se ejecute. **Su forma la determina
+ * `BiometricVerificationResponse.deliveryMode`, que es el discriminador.**
+ *
+ * Se modela como TRES clases + una unión de tipos en vez de un objeto con todo opcional. Con la
+ * unión, TypeScript obliga al caller a hacer el `switch (deliveryMode)` y sabe exactamente qué
+ * campos tiene en cada rama. Con un objeto plano de campos opcionales, el compilador no ayuda y el
+ * caller termina haciendo `link!` — que es el bug esperando a que entre el segundo proveedor.
+ *
+ * `biometrics-business` — Entrega 1 (solo `RedirectDelivery` produce valores reales).
+ */
+/**
+ * `deliveryMode = REDIRECT`. El usuario abre el link y ejecuta el biométrico ahí.
+ * Es lo que produce Metamap: una URL hospedada, acortada, con TTL.
+ */
+export declare class RedirectDelivery {
+    /**
+     * La URL a abrir. Ya viene acortada — si el acortador no respondió, viene la larga.
+     * Que el acortador falle NO detiene la operación: un QR más denso se escanea igual.
+     */
+    link: string;
+    /** Hasta cuándo sirve el link. ISO-8601 UTC con `Z`. */
+    expiresAt: string;
+}
+/**
+ * `deliveryMode = CHALLENGE`. El biométrico corre en el dispositivo (Apple Face ID, biometría de
+ * Android) y el cliente devuelve una attestation firmada.
+ *
+ * ⚠️ **Declarado, sin implementar.** El endpoint que recibe la attestation
+ * (`POST /.../{id}/assertion`) queda fuera de la Entrega 1 a propósito — el contrato ya lo admite
+ * sin romperse, que es todo lo que hacía falta decidir ahora.
+ */
+export declare class ChallengeDelivery {
+    /** El desafío que el dispositivo debe firmar. */
+    challenge: string;
+    /** Nonce anti-replay. Un solo uso. */
+    nonce: string;
+    /** Hasta cuándo sirve el challenge. ISO-8601 UTC con `Z`. */
+    expiresAt: string;
+}
+/**
+ * `deliveryMode = IMMEDIATE`. No hay nada que entregar: el biométrico ya corrió en el servidor
+ * (Amazon Rekognition) y el veredicto viene en `result` de la misma respuesta.
+ *
+ * Vacío a propósito. Existe para que la unión sea exhaustiva y el `switch` del caller no necesite
+ * un `default` que trague casos nuevos en silencio.
+ *
+ * ⚠️ Declarado, sin implementar.
+ */
+export declare class ImmediateDelivery {
+    /** Reservado. Nunca se llena hoy — existe para que la clase no sea estructuralmente vacía. */
+    note?: string;
+}
+/**
+ * La unión. El caller discrimina con `deliveryMode`:
+ *
+ * ```ts
+ * switch (res.deliveryMode) {
+ *   case BiometricDeliveryModeEnum.REDIRECT:  abrir((res.delivery as RedirectDelivery).link); break;
+ *   case BiometricDeliveryModeEnum.CHALLENGE: firmar(res.delivery as ChallengeDelivery); break;
+ *   case BiometricDeliveryModeEnum.IMMEDIATE: leer(res.result); break;
+ * }
+ * ```
+ */
+export type BiometricDelivery = RedirectDelivery | ChallengeDelivery | ImmediateDelivery;

package/bin/biometrics/dtos/BiometricDelivery.js

@@ -0,0 +1,89 @@
+"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.ImmediateDelivery = exports.ChallengeDelivery = exports.RedirectDelivery = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Lo que el caller necesita para que el biométrico se ejecute. **Su forma la determina
+ * `BiometricVerificationResponse.deliveryMode`, que es el discriminador.**
+ *
+ * Se modela como TRES clases + una unión de tipos en vez de un objeto con todo opcional. Con la
+ * unión, TypeScript obliga al caller a hacer el `switch (deliveryMode)` y sabe exactamente qué
+ * campos tiene en cada rama. Con un objeto plano de campos opcionales, el compilador no ayuda y el
+ * caller termina haciendo `link!` — que es el bug esperando a que entre el segundo proveedor.
+ *
+ * `biometrics-business` — Entrega 1 (solo `RedirectDelivery` produce valores reales).
+ */
+/**
+ * `deliveryMode = REDIRECT`. El usuario abre el link y ejecuta el biométrico ahí.
+ * Es lo que produce Metamap: una URL hospedada, acortada, con TTL.
+ */
+class RedirectDelivery {
+}
+exports.RedirectDelivery = RedirectDelivery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RedirectDelivery.prototype, "link", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsISO8601)({ strict: true }),
+    __metadata("design:type", String)
+], RedirectDelivery.prototype, "expiresAt", void 0);
+/**
+ * `deliveryMode = CHALLENGE`. El biométrico corre en el dispositivo (Apple Face ID, biometría de
+ * Android) y el cliente devuelve una attestation firmada.
+ *
+ * ⚠️ **Declarado, sin implementar.** El endpoint que recibe la attestation
+ * (`POST /.../{id}/assertion`) queda fuera de la Entrega 1 a propósito — el contrato ya lo admite
+ * sin romperse, que es todo lo que hacía falta decidir ahora.
+ */
+class ChallengeDelivery {
+}
+exports.ChallengeDelivery = ChallengeDelivery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ChallengeDelivery.prototype, "challenge", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ChallengeDelivery.prototype, "nonce", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsISO8601)({ strict: true }),
+    __metadata("design:type", String)
+], ChallengeDelivery.prototype, "expiresAt", void 0);
+/**
+ * `deliveryMode = IMMEDIATE`. No hay nada que entregar: el biométrico ya corrió en el servidor
+ * (Amazon Rekognition) y el veredicto viene en `result` de la misma respuesta.
+ *
+ * Vacío a propósito. Existe para que la unión sea exhaustiva y el `switch` del caller no necesite
+ * un `default` que trague casos nuevos en silencio.
+ *
+ * ⚠️ Declarado, sin implementar.
+ */
+class ImmediateDelivery {
+}
+exports.ImmediateDelivery = ImmediateDelivery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], ImmediateDelivery.prototype, "note", void 0);

package/bin/biometrics/dtos/BiometricSubject.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Datos del SUJETO que el proveedor necesita, además del `directoryId`.
+ *
+ * 🔴 **Tipado y CERRADO, jamás un `Record<string, unknown>`.** Un mapa abierto en un boundary es
+ * antipatrón Fiado, pero el problema real es peor: sería un canal por el que cualquier caller le
+ * puede filtrar PII a un tercero sin que nadie lo revise. Lo que viaja a un proveedor externo se
+ * declara campo por campo.
+ *
+ * **No confundir con `callerContext`**, que es correlación opaca del caller y NUNCA sale de Fiado.
+ * Son dos cosas que se mezclan seguido: "datos que el proveedor necesita" vs "mi correlación".
+ *
+ * **Todos opcionales, con resolución del lado del servicio (DEC-005b).** Lo que venga acá gana; lo
+ * que falte, `biometrics-business` lo resuelve contra `fiado-identity-lambda` a partir del
+ * `directoryId`. Si tras eso sigue faltando alguno, responde `SUBJECT_DATA_INCOMPLETE` (422)
+ * nombrando los CAMPOS, jamás sus valores.
+ *
+ * 🔴 **Ese error existe para prevenir una falla muda ya vivida.** Con la metadata de identidad
+ * vacía, el proveedor genera una verificación HUÉRFANA: el usuario hace la selfie completa, el
+ * webhook no la puede asociar a nadie, y el flujo queda colgado para siempre con la persona ya
+ * fuera de la tienda. Fallar temprano y ruidoso es la única respuesta correcta.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export declare class BiometricSubject {
+    /** Identificador de la persona en el directorio de Fiado. */
+    peopleId?: string;
+    /**
+     * País del sujeto en el catálogo de Fiado (`CountryId`). MX es `'484'`.
+     *
+     * ⚠️ Numérico-como-string a propósito: es el mismo valor que usa el resto de la plataforma.
+     * Un caller que mande `'MX'` acá rompería la metadata del proveedor.
+     */
+    countryId?: string;
+    /**
+     * Teléfono **ya en E.164**, con `+` y código de país (`+521234567890`).
+     *
+     * ⚠️ **La normalización es del caller, no de este servicio.** El wizard, por ejemplo, guarda 10
+     * dígitos crudos en su sesión y los convierte con `toE164Mx()` solo al cruzar hacia el
+     * proveedor. Mandar 10 dígitos pelados acá produce una metadata que el proveedor acepta y que
+     * después nadie puede reconciliar.
+     */
+    phoneNumber?: string;
+}

package/bin/biometrics/dtos/BiometricSubject.js

@@ -0,0 +1,63 @@
+"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.BiometricSubject = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Datos del SUJETO que el proveedor necesita, además del `directoryId`.
+ *
+ * 🔴 **Tipado y CERRADO, jamás un `Record<string, unknown>`.** Un mapa abierto en un boundary es
+ * antipatrón Fiado, pero el problema real es peor: sería un canal por el que cualquier caller le
+ * puede filtrar PII a un tercero sin que nadie lo revise. Lo que viaja a un proveedor externo se
+ * declara campo por campo.
+ *
+ * **No confundir con `callerContext`**, que es correlación opaca del caller y NUNCA sale de Fiado.
+ * Son dos cosas que se mezclan seguido: "datos que el proveedor necesita" vs "mi correlación".
+ *
+ * **Todos opcionales, con resolución del lado del servicio (DEC-005b).** Lo que venga acá gana; lo
+ * que falte, `biometrics-business` lo resuelve contra `fiado-identity-lambda` a partir del
+ * `directoryId`. Si tras eso sigue faltando alguno, responde `SUBJECT_DATA_INCOMPLETE` (422)
+ * nombrando los CAMPOS, jamás sus valores.
+ *
+ * 🔴 **Ese error existe para prevenir una falla muda ya vivida.** Con la metadata de identidad
+ * vacía, el proveedor genera una verificación HUÉRFANA: el usuario hace la selfie completa, el
+ * webhook no la puede asociar a nadie, y el flujo queda colgado para siempre con la persona ya
+ * fuera de la tienda. Fallar temprano y ruidoso es la única respuesta correcta.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+class BiometricSubject {
+}
+exports.BiometricSubject = BiometricSubject;
+__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)
+], BiometricSubject.prototype, "peopleId", void 0);
+__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)
+], BiometricSubject.prototype, "countryId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^\+[1-9]\d{7,14}$/, {
+        message: 'phoneNumber debe venir en E.164 con + y codigo de pais (ej. +521234567890)',
+    }),
+    __metadata("design:type", String)
+], BiometricSubject.prototype, "phoneNumber", void 0);

package/bin/biometrics/dtos/requests/CreateBiometricVerificationRequest.d.ts

@@ -0,0 +1,73 @@
+import { BiometricProviderEnum } from '../../enums/BiometricProviderEnum';
+import { BiometricTypeEnum } from '../../enums/BiometricTypeEnum';
+import { BiometricSubject } from '../BiometricSubject';
+/**
+ * `POST /private/biometric-verifications` — pedir una verificación biométrica de una persona.
+ *
+ * El caller dice QUÉ necesita (`type`), QUIÉN lo ejecuta (`provider`) y PARA QUIÉN es
+ * (`directoryId`). Todo lo demás — resolver la foto de referencia, publicarla, firmarla, armar la
+ * metadata del proveedor, acortar el link — lo hace `biometrics-business`. Ese es el punto: que el
+ * segundo producto que necesite biometría haga un `POST` en vez de un proyecto.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export declare class CreateBiometricVerificationRequest {
+    /**
+     * QUÉ biométrico. Hoy solo `FACEMATCH` está implementado; el resto devuelve
+     * `BIOMETRIC_NOT_SUPPORTED` (422).
+     */
+    type: BiometricTypeEnum;
+    /**
+     * QUIÉN lo ejecuta. **Obligatorio** (DEC-004): el caller lo nombra, el servicio no resuelve un
+     * default. Hoy solo `METAMAP`.
+     *
+     * ⚠️ **TD-001**: esto acopla a los callers. Cambiar de proveedor obliga a tocar y redesplegar a
+     * todos. Se aceptó a cambio de que la elección sea explícita y auditable en cada request.
+     */
+    provider: BiometricProviderEnum;
+    /**
+     * PARA QUIÉN es. Es la llave con la que se resuelve la foto de referencia y los datos que falten
+     * de `subject`.
+     *
+     * `@IsNotEmpty()` y no solo `@IsString()`: un `''` colado pasaría el boundary y fallaría tres
+     * pasos río abajo, contra identity, con un error que no apunta a nada.
+     */
+    directoryId: string;
+    /**
+     * QUIÉN pide (el producto o lambda: `surekeep-wizard`, `user-wallet-app`…). Para auditoría y
+     * trazabilidad.
+     *
+     * ⚠️ **No autoriza nada** (TD-009). El `GET` no lo valida: hoy el aislamiento es que los dos
+     * endpoints son VPC-only, así que solo lambdas de Fiado llegan. Está anotado como deuda
+     * consciente, no como olvido.
+     */
+    requestedBy: string;
+    /**
+     * Datos del sujeto que el proveedor necesita. Lo que mandes gana; lo que falte se resuelve
+     * contra identity. Ver `BiometricSubject` — sobre todo la nota de por qué `phoneNumber` va en
+     * E.164 y la normalización es tuya.
+     */
+    subject?: BiometricSubject;
+    /**
+     * Override de la foto de referencia. Si no viene, el servicio la resuelve solo: pide la **selfie
+     * del KYC** a identity (no el avatar `PROFILE_PICTURE`, que el KYC nunca genera) y la publica.
+     *
+     * Úsalo solo si ya tienes la foto correcta a mano y quieres ahorrarte el round-trip.
+     */
+    referenceImageUrl?: string;
+    /**
+     * Vigencia de la entrega, en segundos. Default 3600.
+     *
+     * El techo de 24 h no es arbitrario: lo que se entrega es una identidad abierta. Un link de
+     * verificación que sobreviva a la operación que lo pidió es una puerta sin nadie mirándola.
+     */
+    ttlSeconds?: number;
+    /**
+     * Correlación tuya, opaca. Te la devuelvo intacta en el `GET`.
+     *
+     * 🔴 **NUNCA viaja al proveedor.** Es lo que la separa de `subject`: uno son datos que el
+     * tercero necesita, esto es un dato que solo te sirve a ti. No metas PII acá — mete tu id de
+     * sesión, de orden, de lo que sea que estés correlacionando.
+     */
+    callerContext?: string;
+}

package/bin/biometrics/dtos/requests/CreateBiometricVerificationRequest.js

@@ -0,0 +1,81 @@
+"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.CreateBiometricVerificationRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const BiometricProviderEnum_1 = require("../../enums/BiometricProviderEnum");
+const BiometricTypeEnum_1 = require("../../enums/BiometricTypeEnum");
+const BiometricSubject_1 = require("../BiometricSubject");
+/**
+ * `POST /private/biometric-verifications` — pedir una verificación biométrica de una persona.
+ *
+ * El caller dice QUÉ necesita (`type`), QUIÉN lo ejecuta (`provider`) y PARA QUIÉN es
+ * (`directoryId`). Todo lo demás — resolver la foto de referencia, publicarla, firmarla, armar la
+ * metadata del proveedor, acortar el link — lo hace `biometrics-business`. Ese es el punto: que el
+ * segundo producto que necesite biometría haga un `POST` en vez de un proyecto.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+class CreateBiometricVerificationRequest {
+}
+exports.CreateBiometricVerificationRequest = CreateBiometricVerificationRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(BiometricTypeEnum_1.BiometricTypeEnum),
+    __metadata("design:type", String)
+], CreateBiometricVerificationRequest.prototype, "type", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(BiometricProviderEnum_1.BiometricProviderEnum),
+    __metadata("design:type", String)
+], CreateBiometricVerificationRequest.prototype, "provider", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateBiometricVerificationRequest.prototype, "directoryId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateBiometricVerificationRequest.prototype, "requestedBy", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => BiometricSubject_1.BiometricSubject),
+    __metadata("design:type", BiometricSubject_1.BiometricSubject)
+], CreateBiometricVerificationRequest.prototype, "subject", void 0);
+__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)
+], CreateBiometricVerificationRequest.prototype, "referenceImageUrl", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(60),
+    (0, class_validator_1.Max)(86400),
+    __metadata("design:type", Number)
+], CreateBiometricVerificationRequest.prototype, "ttlSeconds", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(256),
+    __metadata("design:type", String)
+], CreateBiometricVerificationRequest.prototype, "callerContext", void 0);