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

//! ISO 8583 data-element catalog and typed accessors.
//!
//! Each entry in this catalog binds a data-element number (1..=128) to:
//! - a human label,
//! - an [`Encoding`] (BCD, ASCII, EBCDIC, binary),
//! - a [`LengthRule`] (fixed-N, LL-prefixed up to N, LLL-prefixed up to N),
//! - any semantic constraints (numeric-only, etc.).
//!
//! The default catalog returned by [`default_catalog`] follows ISO 8583:1987
//! (the version every major card network's authorization rails are based
//! on; later 1993/2003 revisions are layered on top by individual
//! dialects). Per-network deltas — e.g. Visa Base I's DE 63 reserved
//! sub-fields, Mastercard MDS's DE 48 sub-element layout — are layered
//! via [`crate::dialect::Dialect::override_field`].
//!
//! The decoded value of every data element is a [`FieldValue`], which
//! is a thin sum over the raw decoded form (numeric digit string,
//! ASCII text, raw bytes). Typed accessors on [`Iso8583Message`] wrap
//! the common cases (`pan()`, `amount_tx()`, `response_code()`, ...).

use serde::{Deserialize, Serialize};

use crate::codec::{
    VarLenKind, ascii_decode, ascii_encode, bcd_decode, bcd_encode, binary_decode,
    ebcdic_decode, ebcdic_encode, var_decode, var_encode,
};
use crate::error::{Error, Result};

/// The five distinct wire encodings ISO 8583 actually uses.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum Encoding {
    /// Packed binary-coded decimal (two digits per byte, high nibble first).
    Bcd,
    /// 7-bit ASCII printable characters.
    Ascii,
    /// IBM-037 EBCDIC.
    Ebcdic,
    /// Opaque bytes (DE 52 PIN block, DE 55 EMV TLV, DE 64 MAC, ...).
    Binary,
}

/// How a data element's length is encoded on the wire.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum LengthRule {
    /// Fixed N digits (BCD/ASCII/EBCDIC) or N bytes (Binary).
    Fixed(usize),
    /// LL-prefixed variable length (max 99 digits/bytes).
    Ll(usize),
    /// LLL-prefixed variable length (max 999 digits/bytes).
    Lll(usize),
}

/// Static metadata for one data element.
#[derive(Copy, Clone, Debug)]
pub struct FieldSpec {
    /// 1..=128.
    pub de: u8,
    /// Human label (for error messages and diagnostics).
    pub label: &'static str,
    /// Wire encoding.
    pub encoding: Encoding,
    /// Length rule.
    pub length: LengthRule,
}

/// A decoded data element value.
///
/// We keep the decoded form close to the wire — `Numeric` for any BCD/ASCII
/// numeric, `Text` for ASCII/EBCDIC text, `Bytes` for opaque binary. The
/// typed accessors on [`Iso8583Message`] reinterpret these into domain
/// types (PAN, amount, currency code, ...).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum FieldValue {
    /// Decoded numeric digits (no leading-zero stripping; BCD or ASCII).
    Numeric(String),
    /// Decoded printable text (ASCII or EBCDIC).
    Text(String),
    /// Raw binary bytes.
    Bytes(Vec<u8>),
}

impl FieldValue {
    /// View as a digit string (Numeric variant only).
    #[must_use]
    pub fn as_numeric(&self) -> Option<&str> {
        match self {
            Self::Numeric(s) => Some(s),
            _ => None,
        }
    }
    /// View as a text string (Text variant only).
    #[must_use]
    pub fn as_text(&self) -> Option<&str> {
        match self {
            Self::Text(s) => Some(s),
            _ => None,
        }
    }
    /// View as raw bytes (Bytes variant only).
    #[must_use]
    pub fn as_bytes(&self) -> Option<&[u8]> {
        match self {
            Self::Bytes(b) => Some(b),
            _ => None,
        }
    }
}

/// The default ISO 8583:1987 data-element catalog covering all DEs in
/// the deliverable spec (DE 2 PAN ... DE 90 original data elements,
/// DE 128 secondary MAC).
///
/// Entries here are conservative defaults; per-network dialects can
/// override individual fields without rebuilding the whole catalog.
#[must_use]
pub fn default_catalog() -> Vec<Option<FieldSpec>> {
    use Encoding::{Ascii, Bcd, Binary};
    use LengthRule::{Fixed, Ll, Lll};
    let mut table: Vec<Option<FieldSpec>> = (0..=128).map(|_| None).collect();
    // The well-known data elements called out in the deliverable spec.
    let entries: &[(u8, &'static str, Encoding, LengthRule)] = &[
        (2, "PAN", Bcd, Ll(19)),
        (3, "Processing code", Bcd, Fixed(6)),
        (4, "Amount, transaction", Bcd, Fixed(12)),
        (7, "Transmission date/time", Bcd, Fixed(10)),
        (11, "Systems trace audit number (STAN)", Bcd, Fixed(6)),
        (12, "Local time (hhmmss)", Bcd, Fixed(6)),
        (13, "Local date (MMDD)", Bcd, Fixed(4)),
        (14, "Expiration date (YYMM)", Bcd, Fixed(4)),
        (18, "Merchant category code (MCC)", Bcd, Fixed(4)),
        (22, "POS entry mode", Bcd, Fixed(3)),
        (25, "POS condition code", Bcd, Fixed(2)),
        (32, "Acquiring institution ID code", Bcd, Ll(11)),
        (35, "Track 2 data", Bcd, Ll(37)),
        (37, "Retrieval reference number (RRN)", Ascii, Fixed(12)),
        (38, "Approval code", Ascii, Fixed(6)),
        (39, "Response code", Ascii, Fixed(2)),
        (41, "Card acceptor terminal ID", Ascii, Fixed(8)),
        (42, "Card acceptor ID (merchant ID)", Ascii, Fixed(15)),
        (43, "Card acceptor name/location", Ascii, Fixed(40)),
        (49, "Currency code, transaction", Bcd, Fixed(3)),
        (52, "PIN block", Binary, Fixed(8)),
        (54, "Additional amounts", Ascii, Lll(120)),
        (55, "ICC / EMV data (TLV)", Binary, Lll(255)),
        (64, "MAC (primary)", Binary, Fixed(8)),
        (90, "Original data elements", Bcd, Fixed(42)),
        (128, "MAC (secondary)", Binary, Fixed(8)),
    ];
    for (de, label, encoding, length) in entries {
        table[*de as usize] = Some(FieldSpec {
            de: *de,
            label,
            encoding: *encoding,
            length: *length,
        });
    }
    table
}

/// Look up a [`FieldSpec`] in a catalog.
pub(crate) fn lookup(catalog: &[Option<FieldSpec>], de: u8) -> Result<FieldSpec> {
    catalog
        .get(de as usize)
        .and_then(|s| s.as_ref())
        .copied()
        .ok_or(Error::UnknownDataElement(de))
}

/// Encode one field's payload onto the wire (length prefix included where
/// the spec calls for one).
pub(crate) fn encode_field(spec: &FieldSpec, value: &FieldValue) -> Result<Vec<u8>> {
    let payload: Vec<u8> = match (spec.encoding, value) {
        (Encoding::Bcd, FieldValue::Numeric(s)) => bcd_encode(s)?,
        (Encoding::Ascii, FieldValue::Numeric(s) | FieldValue::Text(s)) => ascii_encode(s)?,
        (Encoding::Ebcdic, FieldValue::Numeric(s) | FieldValue::Text(s)) => ebcdic_encode(s)?,
        (Encoding::Binary, FieldValue::Bytes(b)) => b.clone(),
        (enc, val) => {
            return Err(Error::InvalidDataElement {
                de: spec.de,
                reason: format!(
                    "value type {:?} not compatible with encoding {:?}",
                    discriminant(val),
                    enc
                ),
            });
        }
    };
    match spec.length {
        LengthRule::Fixed(n) => {
            // For numeric encodings the n is in *digits*; we already
            // padded inside bcd_encode (odd lengths) and ASCII numerics
            // must be exactly N digits (caller's responsibility — we
            // verify here).
            let expected_bytes = match spec.encoding {
                Encoding::Bcd => n.div_ceil(2),
                _ => n,
            };
            if payload.len() != expected_bytes {
                return Err(Error::InvalidDataElement {
                    de: spec.de,
                    reason: format!(
                        "fixed-length DE expects {} bytes, got {}",
                        expected_bytes,
                        payload.len()
                    ),
                });
            }
            Ok(payload)
        }
        LengthRule::Ll(max) => {
            // LL prefix in the dialect's variable-length encoding. Use
            // BCD-prefix for BCD fields, ASCII-prefix otherwise — this
            // matches Visa Base I / Mastercard MDS conventions.
            let kind = if matches!(spec.encoding, Encoding::Bcd | Encoding::Binary) {
                VarLenKind::LlBcd
            } else {
                VarLenKind::LlAscii
            };
            let _ = max;
            var_encode(kind, &payload)
        }
        LengthRule::Lll(max) => {
            let kind = if matches!(spec.encoding, Encoding::Bcd | Encoding::Binary) {
                VarLenKind::LllBcd
            } else {
                VarLenKind::LllAscii
            };
            let _ = max;
            var_encode(kind, &payload)
        }
    }
}

/// Decode one field starting at `offset`. Returns `(value, new_offset)`.
pub(crate) fn decode_field(
    spec: &FieldSpec,
    input: &[u8],
    offset: usize,
) -> Result<(FieldValue, usize)> {
    match spec.length {
        LengthRule::Fixed(n) => match spec.encoding {
            Encoding::Bcd => {
                let (digits, new_offset) = bcd_decode(input, offset, n)?;
                Ok((FieldValue::Numeric(digits), new_offset))
            }
            Encoding::Ascii => {
                let (text, new_offset) = ascii_decode(input, offset, n)?;
                Ok((FieldValue::Text(text), new_offset))
            }
            Encoding::Ebcdic => {
                let (text, new_offset) = ebcdic_decode(input, offset, n)?;
                Ok((FieldValue::Text(text), new_offset))
            }
            Encoding::Binary => {
                let (bytes, new_offset) = binary_decode(input, offset, n)?;
                Ok((FieldValue::Bytes(bytes), new_offset))
            }
        },
        LengthRule::Ll(_) | LengthRule::Lll(_) => {
            let kind = match (spec.length, spec.encoding) {
                (LengthRule::Ll(_), Encoding::Bcd | Encoding::Binary) => VarLenKind::LlBcd,
                (LengthRule::Ll(_), _) => VarLenKind::LlAscii,
                (LengthRule::Lll(_), Encoding::Bcd | Encoding::Binary) => VarLenKind::LllBcd,
                (LengthRule::Lll(_), _) => VarLenKind::LllAscii,
                (LengthRule::Fixed(_), _) => unreachable!(),
            };
            let (payload, new_offset) = var_decode(kind, input, offset)?;
            let value = match spec.encoding {
                Encoding::Bcd => {
                    // For LL/LLL BCD the length prefix expresses digit
                    // count; payload bytes = ceil(digits/2).
                    // We treat the payload bytes as raw and let the
                    // caller drop the pad nibble, since the original
                    // digit count is encoded in the LL prefix itself.
                    // Simpler: decode the prefix-derived digit count
                    // by translating bytes back through bcd_decode.
                    // The var_decode contract returned the *raw bytes*
                    // following the prefix; for BCD that is exactly
                    // ceil(N/2) bytes. We don't know N exactly here
                    // (we only have its byte form), but at the typed
                    // accessor layer the caller knows. For now, store
                    // the BCD digits unpadded (no leading zero pad).
                    let mut digits = String::with_capacity(payload.len() * 2);
                    for byte in &payload {
                        let hi = byte >> 4;
                        let lo = byte & 0x0F;
                        if hi <= 9 {
                            digits.push(char::from(b'0' + hi));
                        }
                        if lo <= 9 {
                            digits.push(char::from(b'0' + lo));
                        }
                    }
                    FieldValue::Numeric(digits)
                }
                Encoding::Ascii => FieldValue::Text(String::from_utf8(payload).map_err(|_| {
                    Error::InvalidDataElement {
                        de: spec.de,
                        reason: "non-UTF8 payload in ASCII variable-length field".into(),
                    }
                })?),
                Encoding::Ebcdic => {
                    let (text, _) = ebcdic_decode(&payload, 0, payload.len())?;
                    FieldValue::Text(text)
                }
                Encoding::Binary => FieldValue::Bytes(payload),
            };
            Ok((value, new_offset))
        }
    }
}

fn discriminant(v: &FieldValue) -> &'static str {
    match v {
        FieldValue::Numeric(_) => "Numeric",
        FieldValue::Text(_) => "Text",
        FieldValue::Bytes(_) => "Bytes",
    }
}

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

    #[test]
    fn catalog_contains_required_des() {
        let cat = default_catalog();
        for de in [2_u8, 3, 4, 7, 11, 39, 41, 42, 49, 52, 55, 64, 90, 128] {
            assert!(cat[de as usize].is_some(), "DE {de} missing from catalog");
        }
    }

    #[test]
    fn fixed_bcd_round_trip() {
        let cat = default_catalog();
        let spec = lookup(&cat, 4).unwrap(); // amount, n12
        let v = FieldValue::Numeric("000000010000".into());
        let enc = encode_field(&spec, &v).unwrap();
        let (back, off) = decode_field(&spec, &enc, 0).unwrap();
        assert_eq!(back, v);
        assert_eq!(off, enc.len());
    }

    #[test]
    fn fixed_ascii_round_trip() {
        let cat = default_catalog();
        let spec = lookup(&cat, 39).unwrap(); // response code
        let v = FieldValue::Text("00".into());
        let enc = encode_field(&spec, &v).unwrap();
        let (back, _) = decode_field(&spec, &enc, 0).unwrap();
        assert_eq!(back, v);
    }

    #[test]
    fn lll_binary_round_trip_emv_blob() {
        let cat = default_catalog();
        let spec = lookup(&cat, 55).unwrap();
        let v = FieldValue::Bytes(vec![0x9F, 0x26, 0x08, 1, 2, 3, 4, 5, 6, 7, 8]);
        let enc = encode_field(&spec, &v).unwrap();
        // LLL BCD prefix: "011" -> 0x01 0x11? No: 011 BCD = 0x01 0x10? Let's just round-trip.
        let (back, _) = decode_field(&spec, &enc, 0).unwrap();
        assert_eq!(back, v);
    }

    #[test]
    fn unknown_de_errors() {
        let cat = default_catalog();
        let err = lookup(&cat, 99).unwrap_err();
        assert!(matches!(err, Error::UnknownDataElement(99)));
    }
}