Steam TOTP (#142)

A new class is added in a `pyotp.contrib.steam` submodule. It's a
subclass of `pyotp.TOTP` and overrides the `generate_otp` method. (all
as mentioned in the issue
[here](pyauth/pyotp#127 (comment)))

Also added some tests and included the new class in the API
Documentation section.

Co-authored-by: Andrey Kislyuk <kislyuk@gmail.com>

docs/index.rst

@@ -15,6 +15,9 @@ API documentation
 .. automodule:: pyotp.utils
    :members:
 
+.. automodule:: pyotp.contrib.steam
+   :members:
+
 
 Table of Contents
 =================

setup.py

@@ -13,7 +13,7 @@
     long_description=open("README.rst").read(),
     python_requires=">=3.6",
     install_requires=[],
-    packages=["pyotp"],
+    packages=["pyotp", "pyotp.contrib"],
     package_dir={"": "src"},
     package_data={"pyotp": ["py.typed"]},
     platforms=["MacOS X", "Posix"],

src/pyotp/__init__.py

@@ -3,6 +3,7 @@
 from typing import Any, Dict, Sequence
 from urllib.parse import unquote, urlparse, parse_qsl
 
+from . import contrib  # noqa:F401
 from .compat import random
 from .hotp import HOTP as HOTP
 from .otp import OTP as OTP

src/pyotp/contrib/__init__.py

@@ -0,0 +1 @@
+from .steam import Steam  # noqa:F401

src/pyotp/contrib/steam.py

@@ -0,0 +1,43 @@
+from typing import Optional
+import hashlib
+
+from ..totp import TOTP
+
+STEAM_CHARS = "23456789BCDFGHJKMNPQRTVWXY"  # steam's custom alphabet
+STEAM_DEFAULT_DIGITS = 5  # Steam TOTP code length
+
+
+class Steam(TOTP):
+    """
+    Steam's custom TOTP. Subclass of `pyotp.totp.TOTP`.
+    """
+
+    def __init__(self, s: str, name: Optional[str] = None,
+                 issuer: Optional[str] = None, interval: int = 30) -> None:
+        """
+        :param s: secret in base32 format
+        :param interval: the time interval in seconds for OTP. This defaults to 30.
+        :param name: account name
+        :param issuer: issuer
+        """
+        self.interval = interval
+        super().__init__(s=s, digits=10, digest=hashlib.sha1, name=name, issuer=issuer)
+
+    def generate_otp(self, input: int) -> str:
+        """
+        :param input: the HMAC counter value to use as the OTP input.
+            Usually either the counter, or the computed integer based on the Unix timestamp
+        """
+        str_code = super().generate_otp(input)
+        int_code = int(str_code)
+
+        steam_code = ""
+        total_chars = len(STEAM_CHARS)
+
+        for _ in range(STEAM_DEFAULT_DIGITS):
+            pos = int_code % total_chars
+            char = STEAM_CHARS[int(pos)]
+            steam_code += char
+            int_code //= total_chars
+
+        return steam_code

test.py

@@ -306,6 +306,47 @@ def test_random_key_generation(self):
             pyotp.random_hex(length=39)
 
 
+class SteamTOTP(unittest.TestCase):
+    def test_match_examples(self):
+        steam = pyotp.contrib.Steam("BASE32SECRET3232")
+
+        self.assertEqual(steam.at(0), "2TC8B")
+        self.assertEqual(steam.at(30), "YKKK4")
+        self.assertEqual(steam.at(60), "M4HQB")
+        self.assertEqual(steam.at(90), "DTVB3")
+
+
+        steam = pyotp.contrib.Steam("FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW")
+
+        self.assertEqual(steam.at(0), "C5V56")
+        self.assertEqual(steam.at(30), "QJY8Y")
+        self.assertEqual(steam.at(60), "R3WQY")
+        self.assertEqual(steam.at(90), "JG3T3")
+
+    def test_verify(self):
+        steam = pyotp.contrib.Steam("BASE32SECRET3232")
+        with Timecop(1662883100):
+            self.assertTrue(steam.verify('N3G63'))
+        with Timecop(1662883100 + 30):
+            self.assertFalse(steam.verify('N3G63'))
+
+        with Timecop(946681223):
+            self.assertTrue(steam.verify('7VP3X'))
+        with Timecop(946681223 + 30):
+            self.assertFalse(steam.verify('7VP3X'))
+
+        steam = pyotp.contrib.Steam("FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW")
+        with Timecop(1662884261):
+            self.assertTrue(steam.verify('V6WKJ'))
+        with Timecop(1662884261 + 30):
+            self.assertFalse(steam.verify('V6WKJ'))
+
+        with Timecop(946681223):
+            self.assertTrue(steam.verify('4MK54'))
+        with Timecop(946681223 + 30):
+            self.assertFalse(steam.verify('4MK54'))
+
+
 class CompareDigestTest(unittest.TestCase):
     method = staticmethod(pyotp.utils.compare_digest)