EvidencePackOptions.java

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Egothor
// Copyright 2026 Accenture
package org.egothor.methodatlas.evidence;

import java.nio.file.Path;

/**
 * Immutable bag of evidence-pack options collected from the command line.
 *
 * <p>
 * This record is constructed directly by {@code CliArgs}; there is no
 * builder. Fields with sensible defaults are documented in the parameter
 * Javadoc.
 * </p>
 *
 * @param framework          target compliance framework; must not be {@code null}
 * @param outputDir          directory in which to materialise the pack; when
 *                           {@code null} the command will derive a default
 *                           location relative to the first scan root
 * @param overwrite          when {@code true}, an existing output directory is
 *                           reused; when {@code false}, a pre-existing directory
 *                           is treated as an error
 * @param keyringFile        encrypted ZeroEcho keyring file holding the signing
 *                           key, or {@code null}; not a JDK PKCS12/JKS keystore
 *                           and not produced by {@code keytool} (use
 *                           {@code -gen-signing-key}). Its {@code .nonce} sidecar
 *                           must sit next to it in an owner-only directory
 * @param keyringEnv         name of an environment variable holding a keyring
 *                           secret bundle (produced by
 *                           {@code -export-keyring-secret}), or {@code null};
 *                           intended for CI/CD pipelines where the keyring is
 *                           supplied through a platform secret. When both
 *                           {@code keyringEnv} and {@code keyringFile} are set,
 *                           the environment variable takes precedence. When both
 *                           are {@code null} the pack is unsigned
 * @param passwordFile       file whose first line is the keyring password, or
 *                           {@code null}
 * @param passwordEnv        name of an environment variable holding the keyring
 *                           password, or {@code null}; when neither password
 *                           option is set, {@code METHODATLAS_KEYRING_PASSWORD}
 *                           and then an interactive prompt are tried
 * @param keyAlias           keyring alias of the signing key; when {@code null}
 *                           the first alias in the keyring is used; for hybrid
 *                           signatures the format is
 *                           {@code "classicAlias/pqcAlias"}
 * @param signatureAlgorithm signature algorithm identifier; {@code null} means
 *                           derive it from the keyring entry (defaulting to
 *                           {@code "Ed25519"} when generated by MethodAtlas); a
 *                           value of the form {@code "classic+pqc"} (for example
 *                           {@code "Ed25519+SPHINCS+"}) selects hybrid signing
 *
 * @see EvidenceFramework
 * @see org.egothor.methodatlas.evidence.SigningKeyGenerator
 */
public record EvidencePackOptions(
        EvidenceFramework framework,
        Path outputDir,
        boolean overwrite,
        Path keyringFile,
        String keyringEnv,
        Path passwordFile,
        String passwordEnv,
        String keyAlias,
        String signatureAlgorithm) {
}