vault_login_classifier.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. """Login / checkout form control classifier for vault autofill.
  2. Python port (~170 LOC) of Merit-Systems/OpenInstinct's
  3. ``lib/manager/server/kernel-login-autofill.ts`` (MIT). Classifies visible
  4. input controls on a page into login-autofill tokens. The vault fill path
  5. uses the classification to select the single best current-password control
  6. (the identifier is agent-visible metadata and is typed by the agent
  7. itself via normal input tools).
  8. Scoring:
  9. - exact autocomplete-token match ................ 100
  10. - type=password (not new/confirm/create/repeat) .. 90
  11. - type=email / type=tel .......................... 85
  12. - label/name regex heuristics .................. 70-75
  13. Hard exclusions: autocomplete ``new-password`` / ``one-time-code``, and
  14. label/name text matching ``(new|confirm|create|repeat)\\s*password``.
  15. """
  16. from __future__ import annotations
  17. import json
  18. import re
  19. import unicodedata
  20. from dataclasses import dataclass
  21. from typing import Any, Dict, List, Optional
  22. import itertools
  23. LOGIN_AUTOFILL_TOKENS = ("username", "email", "tel", "current-password")
  24. # Payment / address autocomplete tokens (WHATWG) the checkout fill targets. ``cc-exp`` (combined
  25. # MM/YY) is derived at fill time from exp_month + exp_year. Field-name/label heuristics below back
  26. # up sites that omit autocomplete attributes.
  27. PAYMENT_AUTOFILL_TOKENS = ("cc-number", "cc-name", "cc-exp", "cc-exp-month", "cc-exp-year", "cc-csc")
  28. ADDRESS_AUTOFILL_TOKENS = ("address-line1", "address-line2", "address-level2", "address-level1",
  29. "postal-code", "country-name", "country")
  30. _CHECKOUT_HEURISTICS = (
  31. (re.compile(r"\b(?:card\s*number|cardnumber|ccnumber|cc\s*num|pan)\b"), "cc-number"),
  32. (re.compile(r"\b(?:name\s*on\s*card|cardholder|cc\s*name|ccname)\b"), "cc-name"),
  33. (re.compile(r"\b(?:cvc|cvv|csc|security\s*code|card\s*code)\b"), "cc-csc"),
  34. (re.compile(r"\b(?:exp(?:iry|iration)?\s*month|exp\s*mm|ccmonth)\b"), "cc-exp-month"),
  35. (re.compile(r"\b(?:exp(?:iry|iration)?\s*year|exp\s*yy(?:yy)?|ccyear)\b"), "cc-exp-year"),
  36. (re.compile(r"\b(?:exp(?:iry|iration)?(?:\s*date)?|mm\s*yy|valid\s*thru)\b"), "cc-exp"),
  37. (re.compile(r"\b(?:address\s*(?:line\s*)?2|apt|suite|unit)\b"), "address-line2"),
  38. (re.compile(r"\b(?:address(?:\s*line\s*1)?|street)\b"), "address-line1"),
  39. (re.compile(r"\b(?:city|town|locality)\b"), "address-level2"),
  40. (re.compile(r"\b(?:state|province|region|county)\b"), "address-level1"),
  41. (re.compile(r"\b(?:zip|postal|postcode)\b"), "postal-code"),
  42. (re.compile(r"\b(?:country)\b"), "country-name"),
  43. )
  44. _EXCLUDED_AUTOCOMPLETE = {"new-password", "one-time-code"}
  45. _RE_EXCLUDED_PASSWORD = re.compile(r"\b(?:new|confirm|create|repeat)\s*password\b")
  46. _RE_EMAIL = re.compile(r"\b(?:e[\s-]?mail|email address)\b")
  47. _RE_TEL = re.compile(r"\b(?:phone|telephone|mobile)\b")
  48. _RE_USERNAME = re.compile(
  49. r"\b(?:user\s*name|username|login|account|member|membership|mileageplus)\b"
  50. )
  51. def _normalize_text(value: str) -> str:
  52. value = unicodedata.normalize("NFKD", value).lower()
  53. return re.sub(r"[^a-z0-9]+", " ", value).strip()
  54. @dataclass(frozen=True)
  55. class LoginControl:
  56. """Descriptor of a visible input control, as inspected in the page."""
  57. autocomplete: str
  58. form_index: Optional[int]
  59. index: int
  60. label: str
  61. name: str
  62. type: str
  63. max_length: Optional[int] = None
  64. @classmethod
  65. def from_dict(cls, raw: dict[str, Any]) -> LoginControl:
  66. form_index = raw.get("formIndex", raw.get("form_index"))
  67. max_length = raw.get("maxLength", raw.get("max_length"))
  68. return cls(
  69. autocomplete=str(raw.get("autocomplete") or ""),
  70. form_index=int(form_index) if form_index is not None else None,
  71. index=int(raw.get("index") or 0),
  72. label=str(raw.get("label") or ""),
  73. name=str(raw.get("name") or ""),
  74. type=str(raw.get("type") or ""),
  75. max_length=int(max_length) if max_length is not None else None,
  76. )
  77. @dataclass(frozen=True)
  78. class ClassifiedLoginControl:
  79. control: LoginControl
  80. score: int
  81. token: str
  82. def classify_login_control(control: LoginControl) -> Optional[ClassifiedLoginControl]:
  83. """Classify one control, or return None if it is not a login fill target."""
  84. autocomplete_tokens = [
  85. t for t in control.autocomplete.lower().split() if t
  86. ]
  87. if any(t in _EXCLUDED_AUTOCOMPLETE for t in autocomplete_tokens):
  88. return None
  89. for token in LOGIN_AUTOFILL_TOKENS:
  90. if token in autocomplete_tokens:
  91. return ClassifiedLoginControl(control, 100, token)
  92. searchable = _normalize_text(
  93. " ".join(part for part in (control.name, control.label) if part)
  94. )
  95. if _RE_EXCLUDED_PASSWORD.search(searchable):
  96. return None
  97. if control.type == "password":
  98. return ClassifiedLoginControl(control, 90, "current-password")
  99. if control.type == "email":
  100. return ClassifiedLoginControl(control, 85, "email")
  101. if control.type == "tel":
  102. return ClassifiedLoginControl(control, 85, "tel")
  103. if _RE_EMAIL.search(searchable):
  104. return ClassifiedLoginControl(control, 75, "email")
  105. if _RE_TEL.search(searchable):
  106. return ClassifiedLoginControl(control, 75, "tel")
  107. if _RE_USERNAME.search(searchable):
  108. return ClassifiedLoginControl(control, 70, "username")
  109. return None
  110. _RE_OTP = re.compile(
  111. r"\b(?:one[\s-]?time|verification|security|auth(?:entication|enticator)?|2fa|two[\s-]?factor|mfa|totp|otp|"
  112. r"passcode|sms)\b.*\b(?:code|pin|token)\b|\b(?:otp|totp|2fa|mfa|verification\s*code|passcode)\b"
  113. )
  114. def classify_otp_controls(controls: list[LoginControl]) -> list[ClassifiedLoginControl]:
  115. """The controls that take a second-factor code. ``autocomplete=one-time-code`` is authoritative;
  116. otherwise a text/tel/number input whose name/label says code/OTP/2FA/verification. Some sites split
  117. the code into one input per digit (``maxlength=1`` boxes): they are returned in DOM order and the
  118. fill spreads the code across them."""
  119. out: list[ClassifiedLoginControl] = []
  120. for c in controls:
  121. tokens = c.autocomplete.lower().split()
  122. if "one-time-code" in tokens:
  123. out.append(ClassifiedLoginControl(c, 100, "one-time-code"))
  124. continue
  125. if c.type not in ("text", "tel", "number", "password", ""):
  126. continue
  127. if _RE_OTP.search(_normalize_text(" ".join(p for p in (c.name, c.label) if p))):
  128. out.append(ClassifiedLoginControl(c, 70, "one-time-code"))
  129. return out
  130. def select_password_fill(
  131. classified: list[ClassifiedLoginControl],
  132. password: str,
  133. ) -> list[dict[str, Any]]:
  134. """Select the single best current-password control to fill.
  135. The vault fill path is password-only: the identifier is agent-visible
  136. metadata and is typed by the agent via normal input tools. This picks
  137. the highest-scoring ``current-password`` control (ties broken by DOM
  138. order) and returns ``[{"index": int, "token": "current-password",
  139. "value": password}]`` or ``[]`` when no password field exists.
  140. """
  141. passwords = [c for c in classified if c.token == "current-password"]
  142. if not passwords or not password:
  143. return []
  144. best_password = min(passwords, key=lambda c: (-c.score, c.control.index))
  145. return [
  146. {
  147. "index": best_password.control.index,
  148. "token": "current-password",
  149. "value": password,
  150. }
  151. ]
  152. def classify_checkout_control(control: LoginControl) -> Optional[ClassifiedLoginControl]:
  153. """Classify one control as a payment/address fill target (autocomplete token exact match 100,
  154. label/name heuristic 70), or None. Password/email inputs are never checkout targets."""
  155. tokens = [t for t in control.autocomplete.lower().split() if t]
  156. for token in PAYMENT_AUTOFILL_TOKENS + ADDRESS_AUTOFILL_TOKENS:
  157. if token in tokens:
  158. return ClassifiedLoginControl(control, 100, "country-name" if token == "country" else token)
  159. if control.type in ("password", "email"):
  160. return None
  161. searchable = _normalize_text(" ".join(part for part in (control.name, control.label) if part))
  162. for pattern, token in _CHECKOUT_HEURISTICS:
  163. if pattern.search(searchable):
  164. return ClassifiedLoginControl(control, 70, token)
  165. return None
  166. def select_checkout_fills(classified: list[ClassifiedLoginControl], secret: dict[str, str],
  167. field_tokens: dict[str, str]) -> list[dict[str, Any]]:
  168. """Map a payment/address secret payload onto the best control per autocomplete token.
  169. ``field_tokens`` is ``PAYMENT_FIELDS`` / ``ADDRESS_FIELDS`` (agent/vault_store.py). A combined
  170. ``cc-exp`` control gets ``MM/YY`` from exp_month + exp_year and then suppresses the separate
  171. month/year fills. Returns ``[{"index", "token", "value"}]``: one control per token, highest
  172. score then DOM order.
  173. """
  174. values: dict[str, str] = {tok: secret[f] for f, tok in field_tokens.items() if secret.get(f)}
  175. if "cc-exp-month" in values and "cc-exp-year" in values:
  176. values["cc-exp"] = f"{values['cc-exp-month'].zfill(2)}/{values['cc-exp-year'][-2:]}"
  177. fills: list[dict[str, Any]] = []
  178. for token, value in values.items():
  179. candidates = sorted((c for c in classified if c.token == token), key=lambda c: (-c.score, c.control.index))
  180. if candidates:
  181. fills.append({"index": candidates[0].control.index, "token": token, "value": value})
  182. if any(f["token"] == "cc-exp" for f in fills):
  183. fills = [f for f in fills if f["token"] not in ("cc-exp-month", "cc-exp-year")]
  184. return fills
  185. # JS expression evaluated in the page to inspect candidate input controls.
  186. # Ported from OpenInstinct's nativeLoginControlInspectionExpression.
  187. # Inspection stamps every input with ``<nonce>:<index>`` under a per-inspection attribute; the fill
  188. # script resolves targets by the stamp of ITS OWN inspection instead of re-querying by position, so
  189. # neither a DOM reflow nor a second inspection in between can redirect the password into another field.
  190. INSPECTION_STAMP_ATTR = "data-hermes-vault-slot"
  191. def build_otp_fills(otp_controls: list[ClassifiedLoginControl], code: str) -> list[dict[str, Any]]:
  192. """One fill per box. Default: the single best-scoring code field takes the whole code.
  193. Per-digit entry only when the page unmistakably uses it: exactly len(code) OTP controls that are all
  194. ``maxlength=1``, all in the same form, and adjacent in DOM order (the classic N-box widget). Anything
  195. looser (several code-like inputs scattered over a page) gets ONE field, never a digit sprayed across
  196. unrelated inputs."""
  197. best = max(otp_controls, key=lambda c: c.score)
  198. boxes = sorted((c for c in otp_controls if c.control.max_length == 1), key=lambda c: c.control.index)
  199. if (len(boxes) == len(code)
  200. and len({b.control.form_index for b in boxes}) == 1
  201. and all(b.control.index - a.control.index == 1 for a, b in itertools.pairwise(boxes))):
  202. return [{"index": b.control.index, "token": "one-time-code", "value": ch} for b, ch in zip(boxes, code)]
  203. return [{"index": best.control.index, "token": "one-time-code", "value": code}]
  204. def build_inspection_js(nonce: str) -> str:
  205. return _LOGIN_CONTROL_INSPECTION_JS_TEMPLATE.replace("__NONCE__", json.dumps(nonce))
  206. _LOGIN_CONTROL_INSPECTION_JS_TEMPLATE = """(() => {
  207. const nonce = __NONCE__;
  208. // Shadow-piercing collect: many logins (Home Assistant, custom-element SPAs) render their
  209. // form inside a shadow root, where document.querySelectorAll never sees it. Walk every
  210. // element (shadow hosts can be anything, not just inputs) and recurse into open shadow roots.
  211. // Forms are collected in the same walk: document.forms misses a <form> inside a shadow root, which
  212. // would leave its controls ungrouped (formIndex null) and merge split OTP boxes across forms.
  213. const elements = [];
  214. const forms = [];
  215. (function walk(root) {
  216. for (const e of root.querySelectorAll("*")) {
  217. if (e.tagName === "INPUT" || e.tagName === "SELECT") elements.push(e);
  218. else if (e.tagName === "FORM") forms.push(e);
  219. if (e.shadowRoot) walk(e.shadowRoot);
  220. }
  221. })(document);
  222. elements.forEach((element, index) => element.setAttribute("data-hermes-vault-slot", nonce + ":" + index));
  223. const out = elements.flatMap((element, index) => {
  224. if (element.disabled || element.readOnly) return [];
  225. if (["hidden", "submit", "button", "reset", "file", "image", "checkbox", "radio"].includes(element.type)) return [];
  226. const style = getComputedStyle(element);
  227. if (style.display === "none" || style.visibility === "hidden" || element.getClientRects().length === 0) return [];
  228. const labels = element.labels ? Array.from(element.labels, (l) => l.textContent || "") : [];
  229. const ariaText = (element.getAttribute("aria-labelledby") || "")
  230. .split(/\\s+/).filter(Boolean)
  231. .map((id) => { const r = element.getRootNode(); const n = (r.getElementById ? r.getElementById(id) : null) || document.getElementById(id); return n ? (n.textContent || "") : ""; })
  232. .join(" ");
  233. const resolvedFormIndex = element.form ? forms.indexOf(element.form) : -1;
  234. return [{
  235. autocomplete: element.autocomplete || "",
  236. formIndex: resolvedFormIndex >= 0 ? resolvedFormIndex : null,
  237. index,
  238. maxLength: element.maxLength > 0 ? element.maxLength : null,
  239. label: [
  240. ...labels,
  241. element.getAttribute("aria-label") || "",
  242. ariaText,
  243. element.getAttribute("placeholder") || "",
  244. element.getAttribute("title") || "",
  245. ].join(" "),
  246. name: [element.name, element.id].join(" "),
  247. type: element.tagName === "SELECT" ? "select" : (element.type || ""),
  248. }];
  249. });
  250. return JSON.stringify(out);
  251. })()"""
  252. def build_fill_js(fills: list[dict[str, Any]], expected_origin: str, nonce: str = "") -> str:
  253. """Build a JS expression that fills the selected controls and reports only a count. The
  254. returned expression never echoes the values back.
  255. ``expected_origin`` is asserted against ``window.location.origin`` synchronously inside the SAME
  256. evaluated script, immediately before any write. If the page navigated between inspection and fill
  257. (TOCTOU), the script writes nothing and returns ``{"refused": "origin_changed", "found": <actual>}``:
  258. proof scope equals mutation scope (#88706). Targets resolve by the ``<nonce>:<index>`` stamp of
  259. THIS inspection; a ``current-password`` fill additionally requires ``type=password``; ``<select>``
  260. controls (country, state, expiry month) match an option by value or visible text. No marker is
  261. left on filled controls so later model-driven DOM reads cannot address them deterministically.
  262. """
  263. payload = json.dumps(
  264. [{"index": f["index"], "token": f.get("token", "current-password"), "value": f["value"]} for f in fills]
  265. )
  266. return (_FILL_JS_TEMPLATE.replace("__EXPECTED_ORIGIN__", json.dumps(expected_origin))
  267. .replace("__FILLS__", payload).replace("__NONCE__", json.dumps(nonce)))
  268. _FILL_JS_TEMPLATE = """(() => {
  269. const expectedOrigin = __EXPECTED_ORIGIN__;
  270. if (window.location.origin !== expectedOrigin) {
  271. return JSON.stringify({ refused: "origin_changed", found: window.location.origin });
  272. }
  273. const fills = __FILLS__;
  274. const nonce = __NONCE__;
  275. // Stamped controls may live inside a shadow root (see the inspection script's walk): collect the
  276. // document and every open shadow root once, then look each stamp up in those roots.
  277. const roots = [];
  278. (function walk(root) {
  279. roots.push(root);
  280. for (const e of root.querySelectorAll("*")) if (e.shadowRoot) walk(e.shadowRoot);
  281. })(document);
  282. const find = (selector) => roots.flatMap((r) => Array.from(r.querySelectorAll(selector)));
  283. let filled = 0;
  284. const norm = (t) => String(t || "").trim().toLowerCase();
  285. for (const f of fills) {
  286. const el = find('[data-hermes-vault-slot="' + nonce + ':' + f.index + '"]')[0];
  287. if (!el || (f.token === "current-password" && el.type !== "password")) continue;
  288. try {
  289. if (el.tagName === "SELECT") {
  290. const want = norm(f.value);
  291. const opt = Array.from(el.options).find((o) => [o.value, o.textContent].some((t) => norm(t) === want || norm(t) === want.replace(/^0/, "")));
  292. if (opt) { el.value = opt.value; el.dispatchEvent(new Event("change", { bubbles: true, composed: true })); filled += 1; }
  293. continue;
  294. }
  295. el.focus();
  296. const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value");
  297. // one-time-code split into single-character boxes: f.value is the slice for THIS box (see build_otp_fills)
  298. if (setter && setter.set) { setter.set.call(el, f.value); } else { el.value = f.value; }
  299. // composed: a component listening on its shadow host must see the value change too.
  300. el.dispatchEvent(new InputEvent("input", { bubbles: true, composed: true, inputType: "insertText" }));
  301. el.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
  302. if (el.value.length > 0) filled += 1;
  303. } catch (e) { /* skip */ }
  304. }
  305. find("[data-hermes-vault-slot]").forEach((n) => n.removeAttribute("data-hermes-vault-slot"));
  306. return JSON.stringify({ filled });
  307. })()"""