# Gestión y Emisión de la Credencial

### **Emisión de una Nueva Credencial**

Este es el proceso completo, paso a paso, que ocurre desde que el ciudadano inicia la solicitud hasta que recibe su credencial.

#### **Paso 1: Inicio de Sesión y Autenticación Fuerte**

El ciudadano necesita probar su identidad al sistema de emisión. Esto se logra mediante el flujo de Código de Autorización de OIDC.

1.  **Acción del Usuario**: El usuario presiona "Solicitar Licencia Digital" en la wallet `Soy Yo RD`.
2.  **Llamada Inicial (Frontend)**: La wallet `Soy Yo RD` genera e invoca una llamada de autorización a `Cuenta Única`. No es una API REST directa, sino una redirección del navegador en la app (o un Custom Chrome Tab / ASWebAuthenticationSession).

    **Ejemplo de URL de Autorización (GET):**
    ```http
    https://auth.cuentaunica.gob.do/auth?
      response_type=code
      &client_id=SOYYO_RD_WALLET_CLIENT_ID
      &scope=openid profile cedula
      &redirect_uri=soyyord://callback
      &state=STATE_STRING_ALEATORIO
      &nonce=NONCE_STRING_ALEATORIO
      &code_challenge=S256_CHALLENGE
      &code_challenge_method=S256
    ```

3.  **Autenticación del Usuario**: El usuario se autentica en la interfaz web de `Cuenta Única` (usuario, contraseña, 2FA).
4.  **Redirección con Código**: `Cuenta Única` redirige de vuelta a la app `Soy Yo RD` a través de la `redirect_uri` con un código de autorización.
5.  **Intercambio del Código por Tokens (Backend-a-Backend)**: La wallet envía el `code` a su propio backend de soporte (o lo hace directamente si es una app confidencial), el cual realiza una llamada **API REST (POST)** al endpoint de token de `Cuenta Única`. Esta comunicación es segura (backend a backend) y evita exponer los tokens en el lado del cliente.

    **Llamada a la API de Token (POST):**
    * **Endpoint:** `https://auth.cuentaunica.gob.do/token`
    * **Headers:** `Content-Type: application/x-www-form-urlencoded`
    * **Body:**
        ```
        grant_type=authorization_code
        &code=CODIGO_RECIBIDO
        &redirect_uri=soyyord://callback
        &client_id=SOYYO_RD_WALLET_CLIENT_ID
        &client_secret=CLIENT_SECRET_DE_LA_APP
        &code_verifier=VERIFIER_ORIGINAL
        ```
6.  **Respuesta de la API de Token**: `Cuenta Úunica` responde con un objeto JSON que contiene los tokens de acceso e identidad.

    **Formato de Respuesta (JSON):**
    ```json
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
      "token_type": "Bearer",
      "expires_in": 3600,
      "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
    }
    ```
    El `id_token` es un **JSON Web Token (JWT)** que, al ser decodificado, contiene la información verificada del ciudadano, como su número de Cédula.

#### **Paso 2: Solicitud Formal de la Credencial**

Con la prueba de identidad (el `id_token` o `access_token`), la wallet ahora puede solicitar la credencial al servidor de emisión del INTRANT.

1.  **Llamada a la API de Emisión (POST)**: La wallet `Soy Yo RD` realiza una llamada HTTPS a la API de `Inji-Certify`.

    * **Endpoint:** `https://api.intrant.gob.do/v1/issue/driving-license`
    * **Headers:** `Authorization: Bearer <access_token_de_cuenta_unica>`
    * **Body (JSON):**
        ```json
        {
          "holderDid": "did:key:z6Mkt...H73tias"
        }
        ```
    * **Información Relevante:**
        * El `access_token` en el header autoriza la operación y permite a `Inji-Certify` identificar al solicitante (consultando el endpoint `/userinfo` de Cuenta Única o validando el `id_token`).
        * El `holderDid` es el Identificador Descentralizado del ciudadano, generado por la wallet. Será el `id` del sujeto (`credentialSubject`) en la VC.

#### **Paso 3: Verificación Interna y Construcción de la VC**

El servidor de emisión ahora tiene todo lo necesario para procesar la solicitud.

1.  **Validación de Identidad**: El backend de `Inji-Certify` valida el `access_token` con `Cuenta Única`.
2.  **Consulta a la Base de Datos**: Utilizando el número de Cédula extraído del token, el sistema realiza una consulta a la base de datos interna del INTRANT para obtener los datos de la licencia del ciudadano.
    * **Mecanismo**: Conexión de base de datos segura (ej. sobre un túnel VPN) con una consulta tipo `SELECT * FROM licencias WHERE cedula = ?`.
3.  **Construcción de la VC**: Si se encuentran datos válidos, `Inji-Certify` ensambla la Credencial Verificable.

    **Formato de la VC (JSON-LD):**
    ```json
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/vdl/v1" // Contexto específico para licencias de conducir
      ],
      "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
      "type": ["VerifiableCredential", "Iso18013DriversLicense"],
      "issuer": "did:web:intrant.gob.do", // DID del INTRANT
      "issuanceDate": "2025-10-26T14:23:14Z",
      "expirationDate": "2029-10-26T14:23:14Z",
      "credentialSubject": {
        "id": "did:key:z6Mkt...H73tias", // DID del ciudadano
        "familyName": "Perez",
        "givenName": "Juan",
        "birthDate": "1990-01-15",
        "issuingCountry": "DO",
        "drivingPrivileges": [
          {
            "vehicleCategory": "B",
            "issueDate": "2021-10-26",
            "expiryDate": "2025-10-26"
          }
        ]
      },
      "proof": { // Este bloque se añade después de firmar
        "type": "Ed25519Signature2020",
        "created": "2025-10-26T14:23:14Z",
        "verificationMethod": "did:web:intrant.gob.do#key-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z58D3...2k9fV" // La firma digital
      }
    }
    ```

4.  **Firma Criptográfica**: El servidor firma el objeto JSON-LD (excluyendo el bloque `proof`) utilizando la clave privada del INTRANT, almacenada en un **Hardware Security Module (HSM)** para máxima seguridad. El resultado es el `proofValue`.

#### **Paso 4: Devolución de la Credencial**

El servidor responde a la llamada API del Paso 2.

* **Respuesta de la API de Emisión (Código 200 OK):**
    * **Body (JSON):** El cuerpo de la respuesta es directamente la Credencial Verificable completa, en formato JSON-LD, tal como se describió arriba.

La wallet `Soy Yo RD` recibe este objeto JSON, valida la firma del emisor (resolviendo el `did:web:intrant.gob.do` para obtener la clave pública) y lo almacena de forma segura en el almacenamiento cifrado del dispositivo.


### **Gestión del Ciclo de Vida: Revocación**

La revocación es crítica. No es suficiente con que una credencial tenga una firma válida; debe estar activa.

* **Mecanismo**: **Status List 2021**. El INTRANT mantiene un endpoint público que expone un bitmap (una larga cadena de bits, 0s y 1s). Cada credencial emitida está asociada a un índice en esta lista.
* **Acción de Revocación**: Cuando un oficial del INTRANT revoca una licencia en el sistema, la acción interna es una **llamada API (PUT o PATCH)** al servicio que gestiona la lista de estado para cambiar el bit en el índice correspondiente de `0` (válido) a `1` (revocado).

    * **Endpoint (interno):** `https://api.intrant.gob.do/v1/statuslist/main`
    * **Body (JSON):**
        ```json
        {
          "credentialId": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
          "status": "revoked"
        }
        ```
* **API Pública de la Lista de Estado**: Los verificadores acceden a esta lista a través de un endpoint público definido en la propia VC (propiedad `credentialStatus`).

    **Llamada del Verificador (GET):**
    * **Endpoint:** `https://api.intrant.gob.do/v1/status/1` (ejemplo)
    * **Respuesta:** Un objeto JSON que contiene el bitmap comprimido. El software del verificador lo usa para comprobar el estado de la credencial que está validando.

Esta arquitectura asegura un flujo de emisión robusto, seguro y estandarizado, donde cada componente se comunica a través de APIs bien definidas, utilizando formatos de datos interoperables como JSON, JWT y JSON-LD.