GenSigningKeyCommand.java

// SPDX-License-Identifier: Apache-2.0

// Copyright 2026 Egothor

// Copyright 2026 Accenture

package org.egothor.methodatlas.evidence;

import java.io.IOException;

import java.io.PrintWriter;

import java.nio.file.Path;

import java.nio.file.Paths;

import java.security.GeneralSecurityException;

/**

 * CLI command handler for the {@code -gen-signing-key} mode, which creates a

 * ZeroEcho keyring containing a fresh signing key pair for evidence-pack

 * signing.

 * <p>

 * The mode is recognised and dispatched by {@code MethodAtlasApp} before the

 * normal scan-argument parsing, mirroring how {@code -diff} is handled. It is

 * self-contained: it parses its own small set of options and never participates

 * in the scan pipeline.

 * </p>

 * <h2>Usage</h2>

 * <pre>{@code

 * methodatlas -gen-signing-key <keyring-file> [-key-alias <alias>] \

 *             [-key-algo <algorithm>] [-overwrite]

 * }</pre>

 * <p>

 * The produced keyring is a plaintext file holding the private key in clear

 * text; protect it with file-system permissions and keep it out of version

 * control and out of any distributed evidence pack. See {@link SigningKeyGenerator}.

 * </p>

 * @see SigningKeyGenerator

 * @see ZeroEchoSigner

 * @since 4.0.0

*/

public final class GenSigningKeyCommand {

    /** Mode flag that selects this command. */

    public static final String FLAG_GEN_SIGNING_KEY = "-gen-signing-key";

    private static final String FLAG_KEY_ALIAS = "-key-alias";

    private static final String FLAG_KEY_ALGO = "-key-algo";

    private static final String FLAG_OVERWRITE = "-overwrite";

    /** Default alias used when {@code -key-alias} is omitted. */

    private static final String DEFAULT_ALIAS = "methodatlas-signing";

    /** Exit code returned on success. */

    private static final int EXIT_OK = 0;

    /** Exit code returned when the arguments are invalid. */

    private static final int EXIT_BAD_ARGS = 2;

    private final Path keyringFile;

    private final String alias;

    private final String algorithm;

    private final boolean overwrite;

/**

     * Creates a new command.

     * @param keyringFile target keyring file; must not be {@code null}

     * @param alias       base alias for the generated key pair

     * @param algorithm   algorithm id, or {@code null} for the default

     * @param overwrite   whether to replace an existing alias

*/

    private GenSigningKeyCommand(Path keyringFile, String alias, String algorithm, boolean overwrite) {

        this.keyringFile = keyringFile;

        this.alias = alias;

        this.algorithm = algorithm;

        this.overwrite = overwrite;

/**

     * Parses {@code -gen-signing-key} arguments and runs the command.

     * @param args full command-line arguments, including the

     *             {@code -gen-signing-key} flag and its value

     * @param out  writer that receives the success summary

     * @return {@code 0} on success, {@code 2} when the arguments are invalid

     * @throws IOException if the keyring cannot be written, an alias collides

     *                     without {@code -overwrite}, or key generation fails

*/

    public static int run(String[] args, PrintWriter out) throws IOException {

        final GenSigningKeyCommand command;

        try {

            command = parse(args);

        } catch (IllegalArgumentException e) {

1 1. run : removed call to java/io/PrintStream::println → SURVIVED

            System.err.println("gen-signing-key: " + e.getMessage());

1 1. run : removed call to java/io/PrintStream::println → SURVIVED

            System.err.println("Usage: -gen-signing-key <keyring-file> [-key-alias <alias>] "

                    + "[-key-algo <algorithm>] [-overwrite]");

1 1. run : replaced int return with 0 for org/egothor/methodatlas/evidence/GenSigningKeyCommand::run → KILLED

            return EXIT_BAD_ARGS;

1 1. run : replaced int return with 0 for org/egothor/methodatlas/evidence/GenSigningKeyCommand::run → KILLED

        return command.execute(out);

100

101

/**

102

     * Parses the command-line arguments into a command instance.

103

104

     * @param args full command-line arguments

105

     * @return parsed command

106

     * @throws IllegalArgumentException if the keyring value is missing or a flag

107

     *                                  lacks its required value

108

*/

109

    @SuppressWarnings("PMD.AvoidReassigningLoopVariables") // ++i consumes a flag's value, matching CliArgs

110

    private static GenSigningKeyCommand parse(String... args) {

111

        Path keyringFile = null;

112

        String alias = DEFAULT_ALIAS;

113

        String algorithm = null;

114

        boolean overwrite = false;

115

116

3 1. parse : removed conditional - replaced comparison check with false → KILLED
2. parse : changed conditional boundary → KILLED
3. parse : removed conditional - replaced comparison check with true → KILLED

        for (int i = 0; i < args.length; i++) {

117

1 1. parse : Changed switch default to be first case → KILLED

            switch (args[i]) {

118

1 1. parse : Changed increment from 1 to -1 → KILLED

                case FLAG_GEN_SIGNING_KEY -> keyringFile = Paths.get(value(args, ++i, FLAG_GEN_SIGNING_KEY));

119

1 1. parse : Changed increment from 1 to -1 → TIMED_OUT

                case FLAG_KEY_ALIAS -> alias = value(args, ++i, FLAG_KEY_ALIAS);

120

1 1. parse : Changed increment from 1 to -1 → TIMED_OUT

                case FLAG_KEY_ALGO -> algorithm = value(args, ++i, FLAG_KEY_ALGO);

121

                case FLAG_OVERWRITE -> overwrite = true;

122

                default -> {

123

                    // Ignore unrelated tokens so the mode can be combined with

124

                    // a leading program name or stray scan arguments.

2 1. parse : removed conditional - replaced equality check with false → SURVIVED
2. parse : removed conditional - replaced equality check with true → KILLED

        if (keyringFile == null) {

129

            throw new IllegalArgumentException("missing keyring file after " + FLAG_GEN_SIGNING_KEY);

130

131

1 1. parse : replaced return value with null for org/egothor/methodatlas/evidence/GenSigningKeyCommand::parse → KILLED

        return new GenSigningKeyCommand(keyringFile, alias, algorithm, overwrite);

132

133

134

/**

135

     * Reads the value following a flag at index {@code i}.

136

137

     * @param args command-line arguments

138

     * @param i    index of the value (already advanced past the flag)

139

     * @param flag the flag whose value is being read, for diagnostics

140

     * @return the value token

141

     * @throws IllegalArgumentException if the value is missing

142

*/

143

    private static String value(String[] args, int i, String flag) {

144

3 1. value : removed conditional - replaced comparison check with true → KILLED
2. value : changed conditional boundary → KILLED
3. value : removed conditional - replaced comparison check with false → KILLED

        if (i >= args.length) {

145

            throw new IllegalArgumentException("missing value after " + flag);

146

147

1 1. value : replaced return value with "" for org/egothor/methodatlas/evidence/GenSigningKeyCommand::value → KILLED

        return args[i];

148

149

150

/**

151

     * Generates the key pair and prints a summary plus the matching

152

     * evidence-pack invocation.

153

154

     * @param out writer that receives the success summary

155

     * @return {@code 0} on success

156

     * @throws IOException if the keyring cannot be written, an alias collides

157

     *                     without {@code -overwrite}, or key generation fails

158

*/

159

    private int execute(PrintWriter out) throws IOException {

160

        final SigningKeyGenerator.GeneratedKey generated;

161

        try {

162

            generated = SigningKeyGenerator.generate(keyringFile, alias, algorithm, overwrite);

163

        } catch (IllegalArgumentException e) {

164

1 1. execute : removed call to java/io/PrintStream::println → SURVIVED

            System.err.println("gen-signing-key: " + e.getMessage());

165

1 1. execute : replaced int return with 0 for org/egothor/methodatlas/evidence/GenSigningKeyCommand::execute → KILLED

            return EXIT_BAD_ARGS;

166

        } catch (GeneralSecurityException e) {

167

            throw new IOException("Signing-key generation failed: " + e.getMessage(), e);

168

169

170

1 1. execute : removed call to java/io/PrintWriter::println → KILLED

        out.println("Generated " + generated.algorithm() + " signing key in "

171

                + generated.keyringFile().toAbsolutePath());

172