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,308 @@
1
+ """Health, Prometheus metrics and the serial port list."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import platform
6
+ import sys
7
+
8
+ from starlette.responses import JSONResponse, PlainTextResponse
9
+ from starlette.routing import Route
10
+
11
+ from ... import __version__, i18n, licences, storage
12
+ from ...notify import no_data_for
13
+ from ...engine import netguard, portlist
14
+ from ...i18n import _
15
+ from .. import auth, proxy
16
+ from .common import Ctx, local_path, unchanged_or
17
+
18
+ # the serial sides of a mapping form (GET /api/ports/select?prefix=)
19
+ _PORT_FIELDS = ("serial_", "serial_b_")
20
+
21
+
22
+ def routes(ctx: Ctx) -> list:
23
+ state, render = ctx.state, ctx.render
24
+
25
+ async def healthz(request):
26
+ return PlainTextResponse("ok")
27
+
28
+ async def licenses_page(request):
29
+ """The licence texts this copy carries (ser2netweb/licences.py), for any signed-in role."""
30
+ texts = await asyncio.to_thread(licences.texts)
31
+ return render(request, "licenses.html", texts=texts)
32
+
33
+ async def metrics(request):
34
+ return PlainTextResponse(await metrics_text(state), media_type=METRICS_TYPE)
35
+
36
+ async def api_ports_json(request):
37
+ return JSONResponse(await state.ports.current())
38
+
39
+ async def api_ports_select(request):
40
+ """An open mapping form's Device field again, with the serial ports there are now
41
+ (its ↻ button): ?prefix=serial_|serial_b_&selected=<what the form has chosen>. For
42
+ operators, as the form is."""
43
+ if deny := ctx.require_role(request, "operator"):
44
+ return deny
45
+ prefix = request.query_params.get("prefix", "")
46
+ if prefix not in _PORT_FIELDS:
47
+ return PlainTextResponse(_("Unknown serial port field."), status_code=400)
48
+ selected = request.query_params.get("selected", "")[:1024]
49
+ ports = portlist.visible(await state.ports.current())
50
+ return render(request, "_serial_port_select.html", fragment=True, prefix=prefix,
51
+ selected=selected, ports=ports, links=portlist.links(ports, (selected,)))
52
+
53
+ async def api_ports_table(request):
54
+ ports = await state.ports.current()
55
+ show_all = request.query_params.get("all") == "1"
56
+ shown = portlist.visible(ports, show_all)
57
+ # refreshed every 5 s: 204 while the ports are what the browser shows already
58
+ # (rendered off the event loop: see Ctx.arender)
59
+ return unchanged_or(request, await ctx.arender(
60
+ request, "_ports_table.html", ports=shown, show_all=show_all,
61
+ hidden=len(ports) - len(portlist.visible(ports)),
62
+ in_use=portlist.used(shown, state.supervisor.devices_in_use())))
63
+
64
+ async def set_language(request):
65
+ """/lang/tr?next=/settings: remember the visitor's UI language (a cookie), then
66
+ go back. Only a local path is followed (no open redirect), under the path prefix
67
+ the request came under (`next` is the page's path without it)."""
68
+ code = request.path_params["code"]
69
+ resp = proxy.redirect(request, local_path(request.query_params.get("next")))
70
+ if code in i18n.LANGUAGES:
71
+ auth.set_cookie(resp, request, state.config, i18n.COOKIE, code, max_age=365 * 86400)
72
+ return resp
73
+
74
+ return [
75
+ Route("/lang/{code}", set_language),
76
+ Route("/healthz", healthz),
77
+ Route("/licenses", licenses_page),
78
+ Route("/metrics", metrics),
79
+ Route("/api/ports.json", api_ports_json),
80
+ Route("/api/ports/select", api_ports_select),
81
+ Route("/api/ports/table", api_ports_table),
82
+ ]
83
+
84
+
85
+ # the exposition format /metrics and /api/v1/metrics answer in
86
+ METRICS_TYPE = "text/plain; version=0.0.4"
87
+
88
+
89
+ async def metrics_text(state) -> str:
90
+ """The Prometheus metrics (text exposition format: exposition()): served at /metrics to
91
+ a web UI session and at /api/v1/metrics to an API token."""
92
+ statuses = state.supervisor.all_status()
93
+ lines = [
94
+ "# ser2netweb metrics",
95
+ "ser2net_up 1",
96
+ *process_metrics(state),
97
+ f"ser2net_mappings_total {len(state.config.mappings)}",
98
+ ]
99
+ # the process's open files and their limit (POSIX: what serial ports, sockets and
100
+ # files share; not reported on Windows)
101
+ fds, fd_limit = netguard.open_fds(), netguard.fd_limit()
102
+ if fds is not None:
103
+ lines.append(f"ser2net_open_fds {fds}")
104
+ if fd_limit is not None:
105
+ lines.append(f"ser2net_fd_limit {fd_limit}")
106
+ # the data folder's disk (traces pause below storage.floor()) and what traces and
107
+ # logs take there
108
+ data_dir = getattr(state, "data_dir", None)
109
+ if data_dir is not None:
110
+ disk = await asyncio.to_thread(storage.usage, data_dir)
111
+ if disk["free"] is not None:
112
+ lines.append(f"ser2net_data_free_bytes {disk['free']}")
113
+ lines.append(f"ser2net_data_size_bytes {disk['total']}")
114
+ lines.append(f"ser2net_traces_bytes {disk['traces']}")
115
+ lines.append(f"ser2net_logs_bytes {disk['logs']}")
116
+ guard = getattr(state, "admin_guard", None)
117
+ if guard is not None:
118
+ lines.append(f"ser2net_admin_connections {len(guard.connections)}")
119
+ budget = netguard.BUDGET
120
+ lines.append(f"ser2net_tls_handshakes_in_progress {len(budget.handshakes)}")
121
+ lines.append(f"ser2net_tls_handshakes_waiting {len(budget.waiting)}") # for a slot
122
+ # connections refused right after accept: near the open-file limit or (Windows) the
123
+ # event loop's socket limit, too many TLS handshakes, the admin UI's own limits
124
+ for why in netguard.REFUSAL_REASONS:
125
+ lines.append(f'ser2net_connections_refused_total{{reason="{why}"}} '
126
+ f"{budget.refused.get(why, 0)}")
127
+ for m in state.config.mappings:
128
+ st = statuses.get(m.id) or {}
129
+ lbl = f'mapping="{_metric_label(m.name)}",id="{_metric_label(m.id)}"'
130
+ running = 1 if st.get("state") == "running" else 0
131
+ lines += [
132
+ *mapping_state_metrics(m, st, lbl),
133
+ *device_traffic_metrics(m, st, lbl),
134
+ f"ser2net_mapping_running{{{lbl}}} {running}",
135
+ f"ser2net_mapping_clients{{{lbl}}} {st.get('client_count', 0)}",
136
+ # bytes read from / written to the serial device, counted once at the device;
137
+ # dropped: sent for the device but not written (see RunnerStatus)
138
+ f"ser2net_mapping_bytes_in_total{{{lbl}}} {st.get('bytes_in', 0)}",
139
+ f"ser2net_mapping_bytes_out_total{{{lbl}}} {st.get('bytes_out', 0)}",
140
+ f"ser2net_mapping_bytes_dropped_total{{{lbl}}} {st.get('bytes_dropped', 0)}",
141
+ f"ser2net_mapping_reconnects_total{{{lbl}}} {st.get('reconnects', 0)}",
142
+ # of those: failed opens of the serial port, and losses of the open port
143
+ f"ser2net_mapping_open_failures_total{{{lbl}}} {st.get('open_failures', 0)}",
144
+ f"ser2net_mapping_device_lost_total{{{lbl}}} {st.get('device_lost', 0)}",
145
+ f"ser2net_mapping_dropped_clients_total{{{lbl}}} {st.get('dropped_clients', 0)}",
146
+ ]
147
+ if m.kind == "net" and m.network.mode == "client":
148
+ # the connection out to the remote server (ser2net_mapping_running is the
149
+ # serial side's)
150
+ up = 1 if st.get("link") == "up" else 0
151
+ lines += [
152
+ f"ser2net_mapping_link_up{{{lbl}}} {up}",
153
+ f"ser2net_mapping_connect_failures_total{{{lbl}}} "
154
+ f"{st.get('connect_failures', 0)}",
155
+ ]
156
+ # Modbus gateways in edge mode: each polled unit, up = it answers (left out until it
157
+ # has been polled), and its failed point reads
158
+ units = [(m, u) for m in state.config.mappings
159
+ for u in (statuses.get(m.id) or {}).get("units") or []]
160
+ for m, u in units:
161
+ if u.get("state") in ("online", "offline"):
162
+ lines.append(f"ser2net_modbus_unit_up{{{_unit_label(m, u)}}} "
163
+ f"{1 if u['state'] == 'online' else 0}")
164
+ for m, u in units:
165
+ lines.append(f"ser2net_modbus_unit_poll_errors_total{{{_unit_label(m, u)}}} "
166
+ f"{u.get('errors', 0)}")
167
+ # mappings that publish to MQTT (while they run): connected to the broker, and the
168
+ # messages not handed to it (see MqttPublisher.state)
169
+ brokers = [(m, mq) for m in state.config.mappings
170
+ if (mq := (statuses.get(m.id) or {}).get("mqtt"))]
171
+ for m, mq in brokers:
172
+ lines.append(f"ser2net_mqtt_connected{{{_label(m)}}} "
173
+ f"{1 if mq.get('state') == 'connected' else 0}")
174
+ for m, mq in brokers:
175
+ lines.append(f"ser2net_mqtt_messages_dropped_total{{{_label(m)}}} "
176
+ f"{mq.get('dropped', 0)}")
177
+ return exposition(lines)
178
+
179
+
180
+ # The # HELP and # TYPE of each series /metrics answers (text exposition format 0.0.4).
181
+ # The names stay as they are, ser2net_mappings_total too (a gauge despite its suffix).
182
+ METRIC_INFO = {
183
+ "ser2net_up": ("gauge", "1 while ser2netweb answers"),
184
+ "ser2net_build_info": ("gauge", "The version that runs (labels), always 1"),
185
+ "ser2net_start_time_seconds": ("gauge", "When this ser2netweb process started (Unix time)"),
186
+ "ser2net_event_loop_lag_seconds": ("gauge", "How late the event loop's last heartbeat "
187
+ "was (a loop that is held up)"),
188
+ "ser2net_event_loop_stalls_total": ("counter", "Heartbeats of the event loop 2 s or more "
189
+ "late"),
190
+ "ser2net_mappings_total": ("gauge", "Mappings configured"),
191
+ "ser2net_open_fds": ("gauge", "Files the process has open (POSIX)"),
192
+ "ser2net_fd_limit": ("gauge", "The process's open-file limit (POSIX)"),
193
+ "ser2net_data_free_bytes": ("gauge", "Free space on the data folder's disk"),
194
+ "ser2net_data_size_bytes": ("gauge", "Size of the data folder's disk"),
195
+ "ser2net_traces_bytes": ("gauge", "What the trace files take in the data folder"),
196
+ "ser2net_logs_bytes": ("gauge", "What the logs take in the data folder"),
197
+ "ser2net_admin_connections": ("gauge", "Connections to the admin UI"),
198
+ "ser2net_tls_handshakes_in_progress": ("gauge", "TLS handshakes under way"),
199
+ "ser2net_tls_handshakes_waiting": ("gauge", "Connections waiting for a TLS handshake slot"),
200
+ "ser2net_connections_refused_total": ("counter", "Connections refused right after accept, "
201
+ "by reason"),
202
+ "ser2net_mapping_enabled": ("gauge", "1 when the mapping is enabled, 0 when it was "
203
+ "stopped (or is off)"),
204
+ "ser2net_mapping_state": ("gauge", "1 for the mapping's state now (label state), 0 for "
205
+ "the others"),
206
+ "ser2net_mapping_running": ("gauge", "1 while the mapping runs"),
207
+ "ser2net_mapping_last_rx_timestamp_seconds": ("gauge", "When the serial device last sent "
208
+ "something (Unix time; 0: not since "
209
+ "the start)"),
210
+ "ser2net_mapping_no_data": ("gauge", "1 while the device is past the mapping's no-data "
211
+ "alarm"),
212
+ "ser2net_mapping_clients": ("gauge", "Clients connected to the mapping"),
213
+ "ser2net_mapping_bytes_in_total": ("counter", "Bytes read from the serial device"),
214
+ "ser2net_mapping_bytes_out_total": ("counter", "Bytes written to the serial device"),
215
+ "ser2net_mapping_bytes_dropped_total": ("counter", "Bytes for the serial device that "
216
+ "were not written"),
217
+ "ser2net_mapping_reconnects_total": ("counter", "Reconnects after the serial port failed "
218
+ "or went away"),
219
+ "ser2net_mapping_open_failures_total": ("counter", "Failed opens of the serial port"),
220
+ "ser2net_mapping_device_lost_total": ("counter", "Losses of the open serial port"),
221
+ "ser2net_mapping_dropped_clients_total": ("counter", "Clients dropped for not reading "
222
+ "fast enough"),
223
+ "ser2net_mapping_link_up": ("gauge", "1 while a connect-out mapping is connected"),
224
+ "ser2net_mapping_connect_failures_total": ("counter", "Failed connect-out attempts"),
225
+ "ser2net_modbus_unit_up": ("gauge", "1 while a polled Modbus unit answers"),
226
+ "ser2net_modbus_unit_poll_errors_total": ("counter", "Failed point reads of a Modbus unit"),
227
+ "ser2net_mqtt_connected": ("gauge", "1 while the mapping is connected to its MQTT broker"),
228
+ "ser2net_mqtt_messages_dropped_total": ("counter", "MQTT messages not handed to the "
229
+ "broker"),
230
+ }
231
+
232
+ # The states a mapping's runner has (RunnerStatus.state): ser2net_mapping_state has one
233
+ # series for each
234
+ MAPPING_STATES = ("running", "reconnecting", "device-missing", "error", "stopped")
235
+
236
+
237
+ def process_metrics(state) -> list[str]:
238
+ """The version that runs, when it started and how its event loop keeps up."""
239
+ labels = (f'version="{_metric_label(__version__)}",'
240
+ f'python="{_metric_label(platform.python_version())}",'
241
+ f'platform="{_metric_label(sys.platform)}"')
242
+ lines = [f"ser2net_build_info{{{labels}}} 1"]
243
+ started = getattr(state, "started_at", None)
244
+ if started is not None:
245
+ lines.append(f"ser2net_start_time_seconds {started:.3f}")
246
+ dog = getattr(state, "loop_watchdog", None) # (ser2netweb/watchdog.py)
247
+ if dog is not None:
248
+ lines.append(f"ser2net_event_loop_lag_seconds {dog.lag:.3f}")
249
+ lines.append(f"ser2net_event_loop_stalls_total {dog.slow_beats}")
250
+ return lines
251
+
252
+
253
+ def mapping_state_metrics(mapping, status: dict, lbl: str) -> list[str]:
254
+ """Whether the mapping is enabled (a mapping stopped on purpose is not; one that
255
+ failed is) and its state, one-hot."""
256
+ now = status.get("state") or "stopped"
257
+ states = MAPPING_STATES if now in MAPPING_STATES else (*MAPPING_STATES, now)
258
+ return [f"ser2net_mapping_enabled{{{lbl}}} {1 if mapping.enabled else 0}"] + [
259
+ f'ser2net_mapping_state{{{lbl},state="{_metric_label(s)}"}} {1 if s == now else 0}'
260
+ for s in states]
261
+
262
+
263
+ def device_traffic_metrics(mapping, status: dict, lbl: str) -> list[str]:
264
+ """When the device last sent something, and, with its no-data alarm on, whether it is
265
+ past it (notify.no_data_for)."""
266
+ lines = [f"ser2net_mapping_last_rx_timestamp_seconds{{{lbl}}} "
267
+ f"{float(status.get('last_rx') or 0):.3f}"]
268
+ if mapping.options.no_data_alarm_s:
269
+ lines.append(f"ser2net_mapping_no_data{{{lbl}}} {1 if no_data_for(mapping, status) else 0}")
270
+ return lines
271
+
272
+
273
+ def _series(line: str) -> str:
274
+ """The series name of a sample line."""
275
+ return line.split("{", 1)[0].split(" ", 1)[0]
276
+
277
+
278
+ def exposition(lines: list[str]) -> str:
279
+ """The metrics text from its sample lines: the samples of each series together (in
280
+ the order the series first appear), behind its # HELP and # TYPE lines (METRIC_INFO;
281
+ a series without an entry gets none), comment lines first."""
282
+ comments = [ln for ln in lines if ln.startswith("#")]
283
+ groups: dict[str, list[str]] = {}
284
+ for ln in lines:
285
+ if not ln.startswith("#"):
286
+ groups.setdefault(_series(ln), []).append(ln)
287
+ out = list(comments)
288
+ for name, samples in groups.items():
289
+ if name in METRIC_INFO:
290
+ kind, text = METRIC_INFO[name]
291
+ out += [f"# HELP {name} {text}", f"# TYPE {name} {kind}"]
292
+ out += samples
293
+ return "\n".join(out) + "\n"
294
+
295
+
296
+ def _label(mapping) -> str:
297
+ return f'mapping="{_metric_label(mapping.name)}",id="{_metric_label(mapping.id)}"'
298
+
299
+
300
+ def _unit_label(mapping, unit: dict) -> str:
301
+ return (f'mapping="{_metric_label(mapping.name)}",id="{_metric_label(mapping.id)}",'
302
+ f'unit="{unit.get("unit")}"')
303
+
304
+
305
+ def _metric_label(name: str) -> str:
306
+ """Escape a mapping name (or id) for a Prometheus label value."""
307
+ return name.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ")
308
+
@@ -0,0 +1,282 @@
1
+ """Two-factor sign-in (TOTP, ser2netweb/web/totp.py) for local accounts: the code step of a
2
+ sign-in, and setting it up or turning it off (Settings → Two-factor sign-in).
3
+
4
+ Off unless an account sets it up. A local account with User.totp_secret signs in in two
5
+ steps: /login checks the password as always, then (challenge) sets a short-lived signed
6
+ cookie naming the account instead of a session and sends the browser to /auth/totp, which
7
+ asks for the code of the authenticator app and only then gives the session. A wrong code
8
+ counts against the address, together with wrong passwords (AppState.rate_limiter), and
9
+ against the account (CODE_ATTEMPTS in CODE_WINDOW_S); a code accepted once is not
10
+ accepted again (the replay guard is in memory: after a restart, a code used just before
11
+ it could be used once more within its 90 s window).
12
+
13
+ Lost authenticator: an admin turns it off in Settings → Users, or `ser2netweb --set-password
14
+ NAME` on the server (ser2netweb/accounts.py) sets a new password and turns it off — also for the
15
+ only admin, and with ser2netweb stopped.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ from starlette.routing import Route
20
+
21
+ from ... import notify
22
+ from ...config import ConfigError
23
+ from ...i18n import _
24
+ from .. import auth, proxy, totp
25
+ from ..auth import LoginRateLimiter
26
+ from .common import Ctx, csrf_failed, local_path
27
+ from .settings import _Flash
28
+
29
+ PAGE = "/settings/totp" # Settings → Two-factor sign-in
30
+ PENDING_COOKIE = "ser2net_2fa" # its name for a request: auth.set_cookie (proxy.cookie_name)
31
+ PENDING_PATH = "/auth/totp" # also its Path (under the public URL's path)
32
+ PENDING_TTL_S = 300 # from the password to the code
33
+ ENROL_TTL_S = 1800 # from showing a new key to confirming it with a code
34
+ CODE_ATTEMPTS = 5 # wrong codes for one account ...
35
+ CODE_WINDOW_S = 300 # ... in this many seconds, then it must wait
36
+ # the code forms are a few short fields
37
+ FORM_MAX_BYTES = 64 * 1024
38
+ FORM_LIMITS = {"max_files": 0, "max_fields": 8, "max_part_size": 16 * 1024}
39
+ NO_STORE = {"Cache-Control": "no-store"} # a page with a key or a code step
40
+
41
+
42
+ def challenge(ctx: Ctx, request, user, nxt: str = ""):
43
+ """`user`'s password was right and their account takes a code too: no session yet,
44
+ the pending cookie for the code step instead (/auth/totp). `nxt`: the page the
45
+ sign-in goes on to (/login?next=, a path without the base path), carried in the
46
+ cookie ("x") to the code step."""
47
+ state = ctx.state
48
+ resp = proxy.redirect(request, PENDING_PATH)
49
+ payload = {"p": "totp", "u": user.username, "v": user.pwd_version}
50
+ if nxt := local_path(nxt, ""):
51
+ payload["x"] = nxt
52
+ auth.set_cookie(resp, request, state.config, PENDING_COOKIE,
53
+ auth.sign_payload(state.config.secret_key, payload,
54
+ ttl_seconds=PENDING_TTL_S),
55
+ max_age=PENDING_TTL_S, path=PENDING_PATH)
56
+ state.log(f"login: password of {user.username} accepted from {ctx.client_ip(request)}; "
57
+ "waiting for the two-factor code")
58
+ return resp
59
+
60
+
61
+ def routes(ctx: Ctx) -> list:
62
+ state, render, client_ip = ctx.state, ctx.render, ctx.client_ip
63
+ current_user, set_session = ctx.current_user, ctx.set_session
64
+ code_limiter = LoginRateLimiter(CODE_ATTEMPTS, CODE_WINDOW_S) # per account
65
+ # what turning it on or off said, for the page its redirect leads to (as Settings does:
66
+ # Post/Redirect/Get), by the browser's CSRF token and the account
67
+ flash = _Flash()
68
+ last_step: dict[str, int] = {} # account -> the time step of its last accepted code
69
+
70
+ def _check(user, code) -> bool:
71
+ """Is `code` a valid code of `user`'s secret now, and not one used before? Then it
72
+ is used up."""
73
+ step = totp.verify(user.totp_secret, code, last_step.get(user.username, -1))
74
+ if step is None:
75
+ return False
76
+ last_step[user.username] = step
77
+ return True
78
+
79
+ # ---------------- the code step of a sign-in ----------------
80
+ def _pending(request) -> dict | None:
81
+ data = auth.read_payload(state.config.secret_key,
82
+ auth.cookie(request, PENDING_COOKIE, PENDING_PATH, legacy=False))
83
+ return data if data and data.get("p") == "totp" else None
84
+
85
+ def _pending_next(request) -> str:
86
+ """Where the sign-in goes on to once the code is right (challenge's `nxt`); "" for
87
+ the dashboard (also a cookie from before it was carried)."""
88
+ data = _pending(request)
89
+ return local_path(data.get("x"), "") if data else ""
90
+
91
+ def _pending_user(request):
92
+ """The account whose password the pending cookie vouches for, while it still takes
93
+ a code: same password version (no password change or sign-out since) and two-factor
94
+ sign-in still on. None otherwise."""
95
+ data = _pending(request)
96
+ if not data or not isinstance(data.get("u"), str):
97
+ return None
98
+ user = state.config.get_user(data["u"])
99
+ if user is None or not user.totp_on or user.pwd_version != data.get("v"):
100
+ return None
101
+ return user
102
+
103
+ def _code_page(request, user, status_code=200, error=None):
104
+ return render(request, "login_totp.html", status_code=status_code, error=error,
105
+ username=user.username, headers=NO_STORE)
106
+
107
+ def _start_again(request, status_code, error):
108
+ resp = render(request, "login.html", status_code=status_code, error=error,
109
+ oidc_enabled=state.config.oidc.enabled, next=_pending_next(request))
110
+ auth.delete_cookie(resp, request, state.config, PENDING_COOKIE, PENDING_PATH)
111
+ return resp
112
+
113
+ async def code_get(request):
114
+ user = _pending_user(request)
115
+ if user is None:
116
+ return proxy.redirect(request, "/login")
117
+ return _code_page(request, user)
118
+
119
+ async def code_post(request):
120
+ form = await request.form(**FORM_LIMITS)
121
+ if not auth.csrf_token_matches(request, form.get("_csrf")):
122
+ return csrf_failed()
123
+ ip = client_ip(request)
124
+ user = _pending_user(request)
125
+ if user is None:
126
+ return _start_again(request, 401, _("The sign-in took too long or was ended. "
127
+ "Sign in again."))
128
+ if state.rate_limiter.blocked(ip): # wrong passwords and codes from this address
129
+ return _start_again(request, 429, _("Too many attempts. Wait a few minutes and "
130
+ "try again."))
131
+ if code_limiter.blocked(user.username):
132
+ return _start_again(request, 429, _("Too many wrong codes. Wait a few minutes "
133
+ "and sign in again."))
134
+ if not _check(user, form.get("code")):
135
+ state.rate_limiter.record_failure(ip)
136
+ code_limiter.record_failure(user.username)
137
+ state.log(f"failed two-factor code for {user.username!r} from {ip}")
138
+ state.failed_logins.add(ip, user.username, "login_failed", "two-factor code")
139
+ state.notifier.emit("login_failed", ip, "", notify.sign_in_detail(
140
+ state.config.notifications, user.username, ip, "", "wrong two-factor code"))
141
+ return _code_page(request, user, 401, _(
142
+ "That code is not right. Enter the code your app shows now; if it never "
143
+ "works, the clock of this server or of your device is off."))
144
+ state.rate_limiter.reset(ip)
145
+ state.name_limiter.reset(user.username) # as a sign-in with the password alone
146
+ code_limiter.reset(user.username)
147
+ state.log(f"login: {user.username} ({user.role}, local, two-factor) from {ip}")
148
+ ctx.audit(request, "login", f"{user.role}, local, two-factor", user=user.username)
149
+ resp = proxy.redirect(request, _pending_next(request) or "/")
150
+ set_session(resp, request, user)
151
+ ctx.new_csrf_token(request)
152
+ auth.delete_cookie(resp, request, state.config, PENDING_COOKIE, PENDING_PATH)
153
+ return resp
154
+
155
+ # ---------------- setting it up / turning it off (Settings) ----------------
156
+ def _browser(request) -> str:
157
+ return getattr(request.state, "csrf_token", None) or ""
158
+
159
+ def _done(request, me, ok: str):
160
+ """A form that did its work: back to the page (a reload doesn't post it again, the
161
+ TR / EN switch has a page to go back to), which says `ok`; the session renewed
162
+ (it ended the account's other sessions)."""
163
+ flash.put(_browser(request), me.username, ok=ok)
164
+ resp = proxy.redirect(request, PAGE)
165
+ set_session(resp, request, me)
166
+ return resp
167
+
168
+ def _page(request, status_code=200, ok=None, error=None, secret=None):
169
+ """Settings → Two-factor sign-in: a new key to set up (or `secret`, the one being
170
+ set up), or, while it is on, the form to turn it off. A page answered to a form
171
+ (refused) names the page's own address (page_url)."""
172
+ me = current_user(request)
173
+ if request.method == "GET" and me is not None and (
174
+ done := flash.take(_browser(request), me.username)):
175
+ ok = done["ok"]
176
+ refusal = None
177
+ if me is None or me.source == "anonymous":
178
+ refusal = _("Sign in to set up two-factor sign-in.")
179
+ elif me.source != "local":
180
+ refusal = _("Your account signs in with {0}: a second factor for it is set up "
181
+ "there (in the directory or the identity provider).").format(
182
+ me.source.upper())
183
+ ctx_vars: dict = {"ok": ok, "error": error, "refusal": refusal, "me": me,
184
+ "enabled": bool(me is not None and me.totp_on)}
185
+ if me is not None and refusal is None and not ctx_vars["enabled"]:
186
+ secret = secret or totp.new_secret()
187
+ ctx_vars.update(secret_grouped=totp.grouped(secret),
188
+ uri=totp.otpauth_uri(secret, me.username),
189
+ enrol=auth.sign_payload(state.config.secret_key,
190
+ {"p": "totp-enrol", "u": me.username,
191
+ "s": secret}, ttl_seconds=ENROL_TTL_S))
192
+ return render(request, "totp.html", status_code=status_code, headers=NO_STORE,
193
+ page_url=None if request.method == "GET" else PAGE, **ctx_vars)
194
+
195
+ async def settings_page(request):
196
+ return _page(request)
197
+
198
+ async def _password_ok(me, password) -> bool:
199
+ # (scrypt: with the sign-ins' limit on such work at a time, AppState.password_work)
200
+ return await state.password_work.run(auth.verify_password, str(password or ""),
201
+ me.password_hash)
202
+
203
+ async def _store(request, me, secret: str):
204
+ """Save `secret` ("" = off) for the signed-in account and end its other sessions
205
+ (pwd_version + 1); None when saved, else the page with the error."""
206
+ try:
207
+ async with state.edit_config():
208
+ user = state.config.get_user(me.username)
209
+ if user is None or user is not me: # deleted or replaced meanwhile
210
+ return _page(request, 409, error=_("Your account changed meanwhile. Sign "
211
+ "in again."))
212
+ user.totp_secret, user.pwd_version = secret, user.pwd_version + 1
213
+ except ConfigError as e: # not saved: nothing changed
214
+ return _page(request, 400, error=str(e))
215
+ return None
216
+
217
+ async def enable_post(request):
218
+ form = await request.form(**FORM_LIMITS)
219
+ if not auth.csrf_token_matches(request, form.get("_csrf")):
220
+ return csrf_failed()
221
+ me = current_user(request)
222
+ if me is None or me.source != "local":
223
+ return _page(request, 400) # the refusal
224
+ if me.totp_on:
225
+ return proxy.redirect(request, PAGE) # on already: the page says so
226
+ data = auth.read_payload(state.config.secret_key, form.get("enrol"))
227
+ if (not data or data.get("p") != "totp-enrol" or data.get("u") != me.username
228
+ or not totp.is_secret(data.get("s"))):
229
+ return _page(request, 400, error=_("This setup has expired. Add the new key below "
230
+ "to your app and try again."))
231
+ secret = data["s"]
232
+ if not await _password_ok(me, form.get("password")):
233
+ return _page(request, 400, error=_("Current password is incorrect."), secret=secret)
234
+ step = totp.verify(secret, form.get("code"))
235
+ if step is None:
236
+ return _page(request, 400, secret=secret, error=_(
237
+ "That code is not right. Enter the code your app shows now for this key; if "
238
+ "it never works, the clock of this server or of your device is off."))
239
+ if failed := await _store(request, me, secret):
240
+ return failed
241
+ last_step[me.username] = step
242
+ state.log(f"two-factor sign-in turned on for {me.username}; their other sessions "
243
+ "were signed out")
244
+ ctx.audit(request, "totp_enable", me.username)
245
+ return _done(request, me, _("Two-factor sign-in is on: signing in now takes a code from "
246
+ "your app too. Your other sessions were signed out."))
247
+
248
+ async def disable_post(request):
249
+ form = await request.form(**FORM_LIMITS)
250
+ if not auth.csrf_token_matches(request, form.get("_csrf")):
251
+ return csrf_failed()
252
+ me = current_user(request)
253
+ if me is None or me.source != "local":
254
+ return _page(request, 400) # the refusal
255
+ if not me.totp_on:
256
+ return proxy.redirect(request, PAGE) # off already: the page says so
257
+ if not await _password_ok(me, form.get("password")):
258
+ return _page(request, 400, error=_("Current password is incorrect."))
259
+ if code_limiter.blocked(me.username):
260
+ return _page(request, 429, error=_("Too many wrong codes. Wait a few minutes and "
261
+ "try again."))
262
+ if not _check(me, form.get("code")):
263
+ code_limiter.record_failure(me.username)
264
+ return _page(request, 400, error=_("That code is not right. Enter the code your "
265
+ "app shows now."))
266
+ if failed := await _store(request, me, ""):
267
+ return failed
268
+ state.log(f"two-factor sign-in turned off for {me.username}; their other sessions "
269
+ "were signed out")
270
+ ctx.audit(request, "totp_disable", me.username)
271
+ return _done(request, me, _("Two-factor sign-in is off: your password alone signs you "
272
+ "in. Your other sessions were signed out."))
273
+
274
+ return [
275
+ Route(PENDING_PATH, code_get, methods=["GET"]),
276
+ Route(PENDING_PATH, code_post, methods=["POST"], max_body_size=FORM_MAX_BYTES),
277
+ Route(PAGE, settings_page, methods=["GET"]),
278
+ Route("/settings/totp/enable", enable_post, methods=["POST"],
279
+ max_body_size=FORM_MAX_BYTES),
280
+ Route("/settings/totp/disable", disable_post, methods=["POST"],
281
+ max_body_size=FORM_MAX_BYTES),
282
+ ]