installer v1 (A+B): install-code enrollment, panel code UI, EXE publish; DPAPI credential store

central/app/enrollment.py

@@ -36,6 +36,58 @@ def new_token() -> str:
     return secrets.token_urlsafe(32)
 
 
+# ---- installation code (XXXX-XXXX-XXXX-XXXX) ----
+#
+# A 16-character Crockford Base32 code = 16 * 5 = 80 bits of entropy. The
+# alphabet deliberately excludes I/L/O/U (ambiguous when retyped by a human);
+# the same alphabet is used so a code cannot contain those letters.
+
+INSTALL_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_INSTALL_CODE_GROUPS = 4
+_INSTALL_CODE_PER_GROUP = 4
+_INSTALL_CODE_LENGTH = _INSTALL_CODE_GROUPS * _INSTALL_CODE_PER_GROUP
+# Crockford transliteration for input normalization: O -> 0, I/L -> 1.
+_INSTALL_CODE_TRANSLIT = str.maketrans({"O": "0", "I": "1", "L": "1"})
+_INSTALL_CODE_RE = re.compile(
+    r"^[" + re.escape(INSTALL_CODE_ALPHABET) + r"]{" + str(_INSTALL_CODE_LENGTH) + r"}$"
+)
+
+
+def generate_install_code() -> str:
+    """Return a fresh installation code formatted XXXX-XXXX-XXXX-XXXX."""
+    chars = "".join(secrets.choice(INSTALL_CODE_ALPHABET) for _ in range(_INSTALL_CODE_LENGTH))
+    return "-".join(
+        chars[i : i + _INSTALL_CODE_PER_GROUP] for i in range(0, _INSTALL_CODE_LENGTH, _INSTALL_CODE_PER_GROUP)
+    )
+
+
+def normalize_install_code(text: str | None) -> str:
+    """Upper-case, drop hyphen/space separators and map Crockford lookalikes,
+    so a human-typed code normalizes to the same digest regardless of how it
+    was entered. Raises ValueError if the result isn't a valid code."""
+    if not text:
+        raise ValueError("empty install code")
+    clean = "".join(ch for ch in text.upper().translate(_INSTALL_CODE_TRANSLIT) if ch.isalnum())
+    if not _INSTALL_CODE_RE.match(clean):
+        raise ValueError(f"invalid install code: {text!r}")
+    return clean
+
+
+def install_code_digest(code: str) -> str:
+    """Hash a normalized install code. Only the hash is ever persisted; the
+    plaintext code exists only in the operator's clipboard/UI and the EXE's
+    memory for the brief instant it is sent to the Hub."""
+    return token_digest(normalize_install_code(code))
+
+
+def valid_install_code(text: str | None) -> bool:
+    try:
+        normalize_install_code(text)
+        return True
+    except ValueError:
+        return False
+
+
 def token_digest(token: str) -> str:
     return hashlib.sha256(token.encode()).hexdigest()