ngx-autofirma

Biblioteca para integrar el cliente de firma digital @firma en Angular.

📋 Descripción

Esta librería proporciona una integración sencilla del cliente de firma digital @firma en aplicaciones Angular, permitiendo la implementación de firmas digitales de manera eficiente y segura.

⚠️ Descargo de responsabilidad

NOTA: Esta librería no es una implementación oficial de @firma ni está afiliada a ninguna entidad oficial. Ha sido desarrollada como un proyecto personal para su uso en la aplicación pasantes®.

⚠️ Estado del Proyecto

IMPORTANTE: Esta librería se encuentra actualmente en fase de desarrollo. No se recomienda su uso en entornos de producción hasta que se alcance una versión estable (1.0.0). Las APIs pueden cambiar sin previo aviso entre versiones menores.

💻 ¿Cómo usar la librería?

Como dependencia en tu proyecto

npm install --save ngx-autofirma

Configuración básica

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { AutofirmaService, autofirmaServiceFactory } from 'ngx-autofirma';

export const appConfig: ApplicationConfig = {
  providers: [{ provide: AutofirmaService, useFactory: autofirmaServiceFactory }],
};

Uso en un componente

import { Component, inject } from '@angular/core';
import { AutofirmaService, autofirmaServiceFactory } from 'ngx-autofirma';

@Component({
  selector: 'ngx-autofirma-demo',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
  providers: [{ provide: AutofirmaService, useFactory: autofirmaServiceFactory }],
})
export class AppComponent {
  private readonly autofirma: AutofirmaService = inject(AutofirmaService);

  ngOnInit(): void {
    this.autofirma.init();
  }
}

📚 Referencia de la API

Interfaces

File

Interfaz que representa un archivo con su nombre y contenido en base64.

interface File {
  name: string;
  contentBase64: string;
}

Propiedades

• name {string} - Nombre del archivo seleccionado.
• contentBase64 {string} - Contenido del archivo codificado en base64.

AutofirmaService

El servicio principal que proporciona la funcionalidad de firma digital. Es una clase abstracta que debe ser instanciada mediante el factory autofirmaServiceFactory.

Métodos

init

Inicializa la conexión con el cliente AutoFirma. Debe ser llamado antes de usar cualquier otro método del servicio.

init(): void

Ejemplo de uso:

ngOnInit(): void {
  this.autofirma.init();
}

echo

Verifica la conexión con el cliente AutoFirma enviando un mensaje de prueba.

echo(): Observable<string>

Retorno

• {Observable} - Retorna un Observable con el mensaje de respuesta del cliente AutoFirma.

Ejemplo de uso:

this.autofirma.echo().subscribe({
  next: (response) => {
    console.log('Conexión establecida:', response);
  },
  error: (error) => {
    console.error('Error de conexión:', error);
  },
});

selectCertificate

Permite al usuario seleccionar un certificado digital del almacén de claves configurado.

selectCertificate(extraParams?: string): Observable<string>

Parámetros

• extraParams {string} (opcional) - Parámetros adicionales para la selección del certificado.

Retorno

• {Observable} - Retorna un Observable con el certificado seleccionado en formato base64.

Ejemplo de uso:

this.autofirma.selectCertificate().subscribe({
  next: (certificate) => {
    console.log('Certificado seleccionado:', certificate);
  },
  error: (error) => {
    console.error('Error al seleccionar certificado:', error);
  },
});

getFileNameContentBase64

Permite seleccionar un archivo local del sistema y obtener su contenido en formato base64.

getFileNameContentBase64(
  title: string,
  extensions: string,
  description: string,
  filePath: string
): Observable<File>

Parámetros

• title {string} - Título del diálogo de selección.
• extensions {string} - Listado de extensiones de fichero permitidas. Estas aparecerán separadas por una coma (',') y sin espacios entre ellas. Por ejemplo: 'pdf,jpg,txt'. El diálogo sólo mostrará los ficheros con estas extensiones, salvo que el usuario establezca lo contrario manualmente en el diálogo.
• description {string} - Descripción del tipo de fichero que se espera cargar. Esta descripción aparecerá asociada a las extensiones indicadas.
• filePath {string} - Ruta absoluta del fichero que se debería seleccionar por defecto o sólo el nombre de fichero sugerido.

Retorno

• {Observable} - Retorna un Observable con un objeto File que contiene el nombre y el contenido en base64 del archivo seleccionado.

Ejemplo de uso:

this.autofirma.getFileNameContentBase64('Seleccionar documento', 'pdf', 'Documentos PDF', '/ruta/inicial').subscribe({
  next: (file: File) => {
    console.log('Nombre del archivo:', file.name);
    console.log('Contenido en base64:', file.contentBase64);
  },
  error: (error) => {
    console.error('Error al seleccionar el archivo:', error.message);
  },
});

Notas importantes

• Este caso de uso no es compatible con el Cliente iOS.
• El método abre un diálogo nativo para seleccionar el archivo.
• Si el usuario cancela la selección, se lanzará un error con el mensaje "Operación cancelada por el usuario".
• El archivo seleccionado se convierte automáticamente a base64.
• El resultado es un objeto que implementa la interfaz File.

getCurrentLog

Obtiene el log actual del cliente AutoFirma.

getCurrentLog(): Observable<string>

Retorno

• {Observable} - Retorna un Observable con el contenido del log.

Ejemplo de uso:

this.autofirma.getCurrentLog().subscribe({
  next: (log) => {
    console.log('Log de AutoFirma:', log);
  },
});

setKeyStore

Establece el almacén de claves a utilizar. Si se cambia el almacén, se resetea automáticamente el signatario sticky.

setKeyStore(keyStore: KeyStore | null): void

Parámetros

• keyStore {KeyStore | null} - El almacén de claves a utilizar. Si es null, se utilizará el almacén por defecto del navegador.

Ejemplo de uso:

import { KeyStore } from 'ngx-autofirma';

// Usar almacén de claves de Mozilla
this.autofirma.setKeyStore(KeyStore.Mozilla);

// Usar almacén por defecto
this.autofirma.setKeyStore(null);

setStickySignatory

Establece si el signatario debe mantenerse entre operaciones (sticky).

setStickySignatory(sticky: boolean): void

Parámetros

• sticky {boolean} - Si es true, el signatario se mantendrá entre operaciones. Si es false, se reseteará.

Ejemplo de uso:

// Mantener el signatario entre operaciones
this.autofirma.setStickySignatory(true);

getErrorMessage

Obtiene el último mensaje de error generado por el servicio.

getErrorMessage(): string

Retorno

• {string} - El mensaje de error, o una cadena vacía si no hay error.

Ejemplo de uso:

const errorMessage = this.autofirma.getErrorMessage();
if (errorMessage) {
  console.error('Error:', errorMessage);
}

getErrorType

Obtiene el tipo del último error generado por el servicio.

getErrorType(): string

Retorno

• {string} - El tipo de error, o una cadena vacía si no hay error.

Ejemplo de uso:

const errorType = this.autofirma.getErrorType();
if (errorType) {
  console.error('Tipo de error:', errorType);
}

Tipos adicionales

KeyStore

Enumeración que representa los diferentes almacenes de claves soportados:

enum KeyStore {
  Windows = 'WINDOWS',
  Apple = 'APPLE',
  PKCS12 = 'PKCS12',
  PKCS11 = 'PKCS11',
  Mozilla = 'MOZ_UNI',
  SharedNSS = 'SHARED_NSS',
  Java = 'JAVA',
  JCEKS = 'JCEKS',
  JavaCE = 'JAVACE',
  DNIeJava = 'DNIEJAVA',
}

📄 Licencia

Este proyecto está licenciado bajo GPL-2.0.

💬 Incidencias y Comentarios

Si encuentras algún problema con la librería o tienes alguna sugerencia de mejora, puedes:

1. Revisar si el problema ya está reportado en la página de incidencias
2. Crear una nueva incidencia si el problema no está reportado
3. Contribuir con comentarios o soluciones a incidencias existentes

Todas las incidencias, comentarios y sugerencias son bienvenidos y nos ayudan a mejorar la librería.

🔗 Enlaces útiles

• Documentación oficial de @firma
• Descargar la última versión disponible de AutoFirma