🔐 Firmas criptográficas de bloques

Firme sus bloques para garantizar autenticidad y no repudio

📦 Package NPM @sowasit/signer 📚 API Reference

Introducción

SoWasIt le permite firmar criptográficamente sus bloques para garantizar su autenticidad y no repudio. Utilizando una Infraestructura de Clave Pública (PKI) con algoritmos ECDSA P-256, puede probar que su organización creó un bloque específico.

💡 Casos de uso :

Cumplimiento regulatorio (firma electrónica cualificada)
Prueba legal de creación de datos
Auditoría y trazabilidad mejoradas
No repudio de transacciones

¿Por qué hacer que un socio firme?

Escenario real: una disputa de entrega

TechCorp se abastece de componentes de SupplyPro y gestiona sus entregas en una cadena SoWasIt. Esto es lo que ocurre según si SupplyPro firma o no los bloques.

❌ Sin firma del socio — el problema

El 15 de enero, SupplyPro realiza una entrega. TechCorp registra ella misma un bloque: "Entrega recibida: 500 unidades, ref. ABC-789".

Tres meses después, SupplyPro envía una factura por 800 unidades, afirmando haber entregado esa cantidad. TechCorp muestra sus bloques que dicen "500 unidades"... pero SupplyPro argumenta que TechCorp creó esos bloques. Nada impidió a TechCorp escribir 500 en lugar de 800 para reducir su factura. Es la palabra de uno contra la del otro.

El problema: si eres tú quien registra los datos en nombre del socio, nada prueba que el socio estuviera de acuerdo con lo que escribiste.

✅ Con firma del socio — la solución

SupplyPro genera su par de claves ECDSA con @sowasit/signer y lo registra con TechCorp. A partir de ahora, para cada entrega, es el propio sistema de SupplyPro quien crea y firma el bloque: "Entrega confirmada: 500 unidades, ref. ABC-789". Opcionalmente, TechCorp puede republicar una versión del bloque que firma él mismo, para confirmar la recepción. Mediante un webhook, el repartidor es notificado y la entrega queda asegurada.

Tres meses después, SupplyPro envía igualmente una factura por 800 unidades. TechCorp saca el bloque firmado por el propio SupplyPro que certifica 500 unidades entregadas. La firma criptográfica de SupplyPro está ahí, verificable e irrevocable — SupplyPro no puede pretender haber entregado 800.

En caso de disputa, TechCorp presenta los bloques firmados por SupplyPro. La prueba es criptográficamente irrefutable y legalmente ejecutable: SupplyPro certificó la cifra por sí mismo.

Otros casos de uso

El mismo principio se aplica en muchos sectores:

Un transportista firma albaranes en su cadena logística
Un organismo de certificación firma sus bloques de auditoría de calidad
Un proveedor firma sus informes de intervención en su GMAO
Un cliente firma su validación de pedido o recepción
Un socio financiero firma las confirmaciones de pago

En resumen: el verdadero valor de las firmas proviene de que un tercero de confianza — no usted — sella los datos. Esto convierte su cadena en una prueba bilateral, oponible a ambas partes.

Ciclo de vida de una clave

1️⃣ Generación de token de inscripción → El propietario de la cadena genera un token para un socio

2️⃣ Generación de par de claves → El socio usa el CLI para crear sus claves ECDSA

3️⃣ Registro de clave pública → El socio envía su clave pública a SoWasIt

4️⃣ Certificación → El socio imprime, firma y sube el documento de certificación

5️⃣ Verificación → El propietario de la cadena verifica el documento del socio

6️⃣ Activación → El propietario activa la clave, el socio puede firmar bloques

7️⃣ Revocación (si es necesario) → El propietario revoca una clave comprometida u obsoleta

Instalación del CLI

El paquete @sowasit/signer está disponible en NPM y se puede usar como herramienta CLI o biblioteca JavaScript/TypeScript.

Instalación global (CLI)

npm install -g @sowasit/signer

Instalación local (biblioteca)

npm install @sowasit/signer

Inicio rápido

1. Generar y registrar un par de claves (Socio)

Primero, obtenga un token de inscripción del propietario de la cadena, luego:

signer add-key \
  --token YOUR_ENROLLMENT_TOKEN \
  --api-key YOUR_API_KEY \
  --passphrase your-secret-passphrase \
  --output ./keys \
  --client-name "Your Company Name" \
  --client-contact "admin@company.com"

Este comando:

Generará un par de claves ECDSA P-256
Registrará la clave pública con SoWasIt
Guardará las claves localmente en ./keys/
Generará un documento de certificación para imprimir, firmar y subir

2. Completar la certificación (Socio)

⚠️ Paso obligatorio: Para permitir que el propietario de la cadena active su clave, debe:

Imprimir el documento de certificación generado (sowasit.certification.txt)
Firmarlo y sellarlo (firma legal de su empresa)
Escanearlo como PDF
Subirlo a través de la API o el panel

3. Crear un bloque firmado (Socio)

Una vez que el propietario de la cadena haya activado su clave (status = active), puede firmar bloques:

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4d5e6f7g8 \
  --api-key sk_your_api_key \
  --content-file ./data.json \
  --passphrase your-secret-passphrase

Referencia CLI

`signer add-key`

Genera un nuevo par de claves y lo registra con SoWasIt.

Option	Description	Required
`-t, --token`	Token de inscripción desde SoWasIt	✓
`-k, --api-key`	Su clave API de SoWasIt	✓
`-o, --output`	Directorio de salida (predeterminado: ./keys)
`-p, --passphrase`	Frase de contraseña para cifrar la clave privada	Recomendado
`--client-name`	Nombre de su empresa
`--client-contact`	Email de contacto

`signer sign`

Firma contenido con su clave privada (sin crear un bloque).

signer sign \
  --key ./keys/sowasit.private.pem \
  --data ./content.json \
  --passphrase secret \
  --output ./signature.json

`signer create-block`

Crea un bloque firmado directamente en SoWasIt.

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4 \
  --api-key sk_xxx \
  --content '{"order": "ORD-001", "status": "shipped"}' \
  --passphrase secret

Uso programático (JavaScript/TypeScript)

Generar un par de claves

import { KeyManager } from '@sowasit/signer';

// Generate key pair
const keyPair = await KeyManager.generateKeyPair({
  passphrase: 'your-secret-passphrase'
});

// Save to disk
await KeyManager.saveKeyPair(keyPair, './keys', 'my-company');

console.log('Key ID:', keyPair.keyId);
console.log('Fingerprint:', keyPair.fingerprint);

Firmar contenido

import { KeyManager } from '@sowasit/signer';

const content = {
  transaction_id: 'TXN-001',
  amount: 1500.00,
  timestamp: Date.now()
};

const privateKey = await KeyManager.loadPrivateKey(
  './keys/my-company.private.pem',
  'your-passphrase'
);

const { signature, algorithm } = KeyManager.signContent(
  content,
  privateKey
);

console.log('Signature:', signature);

Crear un bloque firmado

import { SoWasItClient } from '@sowasit/signer';
import fs from 'node:fs/promises';

const client = new SoWasItClient({
  apiKey: 'sk_your_api_key'
});

const content = {
  event: 'product_shipped',
  order_id: 'ORD-12345',
  timestamp: Date.now()
};

const privateKeyPem = await fs.readFile('./keys/my-company.private.pem', 'utf-8');

const response = await client.createSignedBlock(
  'ch_your_chain_id',
  content,
  privateKeyPem,
  'your_public_key_id',
  'your-passphrase'
);

console.log('Block created:', response.block);

Mejores prácticas de seguridad

🔒 Protección de claves privadas

Siempre use una frase de contraseña para cifrar su clave privada
Nunca cometa claves privadas en Git
Almacene las claves en un gestor de contraseñas o HSM
Las claves privadas se guardan automáticamente con permisos 0600

🔄 Rotación de claves

Genere nuevas claves regularmente (cada 6-12 meses)
Use el mecanismo de reemplazo durante la rotación
Revoque las claves antiguas después de la migración

⚠️ En caso de compromiso

Revoque inmediatamente la clave comprometida
Genere un nuevo par de claves
Notifique al equipo de SoWasIt si es necesario

Endpoints API

POST /keys/enrollment-tokens

Genera un token de inscripción de un solo uso (validez de 7 días).

curl -X POST https://api.sowasit.io/v1/keys/enrollment-tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "authorized_by": "admin@company.com"
    },
    "validity_days": 7
  }'

POST /keys/register

Registra una clave pública con un token de inscripción.

curl -X POST https://api.sowasit.io/v1/keys/register \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_token": "abc123...",
    "public_key": "-----BEGIN PUBLIC KEY-----\n...",
    "algorithm": "ECDSA-P-256",
    "client_info": {
      "name": "My Company SARL",
      "siret": "12345678901234",
      "contact": "admin@company.com"
    }
  }'

GET /keys

Lista todas sus claves públicas.

curl https://api.sowasit.io/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /keys/{keyId}/revoke

Revoca una clave pública.

curl -X POST https://api.sowasit.io/v1/keys/abc123/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Key compromised"
  }'

Solución de problemas

❌ "Block signature is required: tenant has active public keys"

Su tenant tiene claves activas registradas, por lo que todos los bloques deben estar firmados.

Solución: Use signer create-block o firme manualmente con signer sign.

❌ "Invalid passphrase for encrypted private key"

Su clave está cifrada pero proporcionó la frase de contraseña incorrecta o ninguna frase de contraseña.

Solución: Proporcione la frase de contraseña correcta con --passphrase.

❌ "Invalid block signature"

La verificación de la firma falló.

Causas posibles:

El contenido se modificó después de la firma
Se usó una clave privada incorrecta
Formato de firma inválido
El ID de clave pública no coincide con la clave de firma

❌ "Public key is not active"

La clave aún no está activada o ha sido revocada.

Solución: Verifique el estado de la clave en su panel. Complete la certificación si es necesario.

Soporte

Documentación completa: sowasit.io/documentation
Paquete NPM: @sowasit/signer
Panel: sowasit.io/dashboard
Email: support@sowasit.io