@wpelevator/wp-release 0.13.0 → 0.14.0

package/dist/minisign.js

@@ -0,0 +1,128 @@
+import { createHash, sign, verify } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { PUBLIC_KEY_BYTES, digestFile, getRawPublicKey } from "./ed25519.js";
+export const MINISIGN_EXTENSION = '.minisig';
+// Algorithm of a public key, and of a signature of the BLAKE2b-512 digest.
+const KEY_ALGORITHM = 'Ed';
+const HASHED_ALGORITHM = 'ED';
+const KEY_ID_BYTES = 8;
+const SIGNATURE_BYTES = 64;
+const UNTRUSTED_PREFIX = 'untrusted comment: ';
+const TRUSTED_PREFIX = 'trusted comment: ';
+/**
+ * Get the minisign key ID of a public key. minisign picks a random ID when
+ * it generates a key, so wp-release derives one from the public key instead,
+ * which keeps it the same for every signature of the key.
+ *
+ * @param publicKey Public key bytes.
+ * @return 8-byte key ID.
+ */
+function getKeyId(publicKey) {
+    return createHash('blake2b512')
+        .update(publicKey)
+        .digest()
+        .subarray(0, KEY_ID_BYTES);
+}
+/**
+ * Format a key ID like minisign prints it: the hex of the little-endian
+ * 64-bit number.
+ *
+ * @param keyId Key ID bytes.
+ * @return Uppercase hex key ID.
+ */
+function formatKeyId(keyId) {
+    return Buffer.from(keyId).reverse().toString('hex').toUpperCase();
+}
+/**
+ * Get the minisign public key of a key, the base64 line that `minisign -P`
+ * takes and that the second line of a minisign .pub file holds.
+ *
+ * @param key Private or public key.
+ * @return Base64 minisign public key.
+ */
+export function getMinisignPublicKey(key) {
+    const publicKey = getRawPublicKey(key);
+    return Buffer.concat([
+        Buffer.from(KEY_ALGORITHM),
+        getKeyId(publicKey),
+        publicKey,
+    ]).toString('base64');
+}
+/**
+ * Get the raw public key from a minisign public key, the base64 line or the
+ * whole two-line .pub file.
+ *
+ * @param encoded Minisign public key.
+ * @return Public key bytes, or null when it isn't a minisign public key.
+ */
+export function parseMinisignPublicKey(encoded) {
+    const line = encoded
+        .trim()
+        .split('\n')
+        .map((text) => text.trim())
+        .filter((text) => text && !text.startsWith(UNTRUSTED_PREFIX));
+    const bytes = Buffer.from(line.join(''), 'base64');
+    const isMinisign = 1 === line.length &&
+        2 + KEY_ID_BYTES + PUBLIC_KEY_BYTES === bytes.length &&
+        KEY_ALGORITHM === bytes.subarray(0, 2).toString();
+    return isMinisign ? bytes.subarray(2 + KEY_ID_BYTES) : null;
+}
+/**
+ * Create a minisign signature of a file: an Ed25519 signature of its
+ * BLAKE2b-512 digest, and a global signature that also covers the trusted
+ * comment with the signing time and file name.
+ *
+ * @param path       File path.
+ * @param privateKey Private key.
+ * @return Contents of the .minisig file.
+ */
+export async function createMinisignSignature(path, privateKey) {
+    const keyId = getKeyId(getRawPublicKey(privateKey));
+    const signature = sign(null, await digestFile(path, 'blake2b512'), privateKey);
+    const name = basename(path).replace(/[\r\n]/g, ' ');
+    const trustedComment = `timestamp:${Math.floor(Date.now() / 1000)}\tfile:${name}\thashed`;
+    const globalSignature = sign(null, Buffer.concat([signature, Buffer.from(trustedComment)]), privateKey);
+    return [
+        `${UNTRUSTED_PREFIX}signature from wp-release key ${formatKeyId(keyId)}`,
+        Buffer.concat([
+            Buffer.from(HASHED_ALGORITHM),
+            keyId,
+            signature,
+        ]).toString('base64'),
+        `${TRUSTED_PREFIX}${trustedComment}`,
+        globalSignature.toString('base64'),
+        '',
+    ].join('\n');
+}
+/**
+ * Check a file against a minisign signature file, including the global
+ * signature of the trusted comment. Both the BLAKE2b-512 prehashed (ED)
+ * and the legacy (Ed) signatures of minisign are accepted. The key ID isn't
+ * compared, since it only tells minisign which key to use, so signatures of
+ * keys that minisign generated with a random ID are accepted too.
+ *
+ * @param path          File path.
+ * @param signaturePath Signature file path.
+ * @param publicKey     Public key.
+ * @return Whether the signature matches.
+ */
+export async function verifyMinisignSignature(path, signaturePath, publicKey) {
+    const [, encoded = '', trusted = '', encodedGlobal = ''] = (await readFile(signaturePath, 'utf8'))
+        .split('\n')
+        .map((line) => line.trim());
+    const bytes = Buffer.from(encoded, 'base64');
+    const algorithm = bytes.subarray(0, 2).toString();
+    const signature = bytes.subarray(2 + KEY_ID_BYTES);
+    const isValidShape = 2 + KEY_ID_BYTES + SIGNATURE_BYTES === bytes.length &&
+        [HASHED_ALGORITHM, KEY_ALGORITHM].includes(algorithm) &&
+        trusted.startsWith(TRUSTED_PREFIX);
+    return (isValidShape &&
+        verify(null, HASHED_ALGORITHM === algorithm
+            ? await digestFile(path, 'blake2b512')
+            : await readFile(path), publicKey, signature) &&
+        verify(null, Buffer.concat([
+            signature,
+            Buffer.from(trusted.slice(TRUSTED_PREFIX.length)),
+        ]), publicKey, Buffer.from(encodedGlobal, 'base64')));
+}

package/dist/package-deploy.d.ts

@@ -7,6 +7,8 @@ export interface PackageDeployOptions {
     cwd: string;
     /** Config file, instead of the conventional one at the root. */
     configFile?: string;
+    /** Tag format that replaces the tagFormat of the config. */
+    tagFormat?: string;
     /**
      * Ref to deploy: a package release tag, like refs/tags/plugins/alpha/1.2.0,
      * or a branch, like refs/heads/main. A name without refs/ is a release tag
@@ -35,6 +37,10 @@ export interface PackageDeploy<Input> {
     target: string;
     /** Tag or branch that the deploy writes in the target. */
     targetRef: string;
+    /** Host of a remote target repository, like github.com. */
+    targetHost?: string;
+    /** Path of a remote target repository on its host, like owner/repo. */
+    targetPath?: string;
     /** Package, target and ref, with credentials redacted, for logs. */
     label: string;
     /** Options of the deploy. */
@@ -79,6 +85,24 @@ export declare function getDeployPackages(options: {
     cwd: string;
     configFile?: string;
 }): Promise<PackageDeployFiles[]>;
+/**
+ * Get a configured package with the files that its releases ship, from the
+ * files config of its package group, which its deploys use too, for example
+ * to build its ZIP with the same files. Any package of the config works, with
+ * or without a version or deploy targets.
+ *
+ * @param  options            Repository root, config file and package.
+ * @param  options.cwd        Repository root with the wp-release config.
+ * @param  options.configFile Config file, instead of the conventional one at the root.
+ * @param  options.package    Package identifier or path under the configured root.
+ * @return The package and its file selection.
+ * @throws {ValidationError} Without a config, for an invalid one or an unknown package.
+ */
+export declare function getPackageFiles(options: {
+    cwd: string;
+    configFile?: string;
+    package: string;
+}): Promise<PackageDeployFiles>;
 /** Ignore file and patterns that select the files of a package. */
 export interface PackageFileSelection {
     /** Absolute ignore file path, or false to not read one. */
@@ -93,6 +117,10 @@ export interface PackageDeployPlanItem extends PackageDeployRelease {
     targets: Array<{
         target: string;
         ref: string;
+        /** Host of a remote target repository. */
+        host?: string;
+        /** Path of a remote target repository on its host. */
+        path?: string;
     }>;
 }
 /**

package/dist/package-deploy.js

@@ -1,11 +1,11 @@
 import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { loadChangesetConfig, toTargetList } from "./changeset-config.js";
-import { discoverDeployPackages, findPackage } from "./changeset-packages.js";
+import { discoverDeployPackages, discoverConfiguredPackages, findPackage, } from "./changeset-packages.js";
 import { ValidationError } from "./errors.js";
-import { redactUrls } from "./git.js";
+import { parseRepositoryUrl, redactUrls } from "./git.js";
 import { ReleaseRepository } from "./release-repository.js";
-import { formatTag } from "./tag-format.js";
+import { DEFAULT_TAG_FORMAT, formatTag, formatTemplate } from "./tag-format.js";
 import { isPrerelease, isVersion } from "./versions.js";
 /**
  * Get the Git deploys of the configured packages that a ref releases: every
@@ -65,10 +65,35 @@ export async function getDeployPackages(options) {
         files: getFileSelection(pkg, config),
     }));
 }
+/**
+ * Get a configured package with the files that its releases ship, from the
+ * files config of its package group, which its deploys use too, for example
+ * to build its ZIP with the same files. Any package of the config works, with
+ * or without a version or deploy targets.
+ *
+ * @param  options            Repository root, config file and package.
+ * @param  options.cwd        Repository root with the wp-release config.
+ * @param  options.configFile Config file, instead of the conventional one at the root.
+ * @param  options.package    Package identifier or path under the configured root.
+ * @return The package and its file selection.
+ * @throws {ValidationError} Without a config, for an invalid one or an unknown package.
+ */
+export async function getPackageFiles(options) {
+    const config = await requireConfig(options);
+    const pkg = findPackage(await discoverConfiguredPackages(new ReleaseRepository({ cwd: options.cwd }), config), options.package);
+    if (!pkg) {
+        throw new ValidationError(`Unknown package "${options.package}".`);
+    }
+    return {
+        ...toDeployPackage(pkg),
+        files: getFileSelection(pkg, config),
+    };
+}
 async function requireConfig(options) {
     const loaded = await loadChangesetConfig({
         cwd: options.cwd,
         ...(options.configFile ? { configFile: options.configFile } : {}),
+        ...(options.tagFormat ? { tagFormat: options.tagFormat } : {}),
     });
     if (!loaded) {
         throw new ValidationError('No wp-release config found. Add wp-release.config.js or pass --config <path>.');
@@ -112,7 +137,7 @@ function selectPackages(packages, identifiers) {
  * @return Releases.
  */
 function getReleases(packages, config, ref) {
-    const tagFormat = config.tagFormat ?? '{path}/{version}';
+    const tagFormat = config.tagFormat ?? DEFAULT_TAG_FORMAT;
     const tag = ref.startsWith('refs/tags/')
         ? ref.slice('refs/tags/'.length)
         : ref;
@@ -156,12 +181,16 @@ async function getGitDeploy(target, release, config, root, options) {
             .relative(root, await realpath(pkg.directory))
             .split(path.sep)
             .join('/');
+    const location = repository ? parseRepositoryUrl(repository) : undefined;
     return repository
         ? {
             package: toDeployPackage(pkg),
             release: toRelease(release),
             target: redactUrls(repository),
             targetRef: ref,
+            ...(location
+                ? { targetHost: location.host, targetPath: location.path }
+                : {}),
             label: `${pkg.name} to ${redactUrls(repository)} ${ref}`,
             input: {
                 cwd: options.cwd,
@@ -181,7 +210,10 @@ async function getSvnDeploy(target, release, config, options) {
     const pkg = release.package;
     const version = release.version ?? '';
     const stable = !isPrerelease(version);
-    const slug = await resolveTemplate(target.slug ?? '{slug}', release, version);
+    // The WordPress.org slug is the name of the package directory by default.
+    const slug = target.slug
+        ? await resolveTemplate(target.slug, release, version)
+        : path.basename(pkg.directory);
     const message = target.message
         ? await resolveTemplate(target.message, release, version)
         : '';
@@ -230,7 +262,7 @@ async function resolveTemplate(template, release, ref) {
             ref,
             revision: release.revision,
         })
-        : formatTag(template, release.package, release.version ?? '')
+        : formatTemplate(template, release.package, release.version ?? '')
             .replaceAll('{branch}', release.branch ?? '')
             .replaceAll('{ref}', ref)
             .replaceAll('{revision}', release.revision);
@@ -282,6 +314,9 @@ export function getDeployPlan(deploys) {
             targets: items.map((item) => ({
                 target: item.target,
                 ref: item.targetRef,
+                ...(item.targetHost
+                    ? { host: item.targetHost, path: item.targetPath }
+                    : {}),
             })),
         };
     });

package/dist/package-zip.d.ts

@@ -0,0 +1,52 @@
+import type { PackageType } from './checksums.ts';
+import type { FileSelection } from './file-selection.ts';
+export interface ZipPackageInput {
+    /** Directory to archive. */
+    sourceDir: string;
+    /** File selection from resolveFileSelection(). */
+    selection: FileSelection;
+    /** Archive path. */
+    zipPath: string;
+    /** Folder inside the archive, or null for the root. */
+    rootFolder: string | null;
+    /** Plugin or theme slug, for the checksums manifest. */
+    slug: string;
+    /** Version for the checksums manifest. */
+    version?: string | null;
+    /** Package type for the checksums manifest. */
+    type?: PackageType;
+    /** Also write the checksums manifest next to the archive. */
+    checksums?: boolean;
+    /** Overwrite existing output files. */
+    force?: boolean;
+}
+/** Result of zipPackage(). */
+export interface ZipPackageResult {
+    /** Absolute path of the ZIP. */
+    zipPath: string;
+    /** Absolute path of the checksums manifest, set with checksums. */
+    checksumsPath?: string;
+    /** Number of archived files. */
+    files: number;
+}
+/**
+ * Get the checksums manifest path next to an archive, with .checksums.json
+ * instead of .zip.
+ *
+ * @param zipPath Archive path.
+ * @return Manifest path.
+ */
+export declare function getChecksumsPath(zipPath: string): string;
+/**
+ * Write a ZIP of the selected files of a plugin, theme or package, and
+ * optionally the checksums manifest of the same files next to it. The zip
+ * command, with a directory or a configured package release, and the
+ * snapshot builds of a monorepo all use it, so that every ZIP of a package
+ * selects its files the same way. Output files inside the source directory,
+ * and their signatures, are never archived.
+ *
+ * @param  input Files, archive path and manifest options.
+ * @return Paths of the written files and the number of archived files.
+ * @throws {ValidationError} Without selected files, or when an output file exists without force.
+ */
+export declare function zipPackage(input: ZipPackageInput): Promise<ZipPackageResult>;

package/dist/package-zip.js

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "./checksums.js";
+import { ValidationError } from "./errors.js";
+import { ignoreOwnFile, ignoreOwnSignature, loadFileRules, selectFiles, } from "./file-selection.js";
+import { createZip } from "./zip.js";
+const ZIP_EXTENSION = '.zip';
+/**
+ * Get the checksums manifest path next to an archive, with .checksums.json
+ * instead of .zip.
+ *
+ * @param zipPath Archive path.
+ * @return Manifest path.
+ */
+export function getChecksumsPath(zipPath) {
+    const name = zipPath.endsWith(ZIP_EXTENSION)
+        ? zipPath.slice(0, -ZIP_EXTENSION.length)
+        : zipPath;
+    return name + CHECKSUMS_EXTENSION;
+}
+/**
+ * Fail before writing anything when an output file exists.
+ *
+ * @param  paths Output paths.
+ * @param  force Whether existing files are overwritten.
+ * @throws {ValidationError} If a file exists and force isn't set.
+ */
+function checkOverwrite(paths, force) {
+    const existing = paths.filter((path) => !force && existsSync(path));
+    if (existing.length) {
+        throw new ValidationError(`${existing.join(' and ')} already exists, pass --force to overwrite it.`);
+    }
+}
+/**
+ * Write a ZIP of the selected files of a plugin, theme or package, and
+ * optionally the checksums manifest of the same files next to it. The zip
+ * command, with a directory or a configured package release, and the
+ * snapshot builds of a monorepo all use it, so that every ZIP of a package
+ * selects its files the same way. Output files inside the source directory,
+ * and their signatures, are never archived.
+ *
+ * @param  input Files, archive path and manifest options.
+ * @return Paths of the written files and the number of archived files.
+ * @throws {ValidationError} Without selected files, or when an output file exists without force.
+ */
+export async function zipPackage(input) {
+    const { sourceDir, zipPath, force = false } = input;
+    const checksumsPath = input.checksums ? getChecksumsPath(zipPath) : null;
+    const outputs = [zipPath, checksumsPath].filter((path) => null !== path);
+    const rules = await loadFileRules(input.selection);
+    outputs.forEach((path) => ignoreOwnSignature(ignoreOwnFile(rules, sourceDir, path), sourceDir, path));
+    const files = await selectFiles(sourceDir, rules);
+    if (!files.length) {
+        throw new ValidationError(`No files to archive in ${sourceDir}.`);
+    }
+    checkOverwrite(outputs, force);
+    await createZip({
+        sourceDir,
+        files,
+        zipPath,
+        rootFolder: input.rootFolder,
+        force,
+    });
+    if (checksumsPath) {
+        const manifest = await createChecksums({
+            sourceDir,
+            rules,
+            slug: input.slug,
+            version: input.version ?? null,
+            type: input.type,
+        });
+        await writeChecksums(checksumsPath, manifest, force);
+    }
+    return {
+        zipPath,
+        ...(checksumsPath ? { checksumsPath } : {}),
+        files: files.length,
+    };
+}

package/dist/release-repository.d.ts

@@ -66,11 +66,12 @@ export declare class ReleaseRepository {
      */
     createTag(tag: string): Promise<void>;
     /**
-     * Push a tag to the origin remote.
+     * Push a tag to a remote.
      *
-     * @param tag Tag name.
+     * @param tag    Tag name.
+     * @param remote Remote name.
      */
-    pushTag(tag: string): Promise<void>;
+    pushTag(tag: string, remote: string): Promise<void>;
     /**
      * Find the commit that added a file.
      *

package/dist/release-repository.js

@@ -78,12 +78,13 @@ export class ReleaseRepository {
         await this.run(['tag', tag]);
     }
     /**
-     * Push a tag to the origin remote.
+     * Push a tag to a remote.
      *
-     * @param tag Tag name.
+     * @param tag    Tag name.
+     * @param remote Remote name.
      */
-    async pushTag(tag) {
-        await this.run(['push', 'origin', tag]);
+    async pushTag(tag, remote) {
+        await this.run(['push', remote, tag]);
     }
     /**
      * Find the commit that added a file.

package/dist/signing.d.ts

@@ -1,4 +1,8 @@
 import type { KeyObject } from 'node:crypto';
+/**
+ * Extension of the signature files in the format that WordPress core's
+ * verify_file_signature() checks.
+ */
 export declare const SIGNATURE_EXTENSION = ".sig";
 /**
  * Environment variable with the base64 Ed25519 signing key.
@@ -7,11 +11,12 @@ export declare const SIGNING_KEY_ENV = "WP_RELEASE_SIGNING_KEY";
 /**
  * Generate an Ed25519 key pair in the base64 formats used by wp-release.
  *
- * @return Private seed for WP_RELEASE_SIGNING_KEY and public verification key.
+ * @return Private seed for WP_RELEASE_SIGNING_KEY, the base64 public key and the public key of each signature format.
  */
 export declare function generateSigningKeyPair(): {
     privateKey: string;
     publicKey: string;
+    publicKeys: Record<SignatureFormat, string>;
 };
 /**
  * Get an Ed25519 private key from the base64 format that sodium and the
@@ -24,11 +29,13 @@ export declare function generateSigningKeyPair(): {
  */
 export declare function parseSigningKey(encoded: string): KeyObject;
 /**
- * Get an Ed25519 public key from its base64 form.
+ * Get an Ed25519 public key from the base64 32-byte key, a minisign public
+ * key or an OpenSSH ssh-ed25519 public key. They're forms of the same key,
+ * so any of them checks the signatures of every format.
  *
- * @param  encoded Base64 32-byte public key.
+ * @param  encoded Public key.
  * @return Public key.
- * @throws {ValidationError} If the key has an unsupported length.
+ * @throws {ValidationError} If the key isn't in one of the forms.
  */
 export declare function parsePublicKey(encoded: string): KeyObject;
 /**
@@ -55,24 +62,72 @@ export declare function getFileDigest(path: string): Promise<Buffer>;
  * @return Base64 signature.
  */
 export declare function signFile(path: string, privateKey: KeyObject): Promise<string>;
+/** Names of the signature formats. */
+export type SignatureFormat = 'wordpress' | 'minisign' | 'ssh';
+/** How a signature format writes and checks signature files. */
+export interface SignatureFormatHandler {
+    /** Extension of the signature file, appended to the signed file name. */
+    extension: string;
+    /** Get the contents of the signature file of a file. */
+    create: (path: string, privateKey: KeyObject) => Promise<string>;
+    /** Check a file against its signature file. */
+    verify: (path: string, signaturePath: string, publicKey: KeyObject) => Promise<boolean>;
+    /** Get the public key in the form that the verifiers of the format take. */
+    getPublicKey: (key: KeyObject) => string;
+}
+export declare const DEFAULT_SIGNATURE_FORMAT: SignatureFormat;
+/**
+ * Signature formats, all Ed25519 signatures by the same key:
+ *
+ * - wordpress: base64 signature of the SHA-384 digest in <file>.sig, which
+ *   WordPress core's verify_file_signature() checks.
+ * - minisign: <file>.minisig, which `minisign -V` checks.
+ * - ssh: armored SSH signature in <file>.sshsig, which `ssh-keygen -Y verify`
+ *   checks with the "file" namespace.
+ */
+export declare const SIGNATURE_FORMATS: Record<SignatureFormat, SignatureFormatHandler>;
+/**
+ * Check that a value is the name of a signature format.
+ *
+ * @param value Value to check.
+ * @return Whether it's a signature format.
+ */
+export declare function isSignatureFormat(value: string): value is SignatureFormat;
+/**
+ * Get the signature file path of a file.
+ *
+ * @param path   File path.
+ * @param format Signature format.
+ * @return Signature file path.
+ */
+export declare function getSignaturePath(path: string, format?: SignatureFormat): string;
+/**
+ * Get the public key of a key in the form of each signature format.
+ *
+ * @param key Private or public key.
+ * @return Public keys by format.
+ */
+export declare function getPublicKeys(key: KeyObject): Record<SignatureFormat, string>;
 /**
- * Write the signature of a file to a .sig file next to it.
+ * Write the signature of a file to a signature file next to it.
  *
  * @param  path       File path.
  * @param  privateKey Private key from parseSigningKey().
  * @param  force      Whether to overwrite an existing signature file.
+ * @param  format     Signature format.
  * @return Signature file path.
  * @throws {ValidationError} If the signature file exists and force isn't set.
  */
-export declare function writeSignature(path: string, privateKey: KeyObject, force?: boolean): Promise<string>;
+export declare function writeSignature(path: string, privateKey: KeyObject, force?: boolean, format?: SignatureFormat): Promise<string>;
 /**
- * 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
+ * Check a file against a signature file. A wordpress .sig file can hold one
+ * signature per line, and is valid when any of them 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().
+ * @param format        Signature format.
  * @return Whether a signature matches.
  */
-export declare function verifyFileSignature(path: string, signaturePath: string, publicKey: KeyObject): Promise<boolean>;
+export declare function verifyFileSignature(path: string, signaturePath: string, publicKey: KeyObject, format?: SignatureFormat): Promise<boolean>;