@droposs/plugin-cli 0.5.9 → 0.6.1

package/bin/drop-plugin.js

@@ -6,6 +6,7 @@ import {
   testPlugin,
   initPlugin,
   validateManifest,
+  verifyPlugin,
 } from "../dist/index.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -13,6 +14,23 @@ import path from "node:path";
 const command = process.argv[2];
 const args = process.argv.slice(3);
 
+/** Reads `--flag value`; exits with an error when the value is missing. */
+function readFlagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    console.error(`${flag} requires a value`);
+    process.exit(1);
+  }
+  return value;
+}
+
+/** First positional argument, ignoring flags and their values. */
+function positionalArg(argv, flagValues = []) {
+  return argv.find((arg) => !arg.startsWith("-") && !flagValues.includes(arg));
+}
+
 async function runValidate(dir) {
   const manifestPath = path.join(
     path.resolve(process.cwd(), dir),
@@ -36,20 +54,42 @@ function printUsage() {
 Usage:
   drop-plugin init [dir]         Initialize a new plugin from starter template
   drop-plugin build [dir]        Bundle server/client entry points with esbuild and sign
+                                 (--out-manifest <path> keeps the source manifest clean)
   drop-plugin sign [dir]         Calculate SHA-256 digests and sign drop-plugin.json
+                                 (--out-manifest <path> writes the derived manifest elsewhere)
+  drop-plugin verify [dir]       Verify checksums and signature of a bundle
+                                 (--allow-unsigned accepts bundles without a signature)
   drop-plugin validate [dir]     Validate drop-plugin.json against official schema
   drop-plugin test [dir]         Run plugin tests with Node test runner
   drop-plugin pack [dir] [out]   Verify, sign, and package bundle into .dropplugin archive
 `);
 }
 
+async function runVerify(argv) {
+  const allowUnsigned = argv.includes("--allow-unsigned");
+  const dir = positionalArg(argv) || ".";
+  const res = await verifyPlugin(dir, undefined, { allowUnsigned });
+  if (!res.valid) {
+    console.error("Verification failed:");
+    for (const err of res.errors) {
+      console.error(`  - ${err}`);
+    }
+    process.exit(1);
+  }
+  console.log(
+    `Bundle at ${dir} is valid (signature: ${res.signed ? "verified" : "none"}).`,
+  );
+}
+
 async function main() {
   switch (command) {
     case "sign": {
-      const dir = args[0] || ".";
-      const res = await signPlugin(dir);
+      const outManifest = readFlagValue(args, "--out-manifest");
+      const dir = positionalArg(args, [outManifest]) || ".";
+      const res = await signPlugin(dir, undefined, true, { outManifest });
       console.log(
-        `Signed bundle at ${dir}: ${res.fileCount} files verified (signature: ${res.signed ? "yes" : "no"})`,
+        `Signed bundle at ${dir}: ${res.fileCount} files verified (signature: ${res.signed ? "yes" : "no"})` +
+          (outManifest ? `; manifest written to ${outManifest}` : ""),
       );
       break;
     }
@@ -63,8 +103,9 @@ async function main() {
       break;
     }
     case "build": {
-      const dir = args[0] || ".";
-      const res = await buildPlugin(dir);
+      const outManifest = readFlagValue(args, "--out-manifest");
+      const dir = positionalArg(args, [outManifest]) || ".";
+      const res = await buildPlugin(dir, { outManifest });
       console.log(
         `Built plugin at ${dir} (server: ${res.serverBuilt ? "yes" : "no"}, client: ${res.clientBuilt ? "yes" : "no"})`,
       );
@@ -87,6 +128,10 @@ async function main() {
       await runValidate(args[0] || ".");
       break;
     }
+    case "verify": {
+      await runVerify(args);
+      break;
+    }
     case "help":
     case "--help":
     case "-h":

package/dist/builder.d.ts

@@ -3,6 +3,8 @@ export interface BuildOptions {
     sourcemap?: boolean;
     sign?: boolean;
     signingKey?: string;
+    /** Write derived manifest fields here instead of the source manifest. */
+    outManifest?: string;
 }
 export declare function buildPlugin(targetDir?: string, options?: BuildOptions): Promise<{
     serverBuilt: boolean;

package/dist/builder.js

@@ -34,7 +34,13 @@ export async function buildPlugin(targetDir = ".", options = {}) {
             format: "esm",
             sourcemap: options.sourcemap ?? true,
             minify: options.minify ?? false,
-            external: ["@droposs/plugin-sdk", "@drop/plugin-sdk", "h3", "pino"],
+            external: [
+                "@droposs/plugin-sdk",
+                "@droposs/plugin-sdk",
+                "@drop/plugin-sdk",
+                "h3",
+                "pino",
+            ],
         });
         serverBuilt = true;
     }
@@ -63,13 +69,20 @@ export async function buildPlugin(targetDir = ".", options = {}) {
             format: "esm",
             sourcemap: options.sourcemap ?? true,
             minify: options.minify ?? false,
-            external: ["vue", "@droposs/plugin-sdk", "@drop/plugin-sdk"],
+            external: [
+                "vue",
+                "@droposs/plugin-sdk",
+                "@droposs/plugin-sdk",
+                "@drop/plugin-sdk",
+            ],
         });
         clientBuilt = true;
     }
     // 3. Automatically re-sign the plugin bundle after building
     if (options.sign !== false) {
-        await signPlugin(dir, options.signingKey);
+        await signPlugin(dir, options.signingKey, true, {
+            outManifest: options.outManifest,
+        });
     }
     return { serverBuilt, clientBuilt };
 }

package/dist/signer.d.ts

@@ -1,13 +1,44 @@
+import { SIGNATURE_VERSION } from "@drop-oss/plugin-sdk";
+/** Current signature scheme; re-exported for backwards compatibility. */
+export { SIGNATURE_VERSION };
+/**
+ * Signature payload v2: the files aggregate plus the canonical manifest
+ * (excluding its `signature` field), so `id`, `version`, and `capabilities`
+ * are covered and cannot be tampered with undetected. Shared algorithm with
+ * `drop` core's verifier.
+ */
+export declare function signaturePayloadV2(filesAggregate: string, manifest: Record<string, unknown>): string;
 export declare function isInside(base: string, candidate: string): boolean;
 export declare function validateManifest(manifest: unknown): Promise<{
     valid: boolean;
     errors: string[];
 }>;
 export declare function listFiles(root: string, prefix?: string): Promise<string[]>;
-export declare function signPlugin(targetDir: string, signingKey?: string, validate?: boolean): Promise<{
+export interface SignPluginOptions {
+    /**
+     * Write the derived manifest here instead of `<bundle>/drop-plugin.json`.
+     * The source manifest is left untouched, so derived fields (checksum, files,
+     * signature) can live only in a packaged artifact.
+     */
+    outManifest?: string;
+}
+export declare function signPlugin(targetDir: string, signingKey?: string, validate?: boolean, options?: SignPluginOptions): Promise<{
     fileCount: number;
     signed: boolean;
 }>;
+export interface VerifyResult {
+    valid: boolean;
+    signed: boolean;
+    errors: string[];
+}
+/**
+ * Verify a bundle against its shipped manifest: schema validity, per-file and
+ * entry SHA-256 checksums, and (when present) the HMAC signature covering the
+ * file aggregate plus the manifest itself.
+ */
+export declare function verifyPlugin(targetDir: string, signingKey?: string, options?: {
+    allowUnsigned?: boolean;
+}): Promise<VerifyResult>;
 export declare function packPlugin(targetDir: string, outputDir?: string): Promise<{
     packagePath: string;
     id: string;

package/dist/signer.js

@@ -1,23 +1,90 @@
-import { createHash, createHmac } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { readdir, readFile, realpath, stat, writeFile, mkdir, } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 import Ajv from "ajv";
+import { SIGNATURE_VERSION } from "@droposs/plugin-sdk";
 const MANIFEST_FILE = "drop-plugin.json";
+/** Current signature scheme; re-exported for backwards compatibility. */
+export { SIGNATURE_VERSION };
+/** Deterministic JSON so signer and verifier hash identical manifest bytes. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort((a, b) => a.localeCompare(b, "en"));
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Whether a bundle-relative path is executable plugin code. */
+function isBundleCodeFile(rel) {
+    const ext = path.extname(rel).toLowerCase();
+    return ext === ".js" || ext === ".mjs" || ext === ".cjs";
+}
+/**
+ * Aggregate digest over every bundle file, byte-compatible with the digest
+ * `drop` core computes when verifying legacy signatures.
+ */
+async function computeFilesAggregate(bundleDir, files) {
+    const aggregate = createHash("sha256");
+    for (const rel of files) {
+        const bytes = await readFile(path.join(bundleDir, rel));
+        aggregate.update(rel);
+        aggregate.update("\0");
+        aggregate.update(String(bytes.length));
+        aggregate.update("\0");
+        aggregate.update(bytes);
+    }
+    return aggregate.digest("hex");
+}
+/**
+ * Signature payload v2: the files aggregate plus the canonical manifest
+ * (excluding its `signature` field), so `id`, `version`, and `capabilities`
+ * are covered and cannot be tampered with undetected. Shared algorithm with
+ * `drop` core's verifier.
+ */
+export function signaturePayloadV2(filesAggregate, manifest) {
+    const { signature: _ignored, ...signable } = manifest;
+    return createHash("sha256")
+        .update(filesAggregate)
+        .update("\0")
+        .update(stableStringify(signable))
+        .digest("hex");
+}
+function safeEqualHex(a, b) {
+    const left = Buffer.from(a, "hex");
+    const right = Buffer.from(b, "hex");
+    if (left.length !== right.length || left.length === 0)
+        return false;
+    return timingSafeEqual(left, right);
+}
 export function isInside(base, candidate) {
     const rel = path.relative(path.resolve(base), path.resolve(candidate));
     return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 async function loadSchema() {
-    try {
-        const require = createRequire(import.meta.url);
-        const schemaPath = require.resolve("@droposs/plugin-sdk/schema.json");
-        return JSON.parse(await readFile(schemaPath, "utf-8"));
-    }
-    catch {
-        const fallback = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../plugin-sdk/schema/drop-plugin.schema.json");
-        return JSON.parse(await readFile(fallback, "utf-8"));
+    const require = createRequire(import.meta.url);
+    for (const specifier of [
+        "@droposs/plugin-sdk/schema.json",
+        "@droposs/plugin-sdk/schema.json",
+    ]) {
+        try {
+            return JSON.parse(await readFile(require.resolve(specifier), "utf-8"));
+        }
+        catch {
+            // Try the next package scope before falling back to the monorepo path.
+        }
     }
+    const fallback = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../plugin-sdk/schema/drop-plugin.schema.json");
+    return JSON.parse(await readFile(fallback, "utf-8"));
 }
 let cachedValidator = null;
 let cachedErrors = [];
@@ -68,20 +135,11 @@ export async function listFiles(root, prefix = "") {
     }
     return results.sort((a, b) => a.localeCompare(b));
 }
-export async function signPlugin(targetDir, signingKey, validate = true) {
-    const resolvedPath = path.resolve(process.cwd(), targetDir);
-    const bundleDir = await realpath(resolvedPath).catch(() => null);
-    if (!bundleDir) {
-        throw new Error(`Directory not found: ${targetDir}`);
-    }
-    const manifestPath = path.join(bundleDir, MANIFEST_FILE);
-    const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
-    if (validate) {
-        const validation = await validateManifest(manifest);
-        if (!validation.valid) {
-            throw new Error(`Manifest validation failed against schema:\n  ${validation.errors.join("\n  ")}`);
-        }
-    }
+/**
+ * Compute the derived manifest (entry checksum, file checksums, signature)
+ * without writing anything to disk.
+ */
+async function deriveManifest(bundleDir, manifest, signingKey) {
     // Identify primary entry (v1 or v2 server/client entry)
     const entry = manifest.entry ??
         manifest.server?.entry ??
@@ -94,43 +152,189 @@ export async function signPlugin(targetDir, signingKey, validate = true) {
     const entryExists = await stat(entryPath).catch(() => null);
     if (entryExists) {
         const entryBytes = await readFile(entryPath);
-        manifest.checksum = createHash("sha256").update(entryBytes).digest("hex");
+        manifest.checksum = sha256Hex(entryBytes);
     }
     const files = await listFiles(bundleDir);
     const fileChecksums = {};
-    const aggregate = createHash("sha256");
     for (const rel of files) {
         const bytes = await readFile(path.join(bundleDir, rel));
-        fileChecksums[rel] = createHash("sha256").update(bytes).digest("hex");
-        aggregate.update(rel);
-        aggregate.update("\0");
-        aggregate.update(String(bytes.length));
-        aggregate.update("\0");
-        aggregate.update(bytes);
+        fileChecksums[rel] = sha256Hex(bytes);
     }
     manifest.files = fileChecksums;
     const key = signingKey ?? process.env.DROP_PLUGIN_SIGNING_KEY;
     if (key) {
+        manifest.signatureVersion = SIGNATURE_VERSION;
+        const filesAggregate = await computeFilesAggregate(bundleDir, files);
+        const payload = signaturePayloadV2(filesAggregate, manifest);
         manifest.signature = createHmac("sha256", key)
-            .update(aggregate.digest("hex"))
+            .update(payload)
             .digest("hex");
     }
     else {
         delete manifest.signature;
+        delete manifest.signatureVersion;
     }
-    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-    return { fileCount: files.length, signed: Boolean(key) };
+    return { manifest, fileCount: files.length, signed: Boolean(key) };
 }
-export async function packPlugin(targetDir, outputDir) {
+export async function signPlugin(targetDir, signingKey, validate = true, options = {}) {
     const resolvedPath = path.resolve(process.cwd(), targetDir);
     const bundleDir = await realpath(resolvedPath).catch(() => null);
     if (!bundleDir) {
         throw new Error(`Directory not found: ${targetDir}`);
     }
-    // Ensure bundle is signed and validated
-    await signPlugin(bundleDir);
     const manifestPath = path.join(bundleDir, MANIFEST_FILE);
     const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    if (validate) {
+        const validation = await validateManifest(manifest);
+        if (!validation.valid) {
+            throw new Error(`Manifest validation failed against schema:\n  ${validation.errors.join("\n  ")}`);
+        }
+    }
+    const derived = await deriveManifest(bundleDir, manifest, signingKey);
+    const outPath = options.outManifest
+        ? path.resolve(process.cwd(), options.outManifest)
+        : manifestPath;
+    await writeFile(outPath, `${JSON.stringify(derived.manifest, null, 2)}\n`);
+    return { fileCount: derived.fileCount, signed: derived.signed };
+}
+/**
+ * Verify a bundle against its shipped manifest: schema validity, per-file and
+ * entry SHA-256 checksums, and (when present) the HMAC signature covering the
+ * file aggregate plus the manifest itself.
+ */
+export async function verifyPlugin(targetDir, signingKey, options = {}) {
+    const resolvedPath = path.resolve(process.cwd(), targetDir);
+    const bundleDir = await realpath(resolvedPath).catch(() => null);
+    if (!bundleDir) {
+        throw new Error(`Directory not found: ${targetDir}`);
+    }
+    const manifestPath = path.join(bundleDir, MANIFEST_FILE);
+    const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    const errors = [];
+    const validation = await validateManifest(manifest);
+    if (!validation.valid) {
+        errors.push(...validation.errors.map((error) => `schema: ${error}`));
+    }
+    const declared = manifest.files;
+    const files = await listFiles(bundleDir);
+    const present = new Set(files);
+    const codeFiles = files.filter(isBundleCodeFile);
+    if (declared) {
+        for (const rel of files) {
+            const digest = sha256Hex(await readFile(path.join(bundleDir, rel)));
+            if (declared[rel] !== digest) {
+                errors.push(`checksum mismatch: ${rel}`);
+            }
+        }
+        for (const rel of Object.keys(declared)) {
+            const resolved = path.resolve(bundleDir, rel);
+            if (path.isAbsolute(rel) || !isInside(bundleDir, resolved)) {
+                errors.push(`invalid bundle file path: ${rel}`);
+                continue;
+            }
+            if (!present.has(rel)) {
+                errors.push(`declared file missing: ${rel}`);
+            }
+        }
+        for (const rel of codeFiles) {
+            if (!(rel in declared)) {
+                errors.push(`bundle file '${rel}' is not covered by the manifest 'files' checksums`);
+            }
+        }
+    }
+    else if (codeFiles.length > 1) {
+        errors.push("bundle contains multiple code files but no 'files' checksums; refusing unverified imports");
+    }
+    const entry = manifest.entry ?? manifest.server?.entry ?? manifest.client?.entry;
+    if (entry) {
+        const entryPath = path.resolve(bundleDir, entry);
+        if (!isInside(bundleDir, entryPath)) {
+            errors.push(`entry path outside bundle: ${entry}`);
+        }
+        else if (!(await stat(entryPath).catch(() => null))) {
+            errors.push(`entry file missing: ${entry}`);
+        }
+        else if (manifest.checksum) {
+            const digest = sha256Hex(await readFile(entryPath));
+            if (digest !== manifest.checksum) {
+                errors.push(`entry checksum mismatch: ${entry}`);
+            }
+        }
+    }
+    const key = signingKey ?? process.env.DROP_PLUGIN_SIGNING_KEY;
+    let signed = false;
+    if (manifest.signature) {
+        if (!key) {
+            errors.push("manifest is signed but no signing key is available");
+        }
+        else {
+            const filesAggregate = await computeFilesAggregate(bundleDir, files);
+            const resolved = await resolveSignedPayload(bundleDir, manifest, filesAggregate, entry);
+            if (resolved.payload === undefined) {
+                errors.push(resolved.error ?? "unable to reconstruct signature payload");
+            }
+            else {
+                const expected = createHmac("sha256", key)
+                    .update(resolved.payload)
+                    .digest("hex");
+                if (safeEqualHex(expected, manifest.signature)) {
+                    signed = true;
+                }
+                else {
+                    errors.push("signature verification failed");
+                }
+            }
+        }
+    }
+    else if (!options.allowUnsigned) {
+        errors.push("bundle is unsigned (pass --allow-unsigned to accept unsigned bundles)");
+    }
+    return { valid: errors.length === 0, signed, errors };
+}
+/**
+ * Reconstruct the payload a signature covers, depending on the scheme:
+ * v2 covers the file aggregate plus the canonical manifest; legacy bundles
+ * cover the file aggregate, or the entry checksum for single-file bundles.
+ */
+async function resolveSignedPayload(bundleDir, manifest, filesAggregate, entry) {
+    if (manifest.signatureVersion === SIGNATURE_VERSION) {
+        if (!manifest.files) {
+            return { error: "signatureVersion 2 requires manifest file checksums" };
+        }
+        return { payload: signaturePayloadV2(filesAggregate, manifest) };
+    }
+    if (manifest.signatureVersion !== undefined) {
+        return {
+            error: `unsupported signatureVersion: ${manifest.signatureVersion}`,
+        };
+    }
+    if (manifest.files) {
+        return { payload: filesAggregate };
+    }
+    if (manifest.checksum && entry) {
+        return {
+            payload: sha256Hex(await readFile(path.join(bundleDir, entry))),
+        };
+    }
+    return {
+        error: "legacy signature has neither file checksums nor an entry checksum",
+    };
+}
+export async function packPlugin(targetDir, outputDir) {
+    const resolvedPath = path.resolve(process.cwd(), targetDir);
+    const bundleDir = await realpath(resolvedPath).catch(() => null);
+    if (!bundleDir) {
+        throw new Error(`Directory not found: ${targetDir}`);
+    }
+    const manifestPath = path.join(bundleDir, MANIFEST_FILE);
+    const rawManifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    const validation = await validateManifest(rawManifest);
+    if (!validation.valid) {
+        throw new Error(`Manifest validation failed against schema:\n  ${validation.errors.join("\n  ")}`);
+    }
+    // Derive the signed manifest in memory: packing must not dirty the source
+    // tree, the derived fields live in the archive only.
+    const { manifest } = await deriveManifest(bundleDir, rawManifest);
     const id = manifest.id;
     const version = manifest.version;
     if (!id || !version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droposs/plugin-cli",
-  "version": "0.5.9",
+  "version": "0.6.1",
   "description": "Drop Plugin build, test, signing, and packaging CLI for Drop OSS",
   "type": "module",
   "bin": {
@@ -34,18 +34,22 @@
     "packaging",
     "playnite"
   ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.5.1",
     "typescript": "^5.7.0"
   },
   "license": "MIT",
   "dependencies": {
     "ajv": "^8.20.0",
     "esbuild": "^0.28.2",
-    "@droposs/plugin-sdk": "0.5.9"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "node --test"
+    "@droposs/plugin-sdk": "0.6.1"
   }
-}
+}