@wpelevator/wp-release 0.3.0 → 0.4.1

package/dist/commands/verify.js

@@ -1,13 +1,282 @@
-import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, posix, resolve } from 'node:path';
 import { readChecksums, verifyChecksums } from "../checksums.js";
+import { downloadFile, isUrl } from "../download.js";
 import { loadFileRules, parseExclude } from "../file-selection.js";
 import { ValidationError } from "../errors.js";
-import { checkDirectory, getSourceDirArg, ignoreOwnFile, sourceDirArgs, } from "./args.js";
+import { readPackageMeta } from "../package-meta.js";
+import { extractZip, readZipEntries } from "../unzip.js";
+import { SIGNATURE_EXTENSION, parsePublicKey, verifyFileSignature, } from "../signing.js";
+import { checkDirectory, getSourceDirArg, ignoreOwnFile, ignoreOwnSignature, sourceDirArgs, } from "./args.js";
 import { getString, getStrings } from "./command.js";
+/**
+ * Fail unless the manifest has a valid signature file.
+ *
+ * @param  checksumsPath Manifest path.
+ * @param  publicKey     Base64 public key.
+ * @throws {ValidationError} If the signature is missing or doesn't match.
+ */
+async function checkSignature(checksumsPath, publicKey) {
+    const signaturePath = checksumsPath + SIGNATURE_EXTENSION;
+    if (!existsSync(signaturePath)) {
+        throw new ValidationError(`${signaturePath} doesn't exist.`);
+    }
+    if (!(await verifyFileSignature(checksumsPath, signaturePath, parsePublicKey(publicKey)))) {
+        throw new ValidationError(`${signaturePath} isn't a valid signature of ${checksumsPath} for the public key.`);
+    }
+}
+/**
+ * Find the single root folder that every archive entry is in.
+ *
+ * @param  zipPath Archive path.
+ * @return Root folder name.
+ * @throws {ValidationError} If the entries don't share one root folder.
+ */
+async function findRootFolder(zipPath) {
+    const roots = new Set((await readZipEntries(zipPath)).map(({ path }) => path.split('/')[0] ?? ''));
+    const [root] = [...roots];
+    if (1 !== roots.size || !root) {
+        throw new ValidationError(`${zipPath} must have all files in one root folder, or pass the folder with --root-folder.`);
+    }
+    return root;
+}
+/**
+ * Get the directory to check: the source directory, or the files of an
+ * archive extracted into a temporary directory. Archives can be local files
+ * or http(s) URLs, such as the ZIP that WordPress.org builds for a release.
+ *
+ * @param input            Source directory, archive and root folder.
+ * @param input.sourceDir
+ * @param input.zip
+ * @param input.cwd
+ * @param input.rootFolder
+ * @return Directory and cleanup function.
+ */
+async function resolveTarget(input) {
+    const { sourceDir, zip, cwd, rootFolder } = input;
+    if (!zip) {
+        await checkDirectory(sourceDir);
+        return { dir: sourceDir, cleanup: async () => undefined };
+    }
+    const tempDir = await mkdtemp(join(tmpdir(), 'wp-release-verify-'));
+    const cleanup = () => rm(tempDir, { recursive: true, force: true });
+    try {
+        const zipPath = isUrl(zip)
+            ? join(tempDir, 'download.zip')
+            : resolve(cwd, zip);
+        const dir = join(tempDir, 'files');
+        if (isUrl(zip)) {
+            await downloadFile(zip, zipPath);
+        }
+        await mkdir(dir);
+        await extractZip({
+            zipPath,
+            targetDir: dir,
+            rootFolder: rootFolder ?? (await findRootFolder(zipPath)),
+        });
+        return { dir, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/**
+ * Get the path of the embedded manifest inside the checked files: the
+ * explicit path, or the name of the manifest at the root when it's a JSON
+ * file.
+ *
+ * @param  checksumsPath Manifest path.
+ * @param  embedded      Explicit path from --embedded.
+ * @return Relative path, or null when there's no embedded manifest to look for.
+ * @throws {ValidationError} If the explicit path isn't relative.
+ */
+function getEmbeddedPath(checksumsPath, embedded) {
+    const path = posix.normalize(embedded ?? basename(checksumsPath));
+    if (embedded &&
+        (isAbsolute(embedded) ||
+            embedded.includes('\\') ||
+            path.startsWith('../') ||
+            ['.', '..'].includes(path))) {
+        throw new ValidationError(`--embedded must be a path inside the plugin with forward slashes, got "${embedded}".`);
+    }
+    return embedded || path.endsWith('.json') ? path : null;
+}
+/**
+ * Get the manifest and signature pairs to look for inside the checked files.
+ *
+ * @param checksumsPath Manifest path.
+ * @param path          Relative path of the embedded manifest, if any.
+ * @return Pairs of the originals and their copies.
+ */
+function getCopyPairs(checksumsPath, path) {
+    return path
+        ? [
+            { original: checksumsPath, copy: path },
+            {
+                original: checksumsPath + SIGNATURE_EXTENSION,
+                copy: path + SIGNATURE_EXTENSION,
+            },
+        ]
+        : [];
+}
+/**
+ * Check that an explicit --embedded path can be verified: the manifest can't
+ * list its own copies, and the originals to compare with must exist.
+ *
+ * @param  pairs    Pairs of the originals and their copies.
+ * @param  manifest Checksums manifest.
+ * @throws {ValidationError} If a copy is listed or an original is missing.
+ */
+function checkExplicitPairs(pairs, manifest) {
+    pairs.forEach(({ original, copy }) => {
+        if (Object.hasOwn(manifest.files, copy)) {
+            throw new ValidationError(`The checksums list ${copy}, but a manifest can't list its own embedded copy.`);
+        }
+        if (!existsSync(original)) {
+            throw new ValidationError(`--embedded needs ${original} to compare ${copy} with, but it doesn't exist.`);
+        }
+    });
+}
+/**
+ * Check that two paths are the same file or have the same bytes.
+ *
+ * @param original Path of the original.
+ * @param file     Path of the copy.
+ * @return Whether the contents are identical.
+ */
+async function hasSameContents(original, file) {
+    return (resolve(original) === resolve(file) ||
+        (await readFile(original)).equals(await readFile(file)));
+}
+/**
+ * Compare the copies of the manifest and its signature inside the checked
+ * directory with the given ones. A release that ships the manifest and its
+ * signature with the plugin files must ship the same bytes that were
+ * signed, otherwise a verifier on the site would check something else. The
+ * copies are not part of the manifest, since a manifest can't list itself,
+ * so they're skipped when comparing the files.
+ *
+ * With an explicit path both originals and both copies must exist. Without
+ * one, the copies are expected at the root with the name of the manifest,
+ * and a file is treated as a copy only when it exists, the matching
+ * original exists and the manifest doesn't list it. Any other file is
+ * checked like the rest of the files.
+ *
+ * @param  input               Directory, manifest and embedded path.
+ * @param  input.dir           Directory to check.
+ * @param  input.manifest      Checksums manifest.
+ * @param  input.checksumsPath Manifest path.
+ * @param  input.embedded      Explicit path of the embedded manifest.
+ * @return The copies that were found to differ or be missing, and the paths of the existing copies.
+ * @throws {ValidationError} If an explicit path can't be verified.
+ */
+async function checkEmbeddedCopies(input) {
+    const { dir, manifest, checksumsPath, embedded } = input;
+    const pairs = getCopyPairs(checksumsPath, getEmbeddedPath(checksumsPath, embedded));
+    if (embedded) {
+        checkExplicitPairs(pairs, manifest);
+    }
+    const found = pairs.filter(({ original, copy }) => existsSync(join(dir, copy)) &&
+        (embedded ||
+            (existsSync(original) &&
+                !Object.hasOwn(manifest.files, copy))));
+    const results = await Promise.all(found.map(async ({ original, copy }) => ({
+        copy,
+        isSame: await hasSameContents(original, join(dir, copy)),
+    })));
+    return {
+        paths: found.map(({ copy }) => copy),
+        differing: results
+            .filter(({ isSame }) => !isSame)
+            .map(({ copy }) => copy),
+        missing: embedded
+            ? pairs
+                .filter(({ copy }) => !existsSync(join(dir, copy)))
+                .map(({ copy }) => copy)
+            : [],
+    };
+}
+/**
+ * Compare the version in the manifest with the Version header of the
+ * checked files, so that an older signed release can't pass as a newer one.
+ *
+ * @param dir      Directory to check.
+ * @param manifest Checksums manifest.
+ * @return The two versions when they differ, otherwise null.
+ */
+async function findVersionMismatch(dir, manifest) {
+    const meta = await readPackageMeta({
+        dir,
+        slug: manifest.plugin ?? manifest.theme,
+    });
+    const files = meta?.version;
+    return manifest.version && files && manifest.version !== files
+        ? { manifest: manifest.version, files }
+        : null;
+}
+/**
+ * Compare the files of a directory with the manifest and log the result.
+ *
+ * @param input               Directory, manifest and options.
+ * @param input.target
+ * @param input.manifest
+ * @param input.checksumsPath
+ * @param input.exclude
+ * @param input.embedded
+ * @param input.logger
+ * @return Exit code and result.
+ */
+async function verifyTarget(input) {
+    const { target, manifest, checksumsPath, exclude, embedded, logger } = input;
+    const { dir } = target;
+    const copies = await checkEmbeddedCopies({
+        dir,
+        manifest,
+        checksumsPath,
+        embedded,
+    });
+    const rules = ignoreOwnSignature(ignoreOwnFile(await loadFileRules({ exclude: parseExclude(exclude) }), dir, checksumsPath), dir, checksumsPath);
+    copies.paths.forEach((copy) => ignoreOwnFile(rules, dir, join(dir, copy)));
+    const comparison = await verifyChecksums({
+        sourceDir: dir,
+        manifest,
+        rules,
+    });
+    const { matched, extra } = comparison;
+    const missing = [...comparison.missing, ...copies.missing];
+    const changed = [...comparison.changed, ...copies.differing];
+    const versionMismatch = await findVersionMismatch(dir, manifest);
+    const valid = comparison.valid &&
+        !copies.differing.length &&
+        !copies.missing.length &&
+        !versionMismatch;
+    changed.forEach((file) => logger.error(`Changed: ${file}`));
+    missing.forEach((file) => logger.error(`Missing: ${file}`));
+    extra.forEach((file) => logger.error(`Not in the checksums: ${file}`));
+    if (versionMismatch) {
+        logger.error(`The checksums are for version ${versionMismatch.manifest}, but the files are version ${versionMismatch.files}.`);
+    }
+    logger.info(`${matched.length} files match, ${changed.length} changed, ${missing.length} missing and ${extra.length} extra.`);
+    return {
+        exitCode: valid ? 0 : 2,
+        result: {
+            valid,
+            checksumsPath,
+            matched: matched.length,
+            changed,
+            missing,
+            extra,
+            versionMismatch,
+        },
+    };
+}
 export default {
     name: 'verify',
     usage: 'verify [<source-dir>] --checksums <file> [options]',
-    summary: 'Check the files of a plugin or theme directory against a checksums manifest.',
+    summary: 'Check the files of a plugin or theme directory or ZIP against a checksums manifest.',
     help: `Arguments:
   <source-dir>            Plugin or theme directory (default: .), also
                           accepted as --source-dir <dir>
@@ -15,46 +284,85 @@ export default {
 Options:
   --checksums <file>      Checksums manifest from "wp-release checksums" or the
                           WordPress.org checksums API (required)
+  --zip <file|url>        Check the files of this ZIP, a local file or an
+                          http(s) URL such as the ZIP that WordPress.org
+                          builds for a release, instead of <source-dir>
+  --root-folder <name>    Folder in the ZIP (default: the one folder that
+                          every entry is in)
+  --embedded <path>       Where the manifest and its .sig are shipped inside the
+                          files, like includes/checksums.json. Both the
+                          --checksums file and its .sig must exist, both
+                          copies must be shipped, and they must be identical
+                          to them. Without this option, a file with the name
+                          of the --checksums file at the root (and its .sig)
+                          is a copy only when it exists, the matching original
+                          exists and the manifest doesn't list it
+  --public-key <key>      Base64 Ed25519 public key. Checks <checksums>.sig, as
+                          written by "wp-release sign", before comparing any
+                          file, and fails when it's missing or invalid
   --exclude <patterns>    Gitignore-style patterns to skip in both the directory
                           and the manifest, comma-separated or repeated
 
 Reports every changed, missing and extra file, and exits with 2 unless all
-files match. Unlike "checksums" and "zip", verify doesn't read .distignore,
-so that an ignore file inside the checked directory can't hide added files.
-Use --exclude to skip files that aren't part of the release. A file matches when its SHA-256 equals the manifest, or its MD5
-for manifests without SHA-256.`,
+files match. A file matches when its SHA-256 equals the manifest, or its MD5
+for manifests without SHA-256. Exits with 2 too when the manifest version
+differs from the Version header of the files.
+
+Unlike "checksums" and "zip", verify doesn't read .distignore, so that an
+ignore file inside the checked directory can't hide added files. Use
+--exclude to skip files that aren't part of the release.
+
+A manifest can't list itself. A copy of the manifest and of its .sig inside
+the checked files is therefore skipped, but it must be identical to the
+--checksums file. A path that the manifest lists is never skipped, and a
+file that isn't a matching copy is reported as extra. See --embedded for
+where the copies are looked for.`,
     options: {
         checksums: { type: 'string' },
+        zip: { type: 'string' },
+        'root-folder': { type: 'string' },
+        embedded: { type: 'string' },
+        'public-key': { type: 'string' },
         ...sourceDirArgs,
         exclude: { type: 'string', multiple: true },
     },
     async run({ values, positionals, cwd, logger }) {
-        const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
+        const zip = getString(values, 'zip');
+        const sourceArg = positionals.length
+            ? getSourceDirArg(values, positionals)
+            : getString(values, 'source-dir');
         const checksums = getString(values, 'checksums');
         if (!checksums) {
             throw new ValidationError('Pass the checksums manifest with --checksums <file>.');
         }
-        await checkDirectory(sourceDir);
+        if (zip && sourceArg) {
+            throw new ValidationError('Pass either --zip or a source directory, not both.');
+        }
         const checksumsPath = resolve(cwd, checksums);
+        const publicKey = getString(values, 'public-key');
+        if (publicKey) {
+            await checkSignature(checksumsPath, publicKey);
+            logger.info(`Signature of ${checksumsPath} is valid.`);
+        }
         const manifest = await readChecksums(checksumsPath);
-        const rules = ignoreOwnFile(await loadFileRules({
-            exclude: parseExclude(getStrings(values, 'exclude')),
-        }), sourceDir, checksumsPath);
-        const { valid, matched, changed, missing, extra } = await verifyChecksums({ sourceDir, manifest, rules });
-        changed.forEach((file) => logger.error(`Changed: ${file}`));
-        missing.forEach((file) => logger.error(`Missing: ${file}`));
-        extra.forEach((file) => logger.error(`Not in the checksums: ${file}`));
-        logger.info(`${matched.length} files match, ${changed.length} changed, ${missing.length} missing and ${extra.length} extra in ${sourceDir}.`);
-        return {
-            exitCode: valid ? 0 : 2,
-            result: {
-                valid,
+        const target = await resolveTarget({
+            sourceDir: resolve(cwd, sourceArg ?? '.'),
+            zip,
+            cwd,
+            rootFolder: getString(values, 'root-folder'),
+        });
+        try {
+            return await verifyTarget({
+                target,
+                manifest,
                 checksumsPath,
-                matched: matched.length,
-                changed,
-                missing,
-                extra,
-            },
-        };
+                exclude: getStrings(values, 'exclude'),
+                embedded: getString(values, 'embedded'),
+                logger,
+            });
+        }
+        finally {
+            await target.cleanup();
+        }
     },
 };

package/dist/commands/zip.d.ts

@@ -1,3 +1,13 @@
+import type { CommandOutcome } from './command.ts';
+/** Result of the zip command. */
+export interface ZipResult {
+    /** Absolute path of the ZIP. */
+    zipPath: string;
+    /** Absolute path of the checksums manifest, set with --checksums. */
+    checksumsPath?: string;
+    /** Number of archived files. */
+    files: number;
+}
 declare const _default: {
     name: string;
     usage: string;
@@ -29,13 +39,6 @@ declare const _default: {
             type: "string";
         };
     };
-    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
-        exitCode: number;
-        result: {
-            files: number;
-            checksumsPath?: string | undefined;
-            zipPath: string;
-        };
-    }>;
+    run({ values, positionals, cwd, logger, }: import("./command.ts").CommandContext): Promise<CommandOutcome<ZipResult>>;
 };
 export default _default;

package/dist/commands/zip.js

@@ -6,7 +6,7 @@ import { loadFileRules, resolveFileSelection, selectFiles, } from "../file-selec
 import { FILENAME_FORMAT, formatFilename } from "../filename.js";
 import { readPackageMeta } from "../package-meta.js";
 import { createZip } from "../zip.js";
-import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, ignoreOwnFile, resolveOutput, sourceDirArgs, } from "./args.js";
+import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, ignoreOwnFile, ignoreOwnSignature, resolveOutput, sourceDirArgs, } from "./args.js";
 import { getBoolean, getString } from "./command.js";
 const ZIP_EXTENSION = '.zip';
 /**
@@ -74,7 +74,7 @@ always give the same ZIP.`,
         checksums: { type: 'boolean' },
         force: { type: 'boolean' },
     },
-    async run({ values, positionals, cwd, logger }) {
+    async run({ values, positionals, cwd, logger, }) {
         const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
         const slug = getString(values, 'slug') ?? basename(cwd);
         const force = getBoolean(values, 'force');
@@ -95,9 +95,9 @@ always give the same ZIP.`,
             sourceDir,
             ...getFileSelectionInput(values),
         });
-        const rules = ignoreOwnFile(await loadFileRules(selection), sourceDir, zipPath);
+        const rules = ignoreOwnSignature(ignoreOwnFile(await loadFileRules(selection), sourceDir, zipPath), sourceDir, zipPath);
         if (checksumsPath) {
-            ignoreOwnFile(rules, sourceDir, checksumsPath);
+            ignoreOwnSignature(ignoreOwnFile(rules, sourceDir, checksumsPath), sourceDir, checksumsPath);
         }
         const files = await selectFiles(sourceDir, rules);
         if (!files.length) {

package/dist/download.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Check if a location is an http(s) URL instead of a file path.
+ *
+ * @param location File path or URL.
+ * @return Whether it's a URL.
+ */
+export declare function isUrl(location: string): boolean;
+/**
+ * Download a URL to a file. Redirects are followed.
+ *
+ * @param  url  http or https URL.
+ * @param  path Destination file path.
+ * @throws {ValidationError} If the server doesn't answer with a body.
+ */
+export declare function downloadFile(url: string, path: string): Promise<void>;

package/dist/download.js

@@ -0,0 +1,27 @@
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ValidationError } from "./errors.js";
+/**
+ * Check if a location is an http(s) URL instead of a file path.
+ *
+ * @param location File path or URL.
+ * @return Whether it's a URL.
+ */
+export function isUrl(location) {
+    return /^https?:\/\//i.test(location);
+}
+/**
+ * Download a URL to a file. Redirects are followed.
+ *
+ * @param  url  http or https URL.
+ * @param  path Destination file path.
+ * @throws {ValidationError} If the server doesn't answer with a body.
+ */
+export async function downloadFile(url, path) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body) {
+        throw new ValidationError(`Couldn't download ${url}: ${response.status} ${response.statusText}`.trim());
+    }
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(path));
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { run, commands, getHelp, getCommandHelp } from './cli.ts';
+export { run, execute, commands, getHelp, getCommandHelp } from './cli.ts';
 export { getDeployInputFromArgs } from './commands/deploy-svn.ts';
 export { ValidationError, CredentialsError } from './errors.ts';
 export { Logger } from './logger.ts';
@@ -7,13 +7,18 @@ export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules,
 export { FILENAME_FORMAT, formatFilename } from './filename.ts';
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from './checksums.ts';
 export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from './package-meta.ts';
+export { SIGNATURE_EXTENSION, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, getPublicKey, getFileDigest, signFile, writeSignature, verifyFileSignature, } from './signing.ts';
 export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from './zip.ts';
+export { isUrl, downloadFile } from './download.ts';
 export { readZipEntries, getZipEntryErrors, extractZip } from './unzip.ts';
 export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from './version-check.ts';
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from './svn.ts';
 export { syncDirectory, copyFileIfChanged } from './sync.ts';
 export { ASSET_MIME_TYPES, SvnDeploy } from './svn-deploy.ts';
-export type { CliIo } from './cli.ts';
+export type { CliIo, CommandResults } from './cli.ts';
+export type { ChecksumsResult } from './commands/checksums.ts';
+export type { SignResult } from './commands/sign.ts';
+export type { ZipResult } from './commands/zip.ts';
 export type { Command, CommandContext, CommandOutcome, ParsedValues, } from './commands/command.ts';
 export type { DeployArgsInput } from './commands/deploy-svn.ts';
 export type { LoggerOptions, OutputStream } from './logger.ts';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { run, commands, getHelp, getCommandHelp } from "./cli.js";
+export { run, execute, commands, getHelp, getCommandHelp } from "./cli.js";
 export { getDeployInputFromArgs } from "./commands/deploy-svn.js";
 export { ValidationError, CredentialsError } from "./errors.js";
 export { Logger } from "./logger.js";
@@ -7,7 +7,9 @@ export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules,
 export { FILENAME_FORMAT, formatFilename } from "./filename.js";
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from "./checksums.js";
 export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from "./package-meta.js";
+export { SIGNATURE_EXTENSION, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, getPublicKey, getFileDigest, signFile, writeSignature, verifyFileSignature, } from "./signing.js";
 export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from "./zip.js";
+export { isUrl, downloadFile } from "./download.js";
 export { readZipEntries, getZipEntryErrors, extractZip } from "./unzip.js";
 export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from "./version-check.js";
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from "./svn.js";

package/dist/signing.d.ts

@@ -0,0 +1,69 @@
+import type { KeyObject } from 'node:crypto';
+export declare const SIGNATURE_EXTENSION = ".sig";
+/**
+ * Environment variable with the base64 Ed25519 signing key.
+ */
+export declare const SIGNING_KEY_ENV = "WP_RELEASE_SIGNING_KEY";
+/**
+ * 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 declare function parseSigningKey(encoded: string): KeyObject;
+/**
+ * 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 declare function parsePublicKey(encoded: string): KeyObject;
+/**
+ * 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 declare function getPublicKey(privateKey: KeyObject): string;
+/**
+ * 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 declare function getFileDigest(path: string): Promise<Buffer>;
+/**
+ * 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 declare function signFile(path: string, privateKey: KeyObject): Promise<string>;
+/**
+ * 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 declare function writeSignature(path: string, privateKey: KeyObject, force?: boolean): 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
+ * 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 declare function verifyFileSignature(path: string, signaturePath: string, publicKey: KeyObject): Promise<boolean>;