@wpelevator/wp-release 0.2.0 → 0.4.0

package/dist/signing.js

@@ -0,0 +1,140 @@
+import { createHash, createPrivateKey, createPublicKey, sign, verify, } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { ValidationError } from "./errors.js";
+export const SIGNATURE_EXTENSION = '.sig';
+/**
+ * Environment variable with the base64 Ed25519 signing key.
+ */
+export const SIGNING_KEY_ENV = 'WP_RELEASE_SIGNING_KEY';
+const SEED_BYTES = 32;
+const SECRET_KEY_BYTES = 64;
+const PUBLIC_KEY_BYTES = 32;
+// DER prefix of a PKCS#8 Ed25519 private key, followed by the 32-byte seed.
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+// DER prefix of a SPKI Ed25519 public key, followed by the 32-byte key.
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+/**
+ * Decode a base64 key, accepting the base64url alphabet and whitespace.
+ *
+ * @param value Encoded key.
+ * @return Key bytes.
+ */
+function decodeKey(value) {
+    return Buffer.from(value.trim(), 'base64');
+}
+/**
+ * Get an Ed25519 private key from the base64 format that sodium and the
+ * update-client signing_key setting use: a 32-byte seed or a 64-byte
+ * libsodium secret key, which is the seed followed by the public key.
+ *
+ * @param  encoded Base64 key.
+ * @return Private key.
+ * @throws {ValidationError} If the key has an unsupported length.
+ */
+export function parseSigningKey(encoded) {
+    const bytes = decodeKey(encoded);
+    if (SEED_BYTES !== bytes.length && SECRET_KEY_BYTES !== bytes.length) {
+        throw new ValidationError(`The signing key must be a base64 ${SEED_BYTES}-byte Ed25519 seed or ${SECRET_KEY_BYTES}-byte secret key, got ${bytes.length} bytes.`);
+    }
+    return createPrivateKey({
+        key: Buffer.concat([PKCS8_PREFIX, bytes.subarray(0, SEED_BYTES)]),
+        format: 'der',
+        type: 'pkcs8',
+    });
+}
+/**
+ * Get an Ed25519 public key from its base64 form.
+ *
+ * @param  encoded Base64 32-byte public key.
+ * @return Public key.
+ * @throws {ValidationError} If the key has an unsupported length.
+ */
+export function parsePublicKey(encoded) {
+    const bytes = decodeKey(encoded);
+    if (PUBLIC_KEY_BYTES !== bytes.length) {
+        throw new ValidationError(`The public key must be a base64 ${PUBLIC_KEY_BYTES}-byte Ed25519 key, got ${bytes.length} bytes.`);
+    }
+    return createPublicKey({
+        key: Buffer.concat([SPKI_PREFIX, bytes]),
+        format: 'der',
+        type: 'spki',
+    });
+}
+/**
+ * Get the base64 public key for a private key, in the format that
+ * verify_file_signature() callers and update-client take.
+ *
+ * @param privateKey Private key from parseSigningKey().
+ * @return Base64 public key.
+ */
+export function getPublicKey(privateKey) {
+    const der = createPublicKey(privateKey).export({
+        format: 'der',
+        type: 'spki',
+    });
+    return der.subarray(SPKI_PREFIX.length).toString('base64');
+}
+/**
+ * Get the raw SHA-384 digest of a file, which is what WordPress core's
+ * verify_file_signature() verifies the signature against.
+ *
+ * @param path File path.
+ * @return Digest bytes.
+ */
+export async function getFileDigest(path) {
+    const hash = createHash('sha384');
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+    }
+    return hash.digest();
+}
+/**
+ * Sign a file with a detached Ed25519 signature of its raw SHA-384 digest.
+ *
+ * @param path       File path.
+ * @param privateKey Private key from parseSigningKey().
+ * @return Base64 signature.
+ */
+export async function signFile(path, privateKey) {
+    return sign(null, await getFileDigest(path), privateKey).toString('base64');
+}
+/**
+ * Write the signature of a file to a .sig file next to it.
+ *
+ * @param  path       File path.
+ * @param  privateKey Private key from parseSigningKey().
+ * @param  force      Whether to overwrite an existing signature file.
+ * @return Signature file path.
+ * @throws {ValidationError} If the signature file exists and force isn't set.
+ */
+export async function writeSignature(path, privateKey, force = false) {
+    const signaturePath = path + SIGNATURE_EXTENSION;
+    const signature = await signFile(path, privateKey);
+    await writeFile(signaturePath, signature + '\n', {
+        flag: force ? 'w' : 'wx',
+    }).catch((error) => {
+        throw 'EEXIST' === error.code
+            ? new ValidationError(`${signaturePath} already exists, pass --force to overwrite it.`)
+            : error;
+    });
+    return signaturePath;
+}
+/**
+ * Check a file against a .sig file, which holds one base64 signature per
+ * line. The file is valid when any of the signatures match, so that a file
+ * can carry the signatures of a key rotation window.
+ *
+ * @param path          File path.
+ * @param signaturePath Signature file path.
+ * @param publicKey     Public key from parsePublicKey().
+ * @return Whether a signature matches.
+ */
+export async function verifyFileSignature(path, signaturePath, publicKey) {
+    const digest = await getFileDigest(path);
+    const signatures = (await readFile(signaturePath, 'utf8'))
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return signatures.some((signature) => verify(null, digest, publicKey, Buffer.from(signature, 'base64')));
+}

package/dist/svn-deploy.d.ts

@@ -71,9 +71,12 @@ export declare class SvnDeploy {
      */
     prepare(): Promise<void>;
     /**
-     * Check the plugin files before anything is written. A trunk sync needs
-     * a plugin with a Version header that matches the version, and with an
-     * SVN tag also a readme Stable tag that matches.
+     * Check the plugin files before anything is written. A trunk sync or a
+     * tag built from the files needs a plugin with a Version header that
+     * matches the version. When trunk is also copied to the tag, the readme
+     * Stable tag must match too, which a tag-only run skips since a
+     * pre-release tag doesn't change the stable tag. Readme-only updates need
+     * the readme.
      *
      * @throws {ValidationError} When the files or versions don't match.
      */
@@ -88,7 +91,9 @@ export declare class SvnDeploy {
     readPluginMeta(sourceDir: string): Promise<PackageMeta>;
     /**
      * Create a sparse checkout with only the directories the flags write to,
-     * creating the ones that don't exist in the repository yet.
+     * creating the ones that don't exist in the repository yet. An existing
+     * tag that's replaced from the files is checked out in full, so that the
+     * sync can update and delete its files.
      *
      * @throws {ValidationError} If the SVN tag exists and force isn't set.
      */
@@ -109,6 +114,7 @@ export declare class SvnDeploy {
     /**
      * Copy the files for each write flag into the working copy and stage
      * additions, deletions and asset MIME types, then copy trunk to the tag.
+     * Without a trunk sync, the tag is built from the files instead.
      */
     sync(): Promise<void>;
     /**
@@ -133,9 +139,8 @@ export declare class SvnDeploy {
      */
     setAssetMimeTypes(): Promise<void>;
     /**
-     * Copy trunk to the SVN tag, replacing an existing tag with force. Trunk
-     * is copied from the working copy when this run writes to it, and from the
-     * repository otherwise, so that tagging doesn't need a trunk checkout.
+     * Copy the synced trunk to the SVN tag, replacing an existing tag with
+     * force. Without a trunk sync, the tag was already built from the files.
      */
     copyTag(): Promise<void>;
     /**
@@ -184,7 +189,7 @@ export declare class SvnDeploy {
     /**
      * Check if the deploy reads plugin files, which assets-only runs don't.
      *
-     * @return Whether trunk is written.
+     * @return Whether trunk, the readme or a tag is written.
      */
     needsFiles(): boolean;
     /**
@@ -199,12 +204,6 @@ export declare class SvnDeploy {
      * @return Rules description, empty without rules.
      */
     describeRules(): string;
-    /**
-     * Get the repository URL of trunk.
-     *
-     * @return Trunk URL without a double slash.
-     */
-    getTrunkUrl(): string;
     /**
      * Get the path of the tag in the working copy.
      *

package/dist/svn-deploy.js

@@ -9,7 +9,7 @@ import { CredentialsError, ValidationError } from "./errors.js";
 import { loadFileRules, selectFiles } from "./file-selection.js";
 import { readPackageMeta } from "./package-meta.js";
 import { Svn } from "./svn.js";
-import { syncDirectory } from "./sync.js";
+import { copyFileIfChanged, syncDirectory } from "./sync.js";
 import { extractZip } from "./unzip.js";
 import { findVersionMismatches } from "./version-check.js";
 /**
@@ -95,29 +95,39 @@ export class SvnDeploy {
         }
     }
     /**
-     * Check the plugin files before anything is written. A trunk sync needs
-     * a plugin with a Version header that matches the version, and with an
-     * SVN tag also a readme Stable tag that matches.
+     * Check the plugin files before anything is written. A trunk sync or a
+     * tag built from the files needs a plugin with a Version header that
+     * matches the version. When trunk is also copied to the tag, the readme
+     * Stable tag must match too, which a tag-only run skips since a
+     * pre-release tag doesn't change the stable tag. Readme-only updates need
+     * the readme.
      *
      * @throws {ValidationError} When the files or versions don't match.
      */
     async checkVersions() {
-        const { trunk, svnTag, slug } = this.options;
+        const { trunk, readmeOnly, svnTag, slug, readme } = this.options;
         const sourceDir = this.filesDir ?? this.options.sourceDir;
-        if (trunk) {
+        if (this.needsFiles()) {
             const meta = await this.readPluginMeta(sourceDir);
-            const { version, mismatches } = await findVersionMismatches({
-                sourceDir,
-                meta,
-                slug,
-                version: this.options.version,
-                stableTag: Boolean(svnTag),
-            });
-            this.version = version;
-            if (mismatches.length) {
-                throw new ValidationError(mismatches.map(({ message }) => message).join('\n'));
+            if (readmeOnly && !meta.readme) {
+                throw new ValidationError(`${readme} doesn't exist in ${sourceDir}.`);
+            }
+            if (trunk || svnTag) {
+                const { version, mismatches } = await findVersionMismatches({
+                    sourceDir,
+                    meta,
+                    slug,
+                    version: this.options.version,
+                    stableTag: Boolean(trunk && svnTag),
+                });
+                this.version = version;
+                if (mismatches.length) {
+                    throw new ValidationError(mismatches
+                        .map(({ message }) => message)
+                        .join('\n'));
+                }
+                this.logger.info(`Deploying version ${version}.`);
             }
-            this.logger.info(`Deploying version ${version}.`);
         }
     }
     /**
@@ -140,7 +150,9 @@ export class SvnDeploy {
     }
     /**
      * Create a sparse checkout with only the directories the flags write to,
-     * creating the ones that don't exist in the repository yet.
+     * creating the ones that don't exist in the repository yet. An existing
+     * tag that's replaced from the files is checked out in full, so that the
+     * sync can update and delete its files.
      *
      * @throws {ValidationError} If the SVN tag exists and force isn't set.
      */
@@ -159,6 +171,12 @@ export class SvnDeploy {
         if (tagPath && !this.options.force && this.hasTag()) {
             throw new ValidationError(`${tagPath} already exists in ${this.options.svnUrl}. Pass --force to replace it.`);
         }
+        if (tagPath && !this.options.trunk && this.hasTag()) {
+            await this.svn.update({
+                path: join(workingCopy, tagPath),
+                depth: 'infinity',
+            });
+        }
     }
     /**
      * Create and add a top-level directory that's missing from the repository,
@@ -185,9 +203,11 @@ export class SvnDeploy {
     /**
      * Copy the files for each write flag into the working copy and stage
      * additions, deletions and asset MIME types, then copy trunk to the tag.
+     * Without a trunk sync, the tag is built from the files instead.
      */
     async sync() {
-        const { trunk, assets } = this.options;
+        const { trunk, readmeOnly, assets, readme } = this.options;
+        const tagPath = this.getTagPath();
         const workingCopy = this.getWorkingCopy();
         const sourceDir = this.filesDir ?? this.options.sourceDir;
         if (trunk) {
@@ -197,6 +217,16 @@ export class SvnDeploy {
                 targetDir: join(workingCopy, 'trunk'),
             });
         }
+        if (tagPath && !trunk) {
+            await syncDirectory({
+                sourceDir,
+                files: await this.getSourceFiles(sourceDir),
+                targetDir: join(workingCopy, tagPath),
+            });
+        }
+        if (readmeOnly) {
+            await copyFileIfChanged(join(sourceDir, readme), join(workingCopy, 'trunk', readme));
+        }
         if (assets) {
             await this.syncAssets();
         }
@@ -266,20 +296,22 @@ export class SvnDeploy {
         }
     }
     /**
-     * Copy trunk to the SVN tag, replacing an existing tag with force. Trunk
-     * is copied from the working copy when this run writes to it, and from the
-     * repository otherwise, so that tagging doesn't need a trunk checkout.
+     * Copy the synced trunk to the SVN tag, replacing an existing tag with
+     * force. Without a trunk sync, the tag was already built from the files.
      */
     async copyTag() {
         const tagPath = this.getTagPath();
         const workingCopy = this.getWorkingCopy();
-        if (tagPath && this.hasTag()) {
-            this.logger.warning(`Replacing the existing ${tagPath}.`);
-            await this.svn.remove({ paths: [tagPath], cwd: workingCopy });
-        }
-        if (tagPath) {
+        if (tagPath && this.options.trunk) {
+            if (this.hasTag()) {
+                this.logger.warning(`Replacing the existing ${tagPath}.`);
+                await this.svn.remove({
+                    paths: [tagPath],
+                    cwd: workingCopy,
+                });
+            }
             await this.svn.copy({
-                from: this.needsFiles() ? 'trunk' : this.getTrunkUrl(),
+                from: 'trunk',
                 to: tagPath,
                 cwd: workingCopy,
             });
@@ -367,7 +399,7 @@ export class SvnDeploy {
      * @return Planned changes, in order.
      */
     getPlan() {
-        const { svnUrl, trunk, assets, assetsDir, force } = this.options;
+        const { svnUrl, trunk, readmeOnly, assets, assetsDir, readme, force } = this.options;
         const tagPath = this.getTagPath();
         const message = this.options.message ?? this.getDefaultMessage();
         const plan = [
@@ -377,7 +409,11 @@ export class SvnDeploy {
             tagPath && !force && `Stop if ${tagPath} already exists`,
             tagPath && force && `Replace ${tagPath} if it exists`,
             trunk && `Sync ${this.describeSource()} to trunk/`,
-            tagPath && `Copy trunk/ to ${tagPath}`,
+            readmeOnly && `Copy ${readme} to trunk/`,
+            tagPath && trunk && `Copy trunk/ to ${tagPath}`,
+            tagPath &&
+                !trunk &&
+                `Sync ${this.describeSource()} to ${tagPath}`,
             assets && `Sync ${assetsDir} to assets/`,
             this.options.dryRun
                 ? `Skip the commit "${message}" (dry run)`
@@ -392,9 +428,9 @@ export class SvnDeploy {
      * @return Relative paths with their SVN checkout depth.
      */
     getCheckoutPaths() {
-        const { trunk, svnTag, assets } = this.options;
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
         const paths = [];
-        if (trunk) {
+        if (trunk || readmeOnly) {
             paths.push({ path: 'trunk', depth: 'infinity' });
         }
         if (svnTag) {
@@ -411,16 +447,17 @@ export class SvnDeploy {
      * @return Whether to check out and commit.
      */
     hasWrites() {
-        const { trunk, svnTag, assets } = this.options;
-        return Boolean(trunk || svnTag || assets);
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
+        return Boolean(trunk || readmeOnly || svnTag || assets);
     }
     /**
      * Check if the deploy reads plugin files, which assets-only runs don't.
      *
-     * @return Whether trunk is written.
+     * @return Whether trunk, the readme or a tag is written.
      */
     needsFiles() {
-        return this.options.trunk;
+        const { trunk, readmeOnly, svnTag } = this.options;
+        return Boolean(trunk || readmeOnly || svnTag);
     }
     /**
      * Describe the files that are synced, including the ignore rules.
@@ -448,14 +485,6 @@ export class SvnDeploy {
         ];
         return rules.filter(Boolean).join(', ');
     }
-    /**
-     * Get the repository URL of trunk.
-     *
-     * @return Trunk URL without a double slash.
-     */
-    getTrunkUrl() {
-        return `${this.options.svnUrl.replace(/\/+$/, '')}/trunk`;
-    }
     /**
      * Get the path of the tag in the working copy.
      *
@@ -469,11 +498,15 @@ export class SvnDeploy {
         return null;
     }
     getDefaultMessage() {
-        const { trunk, svnTag, assets } = this.options;
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
         if (svnTag) {
             return `Release version ${svnTag}`;
         }
-        const parts = [trunk && 'trunk', assets && 'assets'];
+        const parts = [
+            trunk && 'trunk',
+            readmeOnly && 'readme',
+            assets && 'assets',
+        ];
         return `Update ${parts.filter(Boolean).join(' and ')}`;
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@wpelevator/wp-release",
-	"version": "0.2.0",
-	"description": "Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
+	"version": "0.4.0",
+	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -35,7 +35,9 @@
 		"release",
 		"deploy",
 		"svn",
-		"zip"
+		"zip",
+		"checksums",
+		"signing"
 	],
 	"dependencies": {
 		"ignore": "^7.0.12",