oci/nodeNixosSvc: add kes agent cli arg support

Author: johnalotoski

nix/docker/context/node/bin/run-node

@@ -48,7 +48,8 @@ fi
 
 # Block producer key defaults -- only relevant when CARDANO_BLOCK_PRODUCER=true
 if [[ $CARDANO_BLOCK_PRODUCER == true ]]; then
-  if [[ -z ${CARDANO_SHELLEY_KES_KEY:-} ]]; then
+  # Only default the KES key when not using a KES agent socket
+  if [[ -z ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} && -z ${CARDANO_SHELLEY_KES_KEY:-} ]]; then
     CARDANO_SHELLEY_KES_KEY="$CARDANO_CONFIG_BASE/keys/kes.skey"
   fi
 
@@ -81,7 +82,11 @@ printRunEnv () {
   [[ -n ${CARDANO_TRACER_SOCKET_PATH_CONNECT:-} ]] && echo "CARDANO_TRACER_SOCKET_PATH_CONNECT=$CARDANO_TRACER_SOCKET_PATH_CONNECT"
 
   if [[ ${CARDANO_BLOCK_PRODUCER} == true ]]; then
-    echo "CARDANO_SHELLEY_KES_KEY=$CARDANO_SHELLEY_KES_KEY"
+    if [[ -n ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} ]]; then
+      echo "CARDANO_SHELLEY_KES_AGENT_SOCKET=$CARDANO_SHELLEY_KES_AGENT_SOCKET"
+    else
+      echo "CARDANO_SHELLEY_KES_KEY=$CARDANO_SHELLEY_KES_KEY"
+    fi
     echo "CARDANO_SHELLEY_VRF_KEY=$CARDANO_SHELLEY_VRF_KEY"
     echo "CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=$CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE"
   fi
@@ -99,7 +104,10 @@ cat << EOF > /usr/local/bin/env
 # Docker run ENV vars
 EOF
 
-# TODO-SRE: Add kes-agent CLI arg once available
+if [[ -n ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} ]]; then
+  echo "CARDANO_SHELLEY_KES_AGENT_SOCKET=\"$CARDANO_SHELLEY_KES_AGENT_SOCKET\"" \
+    >> /usr/local/bin/env
+fi
 
 if [[ -n ${CARDANO_TRACER_SOCKET_NETWORK_ACCEPT:-} ]]; then
   echo "CARDANO_TRACER_SOCKET_NETWORK_ACCEPT=\"$CARDANO_TRACER_SOCKET_NETWORK_ACCEPT\"" \
@@ -163,13 +171,20 @@ runNode () {
   )
 
   if [[ $CARDANO_BLOCK_PRODUCER == true ]]; then
+    if [[ -n ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} ]]; then
+      effopts+=(
+        "--shelley-kes-agent-socket" "$CARDANO_SHELLEY_KES_AGENT_SOCKET"
+      )
+    else
+      effopts+=(
+        "--shelley-kes-key" "$CARDANO_SHELLEY_KES_KEY"
+      )
+    fi
     effopts+=(
-      "--shelley-kes-key" "$CARDANO_SHELLEY_KES_KEY"
       "--shelley-vrf-key" "$CARDANO_SHELLEY_VRF_KEY"
       "--shelley-operational-certificate" "$CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE"
     )
   fi
-
   [[ -n ${CARDANO_TRACER_SOCKET_NETWORK_ACCEPT:-} ]] && effopts+=("--tracer-socket-network-accept" "$CARDANO_TRACER_SOCKET_NETWORK_ACCEPT")
   [[ -n ${CARDANO_TRACER_SOCKET_NETWORK_CONNECT:-} ]] && effopts+=("--tracer-socket-network-connect" "$CARDANO_TRACER_SOCKET_NETWORK_CONNECT")
   [[ -n ${CARDANO_TRACER_SOCKET_PATH_ACCEPT:-} ]] && effopts+=("--tracer-socket-path-accept" "$CARDANO_TRACER_SOCKET_PATH_ACCEPT")
@@ -203,6 +218,7 @@ do
       --socket-path) CARDANO_SOCKET_PATH=${val}; found=true;;
       --host-addr) CARDANO_BIND_ADDR=${val}; found=true;;
       --port) CARDANO_PORT=${val}; found=true;;
+      --shelley-kes-agent-socket) CARDANO_SHELLEY_KES_AGENT_SOCKET=${val}; found=true;;
       --shelley-kes-key) CARDANO_SHELLEY_KES_KEY=${val}; found=true;;
       --shelley-vrf-key) CARDANO_SHELLEY_VRF_KEY=${val}; found=true;;
       --shelley-operational-certificate) CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=${val}; found=true;;
@@ -224,6 +240,11 @@ for arg in "${options[@]}"; do
   [[ -n $arg ]] && filteredOpts+=("$arg")
 done
 
+if [[ -n ${CARDANO_SHELLEY_KES_KEY:-} && -n ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} ]]; then
+  echo "ERROR: CARDANO_SHELLEY_KES_KEY and CARDANO_SHELLEY_KES_AGENT_SOCKET are mutually exclusive; use one or the other, not both."
+  exit 1
+fi
+
 printRunEnv
 writeRootEnv
 
@@ -232,7 +253,10 @@ for f in "$CARDANO_CONFIG" "$CARDANO_TOPOLOGY"; do
   [[ -f $f ]] || { echo "ERROR: required file not found: $f"; exit 1; }
 done
 if [[ $CARDANO_BLOCK_PRODUCER == true ]]; then
-  for f in "$CARDANO_SHELLEY_KES_KEY" "$CARDANO_SHELLEY_VRF_KEY" "$CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE"; do
+  if [[ -z ${CARDANO_SHELLEY_KES_AGENT_SOCKET:-} ]]; then
+    [[ -f $CARDANO_SHELLEY_KES_KEY ]] || { echo "ERROR: required block producer key file not found: $CARDANO_SHELLEY_KES_KEY"; exit 1; }
+  fi
+  for f in "$CARDANO_SHELLEY_VRF_KEY" "$CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE"; do
     [[ -f $f ]] || { echo "ERROR: required block producer key file not found: $f"; exit 1; }
   done
 fi

nix/nixos/cardano-node-service.nix

@@ -147,6 +147,8 @@ let
           "--shelley-kes-key ${cfg.kesKey}"}"
         "${optionalString (cfg.operationalCertificate != null)
           "--shelley-operational-certificate ${cfg.operationalCertificate}"}"
+        "${optionalString (cfg.shelleyKesAgentSocket != null)
+          "--shelley-kes-agent-socket ${cfg.shelleyKesAgentSocket}"}"
       ];
       Cardano = [
         "${optionalString (cfg.signingKey != null)
@@ -159,6 +161,8 @@ let
           "--shelley-kes-key ${cfg.kesKey}"}"
         "${optionalString (cfg.operationalCertificate != null)
           "--shelley-operational-certificate ${cfg.operationalCertificate}"}"
+        "${optionalString (cfg.shelleyKesAgentSocket != null)
+          "--shelley-kes-agent-socket ${cfg.shelleyKesAgentSocket}"}"
       ];
     };
     instanceDbPath = cfg.databasePath i;
@@ -449,6 +453,14 @@ in {
         '';
       };
 
+      shelleyKesAgentSocket = mkOption {
+        type = nullOr (either str path);
+        default = null;
+        description = ''
+          Path to the KES agent socket.
+        '';
+      };
+
       socketPath = mkOption {
         type = funcToOr str;
         default = i : "${runtimeDir i}/node.socket";
@@ -909,8 +921,6 @@ in {
             `cardano-cli query ledger-peer-snapshot`
         '';
       };
-
-      # TODO-SRE: Add kes-agent CLI arg opts once available
     };
   };
 
@@ -1022,8 +1032,24 @@ in {
                      as a prefix, for each instance!";
         }
         {
-          assertion = (cfg.kesKey == null) == (cfg.vrfKey == null) && (cfg.kesKey == null) == (cfg.operationalCertificate == null);
-          message = "Shelley Era: all of three [operationalCertificate kesKey vrfKey] options must be defined (or none of them).";
+          assertion = let
+            hasKes   = cfg.kesKey != null;
+            hasVrf   = cfg.vrfKey != null;
+            hasOpcert = cfg.operationalCertificate != null;
+            hasAgent = cfg.shelleyKesAgentSocket != null;
+          in
+            # (1) No forging: none of the four options set
+            (!hasKes && !hasVrf && !hasOpcert && !hasAgent)
+            # (2) Direct KES forging: kesKey + vrfKey + operationalCertificate, no agent socket
+            || (hasKes && !hasAgent && hasVrf && hasOpcert)
+            # (3) KES agent forging: shelleyKesAgentSocket + vrfKey + operationalCertificate, no kesKey
+            || (!hasKes && hasAgent && hasVrf && hasOpcert);
+          message = ''
+            Shelley Era: valid forging configurations are:
+              (1) none of [operationalCertificate kesKey vrfKey shelleyKesAgentSocket] (relay/non-producer node),
+              (2) all of [operationalCertificate kesKey vrfKey] without shelleyKesAgentSocket (direct KES key forging), or
+              (3) [operationalCertificate vrfKey shelleyKesAgentSocket] without kesKey (KES agent forging).
+          '';
         }
         {
           assertion = !(cfg.systemdSocketActivation && (cfg.useNewTopology != false));