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
@@ -0,0 +1,330 @@
1
+ """Optional OpenID Connect (OIDC) single sign-on — authorization-code flow.
2
+
3
+ Endpoints are discovered from the issuer's /.well-known/openid-configuration. The
4
+ returned id_token is validated — signature via the issuer's JWKS, plus iss / aud /
5
+ exp / nonce, its times with CLOCK_SKEW_S of tolerance — using authlib.jose (do NOT
6
+ hand-roll JWT validation). A claim (groups_claim) maps to a ser2netweb role, reusing the
7
+ LDAP group→role logic (whole group names only: ldap_auth.group_matches).
8
+
9
+ The code request carries PKCE (S256; the verifier travels in the signed state cookie).
10
+ Every address the discovery document names, and every redirect on the way, must be
11
+ https:// — http:// only to this machine's loopback address (a provider on the same host),
12
+ where nothing crosses a network — so the client secret, the code and the signing keys
13
+ never travel in clear text (InsecureEndpoint).
14
+
15
+ authlib is an OPTIONAL dependency (lazy import): absent or failing to import => OIDC
16
+ login is disabled with a log line saying which (ser2netweb.optional), and local accounts keep
17
+ working. HTTP uses stdlib urllib; the fetch/post calls are
18
+ injectable so the full flow can be tested without a real provider.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import base64
23
+ import hashlib
24
+ import ipaddress
25
+ import json
26
+ import secrets
27
+ import time
28
+ import urllib.error
29
+ import urllib.parse
30
+ import urllib.request
31
+
32
+ from .. import optional, user_agent
33
+ from ..config import external_name
34
+ from .ldap_auth import role_for_groups # shared group/claim -> role mapping
35
+
36
+ # issuer -> (its discovery document, time.monotonic() when it was fetched)
37
+ _DISCOVERY_CACHE: dict[str, tuple[dict, float]] = {}
38
+ _DISCOVERY_TTL = 3600.0
39
+ # How far this host's clock may be off the identity provider's when an ID token's times
40
+ # (iat, nbf, exp) are checked: two minutes, as authlib's own OIDC client allows. Without
41
+ # it, a host a second behind a provider that stamps iat with the current second (such as
42
+ # Keycloak) has its sign-ins refused as "issued in the future".
43
+ CLOCK_SKEW_S = 120
44
+ _ISSUER_WARNED: set[tuple[str, str]] = set() # (configured, discovered): logged once
45
+
46
+
47
+ class InsecureEndpoint(ValueError):
48
+ """An address from the provider is neither https:// nor loopback http://; the text
49
+ says which, for the log."""
50
+
51
+
52
+ class TokenEndpointError(Exception):
53
+ """The token endpoint refused the code (an HTTP error answer); the text is for the log."""
54
+
55
+
56
+ def _loopback(host: str) -> bool:
57
+ if host.lower() == "localhost":
58
+ return True
59
+ try:
60
+ return ipaddress.ip_address(host).is_loopback
61
+ except ValueError:
62
+ return False
63
+
64
+
65
+ CALLBACK_PATH = "/auth/oidc/callback"
66
+
67
+
68
+ def redirect_uri(settings, request, public_url: str = "") -> str:
69
+ """The redirect URI a sign-in sends to the identity provider, which must have it
70
+ registered: oidc.redirect_uri when set; else, with a public URL (Settings -> Reverse
71
+ proxy), that URL and CALLBACK_PATH; else made from the request as it has been since
72
+ v2.3 - X-Forwarded-Proto or the request's scheme, X-Forwarded-Host or Host, and
73
+ CALLBACK_PATH. Forwarded and X-Forwarded-Port are not read: a working install with a
74
+ blank redirect_uri has this value registered, and reading them would change it. Of a
75
+ list that proxies in a row made (a, b), the first value counts: the one the browser
76
+ used (the whole list made no usable address). Settings shows the value for its own
77
+ request (redirect_uri_is_plain_http)."""
78
+ configured = settings.redirect_uri.strip()
79
+ if configured:
80
+ return configured
81
+ if public_url:
82
+ return public_url + CALLBACK_PATH
83
+ scheme = _first(request.headers.get("x-forwarded-proto")) or request.url.scheme
84
+ host = (_first(request.headers.get("x-forwarded-host")) or request.headers.get("host")
85
+ or request.url.netloc)
86
+ return f"{scheme}://{host}{CALLBACK_PATH}"
87
+
88
+
89
+ def _first(value: str | None) -> str:
90
+ return (value or "").split(",", 1)[0].strip()
91
+
92
+
93
+ def redirect_uri_is_plain_http(uri: str) -> bool:
94
+ """`uri` is an http:// address of another host than this machine's loopback: most
95
+ identity providers (Entra ID, Google, Okta) refuse to register such a redirect URI."""
96
+ try:
97
+ parts = urllib.parse.urlsplit(uri)
98
+ host = parts.hostname or ""
99
+ except ValueError:
100
+ return False
101
+ return parts.scheme.lower() == "http" and not _loopback(host)
102
+
103
+
104
+ def secure_url(url, what: str) -> str:
105
+ """`url` if it is https://, or http:// to a loopback address (127.0.0.0/8, ::1,
106
+ localhost: nothing leaves this machine — a provider on the same host). Raises
107
+ InsecureEndpoint for anything else, such as the http:// addresses a Keycloak behind a
108
+ TLS-terminating proxy advertises when its proxy settings are missing."""
109
+ try:
110
+ parts = urllib.parse.urlsplit(url if isinstance(url, str) else "")
111
+ host = parts.hostname
112
+ except ValueError: # such as an unclosed [IPv6 address
113
+ host = None
114
+ if host and (parts.scheme == "https" or (parts.scheme == "http" and _loopback(host))):
115
+ return url
116
+ raise InsecureEndpoint(
117
+ f"the identity provider's {what} {url!r} is not an https:// address, so OIDC sign-in "
118
+ "is refused (the client secret, the code or the signing keys would go in clear "
119
+ "text). Have the provider announce https:// addresses (behind a TLS proxy: its "
120
+ "proxy / frontend URL settings)")
121
+
122
+
123
+ class _SecureRedirects(urllib.request.HTTPRedirectHandler):
124
+ """Follows a redirect only to an address secure_url() allows."""
125
+
126
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
127
+ secure_url(newurl, "redirect")
128
+ return super().redirect_request(req, fp, code, msg, headers, newurl)
129
+
130
+
131
+ def _opener() -> urllib.request.OpenerDirector:
132
+ """A new one for each request: urllib's HTTPS handler loads the CA certificates when
133
+ it is made (Python 3.12+), and the standalone Linux binary points OpenSSL at the
134
+ system's CA bundle (ser2netweb/standalone.py: SSL_CERT_FILE) only after this module is
135
+ imported. One made at import would trust no provider there."""
136
+ return urllib.request.build_opener(_SecureRedirects)
137
+
138
+
139
+ def _get_json(url: str, timeout: float = 8):
140
+ req = urllib.request.Request( # noqa: S310 - https (secure_url)
141
+ url, headers={"Accept": "application/json", "User-Agent": user_agent()})
142
+ with _opener().open(req, timeout=timeout) as r:
143
+ return json.loads(r.read())
144
+
145
+
146
+ def _post_form(url: str, data: dict, timeout: float = 8):
147
+ body = urllib.parse.urlencode(data).encode()
148
+ req = urllib.request.Request(url, data=body, method="POST", # noqa: S310 - https (secure_url)
149
+ headers={"Content-Type": "application/x-www-form-urlencoded",
150
+ "Accept": "application/json",
151
+ "User-Agent": user_agent()})
152
+ try:
153
+ with _opener().open(req, timeout=timeout) as r:
154
+ return json.loads(r.read())
155
+ except urllib.error.HTTPError as e: # an OAuth error answer: say what it was
156
+ raise TokenEndpointError(f"the token endpoint refused the code: HTTP {e.code} "
157
+ f"{_error_text(e.read(4096))}") from None
158
+
159
+
160
+ def _error_text(body: bytes) -> str:
161
+ """An OAuth error answer (RFC 6749 5.2) for a log line: error (error_description)."""
162
+ try:
163
+ doc = json.loads(body)
164
+ except ValueError:
165
+ doc = None
166
+ if isinstance(doc, dict) and doc.get("error"):
167
+ text = repr(str(doc["error"])[:64])
168
+ if doc.get("error_description"):
169
+ text += f" ({str(doc['error_description'])[:200]!r})"
170
+ return text
171
+ return repr(body[:200].decode("utf-8", "replace"))
172
+
173
+
174
+ def discover(issuer: str, fetch=_get_json) -> dict:
175
+ issuer = issuer.rstrip("/")
176
+ cached = _DISCOVERY_CACHE.get(issuer)
177
+ if cached and (time.monotonic() - cached[1] < _DISCOVERY_TTL):
178
+ return cached[0]
179
+ doc = fetch(secure_url(issuer + "/.well-known/openid-configuration", "discovery document"))
180
+ if not isinstance(doc, dict):
181
+ raise ValueError("the discovery document is not a JSON object")
182
+ _DISCOVERY_CACHE[issuer] = (doc, time.monotonic())
183
+ return doc
184
+
185
+
186
+ def new_code_verifier() -> str:
187
+ """A PKCE code_verifier (RFC 7636: 43-128 unreserved characters; this is 64)."""
188
+ return secrets.token_urlsafe(48)
189
+
190
+
191
+ def code_challenge(verifier: str) -> str:
192
+ """The S256 code_challenge of a code_verifier."""
193
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
194
+ return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
195
+
196
+
197
+ def build_authorize_url(settings, redirect_uri: str, state: str, nonce: str, fetch=_get_json,
198
+ code_verifier: str = "") -> str:
199
+ doc = discover(settings.issuer, fetch=fetch)
200
+ params = {
201
+ "response_type": "code",
202
+ "client_id": settings.client_id,
203
+ "redirect_uri": redirect_uri,
204
+ "scope": settings.scopes or "openid email profile",
205
+ "state": state,
206
+ "nonce": nonce,
207
+ }
208
+ if code_verifier:
209
+ params.update(code_challenge=code_challenge(code_verifier), code_challenge_method="S256")
210
+ endpoint = secure_url(doc.get("authorization_endpoint"), "authorization endpoint")
211
+ return endpoint + ("&" if "?" in endpoint else "?") + urllib.parse.urlencode(params)
212
+
213
+
214
+ def _expected_issuer(settings, doc: dict, log) -> str:
215
+ """The iss the ID token must carry: the discovery document's issuer. One that is not
216
+ the configured issuer URL is logged once (reaching a provider through another URL than
217
+ its public one is common, so it is no reason to refuse)."""
218
+ configured = settings.issuer.rstrip("/")
219
+ issuer = str(doc.get("issuer") or configured)
220
+ if issuer.rstrip("/") != configured and (configured, issuer) not in _ISSUER_WARNED:
221
+ _ISSUER_WARNED.add((configured, issuer))
222
+ log(f"WARNING: OIDC: the discovery document of {configured!r} names the issuer "
223
+ f"{issuer!r}; ID tokens must come from {issuer!r}. If that is not the same "
224
+ f"provider under another address, correct the issuer URL in Settings → Single "
225
+ f"sign-on (OIDC)")
226
+ return issuer
227
+
228
+
229
+ def complete(settings, redirect_uri: str, code: str, nonce: str, logger=None,
230
+ fetch=_get_json, post=_post_form, code_verifier: str = "") -> dict | None:
231
+ """Exchange the auth code for tokens and validate the id_token. Returns the
232
+ verified claims, or None on any failure (never raises). code_verifier: the PKCE
233
+ verifier of this sign-in (none for a state cookie from before PKCE was sent)."""
234
+ log = logger or (lambda _m: None)
235
+ try:
236
+ from authlib.jose import JsonWebKey, jwt
237
+ from authlib.jose.errors import ExpiredTokenError, InvalidTokenError
238
+ except Exception as e: # not only ImportError (e.g. an authlib without authlib.jose)
239
+ log(f"OIDC sign-in disabled: {optional.problem(e, 'authlib')}")
240
+ return None
241
+ try:
242
+ doc = discover(settings.issuer, fetch=fetch)
243
+ request = {
244
+ "grant_type": "authorization_code", "code": code, "redirect_uri": redirect_uri,
245
+ "client_id": settings.client_id, "client_secret": settings.client_secret,
246
+ }
247
+ if code_verifier:
248
+ request["code_verifier"] = code_verifier
249
+ token = post(secure_url(doc.get("token_endpoint"), "token endpoint"), request)
250
+ id_token = token.get("id_token")
251
+ if not id_token:
252
+ log("OIDC: token response had no id_token")
253
+ return None
254
+ jwks = JsonWebKey.import_key_set(fetch(secure_url(doc.get("jwks_uri"), "jwks_uri")))
255
+ claims = jwt.decode(id_token, jwks, claims_options={ # checks the signature
256
+ "iss": {"essential": True, "value": _expected_issuer(settings, doc, log)},
257
+ "aud": {"essential": True, "value": settings.client_id},
258
+ "exp": {"essential": True}, # OIDC Core: an ID token always expires
259
+ })
260
+ try:
261
+ claims.validate(leeway=CLOCK_SKEW_S) # exp / iat / nbf
262
+ except (ExpiredTokenError, InvalidTokenError) as e:
263
+ log(f"OIDC: the ID token was refused ({e}): {_clock_hint(claims)}")
264
+ return None
265
+ if nonce and claims.get("nonce") != nonce:
266
+ log("OIDC: nonce mismatch (possible replay)")
267
+ return None
268
+ return dict(claims)
269
+ except (InsecureEndpoint, TokenEndpointError) as e:
270
+ log(f"OIDC sign-in failed: {e}")
271
+ return None
272
+ except Exception as e: # discovery/token/JWKS/JWT failure -> denied
273
+ log(f"OIDC authentication failed: {type(e).__name__}: {e}")
274
+ return None
275
+
276
+
277
+ def _clock_hint(claims) -> str:
278
+ """How far this host's clock seems off the provider's, for a token refused for its
279
+ times. The provider issued it (iat, under a signature already checked) a moment ago
280
+ by its own clock, so now - iat is about the difference between the two clocks."""
281
+ iat = claims.get("iat")
282
+ if isinstance(iat, bool) or not isinstance(iat, (int, float)):
283
+ return "check that this server's clock is right (time synchronisation, NTP)"
284
+ offset = round(time.time() - iat)
285
+ where = f"{-offset} s behind" if offset < 0 else f"{offset} s ahead of"
286
+ return (f"this server's clock is about {where} the identity provider's ({CLOCK_SKEW_S} s "
287
+ f"are allowed): check the time synchronisation (NTP) of this server and of the "
288
+ f"provider")
289
+
290
+
291
+ def _says_false(value) -> bool:
292
+ return value is False or (isinstance(value, str) and value.strip().lower() == "false")
293
+
294
+
295
+ def _username(claims: dict, settings) -> tuple[str, str]:
296
+ """(the user's name, "") or ("", why the ID token gives none)."""
297
+ for key in (settings.username_claim, "preferred_username", "email", "sub"):
298
+ value = claims.get(key)
299
+ if value:
300
+ if key == "email" and _says_false(claims.get("email_verified")):
301
+ # no fall-back to sub either: that would be another account
302
+ return "", (f"the ID token names the user by the e-mail address {str(value)!r}, "
303
+ f"which the provider has not verified (email_verified: false)")
304
+ return external_name(value), ""
305
+ return "", "the ID token names no user"
306
+
307
+
308
+ def username_from_claims(claims: dict, settings) -> str:
309
+ """The user's name: the username_claim, else preferred_username, email or sub,
310
+ spelled as LDAP/OIDC account names are kept (config.external_name). An e-mail address
311
+ the provider says it has not verified (email_verified: false; a missing claim is
312
+ fine — Entra ID rarely sends it) names nobody: ""."""
313
+ return _username(claims, settings)[0]
314
+
315
+
316
+ def no_username_reason(claims: dict, settings) -> str:
317
+ """Why username_from_claims() gave "", for the log."""
318
+ return _username(claims, settings)[1] or "the ID token names no user"
319
+
320
+
321
+ def groups_from_claims(claims: dict, settings) -> list[str]:
322
+ """The values of the groups claim (a list, or one value)."""
323
+ groups = claims.get(settings.groups_claim) or []
324
+ if not isinstance(groups, (list, tuple)):
325
+ groups = [groups]
326
+ return [str(g) for g in groups]
327
+
328
+
329
+ def role_from_claims(claims: dict, settings):
330
+ return role_for_groups(groups_from_claims(claims, settings), settings)