Saltar a contenido

Firma tu plugin, paso a paso

Este tutorial te lleva de un plugin sin firma a uno firmado y publicado, y después por cada actualización. Si quieres entender primero qué es una firma y qué protege, lee Plugins firmados; aquí solo están los pasos.

Lo que vas a lograr

Quien instale tu plugin verá "Firmado por su autor" en la ventana de instalación, y Kino rechazará cualquier actualización que no venga de tu clave, aunque alguien entre a tu cuenta de GitHub.

Antes de empezar

Necesitas:

  • Node.js 18 o más nuevo (node --version).
  • El kit sdk/ dentro de la carpeta del plugin. Si creaste tu repositorio desde un ejemplo con "Use this template", ya lo tienes.
  • Tu plugin en un repositorio público de GitHub. La firma queda atada a ese repositorio: solo vale cuando el plugin se instala desde ahí, no desde una URL de manifiesto en otro servidor.
  • Kino 0.9.45 o más nuevo en los aparatos de quienes lo instalen.

En los comandos de abajo, cambia tu-usuario/tu-plugin por tu repositorio.

Paso 1: crea tu clave (una sola vez)

La clave es tuya para siempre: la vas a usar en todas las versiones de este plugin. Créala fuera del repositorio, en una carpeta privada:

mkdir -p ~/.config/kino && chmod 700 ~/.config/kino
cd ~/.config/kino
node /ruta/a/tu-plugin/sdk/seal.mjs --keygen
chmod 600 kino-author-key.pem

El comando escribe kino-author-key.pem e imprime su huella, algo como 07DA-B67F-2ACF-B4D3. Anótala: es la que Kino mostrará en los detalles de tu plugin.

Haz una copia de seguridad ahora

Guarda kino-author-key.pem en un gestor de contraseñas o en un disco cifrado. No hay forma de recuperarla: si la pierdes, Kino rechaza tus actualizaciones y cada persona tiene que desinstalar tu plugin e instalarlo otra vez (qué pasa).

Usa una clave nueva solo para esto: no reutilices tu clave SSH de GitHub ni ninguna otra.

Paso 2: protege el repositorio

Aunque la clave vive fuera del repositorio, agrega *.pem al .gitignore por si algún día la copias ahí por error:

cd /ruta/a/tu-plugin
echo '*.pem' >> .gitignore

El kit también te protege: validate.mjs falla si un .pem está en git.

Paso 3: sube el apiVersion

La firma necesita "apiVersion": 5 o más en kino-plugin.json. Si tu plugin ya usa 6, 7 u 8, déjalo así:

"apiVersion": 8,
"entry": "plugin.js"

Paso 4: firma

Siempre después del último cambio a plugin.js y a version:

node sdk/seal.mjs --sign --repo tu-usuario/tu-plugin --key ~/.config/kino/kino-author-key.pem

El comando escribe en tu kino-plugin.json:

"signature": { "authorKey": "<64 caracteres hex>", "value": "<128 caracteres hex>" }
  • authorKey es tu clave pública: está bien que sea visible.
  • Si tu plugin vive en una carpeta del repositorio, usa --repo tu-usuario/tu-repo/carpeta.
  • No edites signature a mano.

Paso 5: comprueba

node sdk/validate.mjs . --repo tu-usuario/tu-plugin

Tiene que terminar en ✓ Kino would accept this plugin y mostrar Clave del autor: XXXX-XXXX-XXXX-XXXX con la huella del paso 1. Si dice que la firma no es válida, mira Cuando algo falla.

Paso 6: publica

Sube kino-plugin.json (con la firma) y plugin.js. Un tag ayuda a que la gente pueda fijar una versión:

git add kino-plugin.json plugin.js .gitignore
git commit -m "Signed release 1.0.0"
git tag v1.0.0
git push origin main v1.0.0

GitHub tarda hasta unos cinco minutos en servir los archivos nuevos.

Paso 7: compruébalo en Kino

  1. En Kino, Plugins ▸ Agregar plugin, escribe tu-usuario/tu-plugin.
  2. La ventana de instalación tiene que decir "Firmado por su autor".
  3. Después de instalar, los detalles del plugin (celular: Gestionar; TV: las acciones del plugin) muestran "Clave del autor" con tu huella.

Desde esa primera instalación, Kino recuerda tu clave para esa persona.

Cada actualización

Repite siempre estos cuatro pasos, en este orden:

  1. Haz tus cambios en plugin.js.
  2. Sube version en kino-plugin.json (por ejemplo 1.0.0 → 1.0.1). Sin eso, nadie recibe la actualización.
  3. Firma otra vez con la misma clave (paso 4) y comprueba (paso 5).
  4. Commit, tag y push (paso 6).

La firma cubre tu plugin.js exacto, el id, la version y el repositorio: cambiar un solo byte, aunque sea un comentario, la invalida. Si cambias solo el README o las capturas, no hace falta firmar otra vez.

Una vez que firmas, firma siempre

Una actualización sin firma o con otra clave se rechaza para todos los que ya tienen tu plugin. Si tu plugin estaba publicado sin firma y empiezas a firmarlo, Kino le pide a cada persona aprobar esa actualización una vez.

Firmar sin pensarlo: que git firme por ti

Que la firma "se venza" con cada cambio es a propósito: es lo que impide publicar código cambiado a tu nombre. Pero no tienes que acordarte de firmar: un hook de git puede hacerlo en cada commit, en tu propio computador.

Crea el archivo .git/hooks/pre-commit en tu repositorio:

#!/bin/sh
# Firma plugin.js antes de cada commit. La firma tiene que cubrir lo que se sube, así que
# plugin.js no puede tener cambios fuera del commit.
if ! git diff --quiet -- plugin.js kino-plugin.json; then
  echo "pre-commit: agrega plugin.js y kino-plugin.json al commit (git add plugin.js kino-plugin.json)" >&2
  exit 1
fi
node sdk/seal.mjs --sign --repo tu-usuario/tu-plugin --key ~/.config/kino/kino-author-key.pem >/dev/null || exit 1
git add kino-plugin.json

y dale permiso de ejecución:

chmod +x .git/hooks/pre-commit

Desde ahí, cada actualización es:

  1. Cambia plugin.js y sube version.
  2. git commit -am "1.0.1": el hook firma y agrega la firma al mismo commit.
  3. git tag v1.0.1 && git push origin main v1.0.1.

  4. Si el hook ve cambios de plugin.js sin agregar al commit, se detiene: firmaría un código distinto del que subes.

  5. Los hooks no viajan con el repositorio: lo creas una vez en cada computador desde el que publicas.
  6. Si tu plugin vive en una carpeta del repositorio, cambia las rutas (carpeta/plugin.js, node carpeta/sdk/seal.mjs … --manifest carpeta/kino-plugin.json) y el --repo (tu-usuario/tu-repo/carpeta).

No firmes en GitHub Actions

Para firmar en la nube tendrías que guardar tu clave privada en los secretos del repositorio, y quien entre a tu cuenta de GitHub podría firmar como tú: justo lo que la firma debe impedir. Firma siempre en tu computador.

Lista rápida

  • [ ] La clave está fuera del repositorio y tiene copia de seguridad.
  • [ ] *.pem está en .gitignore.
  • [ ] "apiVersion" es 5 o más.
  • [ ] Firmaste después del último cambio a plugin.js y a version.
  • [ ] validate.mjs --repo … dice ✓ y muestra tu huella.
  • [ ] La ventana de instalación de Kino dice "Firmado por su autor".

Un ejemplo real

Internet Archive Audio está firmado así (huella 07DA-B67F-2ACF-B4D3): mira el bloque signature de su kino-plugin.json.

Mira también: Plugins firmados (qué protege la firma, cómo cuidar la clave, mensajes de error), el campo signature del manifiesto y Publicar.