Skip to content

Sign your plugin, step by step

This tutorial takes you from an unsigned plugin to a signed, published one, and then through every update. To understand first what a signature is and what it protects, read Signed plugins; here are only the steps.

What you will get

Whoever installs your plugin sees "Firmado por su autor" on the install sheet, and Kino refuses any update that does not come from your key, even if someone gets into your GitHub account.

Before you start

You need:

  • Node.js 18 or newer (node --version).
  • The sdk/ kit inside the plugin's folder. If you created your repository from an example with "Use this template", you already have it.
  • Your plugin in a public GitHub repository. The signature is bound to that repository: it only counts when the plugin is installed from there, not from a manifest URL on another server.
  • Kino 0.9.45 or newer on the devices of the people who install it.

In the commands below, replace your-user/your-plugin with your repository.

Step 1: create your key (once)

The key is yours for good: you will use it for every version of this plugin. Create it outside the repository, in a private folder:

mkdir -p ~/.config/kino && chmod 700 ~/.config/kino
cd ~/.config/kino
node /path/to/your-plugin/sdk/seal.mjs --keygen
chmod 600 kino-author-key.pem

The command writes kino-author-key.pem and prints its fingerprint, something like 07DA-B67F-2ACF-B4D3. Note it down: it is what Kino shows in your plugin's details.

Back it up now

Keep kino-author-key.pem in a password manager or on an encrypted disk. There is no way to recover it: if you lose it, Kino refuses your updates and everyone has to uninstall your plugin and install it again (what happens).

Use a new key just for this: do not reuse your GitHub SSH key or any other.

Step 2: protect the repository

Even though the key lives outside the repository, add *.pem to .gitignore in case you ever copy it there by mistake:

cd /path/to/your-plugin
echo '*.pem' >> .gitignore

The kit protects you too: validate.mjs fails when a .pem file is tracked by git.

Step 3: raise the apiVersion

A signature needs "apiVersion": 5 or newer in kino-plugin.json. If your plugin already uses 6, 7 or 8, leave it:

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

Step 4: sign

Always after the last change to plugin.js and to version:

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

The command writes into your kino-plugin.json:

"signature": { "authorKey": "<64 hex characters>", "value": "<128 hex characters>" }
  • authorKey is your public key: it is fine for it to be visible.
  • If your plugin lives in a folder of the repository, use --repo your-user/your-repo/folder.
  • Do not edit signature by hand.

Step 5: check

node sdk/validate.mjs . --repo your-user/your-plugin

It must end in ✓ Kino would accept this plugin and print Clave del autor: XXXX-XXXX-XXXX-XXXX with the fingerprint from step 1. If it says the signature is not valid, see When something fails.

Step 6: publish

Push kino-plugin.json (with the signature) and plugin.js. A tag lets people pin a version:

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 takes up to about five minutes to serve the new files.

Step 7: check it in Kino

  1. In Kino, Plugins ▸ Agregar plugin, type your-user/your-plugin.
  2. The install sheet must say "Firmado por su autor".
  3. After installing, the plugin's details (phone: Gestionar; TV: the plugin's actions) show "Clave del autor" with your fingerprint.

From that first install on, Kino remembers your key for that person.

Every update

Always repeat these four steps, in this order:

  1. Make your changes to plugin.js.
  2. Raise version in kino-plugin.json (for example 1.0.0 → 1.0.1). Without it, nobody gets the update.
  3. Sign again with the same key (step 4) and check (step 5).
  4. Commit, tag and push (step 6).

The signature covers your exact plugin.js, the id, the version and the repository: changing a single byte, even a comment, breaks it. If you only change the README or the screenshots, there is no need to sign again.

Once you sign, always sign

An update that is unsigned or signed with another key is refused for everyone who already has your plugin. If your plugin was published unsigned and you start signing it, Kino asks each person to approve that update once.

Sign without thinking: let git sign for you

The signature "expiring" with every change is on purpose: it is what stops changed code from being published in your name. But you do not have to remember to sign: a git hook can do it on every commit, on your own computer.

Create the file .git/hooks/pre-commit in your repository:

#!/bin/sh
# Signs plugin.js before every commit. The signature must cover what is committed, so plugin.js
# must have no changes left out of the commit.
if ! git diff --quiet -- plugin.js kino-plugin.json; then
  echo "pre-commit: add plugin.js and kino-plugin.json to the commit first (git add plugin.js kino-plugin.json)" >&2
  exit 1
fi
node sdk/seal.mjs --sign --repo your-user/your-plugin --key ~/.config/kino/kino-author-key.pem >/dev/null || exit 1
git add kino-plugin.json

and make it executable:

chmod +x .git/hooks/pre-commit

From then on, every update is:

  1. Change plugin.js and raise version.
  2. git commit -am "1.0.1": the hook signs and adds the signature to the same commit.
  3. git tag v1.0.1 && git push origin main v1.0.1.

  4. If the hook sees changes to plugin.js left out of the commit, it stops: it would sign different code from what you push.

  5. Hooks do not travel with the repository: create it once on each computer you publish from.
  6. If your plugin lives in a folder of the repository, change the paths (folder/plugin.js, node folder/sdk/seal.mjs … --manifest folder/kino-plugin.json) and the --repo (your-user/your-repo/folder).

Do not sign in GitHub Actions

Signing in the cloud means storing your private key in the repository's secrets, and whoever gets into your GitHub account could sign as you: exactly what the signature must prevent. Always sign on your own computer.

Quick checklist

  • [ ] The key is outside the repository and backed up.
  • [ ] *.pem is in .gitignore.
  • [ ] "apiVersion" is 5 or newer.
  • [ ] You signed after the last change to plugin.js and version.
  • [ ] validate.mjs --repo … says ✓ and prints your fingerprint.
  • [ ] Kino's install sheet says "Firmado por su autor".

A real example

Internet Archive Audio is signed this way (fingerprint 07DA-B67F-2ACF-B4D3): see the signature block of its kino-plugin.json.

See also: Signed plugins (what the signature protects, how to look after the key, error messages), the manifest's signature field and Publishing.