@vormio/plugin-sdk 0.0.0-stage → 0.0.5

package/dist/node/catalog.js

@@ -0,0 +1,240 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from 'node:crypto';
+import { z } from 'zod';
+import { parseManifest, pluginApiVersion, pluginIdSchema, versionSchema, } from "../manifest.js";
+import { packageLimits } from "../package-rules.js";
+/** Limits for a signed plugin catalog. */
+export const catalogLimits = {
+    maxCatalogBytes: 1024 * 1024,
+    maxPlugins: 256,
+    maxReleasesPerPlugin: 8,
+};
+export class CatalogError extends Error {
+    code;
+    problems;
+    constructor(code, problems) {
+        super(problems.join('\n'));
+        this.code = code;
+        this.problems = problems;
+        this.name = 'CatalogError';
+    }
+}
+/**
+ * The manifest fields every host reads, whatever the release's apiVersion. The rest of the manifest
+ * is kept as is: a host parses it fully only for releases of its own apiVersion (`releaseManifest`).
+ */
+const releaseManifestSchema = z.looseObject({
+    apiVersion: z.number().int().min(1),
+    id: pluginIdSchema,
+    version: versionSchema,
+    name: z.string().trim().min(1).max(80),
+    description: z.string().max(400).optional(),
+});
+const releaseSchema = z.strictObject({
+    /** The package's `manifest.json`. */
+    manifest: releaseManifestSchema,
+    /** The package file, relative to the catalog: always directly inside `packages/`. */
+    file: z
+        .string()
+        .regex(/^packages\/[A-Za-z0-9][A-Za-z0-9._-]{0,199}\.vormioplugin$/, 'Use packages/<name>.vormioplugin'),
+    bytes: z.number().int().min(1).max(packageLimits.maxArchiveBytes),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, 'Use lower-case hexadecimal'),
+});
+const payloadSchema = z
+    .strictObject({
+    /** Grows with every publication; hosts refuse a catalog older than one they have seen. */
+    sequence: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    publishedAt: z.iso.datetime(),
+    plugins: z
+        .array(z.strictObject({
+        id: pluginIdSchema,
+        releases: z.array(releaseSchema).min(1).max(catalogLimits.maxReleasesPerPlugin),
+    }))
+        .max(catalogLimits.maxPlugins),
+})
+    .superRefine((payload, context) => {
+    const ids = new Set();
+    const files = new Set();
+    payload.plugins.forEach((plugin, index) => {
+        const issue = (path, message) => context.addIssue({ code: 'custom', path: ['plugins', index, ...path], message });
+        if (ids.has(plugin.id))
+            issue(['id'], 'Plugin IDs must not repeat');
+        ids.add(plugin.id);
+        const versions = new Set();
+        plugin.releases.forEach((release, at) => {
+            if (release.manifest.id !== plugin.id)
+                issue(['releases', at, 'manifest', 'id'], 'The manifest ID must match the plugin ID');
+            if (versions.has(release.manifest.version))
+                issue(['releases', at, 'manifest', 'version'], 'Versions must not repeat');
+            versions.add(release.manifest.version);
+            const file = release.file.toLowerCase();
+            if (files.has(file))
+                issue(['releases', at, 'file'], 'Files must not repeat');
+            files.add(file);
+        });
+    });
+});
+const envelopeSchema = z.strictObject({
+    format: z.literal(1),
+    keyId: z.string().regex(/^[0-9a-f]{16}$/),
+    /** The payload's UTF-8 JSON, base64; the signature covers exactly these bytes. */
+    payload: z.string().min(1),
+    signature: z.string().min(1),
+});
+function problemsOf(error) {
+    return error.issues.map((issue) => `${issue.path.length ? issue.path.join('.') : 'catalog'}: ${issue.message}`);
+}
+/** Decodes canonical base64 only, so that one envelope has exactly one meaning. */
+function decodeBase64(text) {
+    const bytes = Buffer.from(text, 'base64');
+    return bytes.length > 0 && bytes.toString('base64') === text ? bytes : undefined;
+}
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+function parseJson(bytes, what) {
+    try {
+        return JSON.parse(utf8.decode(bytes));
+    }
+    catch {
+        throw new CatalogError('format', [`${what} is not valid UTF-8 JSON`]);
+    }
+}
+// --- Keys ------------------------------------------------------------------------------------
+// A public key is written as the base64 of its 32 raw Ed25519 bytes, short enough to build into the
+// app. Private keys are PKCS#8 PEM files that never leave the publisher's machine.
+function rawPublicKey(publicKey) {
+    const bytes = decodeBase64(publicKey.trim());
+    if (bytes?.length !== 32)
+        throw new CatalogError('key', ['A public key is 32 raw Ed25519 bytes in base64']);
+    return bytes;
+}
+function publicKeyObject(publicKey) {
+    const x = rawPublicKey(publicKey).toString('base64url');
+    return createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x }, format: 'jwk' });
+}
+function publicKeyText(key) {
+    return Buffer.from(key.export({ format: 'jwk' }).x, 'base64url').toString('base64');
+}
+function privateKeyObject(privateKey) {
+    let key;
+    try {
+        key = createPrivateKey(privateKey);
+    }
+    catch {
+        throw new CatalogError('key', ['The private key is not a PEM private key']);
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new CatalogError('key', ['The private key is not an Ed25519 key']);
+    return key;
+}
+/** The first 16 hexadecimal digits of the public key's SHA-256; catalogs name their key by it. */
+export function catalogKeyId(publicKey) {
+    return createHash('sha256').update(rawPublicKey(publicKey)).digest('hex').slice(0, 16);
+}
+/** The public key that belongs to a PEM private key. */
+export function catalogPublicKey(privateKey) {
+    return publicKeyText(createPublicKey(privateKeyObject(privateKey)));
+}
+export function generateCatalogKeys() {
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const text = publicKeyText(publicKey);
+    return {
+        publicKey: text,
+        privateKey: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(),
+        keyId: catalogKeyId(text),
+    };
+}
+// --- Signing and verification ----------------------------------------------------------------
+/** Validates a payload and returns the signed `catalog.json` bytes. */
+export function signCatalog(payload, privateKey) {
+    const result = payloadSchema.safeParse(payload);
+    if (!result.success)
+        throw new CatalogError('format', problemsOf(result.error));
+    const key = privateKeyObject(privateKey);
+    const bytes = Buffer.from(JSON.stringify(payload));
+    const envelope = {
+        format: 1,
+        keyId: catalogKeyId(publicKeyText(createPublicKey(key))),
+        payload: bytes.toString('base64'),
+        signature: sign(null, bytes, key).toString('base64'),
+    };
+    const text = Buffer.from(`${JSON.stringify(envelope, null, 2)}\n`);
+    if (text.length > catalogLimits.maxCatalogBytes)
+        throw new CatalogError('format', ['The catalog is larger than 1 MiB']);
+    return text;
+}
+/**
+ * Checks `catalog.json` against a public key: shape of the envelope, key ID, signature, and only
+ * then the payload. Throws `CatalogError` at the first check that fails.
+ */
+export function verifyCatalog(bytes, publicKey) {
+    if (bytes.length > catalogLimits.maxCatalogBytes)
+        throw new CatalogError('format', ['The catalog is larger than 1 MiB']);
+    const envelope = envelopeSchema.safeParse(parseJson(bytes, 'The catalog'));
+    if (!envelope.success)
+        throw new CatalogError('format', problemsOf(envelope.error));
+    const keyId = catalogKeyId(publicKey);
+    if (envelope.data.keyId !== keyId)
+        throw new CatalogError('key', [
+            `The catalog is signed with key ${envelope.data.keyId}, not ${keyId}`,
+        ]);
+    const payload = decodeBase64(envelope.data.payload);
+    const signature = decodeBase64(envelope.data.signature);
+    if (!payload || signature?.length !== 64)
+        throw new CatalogError('format', ['The payload or signature is not canonical base64']);
+    if (!verify(null, payload, publicKeyObject(publicKey), signature))
+        throw new CatalogError('signature', ['The signature does not match the catalog']);
+    const result = payloadSchema.safeParse(parseJson(payload, 'The payload'));
+    if (!result.success)
+        throw new CatalogError('format', problemsOf(result.error));
+    return { keyId, ...result.data };
+}
+/**
+ * The release's manifest when this SDK's hosts can install it: same apiVersion, and valid under
+ * this SDK's manifest schema. Otherwise the reasons, typically that the release needs a newer host.
+ */
+export function releaseManifest(release) {
+    if (release.manifest.apiVersion !== pluginApiVersion)
+        return {
+            ok: false,
+            problems: [
+                `apiVersion ${release.manifest.apiVersion}; this version supports ${pluginApiVersion}`,
+            ],
+        };
+    return parseManifest(release.manifest);
+}
+// --- Versions --------------------------------------------------------------------------------
+function versionParts(version) {
+    const dash = version.indexOf('-');
+    const core = dash < 0 ? version : version.slice(0, dash);
+    return {
+        core: core.split('.').map(Number),
+        prerelease: dash < 0 ? [] : version.slice(dash + 1).split('.'),
+    };
+}
+/** Orders two semantic versions by precedence: negative, zero or positive, like a sort callback. */
+export function compareVersions(a, b) {
+    const left = versionParts(a);
+    const right = versionParts(b);
+    for (let at = 0; at < 3; at++) {
+        const difference = (left.core[at] ?? 0) - (right.core[at] ?? 0);
+        if (difference)
+            return Math.sign(difference);
+    }
+    // A version without a pre-release ranks above any pre-release of it.
+    if (!left.prerelease.length || !right.prerelease.length)
+        return Math.sign(right.prerelease.length - left.prerelease.length);
+    const count = Math.min(left.prerelease.length, right.prerelease.length);
+    for (let at = 0; at < count; at++) {
+        const x = left.prerelease[at];
+        const y = right.prerelease[at];
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return Math.sign(Number(x) - Number(y));
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return Math.sign(left.prerelease.length - right.prerelease.length);
+}

package/dist/node/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/node/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { CatalogError } from "./catalog.js";
+import { checkPackage, PackageError, readPackageDirectory } from "./package.js";
+import { PublishError, writeCatalog, writeCatalogKeys } from "./publish.js";
+import { writeZip, ZipError } from "./zip.js";
+const usage = [
+    'Usage:',
+    '  vormio-plugin pack <plugin directory> <output.vormioplugin>',
+    '  vormio-plugin keygen <output path prefix>',
+    '  vormio-plugin catalog <release config.json> --key <private key.pem> --out <new folder>',
+].join('\n');
+/** `vormio-plugin pack`: validates a built plugin directory and writes a `.vormioplugin` file. */
+async function pack(source, output) {
+    if (!output.endsWith('.vormioplugin')) {
+        console.error('The output file must end with .vormioplugin');
+        return 2;
+    }
+    const target = resolve(output);
+    if (existsSync(target)) {
+        console.error(`${target} already exists; choose another name or remove it first`);
+        return 1;
+    }
+    const contents = await readPackageDirectory(resolve(source));
+    const checked = checkPackage(contents);
+    const entries = checked.files.map((file) => ({
+        path: file.path,
+        data: contents.get(file.path),
+    }));
+    await writeFile(target, writeZip(entries), { flag: 'wx' });
+    console.log(`${checked.manifest.id} ${checked.manifest.version}: ${entries.length} files → ${target}`);
+    console.log(`digest ${checked.digest}`);
+    return 0;
+}
+/** `vormio-plugin keygen`: creates the key pair a catalog is signed with. */
+async function keygen(prefix) {
+    const keys = await writeCatalogKeys(prefix);
+    console.log(`key ${keys.keyId}`);
+    console.log(`public key ${keys.publicKey}`);
+    console.log(`private key → ${keys.privateKeyFile}`);
+    console.log(`public key → ${keys.publicKeyFile}`);
+    console.log('Keep the private key offline. Never commit, upload or share it.');
+    return 0;
+}
+/** `vormio-plugin catalog`: publishes a signed catalog and its packages into a new folder. */
+async function catalog(args) {
+    let config;
+    let key;
+    let out;
+    for (let at = 0; at < args.length; at++) {
+        const arg = args[at];
+        if (arg === '--key')
+            key = args[++at];
+        else if (arg === '--out')
+            out = args[++at];
+        else if (config === undefined && arg && !arg.startsWith('--'))
+            config = arg;
+        else
+            return usageError();
+    }
+    if (!config || !key || !out)
+        return usageError();
+    const written = await writeCatalog({ config, privateKey: key, out });
+    console.log(`catalog.json: sequence ${written.sequence}, key ${written.keyId}`);
+    for (const release of written.releases)
+        console.log(`  ${release.id} ${release.version} → ${release.file}`);
+    console.log(`Upload the packages folder of ${resolve(out)} first, then catalog.json.`);
+    return 0;
+}
+function usageError() {
+    console.error(usage);
+    return 2;
+}
+async function main(args) {
+    const [command, ...rest] = args;
+    try {
+        if (command === 'pack' && rest.length === 2)
+            return await pack(rest[0], rest[1]);
+        if (command === 'keygen' && rest.length === 1)
+            return await keygen(rest[0]);
+        if (command === 'catalog')
+            return await catalog(rest);
+        return usageError();
+    }
+    catch (error) {
+        if (error instanceof PackageError || error instanceof ZipError) {
+            console.error(`The plugin is not valid:\n${error.message}`);
+            return 1;
+        }
+        if (error instanceof PublishError || error instanceof CatalogError) {
+            console.error(error.message);
+            return 1;
+        }
+        throw error;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/node/index.d.ts

@@ -0,0 +1,8 @@
+export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, type CheckedPackage, } from './package.ts';
+export { readZip, writeZip, ZipError, type ZipEntry } from './zip.ts';
+export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, type Catalog, type CatalogErrorCode, type CatalogKeys, type CatalogPayload, type CatalogPlugin, type CatalogRelease, } from './catalog.ts';
+export { PublishError, writeCatalog, writeCatalogKeys, type WrittenCatalog, type WrittenKeys, } from './publish.ts';
+export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, type Contribution, type ContributionKind, type PluginManifest, } from '../manifest.ts';
+export { checkPackageFiles, checkPackagePath, packageLimits } from '../package-rules.ts';
+export { compositionReportSchema, parseReport, reportLimits } from '../report.ts';
+export type { CompositionReport } from '../bridge.ts';

package/dist/node/index.js

@@ -0,0 +1,8 @@
+export { checkPackage, PackageError, readPackageArchive, readPackageDirectory, } from "./package.js";
+export { readZip, writeZip, ZipError } from "./zip.js";
+export { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, releaseManifest, signCatalog, verifyCatalog, } from "./catalog.js";
+export { PublishError, writeCatalog, writeCatalogKeys, } from "./publish.js";
+// The manifest and package rules again, so Node code needs no DOM types from the runtime entry.
+export { contributionsOf, manifestSchema, missingEntries, parseManifest, permissionSummary, pluginApiVersion, } from "../manifest.js";
+export { checkPackageFiles, checkPackagePath, packageLimits } from "../package-rules.js";
+export { compositionReportSchema, parseReport, reportLimits } from "../report.js";

package/dist/node/package.d.ts

@@ -0,0 +1,25 @@
+import { type PluginManifest } from '../manifest.ts';
+import { type PackageFile } from '../package-rules.ts';
+export declare class PackageError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** A validated plugin: its manifest, file list and content digest. */
+export interface CheckedPackage {
+    manifest: PluginManifest;
+    files: PackageFile[];
+    /** SHA-256 over every file's path and content, in path order. */
+    digest: string;
+}
+/** Validates file contents given as path → bytes (from a zip or a directory). */
+export declare function checkPackage(contents: ReadonlyMap<string, Buffer>): CheckedPackage;
+/**
+ * Reads a plugin directory. Links and junctions are refused rather than followed, and reading stops
+ * as soon as the package limits are exceeded.
+ */
+export declare function readPackageDirectory(directory: string): Promise<Map<string, Buffer>>;
+/** Reads and validates a `.vormioplugin` file. */
+export declare function readPackageArchive(zip: Buffer): {
+    checked: CheckedPackage;
+    contents: Map<string, Buffer>;
+};

package/dist/node/package.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { missingEntries, parseManifest } from "../manifest.js";
+import { checkPackageFiles, packageLimits } from "../package-rules.js";
+import { readZip } from "./zip.js";
+export class PackageError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.problems = problems;
+        this.name = 'PackageError';
+    }
+}
+/** Validates file contents given as path → bytes (from a zip or a directory). */
+export function checkPackage(contents) {
+    const files = [...contents].map(([path, data]) => ({ path, size: data.length }));
+    const problems = checkPackageFiles(files);
+    const manifestBytes = contents.get('manifest.json');
+    if (problems.length || !manifestBytes)
+        throw new PackageError(problems);
+    let json;
+    try {
+        json = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw new PackageError(['manifest.json: not valid JSON']);
+    }
+    const parsed = parseManifest(json);
+    if (!parsed.ok)
+        throw new PackageError(parsed.problems);
+    const missing = missingEntries(parsed.manifest, new Set(contents.keys()));
+    if (missing.length)
+        throw new PackageError(missing.map((entry) => `${entry}: entry not found`));
+    const digest = createHash('sha256');
+    for (const path of [...contents.keys()].sort()) {
+        digest.update(path).update('\0');
+        digest.update(createHash('sha256').update(contents.get(path)).digest()).update('\0');
+    }
+    return {
+        manifest: parsed.manifest,
+        files: files.sort((a, b) => (a.path < b.path ? -1 : 1)),
+        digest: digest.digest('hex'),
+    };
+}
+/**
+ * Reads a plugin directory. Links and junctions are refused rather than followed, and reading stops
+ * as soon as the package limits are exceeded.
+ */
+export async function readPackageDirectory(directory) {
+    const contents = new Map();
+    let total = 0;
+    const visit = async (relative) => {
+        for (const name of (await readdir(join(directory, relative))).sort()) {
+            const path = relative ? `${relative}/${name}` : name;
+            const info = await lstat(join(directory, path));
+            if (info.isSymbolicLink())
+                throw new PackageError([`${path}: links are not allowed`]);
+            if (info.isDirectory()) {
+                await visit(path);
+                continue;
+            }
+            if (!info.isFile())
+                throw new PackageError([`${path}: not a regular file`]);
+            if (contents.size >= packageLimits.maxFiles)
+                throw new PackageError([`more than ${packageLimits.maxFiles} files`]);
+            if (info.size > packageLimits.maxFileBytes)
+                throw new PackageError([`${path}: file too large`]);
+            total += info.size;
+            if (total > packageLimits.maxTotalBytes)
+                throw new PackageError(['package too large']);
+            contents.set(path, await readFile(join(directory, path)));
+        }
+    };
+    await visit('');
+    return contents;
+}
+/** Reads and validates a `.vormioplugin` file. */
+export function readPackageArchive(zip) {
+    const contents = new Map(readZip(zip).map((entry) => [entry.path, entry.data]));
+    return { checked: checkPackage(contents), contents };
+}

package/dist/node/publish.d.ts

@@ -0,0 +1,42 @@
+/** A publication that cannot go ahead; nothing has been written. */
+export declare class PublishError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+export interface WrittenKeys {
+    keyId: string;
+    publicKey: string;
+    privateKeyFile: string;
+    publicKeyFile: string;
+}
+/**
+ * Generates a catalog key pair into `<prefix>.private.pem` and `<prefix>.public.txt`. Refuses to
+ * write inside a Git working tree, where the private key could end up in a commit, and never
+ * overwrites a file.
+ */
+export declare function writeCatalogKeys(prefix: string): Promise<WrittenKeys>;
+export interface WrittenCatalog {
+    keyId: string;
+    sequence: number;
+    releases: {
+        id: string;
+        version: string;
+        file: string;
+        bytes: number;
+        sha256: string;
+    }[];
+}
+/**
+ * Publishes a catalog into a new, empty folder: validates every package the way a host does before
+ * installing it, copies each under a name derived from its content, signs `catalog.json` and checks
+ * the result with the public key. Every check runs before anything is written. Upload the
+ * `packages` folder first and `catalog.json` last.
+ */
+export declare function writeCatalog(options: {
+    /** Release configuration; relative paths in it are resolved against its folder. */
+    config: string;
+    /** PKCS#8 PEM file of the catalog's private key. */
+    privateKey: string;
+    out: string;
+    now?: Date;
+}): Promise<WrittenCatalog>;