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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
chore(extensions): author signing tool + signing spec docs
Juan Denisa4329124dd46
diff --git a/.gitignore b/.gitignoreindex 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.mdindex 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 optionalnever logged). See [`POST /api/v1/plugins/preview`](EXTENSIONS_REGISTRY.md) andthe 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 noteA dockerized backend only sees `/app`, not the host's `frontend/` tree. To installdiff --git a/scripts/sign-extension.mjs b/scripts/sign-extension.mjsnew file mode 100644index 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);+}