ser2netweb 3.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. ser2netweb/__init__.py +20 -0
  2. ser2netweb/__main__.py +6 -0
  3. ser2netweb/accounts.py +503 -0
  4. ser2netweb/cli.py +489 -0
  5. ser2netweb/clock.py +128 -0
  6. ser2netweb/config.py +4491 -0
  7. ser2netweb/console.py +181 -0
  8. ser2netweb/datalock.py +181 -0
  9. ser2netweb/engine/__init__.py +0 -0
  10. ser2netweb/engine/access.py +173 -0
  11. ser2netweb/engine/bindhint.py +115 -0
  12. ser2netweb/engine/bridge.py +1928 -0
  13. ser2netweb/engine/cluster.py +1140 -0
  14. ser2netweb/engine/modbus.py +530 -0
  15. ser2netweb/engine/modbus_gateway.py +1465 -0
  16. ser2netweb/engine/mqtt_pub.py +632 -0
  17. ser2netweb/engine/netguard.py +805 -0
  18. ser2netweb/engine/netinfo.py +199 -0
  19. ser2netweb/engine/portdiag.py +414 -0
  20. ser2netweb/engine/portlist.py +471 -0
  21. ser2netweb/engine/protocols/__init__.py +28 -0
  22. ser2netweb/engine/protocols/base.py +117 -0
  23. ser2netweb/engine/protocols/raw.py +12 -0
  24. ser2netweb/engine/protocols/rfc2217.py +586 -0
  25. ser2netweb/engine/protocols/telnet.py +172 -0
  26. ser2netweb/engine/serial_compat.py +598 -0
  27. ser2netweb/engine/serial_io.py +210 -0
  28. ser2netweb/engine/serial_link.py +414 -0
  29. ser2netweb/engine/sockopts.py +103 -0
  30. ser2netweb/engine/sparkplug.py +538 -0
  31. ser2netweb/engine/sparkplug_node.py +550 -0
  32. ser2netweb/engine/supervisor.py +533 -0
  33. ser2netweb/engine/tls.py +232 -0
  34. ser2netweb/envvars.py +57 -0
  35. ser2netweb/explain.py +117 -0
  36. ser2netweb/healthcheck.py +78 -0
  37. ser2netweb/i18n.py +110 -0
  38. ser2netweb/importer.py +550 -0
  39. ser2netweb/layout.py +118 -0
  40. ser2netweb/licences.py +86 -0
  41. ser2netweb/locale/tr.json +1569 -0
  42. ser2netweb/logsetup.py +253 -0
  43. ser2netweb/logtext.py +23 -0
  44. ser2netweb/notify.py +761 -0
  45. ser2netweb/optional.py +76 -0
  46. ser2netweb/reload.py +295 -0
  47. ser2netweb/runtime.py +762 -0
  48. ser2netweb/sdnotify.py +85 -0
  49. ser2netweb/ser2net_import.py +2001 -0
  50. ser2netweb/signins.py +98 -0
  51. ser2netweb/standalone.py +154 -0
  52. ser2netweb/state.py +1457 -0
  53. ser2netweb/storage.py +130 -0
  54. ser2netweb/textfold.py +51 -0
  55. ser2netweb/tlsreload.py +37 -0
  56. ser2netweb/watchdog.py +201 -0
  57. ser2netweb/web/__init__.py +0 -0
  58. ser2netweb/web/api.py +793 -0
  59. ser2netweb/web/auth.py +699 -0
  60. ser2netweb/web/certinfo.py +144 -0
  61. ser2netweb/web/httpguard.py +413 -0
  62. ser2netweb/web/ldap_auth.py +556 -0
  63. ser2netweb/web/oidc_auth.py +330 -0
  64. ser2netweb/web/proxy.py +398 -0
  65. ser2netweb/web/routes/__init__.py +78 -0
  66. ser2netweb/web/routes/cluster.py +669 -0
  67. ser2netweb/web/routes/common.py +359 -0
  68. ser2netweb/web/routes/console.py +451 -0
  69. ser2netweb/web/routes/forms.py +853 -0
  70. ser2netweb/web/routes/login.py +573 -0
  71. ser2netweb/web/routes/mappings.py +470 -0
  72. ser2netweb/web/routes/ops.py +374 -0
  73. ser2netweb/web/routes/settings.py +2135 -0
  74. ser2netweb/web/routes/system.py +308 -0
  75. ser2netweb/web/routes/totp.py +282 -0
  76. ser2netweb/web/selfsigned.py +129 -0
  77. ser2netweb/web/server.py +483 -0
  78. ser2netweb/web/static/app.css +327 -0
  79. ser2netweb/web/static/app.js +1102 -0
  80. ser2netweb/web/static/htmx.min.js +1 -0
  81. ser2netweb/web/static/points.js +218 -0
  82. ser2netweb/web/static/theme.js +7 -0
  83. ser2netweb/web/static/xterm-addon-fit.js +2 -0
  84. ser2netweb/web/static/xterm.css +218 -0
  85. ser2netweb/web/static/xterm.js +2 -0
  86. ser2netweb/web/templates/_cluster_body.html +109 -0
  87. ser2netweb/web/templates/_console.html +21 -0
  88. ser2netweb/web/templates/_footer.html +13 -0
  89. ser2netweb/web/templates/_login_notice.html +8 -0
  90. ser2netweb/web/templates/_macros.html +21 -0
  91. ser2netweb/web/templates/_mapping_form.html +477 -0
  92. ser2netweb/web/templates/_mapping_log.html +28 -0
  93. ser2netweb/web/templates/_mapping_traces.html +44 -0
  94. ser2netweb/web/templates/_mappings_body.html +149 -0
  95. ser2netweb/web/templates/_modbus_read.html +18 -0
  96. ser2netweb/web/templates/_ports_table.html +37 -0
  97. ser2netweb/web/templates/_serial_port_select.html +48 -0
  98. ser2netweb/web/templates/_shell.html +41 -0
  99. ser2netweb/web/templates/audit.html +55 -0
  100. ser2netweb/web/templates/base.html +77 -0
  101. ser2netweb/web/templates/dashboard.html +72 -0
  102. ser2netweb/web/templates/licenses.html +18 -0
  103. ser2netweb/web/templates/login.html +32 -0
  104. ser2netweb/web/templates/login_totp.html +23 -0
  105. ser2netweb/web/templates/settings.html +830 -0
  106. ser2netweb/web/templates/setup.html +43 -0
  107. ser2netweb/web/templates/totp.html +41 -0
  108. ser2netweb/web/totp.py +94 -0
  109. ser2netweb/winservice.py +1793 -0
  110. ser2netweb-3.0.0.dist-info/METADATA +120 -0
  111. ser2netweb-3.0.0.dist-info/RECORD +121 -0
  112. ser2netweb-3.0.0.dist-info/WHEEL +5 -0
  113. ser2netweb-3.0.0.dist-info/entry_points.txt +2 -0
  114. ser2netweb-3.0.0.dist-info/licenses/COMMERCIAL_LICENSE.md +94 -0
  115. ser2netweb-3.0.0.dist-info/licenses/LICENSE +662 -0
  116. ser2netweb-3.0.0.dist-info/licenses/NOTICE +20 -0
  117. ser2netweb-3.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +105 -0
  118. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/htmx.org.txt +13 -0
  119. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm-addon-fit.txt +19 -0
  120. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm.txt +21 -0
  121. ser2netweb-3.0.0.dist-info/top_level.txt +1 -0
ser2netweb/web/auth.py ADDED
@@ -0,0 +1,699 @@
1
+ """Authentication, sessions, CSRF and login rate-limiting — all stdlib.
2
+
3
+ The admin UI is network-exposed by design, so it is password-protected by default:
4
+ - scrypt password hashing (no extra dependency),
5
+ - a stateless HMAC-signed session cookie (secret from AppConfig.secret_key),
6
+ - double-submit-cookie CSRF protection on every state-changing request, which the
7
+ browser must not say a page of another site made (cross_site),
8
+ - a simple in-memory per-IP login rate limiter to blunt brute force, and a cap on
9
+ how many password checks (and directory sign-ins) run at once (SlowWork).
10
+
11
+ An admin may switch the login requirement off for trusted networks: a visitor
12
+ without a session then gets a pseudo-user with ``admin_ui.anonymous_role``. That
13
+ only applies when every host name the request claims (Host, and X-Forwarded-Host /
14
+ Forwarded from a reverse proxy) is an IP literal, ``localhost`` or this machine's
15
+ own name — a page on an attacker's domain that DNS-rebinds to this UI carries the
16
+ attacker's host name, so it never gets anonymous access (CSRF still applies to
17
+ everything, and cluster peer actions always need a real login). The first-run setup
18
+ page has the same guard (claims_own_host); through another name it needs the one-time
19
+ setup code (AppState.prepare_first_run).
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import asyncio
24
+ import base64
25
+ import functools
26
+ import hashlib
27
+ import hmac
28
+ import ipaddress
29
+ import json
30
+ import re
31
+ import secrets
32
+ import socket
33
+ import time
34
+ import unicodedata
35
+ from collections import OrderedDict, deque
36
+
37
+ from ..engine.netguard import address_key # an IPv6 address by its /64, as the connection caps
38
+ from . import proxy
39
+
40
+ SESSION_COOKIE = "ser2net_session"
41
+ CSRF_COOKIE = "ser2net_csrf"
42
+
43
+ # The scrypt cost of new password hashes: N=2^14, r=8, p=5, OWASP's minimum for scrypt.
44
+ # It needs 16 MiB like the p=1 used before 2.9, and about 5 times the CPU time. A hash
45
+ # names the cost it was made with ("scrypt:N:r:p$<salt hex>$<hash hex>"), so the cost can
46
+ # change without breaking the hashes stored before; one in the format of older versions
47
+ # ("scrypt$<salt hex>$<hash hex>") was made with N=2^14, r=8, p=1.
48
+ _SCRYPT_N = 2 ** 14
49
+ _SCRYPT_R = 8
50
+ _SCRYPT_P = 5
51
+ _DKLEN = 32
52
+ _COST = (_SCRYPT_N, _SCRYPT_R, _SCRYPT_P)
53
+ _LEGACY_COST = (2 ** 14, 8, 1)
54
+ # what a stored hash may ask for (more is refused, not computed): at most 256 MiB
55
+ _MAX_N, _MAX_R, _MAX_P, _MAX_MEM, _MAX_DKLEN = 2 ** 20, 32, 64, 256 * 1024 * 1024, 64
56
+
57
+
58
+ # --------------------------------------------------------------------------
59
+ # password hashing
60
+ # --------------------------------------------------------------------------
61
+ def _cost(scheme: str) -> tuple[int, int, int] | None:
62
+ """(N, r, p) a stored hash's scheme names ("scrypt" or "scrypt:N:r:p"), or None."""
63
+ if scheme == "scrypt":
64
+ return _LEGACY_COST
65
+ name, _sep, rest = scheme.partition(":")
66
+ values = rest.split(":")
67
+ if name != "scrypt" or len(values) != 3 or not all(v.isascii() and v.isdigit()
68
+ for v in values):
69
+ return None
70
+ n, r, p = (int(v) for v in values)
71
+ if not (2 <= n <= _MAX_N and n & (n - 1) == 0 and 1 <= r <= _MAX_R and 1 <= p <= _MAX_P
72
+ and 128 * r * n <= _MAX_MEM):
73
+ return None
74
+ return n, r, p
75
+
76
+
77
+ def _parse(stored) -> tuple[tuple[int, int, int], bytes, bytes] | None:
78
+ """(cost, salt, hash) of a hash_password() result (of any version), or None."""
79
+ parts = str(stored).split("$")
80
+ if len(parts) != 3:
81
+ return None
82
+ cost = _cost(parts[0])
83
+ try:
84
+ salt, expected = bytes.fromhex(parts[1]), bytes.fromhex(parts[2])
85
+ except ValueError:
86
+ return None
87
+ if cost is None or not salt or not 1 <= len(expected) <= _MAX_DKLEN:
88
+ return None
89
+ return cost, salt, expected
90
+
91
+
92
+ def _prep(password: str) -> str:
93
+ """A password as it is hashed: Unicode NFKC, like the cluster key (engine/cluster.py
94
+ key_bytes), so that the same password typed on another device or pasted from
95
+ elsewhere is the same text - a letter with its accent as one character or two (NFD,
96
+ from macOS file names or some PDFs), a no-break space (macOS Option+Space, text from
97
+ Word or the web) for a space, full-width forms. Letters typed on a keyboard, Turkish
98
+ ones included, are NFKC already. Only for local accounts: a directory gets the
99
+ password as it was typed."""
100
+ return unicodedata.normalize("NFKC", password)
101
+
102
+
103
+ def _scrypt(password: str, salt: bytes, cost: tuple[int, int, int], dklen: int) -> bytes:
104
+ n, r, p = cost
105
+ # the memory these parameters need (OpenSSL refuses more than 32 MiB unless told)
106
+ maxmem = 128 * r * (n + p + 2) + 1024 * 1024
107
+ return hashlib.scrypt(password.encode("utf-8"), salt=salt, n=n, r=r, p=p, dklen=dklen,
108
+ maxmem=maxmem)
109
+
110
+
111
+ def hash_password(password: str) -> str:
112
+ salt = secrets.token_bytes(16)
113
+ dk = _scrypt(_prep(password), salt, _COST, _DKLEN)
114
+ return f"scrypt:{_SCRYPT_N}:{_SCRYPT_R}:{_SCRYPT_P}${salt.hex()}${dk.hex()}"
115
+
116
+
117
+ # What a sign-in under a name that has no local account is checked against while there is
118
+ # no directory to ask: a hash of a password nobody knows, so that such a sign-in takes as
119
+ # long as a wrong password and the answer's timing doesn't tell which names have one.
120
+ DUMMY_HASH = (f"scrypt:{_SCRYPT_N}:{_SCRYPT_R}:{_SCRYPT_P}"
121
+ f"${secrets.token_hex(16)}${secrets.token_hex(_DKLEN)}")
122
+
123
+
124
+ def is_password_hash(stored: str) -> bool:
125
+ """Is `stored` a hash_password() result, of this version or an older one?"""
126
+ return _parse(stored) is not None
127
+
128
+
129
+ def needs_rehash(stored: str) -> bool:
130
+ """Was `stored` made with another cost than new hashes get (an older version's)?"""
131
+ parsed = _parse(stored)
132
+ return parsed is None or parsed[0] != _COST or len(parsed[2]) != _DKLEN
133
+
134
+
135
+ def verify_password(password: str, stored: str) -> bool:
136
+ """Does `password` match `stored`? Checked as NFKC (_prep), the form every hash of
137
+ this version is made of; a hash in the format of older versions, which hashed the
138
+ password as typed, is also checked against that when it differs (one scrypt more,
139
+ only for a password that NFKC changes)."""
140
+ parsed = _parse(stored)
141
+ if parsed is None:
142
+ return False
143
+ cost, salt, expected = parsed
144
+ try:
145
+ tries = [_prep(password)]
146
+ if str(stored).startswith("scrypt$") and password != tries[0]:
147
+ tries.append(password)
148
+ return any(hmac.compare_digest(_scrypt(pw, salt, cost, len(expected)), expected)
149
+ for pw in tries)
150
+ except (ValueError, TypeError, MemoryError): # not (encodable) text; out of memory
151
+ return False
152
+
153
+
154
+ # --------------------------------------------------------------------------
155
+ # signed session token
156
+ # --------------------------------------------------------------------------
157
+ def _b64e(data: bytes) -> str:
158
+ return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
159
+
160
+
161
+ def _b64d(s: str) -> bytes:
162
+ pad = "=" * (-len(s) % 4)
163
+ return base64.urlsafe_b64decode(s + pad)
164
+
165
+
166
+ def _sign(secret: str, payload: str) -> str:
167
+ return _b64e(hmac.new(secret.encode("utf-8"), payload.encode("ascii"), hashlib.sha256).digest())
168
+
169
+
170
+ def _payload_secret(secret: str) -> str:
171
+ """What sign_payload's tokens are signed with: derived from the session key, so that
172
+ such a token (the OIDC state cookie) is never a valid session cookie, nor a session
173
+ cookie a valid state."""
174
+ return hmac.new(secret.encode("utf-8"), b"ser2net signed payload", hashlib.sha256).hexdigest()
175
+
176
+
177
+ def _is_int(value) -> bool:
178
+ return isinstance(value, int) and not isinstance(value, bool)
179
+
180
+
181
+ def issue_session(secret: str, ttl_seconds: int, username: str, pwd_version: int = 0) -> str:
182
+ # "n": two sign-ins in the same second still get different tokens, so a logout
183
+ # (RevokedSessions) ends exactly one of them
184
+ payload = _b64e(json.dumps(
185
+ {"exp": int(time.time()) + ttl_seconds, "u": username, "v": int(pwd_version),
186
+ "n": secrets.token_urlsafe(6)}
187
+ ).encode("utf-8"))
188
+ return f"{payload}.{_sign(secret, payload)}"
189
+
190
+
191
+ def decode_session(secret: str, token: str | None) -> dict | None:
192
+ """Verify a session cookie's signature + expiry and return its payload
193
+ ({"u": username, "v": pwd_version, "exp": expiry}), or None if invalid/expired.
194
+ The caller must still confirm the user exists and that pwd_version matches (so a
195
+ password change revokes only that user's sessions)."""
196
+ if not token or "." not in token or not token.isascii(): # ours are ASCII
197
+ return None
198
+ payload, sig = token.rsplit(".", 1)
199
+ if not hmac.compare_digest(sig, _sign(secret, payload)):
200
+ return None
201
+ try:
202
+ data = json.loads(_b64d(payload))
203
+ except (ValueError, json.JSONDecodeError):
204
+ return None
205
+ if not isinstance(data, dict):
206
+ return None
207
+ user, version, exp = data.get("u", ""), data.get("v", 0), data.get("exp", 0)
208
+ if not (isinstance(user, str) and _is_int(version) and _is_int(exp)):
209
+ return None # signed, but not a session token
210
+ if exp <= int(time.time()):
211
+ return None
212
+ return {"u": user, "v": version, "exp": exp}
213
+
214
+
215
+ class RevokedSessions:
216
+ """Session cookies ended by a logout, remembered until they would expire anyway.
217
+
218
+ A cookie is a stateless signed token: the browser deleting it at logout would leave
219
+ a copy of it valid for the rest of its lifetime. Held in memory (a restart forgets
220
+ the list) and never written to config.json, where a save on every logout would
221
+ push real changes out of the 50 backups. Keyed by the token's signature.
222
+
223
+ Bounded: at most PER_USER cookies of one account and MAX_ENTRIES in all. Past that
224
+ nothing remembered is forgotten (that would make someone's copied cookie valid
225
+ again): add() names the account instead, and the caller ends all of its sessions
226
+ (pwd_version + 1), after which its remembered cookies are moot (forget())."""
227
+
228
+ MAX_ENTRIES = 10000
229
+ PER_USER = 100
230
+
231
+ def __init__(self) -> None:
232
+ self._until: dict[str, int] = {} # signature -> the token's expiry (epoch seconds)
233
+ self._owner: dict[str, str] = {} # signature -> the token's account name
234
+ self._count: dict[str, int] = {} # account name -> its signatures in the list
235
+
236
+ def add(self, secret: str, token: str | None) -> str | None:
237
+ """Refuse this token from now on (if it is a valid session at all). Returns its
238
+ account's name when it can't be remembered (that account's share or the list is
239
+ full): the caller ends all of that account's sessions instead. Else None."""
240
+ data = decode_session(secret, token)
241
+ if data is None or token is None:
242
+ return None
243
+ now = int(time.time())
244
+ for sig in [s for s, exp in self._until.items() if exp <= now]:
245
+ self._drop(sig)
246
+ sig, user = token.rsplit(".", 1)[1], data["u"]
247
+ if sig in self._until:
248
+ return None
249
+ if self._count.get(user, 0) >= self.PER_USER or len(self._until) >= self.MAX_ENTRIES:
250
+ return user
251
+ self._until[sig], self._owner[sig] = data["exp"], user
252
+ self._count[user] = self._count.get(user, 0) + 1
253
+ return None
254
+
255
+ def forget(self, username: str) -> None:
256
+ """Drop an account's cookies: all of its sessions were ended another way."""
257
+ for sig in [s for s, u in self._owner.items() if u == username]:
258
+ self._drop(sig)
259
+
260
+ def _drop(self, sig: str) -> None:
261
+ del self._until[sig]
262
+ user = self._owner.pop(sig)
263
+ if self._count[user] > 1:
264
+ self._count[user] -= 1
265
+ else:
266
+ del self._count[user]
267
+
268
+ def __contains__(self, token: object) -> bool:
269
+ if not isinstance(token, str) or "." not in token:
270
+ return False
271
+ exp = self._until.get(token.rsplit(".", 1)[1])
272
+ return exp is not None and exp > time.time()
273
+
274
+ def clear(self) -> None:
275
+ self._until.clear()
276
+ self._owner.clear()
277
+ self._count.clear()
278
+
279
+
280
+ def sign_payload(secret: str, data: dict, ttl_seconds: int = 600) -> str:
281
+ """A short-lived HMAC-signed token carrying a small dict (e.g. the OIDC state +
282
+ nonce stashed in a cookie across the redirect), under a key of its own
283
+ (_payload_secret)."""
284
+ payload = _b64e(json.dumps({**data, "exp": int(time.time()) + ttl_seconds}).encode("utf-8"))
285
+ return f"{payload}.{_sign(_payload_secret(secret), payload)}"
286
+
287
+
288
+ def read_payload(secret: str, token: str | None) -> dict | None:
289
+ if not token or "." not in token or not token.isascii(): # ours are ASCII
290
+ return None
291
+ payload, sig = token.rsplit(".", 1)
292
+ if not hmac.compare_digest(sig, _sign(_payload_secret(secret), payload)):
293
+ return None
294
+ try:
295
+ data = json.loads(_b64d(payload))
296
+ except (ValueError, json.JSONDecodeError):
297
+ return None
298
+ if not isinstance(data, dict) or not _is_int(data.get("exp")) or data["exp"] <= int(time.time()):
299
+ return None
300
+ return data
301
+
302
+
303
+ def session_user(cfg, token: str | None, revoked: RevokedSessions | None = None):
304
+ """Resolve a session cookie to the live User it authenticates, or None.
305
+ Confirms the signed username still exists, its pwd_version is current and its
306
+ sign-in method (LDAP/OIDC) is still on, and that the session was not ended by a
307
+ logout (``revoked``)."""
308
+ data = decode_session(cfg.secret_key, token)
309
+ if data is None or (revoked is not None and token in revoked):
310
+ return None
311
+ user = cfg.get_user(data["u"])
312
+ if user is None or user.pwd_version != data["v"]:
313
+ return None
314
+ if not cfg.source_enabled(user): # LDAP/OIDC switched off: its accounts are signed out
315
+ return None
316
+ return user
317
+
318
+
319
+ # --------------------------------------------------------------------------
320
+ # optional anonymous access (login requirement switched off by an admin)
321
+ # --------------------------------------------------------------------------
322
+ # Not a valid account name: local names can't hold parentheses (forms._username_problem)
323
+ # and LDAP/OIDC names in parentheses are refused (config.external_name_problem). Identity
324
+ # checks compare the source too (an older install may have such an account).
325
+ ANONYMOUS_USERNAME = "(anonymous)"
326
+ # What logs and the audit log name for a failed sign-in whose user name is no account's:
327
+ # people type their password into that field. Not a valid account name either.
328
+ UNKNOWN_USER = "(unknown user)"
329
+ # The longest user name a sign-in is tried with (local names have at most 32 characters);
330
+ # a longer one fails at once, without asking the directory.
331
+ LOGIN_NAME_MAX = 256
332
+
333
+
334
+ @functools.lru_cache(maxsize=1)
335
+ def _own_host_names() -> frozenset:
336
+ # gethostname() only (no DNS lookup on the event loop): the name as configured,
337
+ # its short form and the mDNS "<short>.local" variant.
338
+ full = socket.gethostname().strip().lower()
339
+ short = full.split(".", 1)[0]
340
+ return frozenset(n for n in (full, short, f"{short}.local" if short else "") if n)
341
+
342
+
343
+ def _host_only(host_header: str | None) -> str:
344
+ """'Host' header value without the port (and IPv6 brackets), lower-cased."""
345
+ h = (host_header or "").strip().lower()
346
+ if h.startswith("["):
347
+ return h[1:h.find("]")] if "]" in h else ""
348
+ return h.rsplit(":", 1)[0] if h.count(":") == 1 else h
349
+
350
+
351
+ def is_own_host(host_header: str | None) -> bool:
352
+ """True when the browser addressed this UI by IP, localhost or this machine's own
353
+ name — i.e. not through some other DNS name (the DNS-rebinding guard)."""
354
+ name = _host_only(host_header)
355
+ if not name:
356
+ return False
357
+ try:
358
+ ipaddress.ip_address(name)
359
+ return True
360
+ except ValueError:
361
+ pass
362
+ return name == "localhost" or name in _own_host_names()
363
+
364
+
365
+ _FORWARDED_HOST = re.compile(r'(?:^|[;,\s])host="?([^";,\s]+)', re.IGNORECASE)
366
+
367
+
368
+ def _claimed_hosts(headers) -> list:
369
+ """Every host name the request claims: Host, plus X-Forwarded-Host / Forwarded
370
+ host= when a reverse proxy sets them. All must be this machine for open access
371
+ (requiring more names to match can only narrow it, so a client-supplied header
372
+ can't widen anything)."""
373
+ hosts = [headers.get("host") or ""]
374
+ xfh = headers.get("x-forwarded-host")
375
+ if xfh:
376
+ hosts += [h.strip() for h in xfh.split(",")]
377
+ fwd = headers.get("forwarded")
378
+ if fwd:
379
+ hosts += _FORWARDED_HOST.findall(fwd)
380
+ return hosts
381
+
382
+
383
+ def claims_own_host(headers) -> bool:
384
+ """Every host name the request claims is this machine (is_own_host): the
385
+ DNS-rebinding guard of open access and first-run setup."""
386
+ return all(is_own_host(h) for h in _claimed_hosts(headers))
387
+
388
+
389
+ def foreign_host(headers) -> str:
390
+ """The first claimed host name that is not this machine ('' if there is none)."""
391
+ return next((h for h in _claimed_hosts(headers) if not is_own_host(h)), "")
392
+
393
+
394
+ # --------------------------------------------------------------------------
395
+ # requests that a page of another site makes the browser send
396
+ # --------------------------------------------------------------------------
397
+ SAFE_METHODS = ("GET", "HEAD", "OPTIONS")
398
+ _DEFAULT_PORTS = {"http": "80", "https": "443"}
399
+
400
+
401
+ def _host_port(netloc: str, scheme: str) -> tuple[str, str] | None:
402
+ """('host', 'port') of a Host-style 'host[:port]' (IPv6 in brackets), lower-cased, the
403
+ port of `scheme` when none is given; None when it is not such a value."""
404
+ n = netloc.strip().lower()
405
+ if n.startswith("["):
406
+ end = n.find("]")
407
+ host, rest = (n[:end + 1], n[end + 1:]) if end > 0 else ("", "")
408
+ elif n.count(":") == 1:
409
+ host, rest = n.split(":")[0], n[n.find(":"):]
410
+ else:
411
+ host, rest = ("", "") if ":" in n else (n, "")
412
+ if not host or (rest and not (rest[0] == ":" and rest[1:].isascii() and rest[1:].isdigit())):
413
+ return None
414
+ return host, str(int(rest[1:])) if rest else _DEFAULT_PORTS.get(scheme, "")
415
+
416
+
417
+ def _origin(value: str) -> tuple[str, str, str] | None:
418
+ """(scheme, host, port) of an http(s) origin 'scheme://host[:port]' (no path), the
419
+ scheme's port when none is given; None when it is not such a value."""
420
+ scheme, sep, netloc = value.strip().partition("://")
421
+ scheme = scheme.lower()
422
+ if not sep or scheme not in _DEFAULT_PORTS:
423
+ return None
424
+ hp = _host_port(netloc, scheme)
425
+ return (scheme, *hp) if hp else None
426
+
427
+
428
+ # What a refusal of a page's own request behind a reverse proxy usually needs (all.log).
429
+ PROXY_HINT = ("behind a reverse proxy, pass the browser's address on as Host (nginx: "
430
+ "proxy_set_header Host $http_host; Apache: ProxyPreserveHost On) or as "
431
+ "X-Forwarded-Host")
432
+
433
+
434
+ def cross_site(headers, also=()) -> str:
435
+ """Why the browser says a request was made by a page of another site, or '' when it
436
+ doesn't: the forms and changes of the web UI, and its WebSockets (the console, the
437
+ hex view). Sec-Fetch-Site (sent to HTTPS and localhost) must be same-origin or none;
438
+ without it, an Origin must be one of the hosts the request claims (Host, and
439
+ X-Forwarded-Host / Forwarded host= from a reverse proxy, which a page can't set),
440
+ port included, or one of the origins in `also` ('scheme://host[:port]', an address
441
+ the UI is published under): another port of the same host or a sibling subdomain is
442
+ another site, and its pages can put a CSRF cookie of their own into the browser. A
443
+ request with neither header (a script, a very old browser) is left to the CSRF token
444
+ and the session. The model of Go's net/http CrossOriginProtection."""
445
+ site = (headers.get("sec-fetch-site") or "").strip().lower()
446
+ if site:
447
+ return "" if site in ("same-origin", "none") else f"Sec-Fetch-Site {site!r}"
448
+ origin = headers.get("origin")
449
+ if origin is None:
450
+ return ""
451
+ ours = _origin(origin)
452
+ claimed = _claimed_hosts(headers)
453
+ if ours is not None and (any(_host_port(h, ours[0]) == ours[1:] for h in claimed)
454
+ or any(_origin(o) == ours for o in also)):
455
+ return ""
456
+ return (f"Origin {origin[:200]!r}; this UI was addressed as "
457
+ + ", ".join(repr(h[:100]) for h in claimed))
458
+
459
+
460
+ def anonymous_user(cfg, headers):
461
+ """The pseudo-user for a visitor without a session, or None when login is
462
+ required (the default), setup isn't done yet, or a claimed host isn't this
463
+ machine. Note: a reverse proxy that rewrites Host to 127.0.0.1 without passing
464
+ the original as X-Forwarded-Host/Forwarded hides the real name from this check."""
465
+ ui = cfg.admin_ui
466
+ if ui.require_login or not cfg.password_set:
467
+ return None
468
+ if not claims_own_host(headers):
469
+ return None
470
+ from ..config import User
471
+
472
+ return User(username=ANONYMOUS_USERNAME, role=ui.anonymous_role, source="anonymous")
473
+
474
+
475
+ def request_user(cfg, token: str | None, headers, revoked: RevokedSessions | None = None):
476
+ """The user a request acts as: its session's user, else the anonymous pseudo-user
477
+ when the login requirement is off, else None (must sign in). ``headers`` is the
478
+ request's (or WebSocket's) header mapping; ``revoked`` the logged-out sessions."""
479
+ return session_user(cfg, token, revoked) or anonymous_user(cfg, headers)
480
+
481
+
482
+ # --------------------------------------------------------------------------
483
+ # API bearer token (for the JSON REST API / automation)
484
+ # --------------------------------------------------------------------------
485
+ API_TOKEN_PREFIX = "s2n_" # noqa: S105 - the public prefix of every token
486
+
487
+
488
+ def new_api_token() -> str:
489
+ """A high-entropy bearer token shown to the operator once on generation."""
490
+ return API_TOKEN_PREFIX + secrets.token_urlsafe(32)
491
+
492
+
493
+ def hash_token(token: str) -> str:
494
+ """SHA-256 hex of a token. The token is already 256 bits of entropy, so a fast
495
+ hash (not scrypt) is appropriate — we only store the hash, never the token."""
496
+ return hashlib.sha256(token.encode("utf-8")).hexdigest()
497
+
498
+
499
+ def verify_token(token: str, stored_hash: str) -> bool:
500
+ if not token or not stored_hash:
501
+ return False
502
+ return hmac.compare_digest(hash_token(token), stored_hash)
503
+
504
+
505
+ def find_api_token(cfg, token: str):
506
+ """The API token (config.ApiToken) a request's bearer token is: the one of
507
+ cfg.api_token_hash — as an ApiToken without an id, named 'api-token' in the audit log
508
+ like before there were others — or one of cfg.api_tokens. None when it is none of them.
509
+ Whether it has expired is the caller's to check. Every stored hash is compared, in
510
+ constant time, so how long this takes doesn't tell which one matched."""
511
+ from ..config import ApiToken
512
+
513
+ if not token:
514
+ return None
515
+ digest = hash_token(token).encode("ascii")
516
+ found = None
517
+ stored = [ApiToken(sha256=cfg.api_token_hash, role=cfg.api_token_role)] if cfg.api_token_hash else []
518
+ for candidate in stored + list(cfg.api_tokens):
519
+ # bytes: a hand-edited non-ASCII hash is a mismatch, not an error
520
+ if hmac.compare_digest(digest, str(candidate.sha256).encode("utf-8")) and found is None:
521
+ found = candidate
522
+ return found
523
+
524
+
525
+ def bearer_token(request) -> str:
526
+ """Extract the token from an `Authorization: Bearer <token>` header."""
527
+ header = request.headers.get("authorization", "")
528
+ if header[:7].lower() == "bearer ":
529
+ return header[7:].strip()
530
+ return ""
531
+
532
+
533
+ # --------------------------------------------------------------------------
534
+ # cookies
535
+ # --------------------------------------------------------------------------
536
+ def is_https(request, cfg) -> bool:
537
+ """Did the browser use HTTPS for this request? With admin TLS as the UI's listener
538
+ serves it (AppState.serving_tls: a TLS change applies to new connections at once;
539
+ without the app's state, as config.json sets it); when the request's scheme is https
540
+ (uvicorn's TLS, or X-Forwarded-Proto from a trusted proxy: ser2netweb/web/proxy.py); or when
541
+ the first X-Forwarded-Proto or Forwarded proto= says so, whoever sent it: it only makes
542
+ cookies stricter (Secure) and adds HSTS, which browsers take only over HTTPS, and a
543
+ page can't add those headers to the browser's requests - so a TLS proxy needs no
544
+ trusted-proxy setting for the cookies to be Secure."""
545
+ app = (getattr(request, "scope", None) or {}).get("app")
546
+ state = getattr(getattr(app, "state", None), "appstate", None)
547
+ served = state.serving_tls if state is not None else cfg.admin_ui.tls_enabled
548
+ return served or proxy.browser_https(request)
549
+
550
+
551
+ def set_cookie(response, request, cfg, name: str, value: str, max_age: int,
552
+ path: str = "/") -> None:
553
+ """One of the UI's cookies: HttpOnly, SameSite=Lax, Secure whenever the browser used
554
+ HTTPS (is_https), under the request's path prefix and with its name for the request
555
+ (proxy.cookie_name / cookie_path: by port, path and scheme)."""
556
+ response.set_cookie(proxy.cookie_name(request, name, path), value, max_age=max_age,
557
+ path=proxy.cookie_path(request, path), httponly=True, samesite="lax",
558
+ secure=is_https(request, cfg))
559
+
560
+
561
+ def delete_cookie(response, request, cfg, name: str, path: str = "/") -> None:
562
+ response.delete_cookie(proxy.cookie_name(request, name, path),
563
+ path=proxy.cookie_path(request, path),
564
+ httponly=True, samesite="lax", secure=is_https(request, cfg))
565
+
566
+
567
+ def cookie(request, name: str, path: str = "/", legacy: bool = True) -> str | None:
568
+ """The value of one of the UI's cookies (its name for this request: set_cookie); when
569
+ the request has none under that name, the one under the name 2.8 and older gave it
570
+ (proxy.legacy_cookie_name), unless `legacy` is False. Such a session cookie is moved to
571
+ its new name by GuardMiddleware (legacy_session / move_session)."""
572
+ value = request.cookies.get(proxy.cookie_name(request, name, path))
573
+ if value is None and legacy and (old := proxy.legacy_cookie_name(request, name, path)):
574
+ value = request.cookies.get(old)
575
+ return value
576
+
577
+
578
+ def legacy_session(request, cfg, revoked: RevokedSessions | None = None) -> str | None:
579
+ """A session cookie of this UI under the name of 2.8 and older (a sign-in from before
580
+ the upgrade), when the request has none under its name now: the token, only when it
581
+ is a valid session here. Another instance on this host name may still use that name
582
+ (one of 2.8, or one on port 8080, whose name it is): its cookie doesn't verify with
583
+ this UI's key and is left alone."""
584
+ old = proxy.legacy_cookie_name(request, SESSION_COOKIE)
585
+ if old is None or proxy.cookie_name(request, SESSION_COOKIE) in request.cookies:
586
+ return None
587
+ token = request.cookies.get(old)
588
+ return token if session_user(cfg, token, revoked) is not None else None
589
+
590
+
591
+ def move_session(response, request, cfg, token: str) -> None:
592
+ """Move a legacy_session to the session cookie's name now (the same token, until it
593
+ expires anyway) - unless the response sets or deletes that cookie itself (a sign-in, a
594
+ sign-out) - and delete it under the old name."""
595
+ name = proxy.cookie_name(request, SESSION_COOKIE)
596
+ if not any(c.startswith(name + "=") for c in response.headers.getlist("set-cookie")):
597
+ data = decode_session(cfg.secret_key, token)
598
+ if data is not None:
599
+ set_cookie(response, request, cfg, SESSION_COOKIE, token,
600
+ max_age=max(1, data["exp"] - int(time.time())))
601
+ response.delete_cookie(SESSION_COOKIE, path="/", httponly=True, samesite="lax",
602
+ secure=is_https(request, cfg))
603
+
604
+
605
+ # --------------------------------------------------------------------------
606
+ # CSRF (double-submit cookie)
607
+ # --------------------------------------------------------------------------
608
+ def new_csrf_token() -> str:
609
+ return secrets.token_urlsafe(32)
610
+
611
+
612
+ def csrf_token_matches(request, token) -> bool:
613
+ """Compare a supplied token (header or form field) against the CSRF cookie.
614
+
615
+ Deliberately does NOT read the request body — reading it inside a
616
+ BaseHTTPMiddleware would drain the stream before the route handler can parse
617
+ the form. API/HTMX requests pass the token via the X-CSRF-Token header
618
+ (checked in middleware); plain HTML form posts pass _csrf in the body and are
619
+ validated by their handlers, which read the form exactly once.
620
+ """
621
+ stored = cookie(request, CSRF_COOKIE) # a 2.8 one too, until GuardMiddleware moves it
622
+ if not stored or not token:
623
+ return False
624
+ token = str(token)
625
+ # tokens are ASCII; compare_digest raises on other text, which is just a mismatch
626
+ return token.isascii() and stored.isascii() and hmac.compare_digest(token, stored)
627
+
628
+
629
+ # --------------------------------------------------------------------------
630
+ # login rate limiter (per IP or per user name, sliding window)
631
+ # --------------------------------------------------------------------------
632
+ class LoginRateLimiter:
633
+ """Blocks an address (an IPv6 one by its /64: address_key), or what `key` makes of the
634
+ value given (a user name), after `max_attempts` failed sign-ins in `window_s` seconds.
635
+ Keeps the times of at most that many failures for at most MAX_ADDRESSES keys (when
636
+ full, the one whose last failure is the oldest is forgotten), so addresses that only
637
+ ever fail don't add up in memory."""
638
+
639
+ MAX_ADDRESSES = 4096
640
+
641
+ def __init__(self, max_attempts: int = 8, window_s: int = 300, key=None):
642
+ self.max_attempts = max_attempts
643
+ self.window_s = window_s
644
+ self._key = key or address_key
645
+ self._fails: OrderedDict[str, deque] = OrderedDict()
646
+
647
+ def blocked(self, ip: str) -> bool:
648
+ k = self._key(ip)
649
+ q = self._fails.get(k)
650
+ if q is None:
651
+ return False
652
+ now = time.monotonic()
653
+ while q and now - q[0] > self.window_s:
654
+ q.popleft()
655
+ if not q:
656
+ del self._fails[k]
657
+ return len(q) >= self.max_attempts
658
+
659
+ def record_failure(self, ip: str) -> None:
660
+ k = self._key(ip)
661
+ q = self._fails.get(k)
662
+ if q is None:
663
+ q = self._fails[k] = deque(maxlen=self.max_attempts)
664
+ while len(self._fails) > self.MAX_ADDRESSES:
665
+ self._fails.popitem(last=False)
666
+ else:
667
+ self._fails.move_to_end(k)
668
+ q.append(time.monotonic())
669
+
670
+ def reset(self, ip: str) -> None:
671
+ self._fails.pop(self._key(ip), None)
672
+
673
+
674
+ # --------------------------------------------------------------------------
675
+ # password checks and directory sign-ins: a few at a time
676
+ # --------------------------------------------------------------------------
677
+ class SlowWork:
678
+ """Runs slow sign-in work (scrypt: CPU time and 16 MiB each; a directory bind:
679
+ seconds when the server is slow) in worker threads, at most `limit` at a time; the
680
+ rest wait their turn. A burst of sign-ins thus can't take every thread of the shared
681
+ pool, where serial ports are opened and closed and config.json is saved too, nor
682
+ the memory of one scrypt job per request. busy(): `queue` jobs wait already — a
683
+ sign-in is answered 429 then instead of queueing as well."""
684
+
685
+ def __init__(self, limit: int, queue: int) -> None:
686
+ self.limit, self.queue = limit, queue
687
+ self._slots = asyncio.Semaphore(limit)
688
+ self._pending = 0 # running or waiting
689
+
690
+ def busy(self) -> bool:
691
+ return self._pending >= self.limit + self.queue
692
+
693
+ async def run(self, fn, /, *args, **kwargs):
694
+ self._pending += 1
695
+ try:
696
+ async with self._slots:
697
+ return await asyncio.to_thread(fn, *args, **kwargs)
698
+ finally:
699
+ self._pending -= 1