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>" }
authorKeyes 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
signaturea 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¶
- En Kino, Plugins ▸ Agregar plugin, escribe
tu-usuario/tu-plugin. - La ventana de instalación tiene que decir "Firmado por su autor".
- 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:
- Haz tus cambios en
plugin.js. - Sube
versionenkino-plugin.json(por ejemplo1.0.0→1.0.1). Sin eso, nadie recibe la actualización. - Firma otra vez con la misma clave (paso 4) y comprueba (paso 5).
- 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:
- Cambia
plugin.jsy subeversion. git commit -am "1.0.1": el hook firma y agrega la firma al mismo commit.-
git tag v1.0.1 && git push origin main v1.0.1. -
Si el hook ve cambios de
plugin.jssin agregar al commit, se detiene: firmaría un código distinto del que subes. - Los hooks no viajan con el repositorio: lo creas una vez en cada computador desde el que publicas.
- 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.
- [ ]
*.pemestá en.gitignore. - [ ]
"apiVersion"es 5 o más. - [ ] Firmaste después del último cambio a
plugin.jsy aversion. - [ ]
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.