326 lines
19 KiB
JavaScript
326 lines
19 KiB
JavaScript
// `waybetter store build|sign|verify`: builds an app's part of the shared wayBetter Store catalog,
|
|
// signs it offline with the store's Ed25519 key, and verifies it. The rules are the ones the apps
|
|
// enforce natively (waybetter-host `store::catalog`); docs/STORE.md in the framework has the format.
|
|
//
|
|
// waybetter store build --config store.config.mjs [--out dir] [--base https://…/store/]
|
|
// waybetter store sign [catalog.json] --key <private key> [--pub <public key file>]
|
|
// waybetter store sign --init --key <private key> --pub <public key file> (once; never overwrites)
|
|
// waybetter store verify [catalog.json] --pub <public key file> [--app id]
|
|
//
|
|
// The private key is a PKCS#8 PEM that stays where it is: nothing here prints, copies or moves it.
|
|
// `--key` defaults to $WAYBETTER_STORE_KEY. The signature file `<catalog>.sig` is the base64 of the
|
|
// 64-byte signature over the exact catalog bytes; a public key file is the base64 of the raw 32 bytes.
|
|
import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
|
|
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
|
|
import { pathToFileURL } from 'node:url';
|
|
|
|
export const CATALOG_FORMAT = 2;
|
|
export const DEFAULT_BASE = 'https://waybetter.fyi/store/';
|
|
/** The framework's download hosts (waybetter-host `DEFAULT_HOSTS`). */
|
|
export const DEFAULT_HOSTS = [
|
|
{ host: 'waybetter.fyi', rawFilesOnly: false },
|
|
{ host: 'cdn1.crt.fyi', rawFilesOnly: false },
|
|
{ host: 'git.crt.fyi', rawFilesOnly: true },
|
|
];
|
|
export const PERMISSIONS = ['storage', 'ui', 'clipboard', 'account', 'users', 'commands', 'network', 'network:none'];
|
|
const MAX_BYTES = 2 * 1024 * 1024;
|
|
const MAX_ITEMS = 500;
|
|
const MAX_CATALOG_BYTES = 1024 * 1024;
|
|
// SPKI DER prefix of an Ed25519 public key; the raw 32 bytes follow it.
|
|
const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
|
|
|
|
export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
|
|
|
|
/** A plugin header (waybetter-host `parse_meta`), enough for the catalog: name, description, version, author, permissions. */
|
|
export function pluginHeader(source) {
|
|
const meta = { name: '', description: '', version: '', author: '', permissions: null };
|
|
const body = /^?\s*\/\*\*([\s\S]*?)\*\//.exec(source)?.[1];
|
|
if (!body) return meta;
|
|
for (const raw of body.split(/\r?\n/)) {
|
|
const line = raw.trim().replace(/^\*+/, '').trim();
|
|
const match = /^@(\w+)\s*(.*)$/.exec(line);
|
|
if (!match) continue;
|
|
const [, key, value] = match;
|
|
if (key === 'permissions') {
|
|
const list = value.split(/[\s,]+/).map(token => token.toLowerCase()).filter(token => token && token !== 'none');
|
|
for (const token of list) if (!PERMISSIONS.includes(token)) throw new Error(`unknown permission ${token}`);
|
|
meta.permissions = [...new Set([...(meta.permissions ?? []), ...list])];
|
|
// Same cap as the plugin store's parse_meta (300 characters, no control characters).
|
|
} else if (key in meta) meta[key] = [...value.trim()].filter(ch => ch >= ' ').slice(0, 300).join('');
|
|
}
|
|
return meta;
|
|
}
|
|
|
|
// ---- Validation (the same rules as waybetter-host store::catalog) ------------------------------
|
|
|
|
const validAppId = id => typeof id === 'string' && /^[a-z0-9-]{1,32}$/.test(id);
|
|
const validId = id => typeof id === 'string' && /^[a-z0-9-]{1,40}$/.test(id);
|
|
const text = (value, max) => typeof value === 'string' && [...value].length <= max && !/[\p{Cc}]/u.test(value);
|
|
const hex = value => typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value);
|
|
export const validFileName = file => typeof file === 'string' && file.length > '.plugin.js'.length && file.length <= 128
|
|
&& file.endsWith('.plugin.js') && !file.startsWith('.') && /^[A-Za-z0-9_\-. ]+$/.test(file);
|
|
|
|
/** An https URL native code may download from (waybetter-host `allowed_download_url`). */
|
|
export function allowedUrl(value, hosts = DEFAULT_HOSTS) {
|
|
let url;
|
|
try { url = new URL(value); } catch { return false; }
|
|
if (url.protocol !== 'https:' || url.username || url.password || url.port || url.hash || url.href.length > 2048) return false;
|
|
const rule = hosts.find(h => h.host === url.hostname);
|
|
if (!rule) return false;
|
|
if (rule.rawFilesOnly) {
|
|
const segments = url.pathname.split('/').slice(1);
|
|
return segments.length >= 4 && segments[2] === 'raw' && segments.every(s => s && s !== '..');
|
|
}
|
|
return true;
|
|
}
|
|
|
|
const ITEM_FIELDS = new Set(['apps', 'kind', 'id', 'name', 'author', 'version', 'description', 'category', 'tags', 'url', 'file', 'sha256', 'size', 'preview', 'permissions', 'colors', 'language', 'license', 'credits']);
|
|
const LANGUAGE = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/;
|
|
|
|
/** Problems with one item; `hosts` checks the download hosts (the reading app's own items). */
|
|
export function itemProblems(item, hosts) {
|
|
const bad = [];
|
|
if (!item || typeof item !== 'object' || Array.isArray(item)) return ['not an object'];
|
|
for (const key of Object.keys(item)) if (!ITEM_FIELDS.has(key)) bad.push(`unknown field ${key}`);
|
|
if (!Array.isArray(item.apps) || !item.apps.length || item.apps.length > 16 || !item.apps.every(validAppId) || new Set(item.apps).size !== item.apps.length) bad.push('apps');
|
|
if (item.kind !== 'theme' && item.kind !== 'plugin' && item.kind !== 'strings') bad.push('kind');
|
|
// Any item may name its licence and credit its authors; only a string pack has a language.
|
|
if ((item.license !== undefined && (!text(item.license, 60) || !String(item.license).trim())) || (item.credits !== undefined && !text(item.credits, 600))) bad.push('license or credits');
|
|
if (item.kind !== 'strings' && item.language !== undefined) bad.push('language');
|
|
if (!validId(item.id)) bad.push('id');
|
|
if (!text(item.name, 60) || !String(item.name).trim() || !text(item.author ?? '', 60) || !text(item.description ?? '', 600)) bad.push('name, author or description');
|
|
if (!text(item.version, 32) || !item.version || !text(item.category ?? '', 32)) bad.push('version or category');
|
|
if (item.tags !== undefined && (!Array.isArray(item.tags) || item.tags.length > 12 || !item.tags.every(tag => text(tag, 32)))) bad.push('tags');
|
|
if (typeof item.url !== 'string' || !item.url.startsWith('https://') || (hosts && !allowedUrl(item.url, hosts))) bad.push('url (host not allowed)');
|
|
if (item.preview !== undefined && (typeof item.preview !== 'string' || !item.preview.startsWith('https://') || (hosts && !allowedUrl(item.preview, hosts)))) bad.push('preview');
|
|
if (typeof item.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(item.sha256)) bad.push('sha256');
|
|
if (!Number.isInteger(item.size) || item.size <= 0 || item.size > MAX_BYTES) bad.push('size');
|
|
if (item.kind === 'plugin') {
|
|
if (!validFileName(item.file) || item.colors != null) bad.push('plugin file');
|
|
const p = item.permissions;
|
|
if (p != null && (!Array.isArray(p) || !p.every(x => PERMISSIONS.includes(x)) || new Set(p).size !== p.length || (p.includes('network') && p.includes('network:none')))) bad.push('permissions');
|
|
}
|
|
if (item.kind === 'strings') {
|
|
if (item.file !== undefined || item.permissions !== undefined || item.colors !== undefined) bad.push('string pack fields');
|
|
if (typeof item.language !== 'string' || !LANGUAGE.test(item.language)) bad.push('language');
|
|
}
|
|
if (item.kind === 'theme') {
|
|
if (item.file !== undefined || item.permissions !== undefined) bad.push('theme fields');
|
|
const c = item.colors;
|
|
if (c != null && (typeof c !== 'object' || Object.keys(c).some(k => !['bg', 'surface', 'text', 'accent'].includes(k)) || !hex(c.bg) || !hex(c.text) || !hex(c.accent) || (c.surface !== undefined && !hex(c.surface)))) bad.push('colors');
|
|
}
|
|
return bad;
|
|
}
|
|
|
|
/** Problems with a whole catalog (empty = valid). `app`: that app's items are held to `hosts`. */
|
|
export function catalogProblems(catalog, { app, hosts = DEFAULT_HOSTS } = {}) {
|
|
const out = [];
|
|
if (!catalog || typeof catalog !== 'object') return ['catalog: not an object'];
|
|
for (const key of Object.keys(catalog)) if (!['format', 'name', 'generatedAt', 'items'].includes(key)) out.push(`catalog: unknown field ${key}`);
|
|
if (catalog.format !== CATALOG_FORMAT) out.push(`catalog: format must be ${CATALOG_FORMAT}`);
|
|
if (typeof catalog.name !== 'string' || typeof catalog.generatedAt !== 'string') out.push('catalog: name and generatedAt are strings');
|
|
if (!Array.isArray(catalog.items)) return [...out, 'catalog: items must be a list'];
|
|
if (catalog.items.length > MAX_ITEMS) out.push(`catalog: more than ${MAX_ITEMS} items`);
|
|
const ids = new Set();
|
|
const files = new Set();
|
|
for (const item of catalog.items) {
|
|
const where = `item ${item?.kind}:${item?.id}`;
|
|
for (const problem of itemProblems(item, app && item?.apps?.includes(app) ? hosts : undefined)) out.push(`${where}: invalid ${problem}`);
|
|
for (const a of Array.isArray(item?.apps) ? item.apps : []) {
|
|
const id = `${a}/${item.kind}/${item.id}`;
|
|
if (ids.has(id)) out.push(`${where}: duplicate for app ${a}`);
|
|
ids.add(id);
|
|
if (item.file) {
|
|
const file = `${a}/${String(item.file).toLowerCase()}`;
|
|
if (files.has(file)) out.push(`${where}: duplicate plugin file for app ${a}`);
|
|
files.add(file);
|
|
}
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
// ---- Build ------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Builds `config.app`'s part of the shared catalog in `out`: writes the files the config returns,
|
|
* replaces the app's items (other apps' items stay as they are), removes files only the app's old
|
|
* items used, validates the whole catalog and writes `catalog.json` (sign it afterwards).
|
|
*
|
|
* config: { app, name?, base?, out?, hosts?, items(context) → [{ kind, id, name, author, version,
|
|
* description, category, tags, file (plugins), permissions (plugins), colors (themes), language
|
|
* (string packs), license, credits,
|
|
* path ('plugins/x.plugin.js'), bytes (Buffer|string), preview?: { path, bytes } }] }
|
|
*/
|
|
export async function buildStore(config, options = {}) {
|
|
const app = config.app;
|
|
if (!validAppId(app)) throw new Error('config.app must be an app id (a-z, 0-9, -)');
|
|
const base = options.base ?? config.base ?? DEFAULT_BASE;
|
|
if (!/^https:\/\/[^/]+\/(.*\/)?$/.test(base)) throw new Error('base must be an https URL ending in /');
|
|
const out = resolve(options.out ?? config.out ?? '.');
|
|
const hosts = config.hosts ?? DEFAULT_HOSTS;
|
|
const catalogPath = join(out, 'catalog.json');
|
|
const previous = existsSync(catalogPath) ? JSON.parse(readFileSync(catalogPath, 'utf8')) : null;
|
|
const kept = [];
|
|
const oldFiles = new Set();
|
|
for (const item of previous?.format === CATALOG_FORMAT ? previous.items : []) {
|
|
if (!item.apps?.includes(app)) { kept.push(item); continue; }
|
|
for (const url of [item.url, item.preview]) if (url?.startsWith(base)) oldFiles.add(url.slice(base.length));
|
|
const others = item.apps.filter(a => a !== app);
|
|
if (others.length) kept.push({ ...item, apps: others });
|
|
}
|
|
const inside = path => {
|
|
const target = resolve(out, path);
|
|
const rel = relative(out, target);
|
|
if (!rel || rel.startsWith('..') || isAbsolute(rel) || !/^[\w.\-/]+$/.test(path)) throw new Error(`file path must stay inside the store folder: ${path}`);
|
|
return target;
|
|
};
|
|
const entries = await config.items({ app, base, out });
|
|
const items = [];
|
|
const files = new Map();
|
|
const toBytes = value => (Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8'));
|
|
for (const entry of entries) {
|
|
const bytes = toBytes(entry.bytes);
|
|
files.set(entry.path, { target: inside(entry.path), bytes });
|
|
const item = { apps: [app], kind: entry.kind, id: entry.id, name: entry.name, author: entry.author ?? '', version: entry.version, description: entry.description ?? '', category: entry.category ?? '', tags: entry.tags ?? [], url: `${base}${entry.path}` };
|
|
if (entry.kind === 'plugin') item.file = entry.file;
|
|
item.sha256 = sha256(bytes);
|
|
item.size = bytes.length;
|
|
if (entry.preview) {
|
|
files.set(entry.preview.path, { target: inside(entry.preview.path), bytes: toBytes(entry.preview.bytes) });
|
|
item.preview = `${base}${entry.preview.path}`;
|
|
}
|
|
if (entry.kind === 'plugin') item.permissions = entry.permissions ?? null;
|
|
if (entry.kind === 'theme' && entry.colors) item.colors = entry.colors;
|
|
if (entry.kind === 'strings') item.language = entry.language;
|
|
if (entry.license !== undefined) item.license = entry.license;
|
|
if (entry.credits !== undefined) item.credits = entry.credits;
|
|
items.push(item);
|
|
}
|
|
const catalog = {
|
|
format: CATALOG_FORMAT,
|
|
name: config.name ?? previous?.name ?? 'wayBetter Store',
|
|
generatedAt: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
|
|
items: [...kept, ...items],
|
|
};
|
|
// Nothing is written unless the whole catalog is valid.
|
|
const problems = catalogProblems(catalog, { app, hosts });
|
|
if (problems.length) throw new Error(`the catalog would be invalid:\n ${problems.join('\n ')}`);
|
|
const json = `${JSON.stringify(catalog, null, 2)}\n`;
|
|
if (Buffer.byteLength(json) > MAX_CATALOG_BYTES) throw new Error('the catalog is larger than apps accept (1 MiB)');
|
|
for (const { target, bytes } of files.values()) { mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes); }
|
|
// Files this app's previous build wrote and no item uses any more (never another app's files).
|
|
const stillUsed = new Set(kept.flatMap(item => [item.url, item.preview]).filter(url => url?.startsWith(base)).map(url => url.slice(base.length)));
|
|
for (const path of oldFiles) if (!files.has(path) && !stillUsed.has(path)) rmSync(inside(path), { force: true });
|
|
mkdirSync(out, { recursive: true });
|
|
writeFileSync(catalogPath, json);
|
|
return { catalog, path: catalogPath, items };
|
|
}
|
|
|
|
// ---- Keys and signatures ----------------------------------------------------------------------
|
|
|
|
export function rawPublicKey(publicKey) {
|
|
const der = publicKey.export({ format: 'der', type: 'spki' });
|
|
if (der.length !== 44 || !der.subarray(0, 12).equals(SPKI_PREFIX)) throw new Error('not an Ed25519 public key');
|
|
return der.subarray(12);
|
|
}
|
|
|
|
export function publicKeyFromBase64(value) {
|
|
const raw = Buffer.from(value.trim(), 'base64');
|
|
if (raw.length !== 32) throw new Error('a public key file must be the base64 of 32 raw bytes');
|
|
return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
|
|
}
|
|
|
|
/** Creates the store key once (0600, never overwritten) and writes its public key file. */
|
|
export function initKey(keyPath, pubPath) {
|
|
if (existsSync(keyPath)) {
|
|
const base64 = rawPublicKey(createPublicKey(createPrivateKey(readFileSync(keyPath)))).toString('base64');
|
|
if (!existsSync(pubPath) || readFileSync(pubPath, 'utf8').trim() !== base64) { mkdirSync(dirname(pubPath), { recursive: true }); writeFileSync(pubPath, `${base64}\n`); }
|
|
return { created: false, publicKey: base64 };
|
|
}
|
|
mkdirSync(dirname(keyPath), { recursive: true });
|
|
const { privateKey, publicKey } = generateKeyPairSync('ed25519');
|
|
writeFileSync(keyPath, privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600, flag: 'wx' });
|
|
const base64 = rawPublicKey(publicKey).toString('base64');
|
|
mkdirSync(dirname(pubPath), { recursive: true });
|
|
writeFileSync(pubPath, `${base64}\n`);
|
|
return { created: true, publicKey: base64 };
|
|
}
|
|
|
|
/** Signs the exact bytes of `file` into `<file>.sig`; returns the public key (base64) that verifies it. */
|
|
export function signFile(file, keyPath) {
|
|
const privateKey = createPrivateKey(readFileSync(keyPath));
|
|
const signature = sign(null, readFileSync(file), privateKey).toString('base64');
|
|
writeFileSync(`${file}.sig`, `${signature}\n`);
|
|
return rawPublicKey(createPublicKey(privateKey)).toString('base64');
|
|
}
|
|
|
|
/** Whether `<file>.sig` verifies with any of the public keys (base64 strings). */
|
|
export function verifyFile(file, publicKeys) {
|
|
const signature = Buffer.from(readFileSync(`${file}.sig`, 'utf8').trim(), 'base64');
|
|
if (signature.length !== 64) return false;
|
|
const body = readFileSync(file);
|
|
return publicKeys.some(key => verify(null, body, publicKeyFromBase64(key), signature));
|
|
}
|
|
|
|
// ---- Command line -----------------------------------------------------------------------------
|
|
|
|
const USAGE = `Usage:
|
|
waybetter store build --config <store.config.mjs> [--out <dir>] [--base <https://…/store/>]
|
|
waybetter store sign [catalog.json] --key <private key> [--pub <public key file>]
|
|
waybetter store sign --init --key <private key> --pub <public key file>
|
|
waybetter store verify [catalog.json] --pub <public key file>... [--app <id>]`;
|
|
|
|
function parse(argv) {
|
|
const out = { positional: [], pub: [], init: false };
|
|
for (let i = 0; i < argv.length; i += 1) {
|
|
const arg = argv[i];
|
|
const value = () => { const next = argv[++i]; if (next === undefined) throw new Error(`${arg} needs a value`); return next; };
|
|
if (arg === '--init') out.init = true;
|
|
else if (arg === '--pub') out.pub.push(resolve(value()));
|
|
else if (arg === '--key' || arg === '--config' || arg === '--out' || arg === '--base' || arg === '--app') out[arg.slice(2)] = value();
|
|
else if (arg.startsWith('--')) throw new Error(`unknown option ${arg}`);
|
|
else out.positional.push(arg);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/** Runs `waybetter store …`; returns the lines to print. Throws on errors. */
|
|
export async function storeCommand(argv) {
|
|
const [command, ...rest] = argv;
|
|
const options = parse(rest);
|
|
const catalog = resolve(options.positional[0] ?? 'catalog.json');
|
|
const key = options.key ? resolve(options.key) : process.env.WAYBETTER_STORE_KEY;
|
|
if (command === 'build') {
|
|
if (!options.config) throw new Error(`build needs --config\n${USAGE}`);
|
|
const config = (await import(pathToFileURL(resolve(options.config)).href)).default;
|
|
const { path, items } = await buildStore(config, { out: options.out, base: options.base });
|
|
const count = kind => items.filter(item => item.kind === kind).length;
|
|
return [`store: ${config.app}: ${count('plugin')} plugins, ${count('theme')} themes → ${path}`, 'Now sign it: waybetter store sign <catalog.json> --key <private key>'];
|
|
}
|
|
if (command === 'sign') {
|
|
if (!key) throw new Error('sign needs --key (or WAYBETTER_STORE_KEY)');
|
|
if (options.init) {
|
|
if (!options.pub.length) throw new Error('--init needs --pub');
|
|
const { created, publicKey } = initKey(key, options.pub[0]);
|
|
return [`${created ? 'Created the store key' : 'Store key already exists'}; public key ${publicKey} → ${options.pub[0]}`];
|
|
}
|
|
if (!existsSync(key)) throw new Error(`no store key at ${key} (create it once with --init)`);
|
|
const publicKey = signFile(catalog, key);
|
|
const keys = options.pub.length ? options.pub.map(file => readFileSync(file, 'utf8').trim()) : [publicKey];
|
|
if (!verifyFile(catalog, keys)) throw new Error(`signature of ${catalog} does NOT verify with ${options.pub.join(', ') || 'the key'}`);
|
|
return [`Signed and verified ${catalog}.sig`];
|
|
}
|
|
if (command === 'verify') {
|
|
if (!options.pub.length) throw new Error('verify needs --pub');
|
|
const keys = options.pub.map(file => readFileSync(file, 'utf8').trim());
|
|
if (!verifyFile(catalog, keys)) throw new Error(`signature of ${catalog} does NOT verify with ${options.pub.join(', ')}`);
|
|
const problems = catalogProblems(JSON.parse(readFileSync(catalog, 'utf8')), { app: options.app });
|
|
if (problems.length) throw new Error(`${catalog} is signed but invalid:\n ${problems.join('\n ')}`);
|
|
return [`Verified ${catalog}.sig`];
|
|
}
|
|
throw new Error(USAGE);
|
|
}
|
|
|
|
export { USAGE as STORE_USAGE };
|