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        ZeroEcho keyring file holding the signing key, or
 *                           {@code null}; this is a plaintext ZeroEcho
 *                           {@code KeyringStore} file, not a JDK PKCS12/JKS
 *                           keystore and not produced by {@code keytool} (use
 *                           {@code -gen-signing-key}). Intended for interactive
 *                           CLI use where the file is protected by file-system
 *                           permissions or ACLs
 * @param keyringEnv         name of an environment variable holding the full
 *                           keyring content, or {@code null}; intended for CI/CD
 *                           pipelines where the keyring is supplied through a
 *                           platform secret so the private key never touches the
 *                           runner's disk. When both {@code keyringEnv} and
 *                           {@code keyringFile} are set, the environment variable
 *                           takes precedence. When both are {@code null} the pack
 *                           is unsigned
 * @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,
        String keyAlias,
        String signatureAlgorithm) {
}