hash_users_xml.py

#!/usr/bin/env python3
"""Generate the companion .hash file for a Shadow Fight 2 users.xml file."""

from __future__ import annotations

import argparse
import hashlib
import os
import sys
from pathlib import Path

from dotenv import load_dotenv

DEFAULT_APP_ID = "com.nekki.shadowfight"
DEFAULT_SALT_SUFFIX = "wqO+Qchj|r*QXg7o_KNmLYvpGHdSwqxwlQI2vy618KaD^Pwt-h3H8*uJ"


def md5_hex(data: bytes) -> str:
  """MD5 of bytes, returned as uppercase hex without separators.

  Equivalent to .NET's ``BitConverter.ToString(md5).Replace("-", "")`` that the
  game uses for its hash output, but computed via Python's hashlib so the
  script runs on any platform without the Mono/.NET runtime.
  """
  return hashlib.md5(data).hexdigest().upper()


def normalized_xml_text(xml_path: Path) -> str:
  """Match the game's text normalization before the first MD5.

  The game-written files are UTF-8 with a BOM and pretty indentation. Runtime
  hashes match decoding with BOM removal, trimming each physical line, and
  joining the lines with no separators. This intentionally does not parse or
  reserialize the XML, because serializer differences change the checksum.
  """
  text = xml_path.read_text(encoding="utf-8-sig")
  return "".join(line.strip() for line in text.splitlines())


def build_salt(
  *,
  full_salt: str | None,
  device_value: str | None,
  app_id: str,
  salt_suffix: str,
) -> str | None:
  if full_salt is not None:
    return full_salt
  if device_value is None:
    return None
  if device_value.startswith("and_"):
    device_value = device_value[4:]
  return device_value + app_id + salt_suffix


def compute_users_hash(xml_path: Path, salt: str | None, raw_file: bool) -> str:
  if raw_file:
    first = md5_hex(xml_path.read_bytes())
  else:
    first = md5_hex(normalized_xml_text(xml_path).encode("utf-8"))

  if salt is None:
    return first

  return md5_hex((first + salt).encode("utf-8"))


def default_output_path(xml_path: Path) -> Path:
  return xml_path.with_name(xml_path.name + ".hash")


def main() -> int:
  load_dotenv()

  parser = argparse.ArgumentParser(description="Write users.xml.hash beside a users.xml file.")
  parser.add_argument(
    "xml",
    nargs="?",
    default=".local/saves/users.xml",
    type=Path,
    help="XML file to hash; defaults to ./.local/saves/users.xml",
  )
  parser.add_argument(
    "-o",
    "--output",
    type=Path,
    help="Output hash path; defaults to <xml file>.hash",
  )
  salt_group = parser.add_argument_group("salt")
  salt_group.add_argument(
    "--salt",
    dest="full_salt",
    default=os.environ.get("USER_XML_HASH_SALT"),
    help=(
      "Full second-stage salt. This overrides --device-value, --app-id, "
      "and --salt-suffix. Also read from USER_XML_HASH_SALT."
    ),
  )
  salt_group.add_argument(
    "--device-value",
    default=os.environ.get("USER_XML_HASH_DEVICE_VALUE"),
    help=(
      "Device value of the game install: `and_` plus its "
      "Settings.Secure.ANDROID_ID. Also read from USER_XML_HASH_DEVICE_VALUE."
    ),
  )
  salt_group.add_argument(
    "--app-id",
    default=os.environ.get("USER_XML_HASH_APP_ID", DEFAULT_APP_ID),
    help=(f"Unity Application.identifier value. Defaults to {DEFAULT_APP_ID}; also read from USER_XML_HASH_APP_ID."),
  )
  salt_group.add_argument(
    "--salt-suffix",
    default=os.environ.get("USER_XML_HASH_SALT_SUFFIX", DEFAULT_SALT_SUFFIX),
    help=(
      "Decoded constant appended after the app id. Defaults to "
      f"{DEFAULT_SALT_SUFFIX!r}; also read from "
      "USER_XML_HASH_SALT_SUFFIX."
    ),
  )
  parser.add_argument(
    "--raw-file",
    action="store_true",
    help=(
      "Hash the raw file bytes directly, skipping BOM stripping and line "
      "normalization. Useful only for diagnosing algorithm differences "
      "against the normalized path; the game itself uses the normalized path."
    ),
  )
  parser.add_argument(
    "--print",
    action="store_true",
    help="Print the computed hash after writing it.",
  )
  parser.add_argument(
    "--no-write",
    action="store_true",
    help="Print/compute only; do not write the .hash file.",
  )
  parser.add_argument(
    "--allow-first-stage",
    action="store_true",
    help=(
      "Allow writing the first-stage MD5 when no salt is configured. The "
      "result will NOT match the game's hash. Use only for debugging the "
      "algorithm; do not push a first-stage hash to the phone."
    ),
  )
  args = parser.parse_args()

  xml_path = args.xml.resolve()
  output_path = (args.output or default_output_path(xml_path)).resolve()

  salt = build_salt(
    full_salt=args.full_salt,
    device_value=args.device_value,
    app_id=args.app_id,
    salt_suffix=args.salt_suffix,
  )
  digest = compute_users_hash(xml_path, salt, args.raw_file)

  if salt is None and not args.no_write and not args.allow_first_stage:
    raise SystemExit(
      "No salt configured. Set USER_XML_HASH_DEVICE_VALUE (or "
      "USER_XML_HASH_SALT) in .env, pass --device-value/--salt on the "
      "command line, or pass --allow-first-stage to write the first-stage "
      "MD5 anyway (it will not match the game's hash)."
    )

  if not args.no_write:
    output_path.write_text(digest, encoding="ascii")

  if args.print:
    print(digest)

  return 0


if __name__ == "__main__":
  raise SystemExit(main())