← Files AntomARCHIVED FILE
skills/antom-channel-integration/scripts/aci-cli/src/main/java/com/antom/aci/cli/SpecValidator.java
11.4 KB · Nov 16, 2026 · 06:09 UTC
/* SPDX-License-Identifier: Apache-2.0 */
package com.antom.aci.cli;
import com.fasterxml.jackson.databind.JsonNode;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.lang.model.SourceVersion;
/** Capability and security constraints shared by interactive and JSON entry points. */
final class SpecValidator {
static List<Capability> validate(AdapterSpec spec) {
require(spec != null && spec.schemaVersion == 1, "schemaVersion must be 1");
require(javaName(spec.groupId) && javaName(spec.packageName), "Invalid groupId or Java packageName");
require(spec.artifactId != null && spec.artifactId.matches("[a-z][a-z0-9-]{1,63}"), "Invalid artifactId");
require(spec.version != null && spec.version.matches("[0-9][A-Za-z0-9._-]{0,63}"), "Invalid version");
require(spec.channelCode != null && spec.channelCode.matches("[a-z][a-z0-9_-]{1,63}"), "Invalid channelCode");
if (!"1.5.2".equals(spec.sdkVersion)) {
throw new GenerationException(3, "Template 0.1.0 supports SDK 1.5.2 only");
}
require(Arrays.asList("card", "non-card").contains(spec.paymentType), "paymentType must be card or non-card");
require(Arrays.asList("none", "one", "two").contains(spec.threeDS), "threeDS must be none, one or two");
require(spec.spi != null && !spec.spi.isEmpty(), "Select at least one SPI method");
Set<String> selected = new HashSet<>(spec.spi);
require(selected.size() == spec.spi.size(), "Duplicate SPI methods");
List<Capability> capabilities = new ArrayList<>();
for (String method : spec.spi) {
capabilities.add(Capability.find(method));
}
if ("non-card".equals(spec.paymentType)) {
require("none".equals(spec.threeDS), "Non-card cannot enable 3DS");
require(!selected.contains("capture") && !selected.contains("notifyCapture"), "Non-card cannot enable capture");
}
require(selected.contains("authenticateAuthorize") == "two".equals(spec.threeDS),
"Two-call 3DS requires authenticateAuthorize; other modes must omit it");
for (Capability capability : capabilities) {
if ("payment".equals(capability.getFamily())) {
require(selected.contains("pay"), "PaymentService requires pay");
}
if ("refund".equals(capability.getFamily())) {
require(selected.contains("refund"), "RefundService requires refund");
}
if (capability.isNotification()) {
require(selected.contains("notifyPayment"), "NotificationService requires notifyPayment");
}
}
normalizeSecurityFeatures(spec, capabilities);
require(spec.security != null && spec.security.keySet().equals(selected),
"security must explicitly cover exactly the selected methods");
for (Capability capability : capabilities) {
validateSecurity(capability, spec.security.get(capability.getMethod()));
}
return capabilities;
}
/** Normalize compact inputs once so persisted specs can be validated again by packaging. */
private static void normalizeSecurityFeatures(AdapterSpec spec, List<Capability> capabilities) {
if (spec.securityFeatures == null) {
return;
}
require(spec.security == null || spec.security.isEmpty(),
"Use securityFeatures or detailed security, not both");
require(spec.securityFeatures.signature != null && spec.securityFeatures.encryption != null,
"securityFeatures requires both signature and encryption booleans");
Map<String, Map<String, List<AdapterSpec.SecurityStep>>> security = new LinkedHashMap<>();
for (Capability capability : capabilities) {
Map<String, List<AdapterSpec.SecurityStep>> directions = new LinkedHashMap<>();
for (String direction : capability.getDirections()) {
List<AdapterSpec.SecurityStep> steps = new ArrayList<>();
if ("request".equals(direction)) {
steps.add(featureStep("sign", spec.securityFeatures.signature));
steps.add(featureStep("encrypt", spec.securityFeatures.encryption));
} else {
// Demonstration order only; developers must confirm the institution's actual wire protocol.
steps.add(featureStep("verify", spec.securityFeatures.signature));
steps.add(featureStep("decrypt", spec.securityFeatures.encryption));
}
directions.put(direction, steps);
}
security.put(capability.getMethod(), directions);
}
spec.security = security;
spec.securityFeatures = null;
}
private static AdapterSpec.SecurityStep featureStep(String operation, boolean enabled) {
AdapterSpec.SecurityStep step = new AdapterSpec.SecurityStep();
step.operation = operation;
if (enabled) {
step.implementation = "demo";
step.rule = "demonstration-only feature selected - institution protocol not implemented";
} else {
step.implementation = "none";
step.rule = "feature not selected during project generation";
}
return step;
}
private static void validateSecurity(Capability capability, Map<String, List<AdapterSpec.SecurityStep>> directions) {
require(directions != null && directions.keySet().equals(new HashSet<>(capability.getDirections())),
"Explicit security directions required for " + capability.getMethod());
for (String direction : capability.getDirections()) {
List<String> operations = Arrays.asList("verify", "decrypt");
if ("request".equals(direction)) {
operations = Arrays.asList("sign", "encrypt");
}
List<AdapterSpec.SecurityStep> steps = directions.get(direction);
require(steps != null && steps.size() == 2, "Declare both security operations, using none when inapplicable");
Set<String> seen = new HashSet<>();
for (AdapterSpec.SecurityStep step : steps) {
require(step != null && operations.contains(step.operation) && seen.add(step.operation),
"Duplicate or invalid security operation in " + capability.getMethod() + "/" + direction);
require(Arrays.asList("none", "platform", "adapter", "demo").contains(step.implementation), "Invalid security implementation");
require(step.rule != null && step.rule.matches("[A-Za-z0-9][A-Za-z0-9 ._:/-]{0,255}"),
"Each step requires a non-secret rule reference/reason (ASCII, at most 256 characters)");
require(step.parameters != null, "parameters cannot be null");
if ("none".equals(step.implementation) || "demo".equals(step.implementation)) {
require(step.algorithm == null && step.keyAlgorithm == null
&& step.cipherType == null && step.parameters.isEmpty(),
"none/demo cannot declare algorithm or parameters");
continue;
}
if ("adapter".equals(step.implementation)) {
require(inCatalogue("key", step.keyAlgorithm), "Unknown keyAlgorithm");
require(step.algorithm == null && step.cipherType == null && step.parameters.isEmpty(),
"adapter selects keyAlgorithm; implement protocol options in its customization hook");
} else {
require(step.keyAlgorithm == null, "platform selects key classification internally");
if ("sign".equals(step.operation) || "verify".equals(step.operation)) {
require(inCatalogue("sign", step.algorithm), "Unknown signing algorithm");
require(step.cipherType == null && step.parameters.isEmpty(), "Signing does not accept cipher parameters");
} else {
require(inCatalogue("cipher", step.algorithm), "Unknown cipher algorithm");
validateCipher(step);
}
}
}
}
}
private static void validateCipher(AdapterSpec.SecurityStep step) {
boolean symmetric = CipherCompatibility.isSymmetric(step.algorithm);
String expected = "ASYMMETRIC";
if (symmetric) {
expected = "SYMMETRIC";
}
require(expected.equals(step.cipherType), "cipherType does not match algorithm");
// Runtime IV/AAD/PGP material must be derived in the generated typed request hook, never frozen here.
Set<String> allowed = new HashSet<>(Arrays.asList("mode", "padding", "tagBitLength"));
require(allowed.containsAll(step.parameters.keySet()), "Only static mode/padding/tagBitLength belong in generation config");
if (symmetric || "RSA2".equals(step.algorithm)) {
require(inCatalogue("mode", String.valueOf(step.parameters.get("mode"))), "Explicit cipher mode required");
require(inCatalogue("padding", String.valueOf(step.parameters.get("padding"))), "Explicit cipher padding required");
String mode = String.valueOf(step.parameters.get("mode"));
String padding = String.valueOf(step.parameters.get("padding"));
require(CipherCompatibility.modes(step.algorithm).contains(mode),
"Cipher mode " + mode + " is incompatible with " + step.algorithm);
require(CipherCompatibility.paddings(step.algorithm, mode).contains(padding),
"Cipher padding " + padding + " is incompatible with " + step.algorithm + "/" + mode);
if ("GCM".equals(mode)) {
require(Arrays.asList(96, 104, 112, 120, 128).contains(step.parameters.get("tagBitLength")), "Invalid GCM tagBitLength");
} else {
require(!step.parameters.containsKey("tagBitLength"), "tagBitLength is GCM-only");
}
} else {
require(step.parameters.isEmpty(), "This algorithm has no static block-cipher parameters");
}
}
static boolean inCatalogue(String name, String value) {
return catalogue(name).contains(value);
}
/** Share the bundled SDK choices between interactive menus and configuration validation. */
static List<String> catalogue(String name) {
try (InputStream input = SpecValidator.class.getResourceAsStream("/catalogue.json")) {
JsonNode items = JsonFiles.MAPPER.readTree(input).get(name);
List<String> values = new ArrayList<>();
for (JsonNode item : items) {
values.add(item.asText());
}
return values;
} catch (IOException e) {
throw new GenerationException(3, "Cannot read bundled algorithm catalogue: " + e.getMessage());
}
}
private static boolean javaName(String value) {
return value != null && value.length() < 160 && SourceVersion.isName(value)
&& value.matches("[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+");
}
static void require(boolean condition, String message) {
if (!condition) {
throw new GenerationException(2, message);
}
}
}
SHA-256: 1de5dd89160cb789cb8e14c219213c2e197ae27a1399f00f2ec9efef0a0d5002