gdformat 0.1.0__py3-none-any.whl

gdformat/__init__.py

@@ -0,0 +1,12 @@
+from . import codes
+from . import crypto
+from . import encoding
+from . import enums
+from . import objects
+from . import requests
+from . import responses
+from ._common import Form
+from ._common import ParseError
+from ._common import ParseResult
+from ._common import is_error
+from ._common import is_success

gdformat/_common.py

@@ -0,0 +1,24 @@
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import TypeIs
+
+type Form = Mapping[str, str]
+
+
+class ParseError(StrEnum):
+    MISSING = "missing"
+    INVALID_INTEGER = "invalid_integer"
+    INVALID_VALUE = "invalid_value"
+    INVALID_BASE64 = "invalid_base64"
+    INVALID_LAYOUT = "invalid_layout"
+
+
+type ParseResult[T] = T | ParseError
+
+
+def is_error[T](value: ParseResult[T]) -> TypeIs[ParseError]:
+    return isinstance(value, ParseError)
+
+
+def is_success[T](value: ParseResult[T]) -> TypeIs[T]:
+    return not isinstance(value, ParseError)

gdformat/_wire.py

@@ -0,0 +1,190 @@
+from collections.abc import Mapping
+from enum import IntEnum
+from enum import StrEnum
+
+from gdformat._common import ParseError
+from gdformat._common import ParseResult
+from gdformat.encoding import decode_text
+
+
+def pairs(text: str, separator: str) -> dict[str, str] | None:
+    parts = text.split(separator)
+
+    if len(parts) % 2:
+        return None
+
+    return dict(zip(parts[::2], parts[1::2], strict=True))
+
+
+def split_nonempty(text: str, separator: str) -> list[str]:
+    return [part for part in text.split(separator) if part]
+
+
+class Reader:
+    """Reads typed values out of a string mapping, remembering the first failure.
+    Failed reads return a placeholder so callers can build the whole model in one
+    expression and then check `done`."""
+
+    __slots__ = ("_values", "error")  # One instance per parsed request or object.
+
+    def __init__(self, values: Mapping[str, str]) -> None:
+        self._values = values
+        self.error: ParseError | None = None
+
+    def _fail(self, error: ParseError) -> None:
+        if self.error is None:
+            self.error = error
+
+    def _to_int(self, value: str) -> int:
+        try:
+            return int(value)
+        except ValueError:
+            self._fail(ParseError.INVALID_INTEGER)
+
+            return 0
+
+    def has(self, key: str) -> bool:
+        return bool(self._values.get(key))
+
+    def string(self, key: str, *, default: str | None = None) -> str:
+        value = self._values.get(key)
+
+        if value is not None:
+            return value
+
+        if default is None:
+            self._fail(ParseError.MISSING)
+
+            return ""
+
+        return default
+
+    def integer(self, key: str, *, default: int | None = None) -> int:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return 0
+
+            return default
+
+        return self._to_int(value)
+
+    def optional_integer(self, key: str) -> int | None:
+        value = self._values.get(key)
+
+        if not value:
+            return None
+
+        return self._to_int(value)
+
+    def boolean(self, key: str, *, default: bool = False) -> bool:
+        value = self._values.get(key)
+
+        if not value:
+            return default
+
+        return value == "1"
+
+    def member[E: IntEnum](
+        self, key: str, kind: type[E], *, default: E | None = None
+    ) -> E:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return next(iter(kind))
+
+            return default
+
+        return self._to_member(value, kind)
+
+    def optional_member[E: IntEnum](self, key: str, kind: type[E]) -> E | None:
+        value = self._values.get(key)
+
+        if not value:
+            return None
+
+        return self._to_member(value, kind)
+
+    def _to_member[E: IntEnum](self, value: str, kind: type[E]) -> E:
+        number = self._to_int(value)
+
+        try:
+            return kind(number)
+        except ValueError:
+            self._fail(ParseError.INVALID_VALUE)
+
+            return next(iter(kind))
+
+    def choice[E: StrEnum](
+        self, key: str, kind: type[E], *, default: E | None = None
+    ) -> E:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return next(iter(kind))
+
+            return default
+
+        try:
+            return kind(value)
+        except ValueError:
+            self._fail(ParseError.INVALID_VALUE)
+
+            return next(iter(kind))
+
+    def text(self, key: str, *, default: str | None = None) -> str:
+        value = self._values.get(key)
+
+        if not value:
+            if default is None:
+                self._fail(ParseError.MISSING)
+                return ""
+
+            return default
+
+        decoded = decode_text(value)
+
+        if decoded is None:
+            self._fail(ParseError.INVALID_BASE64)
+
+            return ""
+
+        return decoded
+
+    def integers(self, key: str, *, separator: str = ",") -> tuple[int, ...]:
+        value = self._values.get(key)
+
+        if not value or value == "-":
+            return ()
+
+        return tuple(
+            self._to_int(part) for part in value.strip("()").split(separator) if part
+        )
+
+    def members[E: IntEnum](
+        self,
+        key: str,
+        kind: type[E],
+        *,
+        separator: str = ",",
+    ) -> tuple[E, ...]:
+        value = self._values.get(key)
+
+        if not value or value == "-":
+            return ()
+
+        return tuple(
+            self._to_member(part, kind) for part in value.split(separator) if part
+        )
+
+    def done[T](self, value: T) -> ParseResult[T]:
+        if self.error is not None:
+            return self.error
+
+        return value

gdformat/codes.py

@@ -0,0 +1,59 @@
+from enum import IntEnum
+
+SUCCESS = "1"
+FAILURE = "-1"
+
+
+class LoginError(IntEnum):
+    GENERIC = -1
+    PASSWORD_TOO_SHORT = -8
+    NAME_TOO_SHORT = -9
+    LINKED_TO_OTHER_ACCOUNT = -10
+    WRONG_CREDENTIALS = -11
+    ACCOUNT_DISABLED = -12
+    LINKED_TO_OTHER_STEAM = -13
+
+
+class RegisterError(IntEnum):
+    GENERIC = -1
+    NAME_TAKEN = -2
+    EMAIL_TAKEN = -3
+    NAME_INVALID = -4
+    PASSWORD_INVALID = -5
+    EMAIL_INVALID = -6
+    PASSWORD_TOO_SHORT = -8
+    NAME_TOO_SHORT = -9
+
+
+class SaveError(IntEnum):
+    GENERIC = -1
+    LOGIN_FAILED = -2
+    GENERIC_VISIBLE = -3
+    TOO_LARGE = -4
+    BAD_LOGIN = -5
+    SERVER_ERROR = -6
+
+
+class SongError(IntEnum):
+    NOT_FOUND = -1
+    NOT_ALLOWED = -2
+
+
+class CommentError(IntEnum):
+    REJECTED = -1
+    NONE_FOUND = -2
+    PERMANENT_BAN = -10
+
+
+class ListUploadError(IntEnum):
+    REJECTED = -1
+    BAD_SEED = -10
+
+
+class ModeratorError(IntEnum):
+    REJECTED = -1
+    NOT_MODERATOR = -2
+
+
+def serialise_code(code: int) -> str:
+    return str(int(code))

gdformat/crypto.py

@@ -0,0 +1,296 @@
+import hashlib
+from collections.abc import Iterable
+
+from gdformat.encoding import cyclic_xor
+from gdformat.encoding import decode_base64
+from gdformat.encoding import encode_base64
+from gdformat.encoding import encode_xor_text
+
+KEY_MESSAGE = b"14251"
+KEY_VAULT = b"19283"
+KEY_CHALLENGES = b"19847"
+KEY_LEVEL_PASSWORD = b"26364"
+KEY_COMMENT = b"29481"
+KEY_ACCOUNT_PASSWORD = b"37526"
+KEY_LEVEL_LEADERBOARD = b"39673"
+KEY_LEVEL = b"41274"
+KEY_LOAD = b"48291"
+KEY_LIBRARY = b"57709"
+KEY_RATING = b"58281"
+KEY_CHESTS = b"59182"
+KEY_STATS = b"85271"
+
+SALT_LEVEL = "xI25fpAapCQg"
+SALT_COMMENT = "xPT6iUrtws0J"
+SALT_LIKE = "ysg6pUrtjn0J"
+SALT_PROFILE = "xI35fsAapCRg"
+SALT_LEVEL_LEADERBOARD = "yPg6pUrtWn0J"
+SALT_VAULT = "ask2fpcaqCQ2"
+SALT_CHALLENGES = "oC36fpYaPtdg"
+SALT_REWARDS = "pC26fpYaQCtg"
+SALT_GJP2 = "mI29fmAnxgTs"
+
+_SEED_SAMPLE_SIZE = 50
+_DOWNLOAD_SAMPLE_SIZE = 40
+
+
+def sha1_hex(text: str) -> str:
+    return hashlib.sha1(text.encode()).hexdigest()
+
+
+def gjp2(password: str) -> str:
+    return sha1_hex(password + SALT_GJP2)
+
+
+def chk(values: Iterable[object], key: bytes, salt: str) -> str:
+    joined = "".join(map(str, values)) + salt
+
+    return encode_base64(cyclic_xor(sha1_hex(joined).encode(), key))
+
+
+def sample(data: str, count: int) -> str:
+    if len(data) < count:
+        return data
+
+    return data[:: len(data) // count][:count]
+
+
+def comment_chk(
+    username: str,
+    content: str,
+    level_id: int,
+    percent: int,
+    comment_type: int,
+) -> str:
+    """`content` is the URL-safe base64 form of the comment, as sent on the wire."""
+
+    return chk(
+        (username, content, level_id, percent, comment_type), KEY_COMMENT, SALT_COMMENT
+    )
+
+
+def like_chk(
+    special: int,
+    item_id: int,
+    like: bool,
+    like_type: int,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    return chk(
+        (special, item_id, int(like), like_type, rs, account_id, udid, user_id),
+        KEY_RATING,
+        SALT_LIKE,
+    )
+
+
+def rate_chk(
+    level_id: int,
+    stars: int,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    return chk((level_id, stars, rs, account_id, udid, user_id), KEY_RATING, SALT_LIKE)
+
+
+def download_chk(
+    level_id: int,
+    increment: bool,
+    rs: str,
+    account_id: int,
+    udid: str,
+    user_id: int,
+) -> str:
+    # NOTE: The documentation lists no salt for this value; this follows it as written.
+    return chk((level_id, int(increment), rs, account_id, udid, user_id), KEY_LEVEL, "")
+
+
+def profile_chk(values: Iterable[object]) -> str:
+    return chk(values, KEY_STATS, SALT_PROFILE)
+
+
+def level_leaderboard_chk(values: Iterable[object], rs: str) -> str:
+    return chk((*values, SALT_LEVEL_LEADERBOARD, rs), KEY_LEVEL_LEADERBOARD, "")
+
+
+def level_seed(level_string: str) -> str:
+    """The `seed2` parameter of a level upload."""
+
+    sampled = sample(level_string, _SEED_SAMPLE_SIZE)
+
+    return encode_base64(cyclic_xor(sha1_hex(sampled + SALT_LEVEL).encode(), KEY_LEVEL))
+
+
+def list_seed(level_ids: str, account_id: int, seed2: str) -> str:
+    """The `seed` parameter of a list upload; `seed2` is the random key it was
+    encrypted with."""
+
+    sampled = sample(level_ids, _SEED_SAMPLE_SIZE)
+    digest = sha1_hex(f"{sampled}{account_id}")
+
+    return encode_base64(cyclic_xor(digest.encode(), seed2.encode()))
+
+
+def level_download_hash(level_string: str) -> str:
+    if len(level_string) <= _DOWNLOAD_SAMPLE_SIZE:
+        return sha1_hex(level_string + SALT_LEVEL)
+
+    step = len(level_string) // _DOWNLOAD_SAMPLE_SIZE
+
+    sampled = "".join(
+        level_string[index * step] for index in range(_DOWNLOAD_SAMPLE_SIZE)
+    )
+
+    return sha1_hex(sampled + SALT_LEVEL)
+
+
+def level_metadata_hash(
+    creator_id: int,
+    stars: int,
+    is_demon: bool,
+    level_id: int,
+    verified_coins: bool,
+    feature_score: int,
+    password: int,
+    timely_id: int,
+) -> str:
+    joined = (
+        f"{creator_id},{stars},{is_demon:d},{level_id},{verified_coins:d},"
+        f"{feature_score},{password},{timely_id}"
+    )
+
+    return sha1_hex(joined + SALT_LEVEL)
+
+
+def level_search_hash(levels: Iterable[tuple[int, int, bool]]) -> str:
+    """`levels` yields `(level_id, stars, verified_coins)` per level, in order."""
+
+    parts = []
+
+    for level_id, stars, verified_coins in levels:
+        digits = str(level_id)
+        parts.append(f"{digits[0]}{digits[-1]}{stars}{verified_coins:d}")
+
+    return sha1_hex("".join(parts) + SALT_LEVEL)
+
+
+def map_pack_hash(packs: Iterable[tuple[int, int, int]]) -> str:
+    """`packs` yields `(pack_id, stars, coins)` per pack, in order."""
+
+    parts = []
+
+    for pack_id, stars, coins in packs:
+        digits = str(pack_id)
+        parts.append(f"{digits[0]}{digits[-1]}{stars}{coins}")
+
+    return sha1_hex("".join(parts) + SALT_LEVEL)
+
+
+def gauntlet_hash(gauntlets: Iterable[tuple[int, str]]) -> str:
+    """`gauntlets` yields `(gauntlet_id, comma_separated_level_ids)`, in order."""
+
+    joined = "".join(
+        f"{gauntlet_id}{level_ids}" for gauntlet_id, level_ids in gauntlets
+    )
+
+    return sha1_hex(joined + SALT_LEVEL)
+
+
+def challenges_hash(blob: str) -> str:
+    return sha1_hex(blob + SALT_CHALLENGES)
+
+
+def rewards_hash(blob: str) -> str:
+    return sha1_hex(blob + SALT_REWARDS)
+
+
+LEVEL_LIST_HASH = sha1_hex(SALT_LEVEL)
+
+
+def level_password_wire(password: str | None) -> str:
+    """The plain-text form of a copy password: `0` no copy, `1` free copy, else
+    `1` followed by the digits."""
+
+    if password is None:
+        return "0"
+
+    return f"1{password}"
+
+
+def level_password_from_wire(wire: str) -> str | None:
+    if wire in ("", "0"):
+        return None
+
+    return wire[1:]
+
+
+def level_password_number(password: str | None) -> int:
+    """The numeric form used by the download hash: the plain wire value as an
+    integer. Verified against the official server for 4 and 6 digit passwords;
+    the documented 1,000,000 normalisation is not applied there."""
+
+    return int(level_password_wire(password))
+
+
+def encode_level_password(password: str | None) -> str:
+    if password is None:
+        return "0"
+
+    return encode_xor_text(level_password_wire(password), KEY_LEVEL_PASSWORD)
+
+
+def decode_level_password(encoded: str) -> str | None:
+    if encoded in ("", "0"):
+        return None
+
+    raw = decode_base64(encoded)
+
+    if raw is None:
+        return None
+
+    return level_password_from_wire(
+        cyclic_xor(raw, KEY_LEVEL_PASSWORD).decode("ascii", "replace")
+    )
+
+
+def decode_reward_chk(value: str, key: bytes) -> int | None:
+    """Recovers the client's challenge number from a rewards `chk` parameter."""
+
+    raw = decode_base64(value[5:])
+
+    if raw is None:
+        return None
+
+    number = cyclic_xor(raw, key).decode("ascii", "replace")
+
+    if not number.isdecimal():
+        return None
+
+    return int(number)
+
+
+def encode_reward_blob(plaintext: str, key: bytes) -> str:
+    return encode_base64(cyclic_xor(plaintext.encode(), key))
+
+
+def classic_leaderboard_seed(clicks: int, percentage: int, seconds: int) -> int:
+    return (
+        1482 * 2
+        + (clicks + 3991) * (percentage + 8354)
+        + (seconds + 4085) ** 2
+        - 50028039
+    )
+
+
+def platformer_leaderboard_hash(best_time: int, best_points: int) -> int:
+    number = (
+        ((best_time + 7890) % 34567) * 601
+        + ((abs(best_points) + 3456) % 78901) * 967
+        + 94819
+    ) % 94433
+
+    return ((number ^ (number >> 16)) * 829) % 77849

gdformat/encoding.py

@@ -0,0 +1,122 @@
+import base64
+import binascii
+import gzip
+import random
+import string
+import urllib.parse
+import zlib
+
+_ALPHABET = string.ascii_letters + string.digits
+_SEPARATOR_TABLE = str.maketrans("", "", ":|#~")
+_AGE_UNITS = (
+    (31_536_000, "year"),
+    (2_592_000, "month"),
+    (604_800, "week"),
+    (86_400, "day"),
+    (3_600, "hour"),
+    (60, "minute"),
+    (1, "second"),
+)
+
+
+def cyclic_xor(data: bytes, key: bytes) -> bytes:
+    length = len(data)
+
+    if length == 0:
+        return b""
+
+    repeated = (key * (length // len(key) + 1))[:length]
+    mixed = int.from_bytes(data, "big") ^ int.from_bytes(repeated, "big")
+
+    return mixed.to_bytes(length, "big")
+
+
+def encode_base64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii")
+
+
+def decode_base64(text: str) -> bytes | None:
+    padded = text + "=" * (-len(text) % 4)
+
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except binascii.Error:
+        return None
+
+
+def encode_text(text: str) -> str:
+    return encode_base64(text.encode())
+
+
+def decode_text(text: str) -> str | None:
+    raw = decode_base64(text)
+
+    if raw is None:
+        return None
+
+    return raw.decode("utf-8", "replace")
+
+
+def encode_xor_text(text: str, key: bytes) -> str:
+    return encode_base64(cyclic_xor(text.encode(), key))
+
+
+def decode_xor_text(text: str, key: bytes) -> str | None:
+    raw = decode_base64(text)
+
+    if raw is None:
+        return None
+
+    return cyclic_xor(raw, key).decode("utf-8", "replace")
+
+
+def compress_level(level: str) -> str:
+    return encode_base64(gzip.compress(level.encode(), mtime=0))
+
+
+def decompress_level(data: str) -> str | None:
+    raw = decode_base64(data)
+
+    if raw is None:
+        return None
+
+    try:
+        return zlib.decompress(raw, 15 | 32).decode("utf-8", "replace")
+    except zlib.error:
+        return None
+
+
+def deflate_base64(text: str) -> str:
+    return encode_base64(zlib.compress(text.encode()))
+
+
+def quote_url(url: str) -> str:
+    return urllib.parse.quote(url, safe="")
+
+
+def unquote_url(url: str) -> str:
+    return urllib.parse.unquote(url)
+
+
+def random_string(length: int) -> str:
+    return "".join(random.choices(_ALPHABET, k=length))
+
+
+def strip_separators(text: str) -> str:
+    return text.translate(_SEPARATOR_TABLE)
+
+
+def describe_age(seconds: int) -> str:
+    """Formats a duration the way the official servers do: `3 months`, `1 second`."""
+
+    elapsed = max(seconds, 1)
+
+    for unit, name in _AGE_UNITS:
+        if elapsed < unit:
+            continue
+
+        count = elapsed // unit
+
+        return f"{count} {name}" if count == 1 else f"{count} {name}s"
+
+    return "1 second"