open-standards/openpay/crates/op-iso8583/src/dialect.rs

//! Per-network ISO 8583 dialects.
//!
//! ISO 8583 is a meta-standard. Every card network publishes its own
//! profile — its own catalog overrides, its own MTI subset, its own
//! response-code table, its own MAC algorithm. Five matter for direct
//! acquirer connectivity:
//!
//! - **Visa Base I** (V.I.P. / VisaNet Authorization) — primary
//!   authorization rail. BCD numerics, binary bitmap, CBC-MAC over the
//!   ISO 8583 frame with TDES (PVV / DUKPT-derived working key).
//! - **Mastercard MDS** (Mastercard Debit Switch / Authorization
//!   network) — ISO 8583:1987 with Mastercard-specific DE 48
//!   sub-elements, DE 22 sub-fields (POS entry mode + PIN capability
//!   capability), and an extended response-code table including the
//!   "decline reason" advice codes.
//! - **Amex GNS** (Global Network Services) — historically EBCDIC; on
//!   the modern XML/SOAP track it is JSON but the legacy ISO 8583
//!   bridges still see EBCDIC text fields with Amex-specific MTI
//!   variants for FYC (financial type code).
//! - **Discover Card** — ISO 8583:1993 layout, BCD/ASCII mix, AES
//!   CBC-MAC since 2021. Response-code table aligned to Visa but with
//!   carved-out values in the 1xx range for Discover-specific declines.
//! - **JCB** — closest to ISO 8583:1987 reference; ASCII-prefix
//!   variable-length and TDES CBC-MAC on connectivity bound for the
//!   Tokyo authorization centre.
//!
//! Each dialect implements the [`Dialect`] trait below. Per-field
//! encoding overrides are surfaced via [`Dialect::override_field`].
//! MAC is computed via [`Dialect::mac`].

use op_core::CardNetwork;

use crate::error::{Error, Result};
use crate::fields::{Encoding, FieldSpec, LengthRule, default_catalog};
use crate::message::Mti;

/// Abstraction over the per-network ISO 8583 profile.
///
/// Implementors are zero-sized marker structs ([`VisaBaseI`],
/// [`MastercardMds`], ...); the dialect functions are stateless.
pub trait Dialect {
    /// Human-readable name (used in error messages).
    fn name(&self) -> &'static str;
    /// Which [`CardNetwork`] this dialect represents.
    fn card_network(&self) -> CardNetwork;
    /// Per-field encoding overrides. The default catalog is a starting
    /// point; the dialect returns the modified version.
    fn catalog(&self) -> Vec<Option<FieldSpec>> {
        default_catalog()
    }
    /// Optionally override a single field. Convenience for dialects
    /// that only tweak one or two DEs.
    fn override_field(&self, _de: u8) -> Option<FieldSpec> {
        None
    }
    /// True iff this dialect supports the given MTI.
    fn supports_mti(&self, _mti: Mti) -> bool {
        true
    }
    /// Map a 2-character response code (DE 39) to a human-readable
    /// reason. `None` for unknown codes (the caller should log the raw
    /// code in that case, not invent a meaning).
    fn response_code_meaning(&self, code: &str) -> Option<&'static str>;
    /// Compute the MAC over the given message bytes using `key`.
    /// Returns an 8-byte MAC suitable for DE 64.
    ///
    /// # Errors
    /// Dialect-defined; the reference implementations here return
    /// [`Error::DialectViolation`] if the key is wrong length.
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]>;
}

// ---------- Visa Base I ----------

/// Visa Base I dialect (V.I.P. / VisaNet authorization).
#[derive(Copy, Clone, Debug, Default)]
pub struct VisaBaseI;

impl Dialect for VisaBaseI {
    fn name(&self) -> &'static str {
        "Visa Base I"
    }
    fn card_network(&self) -> CardNetwork {
        CardNetwork::Visa
    }
    fn supports_mti(&self, mti: Mti) -> bool {
        // Visa Base I uses the 0x01xx, 0x02xx, 0x04xx, 0x08xx families.
        matches!(
            mti.0 & 0xFF00,
            0x0100 | 0x0200 | 0x0400 | 0x0800
        )
    }
    fn response_code_meaning(&self, code: &str) -> Option<&'static str> {
        Some(match code {
            "00" => "Approved",
            "01" => "Refer to card issuer",
            "05" => "Do not honor",
            "12" => "Invalid transaction",
            "13" => "Invalid amount",
            "14" => "Invalid card number",
            "30" => "Format error",
            "41" => "Lost card, pick up",
            "43" => "Stolen card, pick up",
            "51" => "Insufficient funds",
            "54" => "Expired card",
            "55" => "Incorrect PIN",
            "57" => "Transaction not permitted to cardholder",
            "61" => "Withdrawal amount exceeds limit",
            "62" => "Restricted card",
            "65" => "Withdrawal frequency exceeds limit",
            "75" => "PIN tries exceeded",
            "91" => "Issuer or switch is unavailable",
            "96" => "System malfunction",
            _ => return None,
        })
    }
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
        cbc_mac_tdes(key, data)
    }
}

// ---------- Mastercard MDS ----------

/// Mastercard MDS dialect.
#[derive(Copy, Clone, Debug, Default)]
pub struct MastercardMds;

impl Dialect for MastercardMds {
    fn name(&self) -> &'static str {
        "Mastercard MDS"
    }
    fn card_network(&self) -> CardNetwork {
        CardNetwork::Mastercard
    }
    fn override_field(&self, de: u8) -> Option<FieldSpec> {
        if de == 48 {
            return Some(FieldSpec {
                de: 48,
                label: "Additional data (Mastercard private)",
                encoding: Encoding::Ascii,
                length: LengthRule::Lll(999),
            });
        }
        None
    }
    fn supports_mti(&self, mti: Mti) -> bool {
        matches!(
            mti.0 & 0xFF00,
            0x0100 | 0x0200 | 0x0400 | 0x0420 | 0x0800
        )
    }
    fn response_code_meaning(&self, code: &str) -> Option<&'static str> {
        Some(match code {
            "00" => "Approved",
            "01" => "Refer to card issuer",
            "05" => "Do not honor",
            "08" => "Honor with ID",
            "12" => "Invalid transaction",
            "14" => "Invalid card number",
            "30" => "Format error",
            "51" => "Insufficient funds",
            "54" => "Expired card",
            "55" => "Invalid PIN",
            "57" => "Transaction not permitted to cardholder",
            "58" => "Transaction not permitted to terminal",
            "62" => "Restricted card",
            "63" => "Security violation",
            "70" => "Contact card issuer",
            "75" => "PIN tries exceeded",
            "82" => "Negative CAM, dCVV, iCVV, or CVV results",
            "91" => "Issuer or switch unavailable",
            "92" => "Routing error",
            "96" => "System malfunction",
            _ => return None,
        })
    }
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
        cbc_mac_tdes(key, data)
    }
}

// ---------- Amex GNS ----------

/// American Express Global Network Services dialect.
#[derive(Copy, Clone, Debug, Default)]
pub struct AmexGns;

impl Dialect for AmexGns {
    fn name(&self) -> &'static str {
        "Amex GNS"
    }
    fn card_network(&self) -> CardNetwork {
        CardNetwork::Amex
    }
    fn override_field(&self, de: u8) -> Option<FieldSpec> {
        // Amex GNS historically encodes DE 41 (terminal ID) and DE 42
        // (merchant ID) as EBCDIC IBM-037 rather than ASCII.
        match de {
            41 => Some(FieldSpec {
                de: 41,
                label: "Terminal ID (EBCDIC, Amex GNS)",
                encoding: Encoding::Ebcdic,
                length: LengthRule::Fixed(8),
            }),
            42 => Some(FieldSpec {
                de: 42,
                label: "Merchant ID (EBCDIC, Amex GNS)",
                encoding: Encoding::Ebcdic,
                length: LengthRule::Fixed(15),
            }),
            43 => Some(FieldSpec {
                de: 43,
                label: "Merchant name/location (EBCDIC, Amex GNS)",
                encoding: Encoding::Ebcdic,
                length: LengthRule::Fixed(40),
            }),
            _ => None,
        }
    }
    fn response_code_meaning(&self, code: &str) -> Option<&'static str> {
        Some(match code {
            "000" | "00" => "Approved",
            "100" | "05" => "Decline",
            "101" => "Expired card",
            "109" => "Invalid merchant",
            "110" => "Invalid amount",
            "111" => "Invalid card number",
            "115" => "Requested function not supported",
            "120" => "Not permitted",
            "121" => "Limit exceeded",
            "125" => "Card not effective",
            "187" => "Transaction not allowed",
            "200" | "04" => "Pick up card",
            "400" => "Reversal accepted",
            "900" => "Advice acknowledged",
            _ => return None,
        })
    }
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
        cbc_mac_tdes(key, data)
    }
}

// ---------- Discover Card ----------

/// Discover Card dialect.
#[derive(Copy, Clone, Debug, Default)]
pub struct DiscoverCard;

impl Dialect for DiscoverCard {
    fn name(&self) -> &'static str {
        "Discover"
    }
    fn card_network(&self) -> CardNetwork {
        CardNetwork::Discover
    }
    fn response_code_meaning(&self, code: &str) -> Option<&'static str> {
        Some(match code {
            "00" => "Approved",
            "01" => "Refer to issuer",
            "05" => "Do not honor",
            "12" => "Invalid transaction",
            "14" => "Invalid account number",
            "39" => "No credit account",
            "51" => "Insufficient funds",
            "54" => "Expired card",
            "55" => "Invalid PIN",
            "57" => "Transaction not permitted",
            "58" => "Transaction not allowed at terminal",
            "61" => "Exceeds withdrawal limit",
            "91" => "Issuer unavailable",
            "96" => "System malfunction",
            _ => return None,
        })
    }
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
        // Discover migrated to AES CBC-MAC; for the reference
        // implementation here we use the same CBC-MAC primitive
        // parameterised by an AES-128 block cipher.
        cbc_mac_aes128(key, data)
    }
}

// ---------- JCB ----------

/// JCB dialect.
#[derive(Copy, Clone, Debug, Default)]
pub struct Jcb;

impl Dialect for Jcb {
    fn name(&self) -> &'static str {
        "JCB"
    }
    fn card_network(&self) -> CardNetwork {
        // JCB shares the Discover routing infrastructure in many
        // regions; for op-core CardNetwork mapping we use Discover.
        CardNetwork::Discover
    }
    fn response_code_meaning(&self, code: &str) -> Option<&'static str> {
        Some(match code {
            "00" => "Approved",
            "01" => "Refer to issuer",
            "05" => "Do not honor",
            "14" => "Invalid card number",
            "51" => "Insufficient funds",
            "54" => "Expired card",
            "55" => "Invalid PIN",
            "91" => "Issuer unavailable",
            _ => return None,
        })
    }
    fn mac(&self, key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
        cbc_mac_tdes(key, data)
    }
}

// ---------- Reference MAC implementations ----------

/// CBC-MAC over a `data` slice using a TDES (3DES) two-key bundle.
///
/// Key must be 16 bytes (K1‖K2; K3 = K1, "2-key TDES" as Visa Base I and
/// JCB use). The reference implementation here uses a simple
/// 8-byte-block CBC chain with an internal pseudo-TDES that is
/// **deterministic and key-dependent** so test vectors are reproducible
/// without pulling in a heavyweight crypto dependency. For a production
/// deployment, swap this with `des::TdesEde2 + cbc::Mac`.
///
/// The implementation:
///
/// 1. Zero-pads `data` up to a multiple of 8 bytes.
/// 2. XORs each block into the running state.
/// 3. After each XOR, applies a key-derived block scrambling round
///    (a 16-round Feistel network using the two halves of the key as
///    round keys).
/// 4. Returns the final 8-byte state.
///
/// This is **NOT** cryptographically secure on its own; the production
/// build swaps it for a real TDES. It is deterministic, reproducible
/// across platforms (no FFI, no SIMD), and exact-byte test-vector
/// stable, which is what the conformance tests need.
fn cbc_mac_tdes(key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
    if key.len() != 16 {
        return Err(Error::DialectViolation {
            dialect: "TDES MAC",
            reason: format!("expected 16-byte key, got {}", key.len()),
        });
    }
    let mut state = [0_u8; 8];
    let mut padded = data.to_vec();
    while padded.len() % 8 != 0 {
        padded.push(0);
    }
    let k1 = &key[..8];
    let k2 = &key[8..16];
    for block in padded.chunks_exact(8) {
        for (s, b) in state.iter_mut().zip(block.iter()) {
            *s ^= *b;
        }
        feistel_round(&mut state, k1, k2);
    }
    Ok(state)
}

/// CBC-MAC over `data` using an AES-128 key.
///
/// Same disclaimers as [`cbc_mac_tdes`] — this is the deterministic
/// reference primitive used by the conformance test vectors; production
/// builds plug in `aes::Aes128 + cbc::Mac`. The Feistel round uses a
/// 16-byte key, mixing both halves into each round.
fn cbc_mac_aes128(key: &[u8], data: &[u8]) -> Result<[u8; 8]> {
    if key.len() != 16 {
        return Err(Error::DialectViolation {
            dialect: "AES-128 MAC",
            reason: format!("expected 16-byte key, got {}", key.len()),
        });
    }
    let mut state = [0_u8; 8];
    let mut padded = data.to_vec();
    while padded.len() % 8 != 0 {
        padded.push(0);
    }
    let k1 = &key[..8];
    let k2 = &key[8..16];
    for block in padded.chunks_exact(8) {
        for (s, b) in state.iter_mut().zip(block.iter()) {
            *s ^= *b;
        }
        feistel_round(&mut state, k1, k2);
        feistel_round(&mut state, k2, k1);
    }
    Ok(state)
}

/// A toy Feistel round used by the reference MAC primitives.
/// Splits the 8-byte block into two 4-byte halves and runs 8 rounds
/// of (L, R) → (R, L ⊕ F(R, K_round)), where F is byte rotation +
/// key XOR.
fn feistel_round(state: &mut [u8; 8], k1: &[u8], k2: &[u8]) {
    let mut l = [state[0], state[1], state[2], state[3]];
    let mut r = [state[4], state[5], state[6], state[7]];
    for round in 0..8 {
        let key_slice = if round % 2 == 0 { k1 } else { k2 };
        let mut f = [0_u8; 4];
        for i in 0..4 {
            // Mix: rotate R, XOR with key (rotating selection), XOR with round.
            let rot = r[(i + 1) % 4];
            f[i] = rot
                ^ key_slice[(i + round) % key_slice.len()]
                ^ (round as u8).wrapping_mul(0x9E);
        }
        let new_r = [l[0] ^ f[0], l[1] ^ f[1], l[2] ^ f[2], l[3] ^ f[3]];
        l = r;
        r = new_r;
    }
    state[0] = l[0];
    state[1] = l[1];
    state[2] = l[2];
    state[3] = l[3];
    state[4] = r[0];
    state[5] = r[1];
    state[6] = r[2];
    state[7] = r[3];
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn visa_base_i_supports_known_mtis() {
        let d = VisaBaseI;
        assert!(d.supports_mti(Mti::AUTH_REQUEST));
        assert!(d.supports_mti(Mti::FINANCIAL_REQUEST));
        assert!(d.supports_mti(Mti::REVERSAL_ADVICE));
        assert!(d.supports_mti(Mti::NETWORK_REQUEST));
    }

    #[test]
    fn visa_response_code_lookup() {
        let d = VisaBaseI;
        assert_eq!(d.response_code_meaning("00"), Some("Approved"));
        assert_eq!(d.response_code_meaning("51"), Some("Insufficient funds"));
        assert_eq!(d.response_code_meaning("ZZ"), None);
    }

    #[test]
    fn mastercard_overrides_de48_to_ascii_lllvar() {
        let d = MastercardMds;
        let f = d.override_field(48).expect("DE 48 override");
        assert_eq!(f.encoding, Encoding::Ascii);
    }

    #[test]
    fn amex_overrides_de42_to_ebcdic() {
        let d = AmexGns;
        let f = d.override_field(42).expect("DE 42 override");
        assert_eq!(f.encoding, Encoding::Ebcdic);
    }

    // --- MAC reproducibility tests. These are golden-vector tests of our
    // reference Feistel-based MAC primitive: they catch regressions in
    // bitmap framing & dialect routing without depending on a heavy
    // crypto crate. The exact bytes are stable because the primitive is
    // pure-functional and platform-independent. ---

    #[test]
    fn tdes_mac_deterministic_visa() {
        let d = VisaBaseI;
        let key = [0_u8; 16];
        let data = b"VisaBaseI test vector 0";
        let mac1 = d.mac(&key, data).unwrap();
        let mac2 = d.mac(&key, data).unwrap();
        assert_eq!(mac1, mac2);
        // Output is *not* all zeros (sanity check; an all-zero MAC over
        // non-empty data would indicate a constant-output bug).
        assert_ne!(mac1, [0_u8; 8]);
    }

    #[test]
    fn tdes_mac_key_sensitive() {
        let d = MastercardMds;
        let data = b"some message";
        let mac_a = d.mac(&[0_u8; 16], data).unwrap();
        let mac_b = d.mac(&[1_u8; 16], data).unwrap();
        assert_ne!(mac_a, mac_b);
    }

    #[test]
    fn aes_mac_discover_different_from_tdes_visa() {
        let key = [0x42_u8; 16];
        let data = b"common";
        let visa_mac = VisaBaseI.mac(&key, data).unwrap();
        let disc_mac = DiscoverCard.mac(&key, data).unwrap();
        assert_ne!(visa_mac, disc_mac);
    }

    #[test]
    fn jcb_supports_all_messages() {
        let d = Jcb;
        assert!(d.supports_mti(Mti::AUTH_REQUEST));
        assert!(d.supports_mti(Mti::FINANCIAL_REQUEST));
    }

    #[test]
    fn bad_key_length_rejected() {
        let err = VisaBaseI.mac(&[0_u8; 7], b"x").unwrap_err();
        assert!(matches!(err, Error::DialectViolation { .. }));
        let err = DiscoverCard.mac(&[0_u8; 7], b"x").unwrap_err();
        assert!(matches!(err, Error::DialectViolation { .. }));
    }
}