Added codec: esab46

Author: dhondta

README.md

@@ -363,6 +363,7 @@ This category also contains `ascii85`, `adobe`, `[x]btoa`, `zeromq` with the `ba
 - [X] `citrix`: aka Citrix CTX1 password encoding
 - [X] `columnar`: aka Columnar Transposition Cipher (keyword-ordered columns ; a second keyword gives the double transposition)
 - [X] `enigma`: aka Enigma machine (Enigma I, M3 and M4, with reflector, rotors, rings, positions and plugboard)
+- [X] `esab46`: aka ESAB-46 (Base64 with a shuffled alphabet, from online JavaScript tools)
 - [X] `foursquare`: aka Four-square Cipher (bigrams substituted with two keyed squares and two plain ones)
 - [X] `fractionated-morse`: aka Fractionated Morse Cipher (Morse code split into groups of three symbols, each replaced by a letter of a keyed alphabet)
 - [X] `gronsfeld`: aka Gronsfeld Cipher (variant of Vigenere Cipher with a numeric key)

docs/pages/enc/crypto.md

@@ -380,6 +380,23 @@ The settings are given with the codec name as `enigma-[reflector]-[rotors]-[ring
 
 -----
 
+### ESAB-46
+
+This toy cipher ("Base-64" reversed) comes from online JavaScript encryption tools. Like [ATOM-128](#atom-128), it is Base64 with a shuffled alphabet, whose 65th character (`/`) is used for padding, and the text is first escaped with JavaScript's `escape()`, then unescaped after decoding.
+
+**Codec** | **Conversions** | **Aliases** | **Comment**
+:---: | :---: | --- | ---
+`esab46` | text <-> ESAB-46 ciphertext | `esab-46`, `esb46`, `esb_46` | 
+
+```python
+>>> codext.encode("this is a test", "esab46")
+'9sRZ8i0ivsVj6z5gLy0iv4xV8nw/'
+>>> codext.decode("9sRZ8i0ivsVj6z5gLy0iv4xV8nw/", "esab-46")
+'this is a test'
+```
+
+-----
+
 ### Four-square Cipher
 
 The Four-square cipher, invented by Felix Delastelle, substitutes pairs of letters using four squares arranged in a 2x2 matrix: the upper-left and lower-right ones hold the alphabet in order, while the upper-right and lower-left ones are filled with two keywords. The first letter of each pair is located in the upper-left square and the second one in the lower-right square ; they are replaced by the letters at the other corners of the rectangle they form (in the upper-right square, then in the lower-left one).

src/codext/crypto/__init__.py

@@ -14,6 +14,7 @@
 from .citrix import *
 from .columnar import *
 from .enigma import *
+from .esab46 import *
 from .foursquare import *
 from .fractionatedmorse import *
 from .hill import *

src/codext/crypto/_jsbase64.py

@@ -0,0 +1,71 @@
+# -*- coding: UTF-8 -*-
+"""Base64 variants, shared by the toy ciphers of online JavaScript encryption tools (ATOM-128, ESAB-46).
+
+These ciphers are Base64 with a shuffled alphabet of 65 characters, whose last one is used for padding. As in the
+ original JavaScript, the text is first escaped with JavaScript's escape() (e.g. " " becoming "%20" and "é" becoming
+ "%E9"), and unescaped after decoding ; ciphertexts made without this escaping (i.e. from the UTF-8 bytes of the text)
+ are then decoded the same way.
+"""
+import builtins
+import re
+from base64 import b64decode, b64encode
+from binascii import Error as B64Error
+from string import ascii_letters, ascii_lowercase as LC, ascii_uppercase as UC, digits
+
+from ..__common__ import ensure_str, exc_name, handle_error
+
+
+B64 = UC + LC + digits + "+/="
+# characters left as is by JavaScript's escape()
+_SAFE = set(ascii_letters + digits + "@*_+-./")
+
+
+def js_escape(text):
+    """ Escape a string like JavaScript's escape() (characters beyond the BMP being escaped as surrogate pairs). """
+    r = ""
+    for c in text:
+        if c in _SAFE:
+            r += c
+        elif ord(c) < 256:
+            r += f"%{ord(c):02X}"
+        else:
+            u = c.encode("utf-16-be", "surrogatepass")
+            r += "".join(f"%u{u[i:i+2].hex().upper()}" for i in range(0, len(u), 2))
+    return r
+
+
+def js_unescape(text):
+    """ Unescape a string like JavaScript's unescape() (surrogate pairs being joined). """
+    s = re.sub(r"%u([0-9a-fA-F]{4})|%([0-9a-fA-F]{2})", lambda m: chr(int(m.group(1) or m.group(2), 16)), text)
+    return s.encode("utf-16-be", "surrogatepass").decode("utf-16-be", "replace")
+
+
+def js_base64(name, alphabet):
+    """ Make the encoding and decoding functions of a Base64 variant, given its alphabet (with the padding character
+         last). """
+    enc_map = str.maketrans(B64, alphabet)
+
+    def encode(text, errors="strict"):
+        return b64encode(js_escape(ensure_str(text)).encode()).decode().translate(enc_map), len(text)
+
+    def decode(text, errors="strict"):
+        _h, t, r = handle_error(name, errors, decode=True), re.sub(r"\s", "", ensure_str(text)), ""
+        for i, c in enumerate(t):
+            if c in alphabet:
+                r += B64[alphabet.index(c)]
+            else:
+                # invalid characters are dropped (as the original JavaScript does) when not in strict mode
+                _h(c, i)
+        try:
+            r = b64decode(r, validate=True)
+        except B64Error:
+            if errors == "strict":
+                raise getattr(builtins, f"{exc_name(name)}DecodeError")(f"'{name}' codec can't decode: incorrect "
+                                                                         "padding")
+            # otherwise, the padding is fixed, dropping an incomplete last character
+            r = r.replace("=", "")
+            r = r[:len(r) - (len(r) % 4 == 1)]
+            r = b64decode(r + "=" * (-len(r) % 4))
+        return js_unescape(r.decode("latin-1")), len(text)
+
+    return encode, decode

src/codext/crypto/atom128.py

@@ -14,12 +14,8 @@
 
 Reference: https://github.com/gungunfebrianza/Mastering-Cryptography/blob/master/ATOM-128/ATOM-128.js
 """
-import re
-from base64 import b64decode, b64encode
-from binascii import Error as B64Error
-from string import ascii_letters, ascii_lowercase as LC, ascii_uppercase as UC, digits
-
-from ..__common__ import *
+from ._jsbase64 import js_base64
+from ..__common__ import add
 
 
 __examples__ = {
@@ -30,55 +26,5 @@
 __guess__ = ["atom128"]
 
 
-B64 = UC + LC + digits + "+/="
-ATOM128 = "/128GhIoPQROSTeUbADfgHijKLM+n0pFWXY456xyzB7=39VaqrstJklmNuZvwcdEC"
-# characters left as is by JavaScript's escape()
-_SAFE = set(ascii_letters + digits + "@*_+-./")
-
-
-def js_escape(text):
-    """ Escape a string like JavaScript's escape() (characters beyond the BMP being escaped as surrogate pairs). """
-    r = ""
-    for c in text:
-        if c in _SAFE:
-            r += c
-        elif ord(c) < 256:
-            r += f"%{ord(c):02X}"
-        else:
-            u = c.encode("utf-16-be", "surrogatepass")
-            r += "".join(f"%u{u[i:i+2].hex().upper()}" for i in range(0, len(u), 2))
-    return r
-
-
-def js_unescape(text):
-    """ Unescape a string like JavaScript's unescape() (surrogate pairs being joined). """
-    s = re.sub(r"%u([0-9a-fA-F]{4})|%([0-9a-fA-F]{2})", lambda m: chr(int(m.group(1) or m.group(2), 16)), text)
-    return s.encode("utf-16-be", "surrogatepass").decode("utf-16-be", "replace")
-
-
-def atom128_encode(text, errors="strict"):
-    r = b64encode(js_escape(ensure_str(text)).encode()).decode()
-    return r.translate(str.maketrans(B64, ATOM128)), len(text)
-
-
-def atom128_decode(text, errors="strict"):
-    _h, t, r = handle_error("atom128", errors, decode=True), re.sub(r"\s", "", ensure_str(text)), ""
-    for i, c in enumerate(t):
-        if c in ATOM128:
-            r += B64[ATOM128.index(c)]
-        else:
-            # invalid characters are dropped (as the original JavaScript does) when not in strict mode
-            _h(c, i)
-    try:
-        r = b64decode(r, validate=True)
-    except B64Error:
-        if errors == "strict":
-            raise Atom128DecodeError("'atom128' codec can't decode: incorrect padding")  # noqa: F821
-        # otherwise, the padding is fixed, dropping an incomplete last character
-        r = r.replace("=", "")
-        r = r[:len(r) - (len(r) % 4 == 1)]
-        r = b64decode(r + "=" * (-len(r) % 4))
-    return js_unescape(r.decode("latin-1")), len(text)
-
-
-add("atom128", atom128_encode, atom128_decode, r"^atom[-_]?128$", printables_rate=1., expansion_factor=(1.6, .3))
+add("atom128", *js_base64("atom128", "/128GhIoPQROSTeUbADfgHijKLM+n0pFWXY456xyzB7=39VaqrstJklmNuZvwcdEC"),
+    r"^atom[-_]?128$", printables_rate=1., expansion_factor=(1.6, .3))

src/codext/crypto/esab46.py

@@ -0,0 +1,30 @@
+# -*- coding: UTF-8 -*-
+"""ESAB-46 Codec - ESAB-46 content encoding.
+
+ESAB-46 ("Base-64" reversed) is a toy cipher found on online JavaScript encryption tools. It is Base64 with a shuffled
+ alphabet, whose 65th character ("/") is used for padding. As in the original JavaScript, the text is first escaped with
+ JavaScript's escape() (e.g. " " becoming "%20" and "é" becoming "%E9"), and unescaped after decoding ; ciphertexts made
+ without this escaping (i.e. from the UTF-8 bytes of the text) are then decoded the same way.
+
+This codec:
+- en/decodes strings from str to str
+- en/decodes strings from bytes to bytes
+- decodes file content to str (read)
+- encodes file content from str to bytes (write)
+
+Reference: https://crypo.tonylao.com/esab46c.htm
+"""
+from ._jsbase64 import js_base64
+from ..__common__ import add
+
+
+__examples__ = {
+    'enc(esab46|esab-46|esb46|esb_46)': {'this is a test': "9sRZ8i0ivsVj6z5gLy0iv4xV8nw/", 'test': "9s1j9A//", '': ""},
+    'dec(esab46)': {'9s1j9A//': "test", '9s1j 9A//': "test", '9s1j9A/': None, '9s1j9A/%': None},
+    'enc-dec(esab46)': ["this is a test", "Hello, World! 1234", "\xe9t\xe9 ☃ \U0001F600", "100% sure", "a"],
+}
+__guess__ = ["esab46"]
+
+
+add("esab46", *js_base64("esab46", "ABCDqrs456tuvNOPwxyz012KLM3789=+QRSTUVWXYZabcdefghijklmnopEFGHIJ/"),
+    r"^esa?b[-_]?46$", printables_rate=1., expansion_factor=(1.6, .3))