Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

chore(extensions): author signing tool + signing spec docs

Juan Denisa4329124dd46
diff --git a/.gitignore b/.gitignore
index ab94cbd7..4e2ce3d3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -201,3 +201,6 @@ frontend/src/plugins/serverkit-k8s/
frontend/src/plugins/serverkit-mail/
frontend/src/plugins/serverkit-tramo/
/graphify-out
+
+# Extension release signing keys (private halves — never commit; see scripts/sign-extension.mjs)
+scripts/keys/
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index b323d138..e2b5d9c2 100644
--- a/docs/EXTENSIONS.md
+++ b/docs/EXTENSIONS.md
@@ -561,6 +561,68 @@ Private repos and GitHub's anonymous rate limit are handled by the optional
never logged). See [`POST /api/v1/plugins/preview`](EXTENSIONS_REGISTRY.md) and
the site's [Installing](https://serverkit.ai/docs/extensions/installing) guide.
+### Release signing (ed25519)
+
+Release zips can carry a **detached ed25519 signature** so the panel proves
+*origin*, not just integrity (a sha256 in the index only says the bytes match
+the index — whoever can edit the index can edit the hash beside it). The scheme
+is deliberately minimal (plan 55, D3): no PKI, no key servers.
+
+**Signature format** — a minisign-style envelope, base64 of 74 bytes:
+
+```
+"ED" (2 bytes) || key_num (8 bytes) || ed25519 signature (64 bytes)
+```
+
+- `ED` marks a *pure* ed25519 signature over the raw zip bytes.
+- `key_num` is `sha256(public_key)[:8]`, binding the envelope to the exact
+ key that made it — a `publisher_key_id` cannot be pointed at a different
+ pinned key than the one that signed.
+
+**Sign a release** with `scripts/sign-extension.mjs`:
+
+```bash
+# once per publisher — keep the key file PRIVATE and out of git
+node scripts/sign-extension.mjs keygen --key-id my-publisher --out <safe dir>
+
+# per release — writes <bundle>.zip.minisig and prints the index fields
+node scripts/sign-extension.mjs sign my-ext-1.0.0.zip --key <safe dir>/my-publisher.signing-key.json
+```
+
+Ship the `.minisig` beside the zip as a release asset (the GitHub preview flow
+looks for `<zip URL>.minisig` automatically). For registry-listed extensions,
+paste the printed `signature` + `publisher_key_id` into the index entry
+(schema v3; v1/v2 indexes without them stay valid — those entries are simply
+treated as unsigned).
+
+**Key model.** The panel pins publisher public keys in
+`backend/app/data/extension_signing_keys.json` (the `serverkit-official`
+first-party key ships there). Operators can trust additional publisher keys via
+`SERVERKIT_TRUSTED_EXTENSION_KEYS` (path to a JSON file with the same shape) —
+that file is also the rotation path: pin the new key, sign new releases with
+it, remove the old entry once nothing references it.
+
+**What the panel does with a signature** (verify logic:
+`app/services/signing_service.py`):
+
+| Verdict | Meaning | Install behavior |
+|---|---|---|
+| `verified` | Signature valid under a pinned key | Installs; no extra friction |
+| `unsigned` | No signature present | Installs behind the existing consent surfaces (preview card badge, registry risk dialog) — never a hard block |
+| `untrusted_key` | Signed, but the publisher key isn't pinned | Registry: 409 consent ("install anyway"); manual: consent card warns |
+| `invalid` | Malformed envelope, key-id mismatch, or verify failed | **Hard failure, always.** Acknowledgment can never override a bad signature |
+
+The verdict is stamped on the installed extension (panel-managed `_signature`
+config key, surfaced as `signature` in the plugin API dict) so origin
+verification stays visible after install. The sha256 runtime-frontend hash
+check is unaffected — signatures cover the zip, `_frontend_hashes` still pins
+the served `.mjs` bundle bytes.
+
+Honesty note (D2): a signature verifies *when present*. Until every
+first-party release is signed, an unsigned first-party index entry still
+installs on the strength of the index itself (TLS + the registry repo's PR
+review), so the index's integrity remains part of the trust story.
+
### Docker note
A dockerized backend only sees `/app`, not the host's `frontend/` tree. To install
diff --git a/scripts/sign-extension.mjs b/scripts/sign-extension.mjs
new file mode 100644
index 00000000..1a0fd4ff
--- /dev/null
+++ b/scripts/sign-extension.mjs
@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * sign-extension.mjs — sign ServerKit extension release zips (plan 55, D3).
+ *
+ * Extensions are signed with ed25519 detached signatures in a minisign-style
+ * envelope: base64 of "ED" (2 bytes) || key_num (8 bytes) || signature (64
+ * bytes), where the signature is over the raw zip bytes and key_num is
+ * sha256(public_key)[:8]. The panel pins publisher public keys in
+ * backend/app/data/extension_signing_keys.json and verifies at install;
+ * unsigned extensions install behind an explicit consent step, and a bad
+ * signature is a hard failure. See docs/EXTENSIONS.md ("Release signing").
+ *
+ * Usage:
+ * node scripts/sign-extension.mjs keygen --key-id <id> [--out <dir>]
+ * Generate a publisher keypair. Writes <out>/<id>.signing-key.json
+ * (KEEP THIS FILE PRIVATE and out of git) and prints the public-key
+ * entry to pin in extension_signing_keys.json.
+ *
+ * node scripts/sign-extension.mjs sign <bundle.zip> --key <keyfile.json>
+ * Signs the zip, writes <bundle.zip>.minisig next to it, and prints
+ * the `signature` / `publisher_key_id` fields for the registry index.
+ *
+ * node scripts/sign-extension.mjs verify <bundle.zip> --key <keyfile.json>
+ * Local sanity check that a zip verifies against the key's public half
+ * (the same check the panel runs at install).
+ */
+import { createHash, generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const MARKER = Buffer.from('ED'); // pure ed25519 over raw bytes
+const KEY_NUM_LEN = 8;
+
+const fail = (msg) => {
+ process.stderr.write(`error: ${msg}\n`);
+ process.exit(1);
+};
+
+const keyNumFor = (pubRaw) =>
+ createHash('sha256').update(pubRaw).digest().subarray(0, KEY_NUM_LEN);
+
+function loadKeyFile(path) {
+ if (!existsSync(path)) fail(`key file not found: ${path}`);
+ let data;
+ try {
+ data = JSON.parse(readFileSync(path, 'utf8'));
+ } catch (e) {
+ fail(`could not parse key file ${path}: ${e.message}`);
+ }
+ if (data.algorithm !== 'ed25519' || !data.secret_key_pkcs8 || !data.public_key) {
+ fail(`${path} is not a sign-extension key file (need algorithm/public_key/secret_key_pkcs8)`);
+ }
+ return data;
+}
+
+function cmdKeygen(argv) {
+ let keyId = null;
+ let outDir = '.';
+ for (let i = 0; i < argv.length; i++) {
+ if (argv[i] === '--key-id') keyId = argv[++i];
+ else if (argv[i] === '--out') outDir = argv[++i];
+ }
+ if (!keyId || !/^[a-z0-9][a-z0-9-]*$/.test(keyId)) {
+ fail('keygen needs --key-id <id> (lowercase letters, digits, dashes)');
+ }
+
+ const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+ const pubDer = publicKey.export({ type: 'spki', format: 'der' });
+ const pubRaw = pubDer.subarray(pubDer.length - 32); // SPKI wrapper → raw key
+ const secDer = privateKey.export({ type: 'pkcs8', format: 'der' });
+
+ mkdirSync(outDir, { recursive: true });
+ const keyPath = join(outDir, `${keyId}.signing-key.json`);
+ writeFileSync(keyPath, JSON.stringify({
+ key_id: keyId,
+ algorithm: 'ed25519',
+ created: new Date().toISOString().slice(0, 10),
+ public_key: pubRaw.toString('base64'),
+ secret_key_pkcs8: secDer.toString('base64'),
+ }, null, 2) + '\n', { mode: 0o600 });
+
+ process.stdout.write(`\nPrivate key written to ${keyPath}\n`);
+ process.stdout.write('KEEP IT PRIVATE and out of git — anyone holding it can sign as you.\n');
+ process.stdout.write('\nPin this entry in backend/app/data/extension_signing_keys.json:\n\n');
+ process.stdout.write(JSON.stringify({
+ key_id: keyId,
+ publisher: 'ServerKit (first-party)',
+ algorithm: 'ed25519',
+ public_key: pubRaw.toString('base64'),
+ }, null, 2) + '\n');
+}
+
+function cmdSign(argv) {
+ const zipPath = argv.find((a) => !a.startsWith('--'));
+ let keyPath = null;
+ for (let i = 0; i < argv.length; i++) {
+ if (argv[i] === '--key') keyPath = argv[++i];
+ }
+ if (!zipPath) fail('sign needs a zip path: sign <bundle.zip> --key <keyfile.json>');
+ if (!keyPath) fail('sign needs --key <keyfile.json> (from keygen)');
+ if (!existsSync(zipPath)) fail(`zip not found: ${zipPath}`);
+
+ const key = loadKeyFile(keyPath);
+ const privateKey = createPrivateKey({
+ key: Buffer.from(key.secret_key_pkcs8, 'base64'), format: 'der', type: 'pkcs8',
+ });
+ const pubRaw = Buffer.from(key.public_key, 'base64');
+ const zipBytes = readFileSync(zipPath);
+
+ const sig = edSign(null, zipBytes, privateKey);
+ const envelope = Buffer.concat([MARKER, keyNumFor(pubRaw), sig]);
+ const sigB64 = envelope.toString('base64');
+
+ const sigPath = `${zipPath}.minisig`;
+ writeFileSync(sigPath, sigB64 + '\n');
+
+ process.stdout.write(`\nSignature written to ${sigPath} (ship it beside the zip as a release asset).\n`);
+ process.stdout.write('\nRegistry index fields for this release:\n\n');
+ process.stdout.write(` "signature": "${sigB64}",\n`);
+ process.stdout.write(` "publisher_key_id": "${key.key_id}"\n`);
+}
+
+function cmdVerify(argv) {
+ const positional = argv.filter((a) => !a.startsWith('--') && a !== argv[argv.indexOf('--key') + 1]);
+ const zipPath = positional[0];
+ let keyPath = null;
+ for (let i = 0; i < argv.length; i++) {
+ if (argv[i] === '--key') keyPath = argv[++i];
+ }
+ if (!zipPath) fail('verify needs a zip path: verify <bundle.zip> --key <keyfile.json>');
+ if (!keyPath) fail('verify needs --key <keyfile.json> (only its public half is used)');
+
+ const key = loadKeyFile(keyPath);
+ const sigPath = `${zipPath}.minisig`;
+ if (!existsSync(sigPath)) fail(`signature file not found: ${sigPath}`);
+ const blob = Buffer.from(readFileSync(sigPath, 'utf8').trim(), 'base64');
+ if (blob.length !== 74 || blob.subarray(0, 2).toString() !== 'ED') {
+ fail(`${sigPath} is not a ServerKit ed25519 envelope`);
+ }
+ const pubRaw = Buffer.from(key.public_key, 'base64');
+ if (!blob.subarray(2, 10).equals(keyNumFor(pubRaw))) {
+ fail(`signature was made by a different key than ${keyPath}`);
+ }
+ const publicKey = createPublicKey({
+ key: Buffer.concat([
+ // SPKI prefix for ed25519 (12 bytes) + raw key
+ Buffer.from('302a300506032b6570032100', 'hex'), pubRaw,
+ ]),
+ format: 'der', type: 'spki',
+ });
+ const ok = edVerify(null, readFileSync(zipPath), publicKey, blob.subarray(10));
+ if (!ok) fail('signature does NOT match the zip bytes (tampered or wrong zip)');
+ process.stdout.write(`OK: ${zipPath} verifies with key "${key.key_id}"\n`);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === 'keygen') cmdKeygen(rest);
+else if (command === 'sign') cmdSign(rest);
+else if (command === 'verify') cmdVerify(rest);
+else {
+ process.stderr.write('usage: sign-extension.mjs <keygen|sign|verify> … (see header comment)\n');
+ process.exit(1);
+}