#!/usr/bin/env bash
# shellcheck shell=bash
set -Eeuo pipefail

: <<'DOC'
===============================================================================
This script is a forensic inspection tool for ext2/3/4 partition images that
have been rescued with ddrescue or similar methods. It allows the user to map
and inspect specific regions of an image by either disk sector (LBA) or ext
filesystem block number.
===============================================================================
This script is not POSIX compliant and uses bash-specific features
===============================================================================
I coached ChatGPT to generate this script based on my requirements and style
guidance. The development was iterative, with one unit of functionality added at
a time, followed by the addition of guardrails, getopts, usage, shellcheck and
polish.
===============================================================================
Notes on POSIX vs. Bash-Specific Features
-------------------------------------------------------------------------------
This script currently requires Bash and GNU userland tools for full
functionality. The following elements are not POSIX, grouped by type:

Bash language features:
  - set -o pipefail and set -E (not POSIX, Bash/Ksh extensions)
  - Arrays and array expansion: VIEW=(hexdump -C), "${VIEW[@]}"
  - [[ ... ]] test syntax and =~ regex
  - Arithmetic evaluation: (( ... ))
  - Process substitution: tee >( zeros_or_not ... )
  - printf '%q' (shell escaping, Bash extension)

External utilities and flags (GNU/BSD specific):
  - stat (GNU: stat -Lc %s, BSD: stat -f%z); not POSIX
  - dd flags: iflag=skip_bytes,count_bytes, status=none (GNU only)
  - cmp -n N (limit compare to N bytes, GNU extension)
  - hexdump -C (canonical output, not POSIX mandated)
  - od -Ax (BSD/GNU form; POSIX form is od -A x -t x1 -v)
  - dumpe2fs (and future debugfs) are ext2/3/4 tools, not POSIX

Likely POSIX-OK:
  - set -e and set -u are POSIX compliant
  - awk, sed, grep, printf with used options are POSIX
  - $(( ... )) arithmetic expansion is POSIX
  - here-docs (including quoted delimiters) are POSIX
  - command -v is POSIX

In short:
  - The script is Bash-only today.
  - Porting to strict /bin/sh would require replacing arrays,
    [[ ... ]], (( ... )), process substitution, and GNU-specific dd/stat.
===============================================================================
DOC

# ===== usage & small helpers =====

usage() {
  cat >&2 <<'EOF'
Usage:
  ext_block_inspector.sh -i <image> --fs-block=<N> [--fs-block-size=<bytes>] [--sector-bytes=<bytes>]
  ext_block_inspector.sh -i <image> --lba=<DISK_LBA> --part-start=<PART_START_LBA> [--sector-bytes=<bytes>]

Options:
  -i, --image=<PATH>          Path to partition image (required)
      --fs-block=<N>          Filesystem block index (0-based; 1:1 with image; ddrescuelog -b <FS_BS>)
      --lba=<N>               Disk LBA (512-byte sectors by default)
      --part-start=<N>        Partition start LBA on original disk (required with --lba)
      --sector-bytes=<BYTES>  LBA sector size. Default: 512
      --fs-block-size=<BYTES> filesystem block size override. Default reads from image.
  -h, --help                  Show this help

Note: long options must be used with '=' (e.g. --fs-block=123), not space separation.
Note: current version supports ext2/3/4 filesystems but could be expanded to support others.
EOF
  exit 2
}

die()  { printf '%s\n' "$*" >&2; exit 1; }
warn() { printf 'Warning: %s\n' "$*" >&2; }
note() { printf '%s\n' "$*" >&2; }
is_uint() { [[ "${1-}" =~ ^[0-9]+$ ]]; }

# ===== deps & viewer =====

ensure_deps() {
  local need=(dd awk grep printf dumpe2fs cmp tee stat stdbuf)
  local ok=1
  for bin in "${need[@]}"; do
    command -v "$bin" >/dev/null 2>&1 || { printf 'Missing dependency: %s\n' "$bin" >&2; ok=0; }
  done
  if ! command -v hexdump >/dev/null 2>&1; then
    command -v od >/dev/null 2>&1 || { printf 'Missing dependency: hexdump or od\n' >&2; ok=0; }
  fi
  (( ok == 1 )) || exit 127
}

# Note: uses a small array; keep Bash shebang.
set_viewer() {
  if command -v hexdump >/dev/null 2>&1; then
    VIEW=(hexdump -C)
  else
    VIEW=(od -Ax -tx1 -v)
  fi
}

print_view_cmd() {
  # Show exactly what will execute (shell-safe quoting)
  printf '[cmd] %s\n' "$(printf '%q ' "${VIEW[@]}")" >&2
}

# ===== image introspection (globals) =====

IMG=""
IMG_SIZE=0
SECTOR_BYTES="512"
FS_BS=""         # optional override; auto-detected otherwise
FS_BS_ACTUAL=""
FIRST_BLOCK="0"
BLKCNT=0
PER_BLK=0        # sectors per filesystem block

init_image() {
  local img=${1:?image path required}
  [[ -r "$img" ]] || die "Image not readable: $img"

  # Ensure stable parsing from dumpe2fs output
  export LC_ALL=C

  # image size (GNU/BSD stat)
  if IMG_SIZE=$(stat -Lc %s "$img" 2>/dev/null); then :; else IMG_SIZE=$(stat -f%z "$img"); fi

  FS_BS_ACTUAL=$(dumpe2fs -h "$img" 2>/dev/null | awk -F': *' '/Block size:/ {gsub(/[^0-9]/,"",$2); print $2}')
  FIRST_BLOCK=$(dumpe2fs -h "$img" 2>/dev/null | awk -F': *' '/First block:/ {gsub(/[^0-9]/,"",$2); print $2}')
  BLKCNT=$(dumpe2fs -h "$img" 2>/dev/null | awk -F': *' '/Block count:/ {gsub(/[^0-9]/,"",$2); print $2}')

  [[ -n "$FS_BS_ACTUAL" && -n "$BLKCNT" ]] || die 'Could not read filesystem parameters from image'

  if [[ -n "$FS_BS" && "$FS_BS" != "$FS_BS_ACTUAL" ]]; then
    warn "FS_BS override ($FS_BS) differs from image block size ($FS_BS_ACTUAL). Using image value."
  fi
  FS_BS="$FS_BS_ACTUAL"

  (( FS_BS % SECTOR_BYTES == 0 )) || die "FS_BS ($FS_BS) is not a multiple of sector bytes ($SECTOR_BYTES)"
  PER_BLK=$(( FS_BS / SECTOR_BYTES ))
}

# ===== parked debugfs (no-op for now) =====
debugfs_probe() { :; }

# ===== zero-detect & viewer wrapper =====

zeros_or_not() {
  # stdin is the byte stream; $1=label text, $2=byte count
  local label=${1:?label required}
  local nbytes=${2:?byte-count required}
  # Bound the comparison to avoid infinite /dev/zero length mismatch
  if cmp -s -n "$nbytes" - /dev/zero; then
    printf '[zeros] all-zero (%s)\n' "$label"
  else
    printf '[zeros] non-zero (%s)\n' "$label"
  fi
}

preview_and_zero() {
  # stdin is the byte stream; $1=byte-count, $2=label
  local nbytes=${1:?byte-count required}
  local label=${2:?label required}
  # One tee fork to zero-check; main stream to hex viewer, then stdbuf to mitigate stdout and stderr interleaving 
  tee >( zeros_or_not "$label" "$nbytes" 1>&2 ) | stdbuf -o "$nbytes" "${VIEW[@]}" 
}

# ===== read by filesystem block (1:1 with image) =====

read_from_fsblock() {
  local img=${1:?} fs_block=${2:?}
  is_uint "$fs_block" || die 'FS block must be a non-negative integer'

  init_image "$img"
  set_viewer

  (( fs_block >= 0 && fs_block < BLKCNT )) || die "FS_BLOCK $fs_block out of range [0..$((BLKCNT-1))]"
  local block_off=$(( fs_block * FS_BS ))
  (( block_off + FS_BS <= IMG_SIZE )) || die "Requested range [$block_off..$((block_off+FS_BS))) exceeds image size $IMG_SIZE"

  note "IMG=$img"
  note "IMG_SIZE=$IMG_SIZE  SECTOR_BYTES=$SECTOR_BYTES  FS_BS=$FS_BS  PER_BLK=$PER_BLK"
  note "First block=$FIRST_BLOCK  Block count=$BLKCNT"
  note "FS_BLOCK=$fs_block  offset=$block_off"
  print_view_cmd

  note "[read] ${FS_BS}-byte filesystem block FS_BLOCK=$fs_block (offset=$block_off)"
  dd if="$img" bs="$FS_BS" skip="$fs_block" count=1 status=none   | preview_and_zero "$FS_BS" "${FS_BS} bytes"
}

# ===== read by disk LBA + partition start =====

read_from_lba() {
  local img=${1:?} lba=${2:?} part_start=${3:?}
  is_uint "$lba" || die 'LBA must be a decimal integer'
  is_uint "$part_start" || die 'PART_START_LBA must be a decimal integer'

  init_image "$img"
  set_viewer

  local sect_in_part=$(( lba - part_start ))
  (( sect_in_part >= 0 )) || die "LBA $lba is before partition start $part_start"

  local byte_off=$(( sect_in_part * SECTOR_BYTES ))
  local fs_block=$(( sect_in_part / PER_BLK ))
  local intra_sec=$(( sect_in_part % PER_BLK ))

  (( byte_off + SECTOR_BYTES <= IMG_SIZE )) || die "Requested byte range [$byte_off..$((byte_off+SECTOR_BYTES))) exceeds image size $IMG_SIZE"
  (( fs_block >= 0 && fs_block < BLKCNT )) || die "FS_BLOCK $fs_block out of range [0..$((BLKCNT-1))]"

  note "IMG=$img"
  note "IMG_SIZE=$IMG_SIZE  SECTOR_BYTES=$SECTOR_BYTES  FS_BS=$FS_BS  PER_BLK=$PER_BLK"
  note "First block=$FIRST_BLOCK  Block count=$BLKCNT"
  note "DISK_LBA=$lba  PART_START_LBA=$part_start  sect_in_part=$sect_in_part"
  note "FS_BLOCK=$fs_block  sector_in_4k=$intra_sec  byte_off=$byte_off"
  print_view_cmd

  # 512-byte sector
  note "[read] 512 bytes at sector_in_partition=$sect_in_part (byte_off=$byte_off)"
  dd if="$img" iflag=skip_bytes,count_bytes skip="$byte_off" count="$SECTOR_BYTES" status=none   | preview_and_zero "$SECTOR_BYTES" "512 bytes"

  # Whole FS block
  local block_off=$(( fs_block * FS_BS ))
  note "[read] ${FS_BS}-byte filesystem block FS_BLOCK=$fs_block (offset=$block_off)"
  dd if="$img" bs="$FS_BS" skip="$fs_block" count=1 status=none   | preview_and_zero "$FS_BS" "${FS_BS} bytes"

  # The 512 bytes within that block for this LBA
  note "[read] 512 bytes within FS_BLOCK=$fs_block at sector_in_4k=$intra_sec"
  dd if="$img" bs="$FS_BS" skip="$fs_block" count=1 status=none   | dd bs="$SECTOR_BYTES" skip="$intra_sec" count=1 status=none   | preview_and_zero "$SECTOR_BYTES" "512 bytes"
}

# ===== option parsing (getopts with long options) =====
# Should be POSIX compatible
# Thank you: https://stackoverflow.com/users/519360/adam-katz
# https://stackoverflow.com/a/28466267/490487

IMG=""
LBA=""
PART_START=""
FS_BLOCK=""
SECTOR_BYTES="512"
FS_BS=""

while getopts hi:l:p:B:s:k:-: opt; do
  if [[ "$opt" == "-" ]]; then
    opt=${OPTARG%%=*}
    OPTARG=${OPTARG#"$opt"}
    OPTARG=${OPTARG#=}
  fi
  case "$opt" in
    h|help) usage ;;
    i|image) IMG=${OPTARG:-} ;;
    l|lba) LBA=${OPTARG:-} ;;
    p|part-start) PART_START=${OPTARG:-} ;;
    B|fs-block) FS_BLOCK=${OPTARG:-} ;;
    s|sector-bytes) SECTOR_BYTES=${OPTARG:-} ;;
    k|fs-block-size) FS_BS=${OPTARG:-} ;;   # optional override; auto-detected by default
    \?) usage ;;
    *)  printf 'Illegal option --%s\n' "$opt" >&2; usage ;;
  esac
done
shift $((OPTIND-1))

ensure_deps
set_viewer

# ===== dispatch =====

if [[ -n "$FS_BLOCK" ]]; then
  [[ -n "$IMG" ]] || usage
  read_from_fsblock "$IMG" "$FS_BLOCK"
  exit 0
fi

if [[ -n "$LBA" || -n "$PART_START" ]]; then
  [[ -n "$IMG" && -n "$LBA" && -n "$PART_START" ]] || usage
  read_from_lba "$IMG" "$LBA" "$PART_START"
  exit 0
fi

usage