@vormio/plugin-sdk 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @vormio/plugin-sdk
 
-The manifest schema, runtime helpers and packaging command for writing Vormio plugins. The package is versioned with Vormio-Core (currently 0.0.3) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.3`.
+The manifest schema, runtime helpers and packaging command for writing Vormio plugins, plus the commands that publish a signed plugin catalog. The package is versioned with Vormio-Core (currently 0.0.5) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.5`.
 
 Plugin contract version: `apiVersion: 1`. During development (0.0.x) there is no cross-version compatibility promise: the host loads only plugins with the same `apiVersion` as its own.
 
@@ -63,9 +63,15 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 
 **Allowed files**: `html js mjs css json wasm png jpg jpeg webp svg woff2 txt md`. Links, `..` paths, Windows reserved names and names that differ only by case are not allowed.
 
-**Limits**: at most 1,024 files, 16 MiB per file and 64 MiB in total.
+**Limits**: at most 1,024 files, 16 MiB per file and 64 MiB in total; the `.vormioplugin` file itself is at most 96 MiB.
 
-**Permission fingerprint**: the grant a library records covers each extension point's ID (analyzers included), `formats` and `companionFormats`. An upgrade that changes only code, name or version keeps the grant; widening what the plugin reads or adding an extension point requires the user to enable it again.
+**Grants**: a library records what the user approved for each extension point (analyzers included): its ID, `formats` and `companionFormats`. A version that reads no more than that keeps running without asking again, including:
+
+- an upgrade that changes only code, name or version
+- an upgrade that reads less
+- a rollback
+
+Reading more formats or companion formats, or adding an extension point, requires the user to enable the plugin again, and that approval is added to what was approved before.
 
 ## Runtime API
 
@@ -158,3 +164,69 @@ npx vormio-plugin pack <build-output-folder> <output-file.vormioplugin>
 The command validates the manifest and every file, then writes a zip-format `.vormioplugin`. It never overwrites an existing output file.
 
 During development, open the **插件** (Plugins) page in Vormio, choose **添加开发目录…** (Add development folder…) and point it at the build output folder. The host watches the folder: every change is validated again, and a valid build reloads the plugin. If validation fails, the last valid version stays loaded and the error is shown on the plugin card. Vormio never runs build commands.
+
+## Plugin catalogs
+
+A plugin catalog is a signed `catalog.json` plus the plugin packages it lists, on static hosting. Vormio installs and updates plugins from it. Publishers produce one with two commands:
+
+```bash
+npx vormio-plugin keygen <key-path-prefix>
+npx vormio-plugin catalog <release-config.json> --key <private-key.pem> --out <new-folder>
+```
+
+- `keygen` generates an Ed25519 key pair: `<prefix>.private.pem` (PKCS#8) and `<prefix>.public.txt` (the base64 of the 32-byte public key; hosts build this line in). It refuses to write inside a Git working tree and never overwrites a file. The private key stays on the publisher's machine: never commit or upload it.
+- The release configuration lists every package in the new catalog, relative to the configuration file:
+
+  ```json
+  {
+    "previous": "published/3/catalog.json",
+    "packages": ["artifacts/model-viewer-0.2.0.vormioplugin"]
+  }
+  ```
+
+  `previous` is the catalog currently online. The new catalog's sequence is its sequence plus 1, and it must be signed with the same key. A first publication has no previous catalog and uses `"initialSequence": 1` instead.
+
+- `catalog` does the following:
+  - Validates every package with the rules a host applies when installing it.
+  - Copies each package to `packages/<plugin ID>-<version>-<first 12 hex digits of its SHA-256>.vormioplugin`.
+  - Writes and signs `catalog.json`, then verifies it with the public key.
+
+  The output folder must be new or empty. If any check fails, nothing is written.
+
+- Upload `packages/` first and `catalog.json` last. Do not cache `catalog.json`. Package file names change with their content, so packages can be cached for a long time.
+
+**Format**: `catalog.json` is an envelope `{ format: 1, keyId, payload, signature }`:
+
+- `payload` is the base64 of the content's UTF-8 JSON.
+- `signature` is the Ed25519 signature of those bytes.
+- `keyId` is the first 16 hex digits of the public key's SHA-256.
+
+The content:
+
+```ts
+interface CatalogPayload {
+  sequence: number // Grows by 1 per publication; hosts refuse a sequence lower than one they have seen
+  publishedAt: string // ISO 8601, UTC
+  plugins: {
+    id: string
+    releases: {
+      manifest: object // The package's manifest.json, as is
+      file: string // packages/<name>.vormioplugin, relative to catalog.json
+      bytes: number
+      sha256: string // SHA-256 of the whole package file, lowercase hex
+    }[]
+  }[]
+}
+```
+
+- Limits:
+  - `catalog.json` is at most 1 MiB.
+  - At most 256 plugins, with at most 8 releases each.
+  - Package files are at most 96 MiB.
+
+  Plugin IDs, and the versions of one plugin, must not repeat. `manifest.id` must match the plugin ID.
+
+- One plugin can list releases for hosts of different `apiVersion`s side by side. A host installs only releases with its own `apiVersion` whose manifest passes its own validation; it shows the rest as needing a newer Vormio.
+- Hosts verify the signature before reading the content. A downloaded package must match `bytes` and `sha256`, then pass the rules of a local install, and its manifest must equal the one in the catalog.
+
+`@vormio/plugin-sdk/node` exports the same functionality: `verifyCatalog`, `signCatalog`, `writeCatalog`, `writeCatalogKeys`, `releaseManifest` and `compareVersions`.

package/dist/manifest.d.ts

@@ -8,6 +8,10 @@ declare const contributionSchema: z.ZodObject<{
     companionFormats: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type Contribution = z.output<typeof contributionSchema>;
+/** `publisher.name`. The `vormio` publisher is reserved for the host. */
+export declare const pluginIdSchema: z.ZodString;
+/** A semantic version without build metadata. */
+export declare const versionSchema: z.ZodString;
 export declare const manifestSchema: z.ZodObject<{
     apiVersion: z.ZodLiteral<1>;
     id: z.ZodString;

package/dist/manifest.js

@@ -22,16 +22,19 @@ const contributionList = z
     .max(8)
     .default([])
     .refine((items) => unique(items.map((item) => item.id)), 'Contribution IDs must not repeat');
+/** `publisher.name`. The `vormio` publisher is reserved for the host. */
+export const pluginIdSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]{0,39}\.[a-z0-9][a-z0-9-]{0,39}$/, 'Use publisher.name')
+    .refine((id) => !id.startsWith('vormio.'), 'The vormio publisher is reserved');
+/** A semantic version without build metadata. */
+export const versionSchema = z
+    .string()
+    .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/, 'Use a semantic version');
 export const manifestSchema = z.strictObject({
     apiVersion: z.literal(pluginApiVersion),
-    /** `publisher.name`. The `vormio` publisher is reserved for the host. */
-    id: z
-        .string()
-        .regex(/^[a-z0-9][a-z0-9-]{0,39}\.[a-z0-9][a-z0-9-]{0,39}$/, 'Use publisher.name')
-        .refine((id) => !id.startsWith('vormio.'), 'The vormio publisher is reserved'),
-    version: z
-        .string()
-        .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/, 'Use a semantic version'),
+    id: pluginIdSchema,
+    version: versionSchema,
     name: z.string().trim().min(1).max(80),
     description: z.string().max(400).default(''),
     contributions: z

package/dist/node/catalog.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { type ManifestResult } from '../manifest.ts';
+/** Limits for a signed plugin catalog. */
+export declare const catalogLimits: {
+    readonly maxCatalogBytes: number;
+    readonly maxPlugins: 256;
+    readonly maxReleasesPerPlugin: 8;
+};
+/** Which check a catalog failed: its shape, the key it was signed with, or the signature itself. */
+export type CatalogErrorCode = 'format' | 'key' | 'signature';
+export declare class CatalogError extends Error {
+    readonly code: CatalogErrorCode;
+    readonly problems: readonly string[];
+    constructor(code: CatalogErrorCode, problems: readonly string[]);
+}
+declare const payloadSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    publishedAt: z.ZodISODateTime;
+    plugins: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        releases: z.ZodArray<z.ZodObject<{
+            manifest: z.ZodObject<{
+                apiVersion: z.ZodNumber;
+                id: z.ZodString;
+                version: z.ZodString;
+                name: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>;
+            file: z.ZodString;
+            bytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** What `signCatalog` signs. */
+export type CatalogPayload = z.input<typeof payloadSchema>;
+/** A catalog whose signature has been verified. */
+export type Catalog = z.output<typeof payloadSchema> & {
+    keyId: string;
+};
+export type CatalogPlugin = Catalog['plugins'][number];
+export type CatalogRelease = CatalogPlugin['releases'][number];
+/** The first 16 hexadecimal digits of the public key's SHA-256; catalogs name their key by it. */
+export declare function catalogKeyId(publicKey: string): string;
+/** The public key that belongs to a PEM private key. */
+export declare function catalogPublicKey(privateKey: string): string;
+export interface CatalogKeys {
+    /** Base64 of the raw key; hosts build it in. */
+    publicKey: string;
+    /** PKCS#8 PEM. */
+    privateKey: string;
+    keyId: string;
+}
+export declare function generateCatalogKeys(): CatalogKeys;
+/** Validates a payload and returns the signed `catalog.json` bytes. */
+export declare function signCatalog(payload: CatalogPayload, privateKey: string): Buffer;
+/**
+ * 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 declare function verifyCatalog(bytes: Uint8Array, publicKey: string): Catalog;
+/**
+ * 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 declare function releaseManifest(release: CatalogRelease): ManifestResult;
+/** Orders two semantic versions by precedence: negative, zero or positive, like a sort callback. */
+export declare function compareVersions(a: string, b: string): number;
+export {};

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.js

@@ -2,16 +2,18 @@
 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>';
+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 main(args) {
-    const [command, source, output] = args;
-    if (command !== 'pack' || !source || !output) {
-        console.error(usage);
-        return 2;
-    }
+async function pack(source, output) {
     if (!output.endsWith('.vormioplugin')) {
         console.error('The output file must end with .vormioplugin');
         return 2;
@@ -21,23 +23,76 @@ async function main(args) {
         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 {
-        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;
+        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;
     }
 }

package/dist/node/index.d.ts

@@ -1,5 +1,7 @@
 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';

package/dist/node/index.js

@@ -1,5 +1,7 @@
 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";

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>;

package/dist/node/publish.js

@@ -0,0 +1,213 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { packageLimits } from "../package-rules.js";
+import { CatalogError, catalogKeyId, catalogLimits, catalogPublicKey, compareVersions, generateCatalogKeys, signCatalog, verifyCatalog, } from "./catalog.js";
+import { PackageError, readPackageArchive } from "./package.js";
+import { ZipError } from "./zip.js";
+/** A publication that cannot go ahead; nothing has been written. */
+export class PublishError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.problems = problems;
+        this.name = 'PublishError';
+    }
+}
+/** The Git working tree containing a folder, if any. */
+function gitWorkingTree(folder) {
+    for (let current = resolve(folder);;) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function readInput(path, what) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new PublishError([`${what} not found: ${path}`]);
+        throw error;
+    }
+}
+/**
+ * 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 async function writeCatalogKeys(prefix) {
+    const base = resolve(prefix);
+    const repository = gitWorkingTree(dirname(base));
+    if (repository)
+        throw new PublishError([
+            `${dirname(base)} is inside the Git working tree ${repository}; keep private keys outside every repository`,
+        ]);
+    const privateKeyFile = `${base}.private.pem`;
+    const publicKeyFile = `${base}.public.txt`;
+    for (const file of [privateKeyFile, publicKeyFile])
+        if (existsSync(file))
+            throw new PublishError([`${file} already exists`]);
+    const keys = generateCatalogKeys();
+    await mkdir(dirname(base), { recursive: true });
+    await writeFile(privateKeyFile, keys.privateKey, { flag: 'wx', mode: 0o600 });
+    await writeFile(publicKeyFile, `${keys.publicKey}\n`, { flag: 'wx' });
+    return { keyId: keys.keyId, publicKey: keys.publicKey, privateKeyFile, publicKeyFile };
+}
+const releaseConfigSchema = z
+    .strictObject({
+    /** The catalog currently published; the new one continues its sequence. */
+    previous: z.string().min(1).optional(),
+    /** The sequence of a first publication, when there is no previous catalog. */
+    initialSequence: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
+    /** Every package the new catalog offers, as `.vormioplugin` files. */
+    packages: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(catalogLimits.maxPlugins * catalogLimits.maxReleasesPerPlugin),
+})
+    .refine((config) => (config.previous === undefined) !== (config.initialSequence === undefined), {
+    message: 'Give either previous or initialSequence',
+});
+async function readRelease(path) {
+    const size = (await stat(path).catch(() => undefined))?.size;
+    if (size === undefined)
+        throw new PublishError([`Package not found: ${path}`]);
+    if (size > packageLimits.maxArchiveBytes)
+        throw new PublishError([`${path}: larger than ${packageLimits.maxArchiveBytes} bytes`]);
+    const data = await readInput(path, 'Package');
+    try {
+        const { checked, contents } = readPackageArchive(data);
+        const sha256 = createHash('sha256').update(data).digest('hex');
+        const { id, version } = checked.manifest;
+        return {
+            id,
+            version,
+            // The manifest as the package has it, so hosts compare like with like after downloading.
+            manifest: JSON.parse(contents.get('manifest.json').toString('utf8')),
+            data,
+            sha256,
+            file: `packages/${id}-${version}-${sha256.slice(0, 12)}.vormioplugin`,
+        };
+    }
+    catch (error) {
+        if (error instanceof PackageError)
+            throw new PublishError(error.problems.map((problem) => `${path}: ${problem}`));
+        if (error instanceof ZipError)
+            throw new PublishError([`${path}: ${error.message}`]);
+        throw error;
+    }
+}
+/**
+ * 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 async function writeCatalog(options) {
+    const configFile = resolve(options.config);
+    const base = dirname(configFile);
+    let json;
+    try {
+        json = JSON.parse((await readInput(configFile, 'Release configuration')).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new PublishError([`${configFile}: not valid JSON`]);
+        throw error;
+    }
+    const parsed = releaseConfigSchema.safeParse(json);
+    if (!parsed.success)
+        throw new PublishError(parsed.error.issues.map((issue) => `${issue.path.join('.') || 'config'}: ${issue.message}`));
+    const config = parsed.data;
+    const privateKey = (await readInput(resolve(options.privateKey), 'Private key')).toString('utf8');
+    const publicKey = catalogPublicKey(privateKey);
+    const keyId = catalogKeyId(publicKey);
+    // The private key cannot be inside an empty folder, so this also keeps it out of the upload.
+    const out = resolve(options.out);
+    if (existsSync(out) && (await readdir(out)).length > 0)
+        throw new PublishError([`${out} is not empty; publish into a new folder`]);
+    let sequence = config.initialSequence;
+    if (config.previous !== undefined) {
+        const previousFile = resolve(base, config.previous);
+        try {
+            sequence =
+                verifyCatalog(await readInput(previousFile, 'Previous catalog'), publicKey).sequence + 1;
+        }
+        catch (error) {
+            if (error instanceof CatalogError)
+                throw new PublishError(error.problems.map((problem) => `${previousFile}: ${problem}`));
+            throw error;
+        }
+    }
+    const problems = [];
+    const plugins = new Map();
+    for (const path of config.packages) {
+        try {
+            const release = await readRelease(resolve(base, path));
+            const releases = plugins.get(release.id) ?? [];
+            if (releases.some((other) => other.version === release.version))
+                problems.push(`${release.id} ${release.version} is listed more than once`);
+            releases.push(release);
+            plugins.set(release.id, releases);
+        }
+        catch (error) {
+            if (!(error instanceof PublishError))
+                throw error;
+            problems.push(...error.problems);
+        }
+    }
+    if (problems.length)
+        throw new PublishError(problems);
+    const ordered = [...plugins.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([id, releases]) => ({
+        id,
+        releases: releases.sort((a, b) => compareVersions(b.version, a.version)),
+    }));
+    const payload = {
+        sequence,
+        publishedAt: (options.now ?? new Date()).toISOString(),
+        plugins: ordered.map(({ id, releases }) => ({
+            id,
+            releases: releases.map(({ manifest, file, data, sha256 }) => ({
+                manifest: manifest,
+                file,
+                bytes: data.length,
+                sha256,
+            })),
+        })),
+    };
+    let catalog;
+    try {
+        catalog = signCatalog(payload, privateKey);
+    }
+    catch (error) {
+        if (error instanceof CatalogError)
+            throw new PublishError([...error.problems]);
+        throw error;
+    }
+    await mkdir(join(out, 'packages'), { recursive: true });
+    const releases = ordered.flatMap(({ releases }) => releases);
+    for (const release of releases)
+        await writeFile(join(out, release.file), release.data, { flag: 'wx' });
+    await writeFile(join(out, 'catalog.json'), catalog, { flag: 'wx' });
+    verifyCatalog(await readFile(join(out, 'catalog.json')), publicKey);
+    return {
+        keyId,
+        sequence,
+        releases: releases.map(({ id, version, file, data, sha256 }) => ({
+            id,
+            version,
+            file,
+            bytes: data.length,
+            sha256,
+        })),
+    };
+}

package/dist/package-rules.d.ts

@@ -4,6 +4,8 @@ export declare const packageLimits: {
     readonly maxFileBytes: number;
     readonly maxTotalBytes: number;
     readonly maxPathLength: 240;
+    /** A `.vormioplugin` file. Archives are read whole, so this bounds memory before validation. */
+    readonly maxArchiveBytes: number;
 };
 /** Static file types a package may contain. Executables and archives are never accepted. */
 export declare const packageExtensions: ReadonlySet<string>;

package/dist/package-rules.js

@@ -4,6 +4,8 @@ export const packageLimits = {
     maxFileBytes: 16 * 1024 * 1024,
     maxTotalBytes: 64 * 1024 * 1024,
     maxPathLength: 240,
+    /** A `.vormioplugin` file. Archives are read whole, so this bounds memory before validation. */
+    maxArchiveBytes: 96 * 1024 * 1024,
 };
 /** Static file types a package may contain. Executables and archives are never accepted. */
 export const packageExtensions = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vormio/plugin-sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Manifest schema, runtime helpers and packaging for Vormio plugins.",
   "license": "MIT",
   "keywords": [