httpdis 0.6.28__tar.gz → 0.6.30__tar.gz

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 (35) hide show
  1. httpdis-0.6.30/PKG-INFO +470 -0
  2. httpdis-0.6.30/README.md +423 -0
  3. httpdis-0.6.30/RELEASE +1 -0
  4. httpdis-0.6.30/VERSION +1 -0
  5. httpdis-0.6.30/httpdis/auth_backend.py +320 -0
  6. httpdis-0.6.30/httpdis/auth_sqlite.py +207 -0
  7. httpdis-0.6.30/httpdis/authentication.py +76 -0
  8. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/config.py +1 -0
  9. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/ext/httpdis_json.py +11 -0
  10. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/httpdis.py +361 -209
  11. httpdis-0.6.30/httpdis.egg-info/PKG-INFO +470 -0
  12. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/SOURCES.txt +7 -0
  13. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/requires.txt +6 -0
  14. {httpdis-0.6.28 → httpdis-0.6.30}/setup.py +2 -0
  15. {httpdis-0.6.28 → httpdis-0.6.30}/setup.yml +2 -2
  16. httpdis-0.6.30/tests/test_auth_backend.py +250 -0
  17. httpdis-0.6.30/tests/test_auth_sqlite.py +222 -0
  18. httpdis-0.6.30/tests/test_authentication_provider.py +188 -0
  19. httpdis-0.6.30/tests/test_context.py +290 -0
  20. httpdis-0.6.28/PKG-INFO +0 -173
  21. httpdis-0.6.28/README.md +0 -130
  22. httpdis-0.6.28/RELEASE +0 -1
  23. httpdis-0.6.28/VERSION +0 -1
  24. httpdis-0.6.28/httpdis.egg-info/PKG-INFO +0 -173
  25. {httpdis-0.6.28 → httpdis-0.6.30}/LICENSE +0 -0
  26. {httpdis-0.6.28 → httpdis-0.6.30}/MANIFEST.in +0 -0
  27. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/__init__.py +0 -0
  28. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/ext/__init__.py +0 -0
  29. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/dependency_links.txt +0 -0
  30. {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/top_level.txt +0 -0
  31. {httpdis-0.6.28 → httpdis-0.6.30}/pyproject.toml +0 -0
  32. {httpdis-0.6.28 → httpdis-0.6.30}/requirements.txt +0 -0
  33. {httpdis-0.6.28 → httpdis-0.6.30}/setup.cfg +0 -0
  34. {httpdis-0.6.28 → httpdis-0.6.30}/tests/test_body_limits.py +0 -0
  35. {httpdis-0.6.28 → httpdis-0.6.30}/tests/test_httpdis.py +0 -0
@@ -0,0 +1,470 @@
1
+ Metadata-Version: 2.4
2
+ Name: httpdis
3
+ Version: 0.6.30
4
+ Summary: httpdis
5
+ Home-page: https://github.com/decryptus/httpdis
6
+ Author: Adrien Delle Cave
7
+ Author-email: pypi@doowan.net
8
+ License: License GPL-3
9
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
10
+ Classifier: Natural Language :: English
11
+ Classifier: Operating System :: Unix
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 2
14
+ Classifier: Programming Language :: Python :: 2.7
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.5
17
+ Classifier: Programming Language :: Python :: 3.6
18
+ Classifier: Programming Language :: Python :: 3.7
19
+ Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
20
+ Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: LEPL; python_version < "3.6"
24
+ Requires-Dist: python-magic
25
+ Requires-Dist: sonicprobe>=0.3.52
26
+ Requires-Dist: rfc6266; python_version < "3.4"
27
+ Requires-Dist: rfc6266-parser; python_version >= "3.4" and python_version < "3.6"
28
+ Requires-Dist: uc-rfc6266-parser; python_version >= "3.6"
29
+ Requires-Dist: six>=1.13.0
30
+ Requires-Dist: legacy-cgi; python_version >= "3.13"
31
+ Requires-Dist: legacycrypt; python_version >= "3.13"
32
+ Provides-Extra: auth
33
+ Requires-Dist: argon2-cffi<26,>=23.1; python_version >= "3.10" and extra == "auth"
34
+ Requires-Dist: sonicprobe>=0.3.55; extra == "auth"
35
+ Dynamic: author
36
+ Dynamic: author-email
37
+ Dynamic: classifier
38
+ Dynamic: description
39
+ Dynamic: description-content-type
40
+ Dynamic: home-page
41
+ Dynamic: license
42
+ Dynamic: license-file
43
+ Dynamic: provides-extra
44
+ Dynamic: requires-dist
45
+ Dynamic: requires-python
46
+ Dynamic: summary
47
+
48
+ # HTTPdis
49
+
50
+ A small synchronous HTTP dispatcher for Python services: named and regex routes,
51
+ JSON/form payloads, responses, static files and Basic authentication.
52
+ Used by [dwho](https://github.com/decryptus/dwho), Covenant and Auton.
53
+ **HTTPdis is a reference to the TARDIS** in Doctor Who, matching the naming of
54
+ Sonicprobe, dwho and Auton. This is independent software, not an official product.
55
+
56
+ ## When to use it
57
+
58
+ HTTPdis is useful for maintaining and extending services already built around its
59
+ request handlers and lifecycle hooks. It uses the Python standard HTTP server and
60
+ sonicprobe workers; it is not an ASGI server. For an unrelated new application,
61
+ compare the maintenance cost of this custom stack with a maintained web framework.
62
+
63
+ ## Installation
64
+
65
+ ```sh
66
+ python -m pip install httpdis
67
+ ```
68
+
69
+ The declared range remains Python 2.7 and Python 3.5+. Legacy installations require
70
+ compatible dependency versions. On Python 3.13+, `legacy-cgi` and `legacycrypt`
71
+ replace removed standard-library APIs while preserving multipart and password-file
72
+ interfaces. Static MIME detection requires libmagic. See the CI matrix for actual
73
+ tested interpreters and the tests for the covered behaviors.
74
+
75
+ ## Minimal JSON service
76
+
77
+ ```python
78
+ from httpdis.ext import httpdis_json as server
79
+
80
+ def health(request):
81
+ return {'status': 'ok'}
82
+
83
+ server.register(health, 'GET', name='health')
84
+ options = {'listen_addr': '127.0.0.1', 'listen_port': 8080, 'max_workers': 2}
85
+ server.init(options)
86
+ server.run(options)
87
+ ```
88
+
89
+ ```sh
90
+ curl http://127.0.0.1:8080/health
91
+ ```
92
+
93
+ Handlers receive a request with `get_path()`, `query_params()`, `payload_params()`,
94
+ `get_headers()` and `get_server_vars()`. They may return data or an `HttpResponse`
95
+ / `HttpResponseJson` to control status and headers. `register` supports method
96
+ lists, compiled regular expressions and `safe_init`, `at_start`, `at_stop` hooks.
97
+ Routes and options are process-global; use a separate process for independent apps.
98
+
99
+ ## Request body limits
100
+
101
+ Since HTTPdis 0.6.28, `register(..., max_body_size=...)` sets the body limit
102
+ for a named or regex route. It applies to POST, PUT and PATCH before reading or
103
+ parsing the body; oversized requests return HTTP 413.
104
+
105
+ ```python
106
+ server.register(action_handler, 'POST', name='v1/actions', max_body_size=1024)
107
+ server.register(notification_handler, 'POST', name='v1/notifications',
108
+ max_body_size=64 * 1024)
109
+ ```
110
+
111
+ Define your handlers before registering them. The value is a non-negative integer
112
+ number of **bytes**. `0` allows only an empty body; `None` or an omitted argument
113
+ uses the current global `max_body_size` option (1 MiB by default). A route value
114
+ replaces the global default and may be smaller or larger. It does not change other
115
+ routes or the global option. Negative values, booleans, floats and strings are
116
+ rejected during registration.
117
+
118
+ Existing registrations and positional arguments remain compatible. JSON services
119
+ using `httpdis.ext.httpdis_json.register` share the same option. GET/HEAD/DELETE
120
+ continue to use the query handler; this option does not change their behavior.
121
+
122
+ ## Authentication and deployment
123
+
124
+ Configure `auth_basic_file` with a trusted htpasswd file and `auth_basic` with the
125
+ realm. Set `to_auth=True` on protected routes, or use a username list such as
126
+ `to_auth=['alice']`. A protected route without configured authentication now returns
127
+ 401 rather than allowing the request. Invalid credentials are rejected; request
128
+ credentials are isolated between threads. Existing `{SHA}` and system crypt hashes
129
+ remain readable for compatibility; legacy SHA-1/DES hashes are not recommendations
130
+ for new password storage. Basic credentials require HTTPS in transit.
131
+
132
+ Bind to loopback or a private interface behind a reverse proxy providing TLS,
133
+ request timeouts, connection limits and access controls. This release does not
134
+ claim complete HTTP parser hardening for hostile public traffic. Configure
135
+ `max_body_size` to limit request bodies. Chunked request bodies are not supported.
136
+ Internal exceptions are logged server-side and return a generic 500 to clients.
137
+
138
+ ## Static files
139
+
140
+ A static route uses `static=True` and `root='/srv/public'`. Regex routes can use
141
+ `replacement` to map URLs to filenames. Resolved symlinks outside the root are
142
+ rejected. Treat the static directory as administrator-controlled; these checks are
143
+ not a filesystem sandbox against concurrent hostile filesystem modifications.
144
+ Invalid `If-Modified-Since` values are ignored. Files are buffered in memory, so
145
+ serve large downloads through the reverse proxy.
146
+
147
+ ## Compatibility fixes
148
+
149
+ - Correct UTF-8 response byte lengths and duplicate Content-Type/Length headers.
150
+ - Correct Basic authentication on Python 3 and username-list registration.
151
+ - Keep credentials isolated across request threads and reject malformed headers.
152
+ - Reject missing authentication on protected routes and truncated request bodies.
153
+ - Resolve static paths before checking containment; tolerate invalid dates.
154
+ - Keep removed CGI/crypt functionality available through compatibility packages.
155
+
156
+ The dependency loop with sonicprobe is retained because sonicprobe's historical
157
+ HTTP JSON module re-exports HTTPdis. A future major release should untangle it.
158
+
159
+ ## Development and publication
160
+
161
+ ```sh
162
+ python -m pip install -e . mock
163
+ python -m unittest discover -s tests -v
164
+ python -m pip install build twine
165
+ python -m build
166
+ python -m twine check --strict dist/*
167
+ ```
168
+
169
+ Update `VERSION`, `RELEASE` and `setup.yml` together. After tests and distribution
170
+ validation succeed, the master publication workflow creates `vX.Y.Z` and uploads
171
+ via Trusted Publishing (`decryptus/httpdis`, `pypi.yml`, environment `pypi`).
172
+ Already-tagged versions are not replaced by ordinary master commits.
173
+
174
+ License: GPL-3.0-or-later. Original authors and Wazo/Proformatique copyrights are
175
+ preserved in the source files.
176
+
177
+ See the [September 2026 code and architecture review](docs/REVIEW.md) (French).
178
+
179
+
180
+ ### Independent embedded servers
181
+
182
+ Use `HttpServerContext` when multiple HTTPdis servers must coexist in one process.
183
+ Each context owns its routes, options, authentication object and lifecycle state:
184
+
185
+ ```python
186
+ from httpdis.ext.httpdis_json import HttpServerContext
187
+
188
+ api = HttpServerContext()
189
+ api.register(lambda request: {'status': 'ready'}, 'GET', name='health')
190
+ api.init({'listen_addr': '127.0.0.1', 'listen_port': 8666,
191
+ 'max_body_size': 1048576})
192
+ api.run() # Blocking; another thread or the launcher may call api.stop().
193
+ ```
194
+
195
+ `httpdis.httpdis.HttpServerContext` uses the plain HTTP handler;
196
+ `httpdis.ext.httpdis_json.HttpServerContext` uses the JSON handler. The registration
197
+ arguments and route callbacks match the existing module API. Callbacks can obtain
198
+ the owning context through `request.get_context()`. Application services should
199
+ still receive explicit decoded values and caller identity, not HTTP requests.
200
+
201
+ `run(options=None, http_req_handler=..., http_server_class=...)` binds a private
202
+ handler subclass, so server version settings and mutable content-type lists do
203
+ not modify the supplied handler class or another server. Omitting `options`
204
+ passes the context's initialized options to `at_start`; supplying it preserves
205
+ the historical callback argument behavior. `context.server` exposes the running
206
+ transport (including the actual port when listening on port 0).
207
+
208
+ For a separately constructed stdlib-compatible HTTP server, use
209
+ `context.bind_handler(YourHandler)` or assign `server.httpdis_context = context`
210
+ before serving requests. The bound handler carries its context explicitly.
211
+
212
+ Register routes and initialize before serving. A context rejects concurrent
213
+ `run()` calls and reinitialization while running. `stop()` affects only that
214
+ context and is idempotent until the next `init()`. A stopped context must be
215
+ initialized before restarting. Reinitialization retains registered routes, as
216
+ with the historical API. This is not a hot-reconfiguration interface. Hooks still
217
+ run per registered method/route entry; sharing application objects in callbacks
218
+ is the caller's responsibility. Transport shutdown retains Sonicprobe's existing
219
+ worker behavior; it does not forcibly cancel running application callbacks.
220
+
221
+ Signals remain process-wide. Context initialization does **not** install handlers
222
+ unless `use_sigterm_handler=True` is explicitly requested. In an embedded process,
223
+ let the launcher choose which contexts to stop.
224
+
225
+ ### Compatibility with the global API
226
+
227
+ The module-level `register`, `init`, `run`, `stop` and `sigterm_handler` functions
228
+ remain available with their existing signatures, including the JSON wrappers.
229
+ They delegate to a default context. Historical `_COMMANDS`, `_NCMD`, `_RCMD`,
230
+ `_OPTIONS`, `_AUTH`, `_HTTP_SERVER` and `_KILLED` attributes still reflect that
231
+ context, including direct reassignment. Handlers used without an explicit context
232
+ continue to use this default. Global `init()` still installs signal handlers by
233
+ default. These global calls remain a single shared server configuration; use
234
+ explicit contexts for independent servers.
235
+
236
+ Routes, authentication, response formats, route/global body-limit fallback and
237
+ lifecycle callback arguments remain compatible. Handler classes are now bound
238
+ through a subclass rather than modified in place. Repeated `stop()` calls no
239
+ longer repeat shutdown hooks. Startup/serving failures close the created socket,
240
+ and shutdown-hook failures still trigger transport cleanup.
241
+
242
+ The default schema is defined once in `httpdis.config`. Both historical
243
+ `DEFAULT_OPTIONS` import paths remain independent dictionaries with the same
244
+ initial values; `get_default_options()` returns a fresh dictionary. Mutating an
245
+ export is not a way to reconfigure an already initialized context.
246
+
247
+
248
+ ## Application-owned authentication providers (development)
249
+
250
+ The embedding daemon may supply `auth_provider` when initializing a server context.
251
+ This is an additive extension, not a new default authentication backend. HTTPdis
252
+ neither chooses credential storage nor opens a database for this interface.
253
+
254
+ ```python
255
+ from httpdis.authentication import AuthenticationProvider, Identity
256
+ from httpdis.ext.httpdis_json import HttpServerContext
257
+
258
+ class DaemonProvider(AuthenticationProvider):
259
+ challenge = 'Bearer'
260
+
261
+ def __init__(self, credential_service):
262
+ self.credentials = credential_service
263
+
264
+ def authenticate(self, request):
265
+ # The supplied service verifies expiry/revocation and returns an account.
266
+ account = self.credentials.verify(request.header('authorization'))
267
+ if account is None:
268
+ return None
269
+ return Identity(account.name, 'token', account.scopes)
270
+
271
+ context = HttpServerContext()
272
+ # credential_service is constructed/configured by the embedding application.
273
+ # context.init({'auth_provider': DaemonProvider(credential_service), ...})
274
+ ```
275
+
276
+ Use the same `auth_provider` option on the existing options object or module-level
277
+ `init()` facade when needed. Independent daemons must use independent
278
+ `HttpServerContext` instances; the historical module facade remains a singleton.
279
+ DWho/application configuration should construct a provider explicitly and pass the
280
+ instance. No dynamic backend import, YAML syntax, credential path or default store
281
+ is introduced by HTTPdis here.
282
+
283
+ A provider implements `authenticate(AuthenticationRequest)` and returns an
284
+ immutable `Identity(principal, method, scopes)`. It may return `None` or raise
285
+ `AuthenticationDenied` for invalid/missing/expired/revoked credentials. Backend
286
+ failure, including `AuthenticationUnavailable`, produces a generic HTTP 503;
287
+ exception details are not exposed or logged by the adapter. There is no fallback
288
+ to Basic or anonymous access after provider failure. A fixed optional `challenge`
289
+ sets WWW-Authenticate on HTTP 401. Route user allowlists still apply (HTTP 403).
290
+
291
+ The request contains the method, parsed path without query parameters, selected
292
+ security headers as immutable pairs, and the direct socket peer address. Header
293
+ lookup is case-insensitive; duplicate security headers are rejected. Forwarded
294
+ identity headers are never trusted or passed through this contract. No HTTP
295
+ handler, request body or mutable server context is passed to the provider. Do not
296
+ log header values: they contain credentials and cookies. The request repr is redacted.
297
+
298
+ Successful requests expose `HTTP_AUTH_USER` for existing applications and
299
+ `HTTP_AUTH_IDENTITY` for the verified method/scopes. They never expose a password.
300
+ **Scopes are data, not automatic authorization:** applications must enforce them
301
+ alongside endpoint/owner/maintenance permissions before accepting scoped tokens.
302
+ Authentication applies only to routes registered with `to_auth`; this extension
303
+ does not silently make public routes private.
304
+
305
+ Providers and their storage adapters must support concurrent calls. Their lifecycle,
306
+ configuration, defaults, persistence, revocation and shutdown belong to the daemon.
307
+ Two contexts may use distinct provider instances and stores without sharing state.
308
+ Sharing a provider is an explicit application decision. HTTPdis does not cache
309
+ provider identities or take ownership of the supplied backend.
310
+
311
+ ### Compatibility and remaining work
312
+
313
+ Without `auth_provider`, Basic, `auth_basic_file`, `auth_basic`, route allowlists
314
+ and the historical API keep their behavior. Configuring both a provider and
315
+ `auth_basic_file` is rejected rather than establishing an implicit fallback.
316
+ The new contract uses syntax supported by the existing Python compatibility matrix
317
+ and adds no required dependency.
318
+
319
+ The provider contract alone does not supply accounts or credential verification;
320
+ the optional local service described below supplies those separately. Browser login
321
+ HTTP routes and TOTP enrollment/replay protection remain pending. The contract does
322
+ not configure cookies, HTTPS, CSRF or CORS automatically.
323
+ Browser sessions must not be exposed until those transport controls and the backend
324
+ are implemented and tested together. Existing HTTPdis CORS/OPTIONS behavior is
325
+ unchanged by this compatibility-preserving addition.
326
+
327
+ ## Local authentication backend (development, optional)
328
+
329
+ `httpdis.auth_backend.LocalAuthService` supplies local account, opaque session and
330
+ opaque API token behavior behind the provider contract. **The daemon must supply
331
+ both a store and a password adapter.** No file path, database, credentials, accounts
332
+ or HTTP login routes are created by importing HTTPdis.
333
+
334
+ ```python
335
+ from httpdis.auth_backend import LocalAuthService, Argon2Passwords, BearerAuthProvider
336
+
337
+ # store is selected and constructed by the application, not HTTPdis.
338
+ # auth = LocalAuthService(store=store, passwords=Argon2Passwords(), audit=audit)
339
+ # context.init({'auth_provider': BearerAuthProvider(auth), ...})
340
+ ```
341
+
342
+ Install `httpdis[auth]` on Python 3.10+ to use the optional maintained
343
+ `argon2-cffi` adapter. It creates Argon2id password hashes. The core/provider
344
+ contract and injected service remain compatible with the legacy interpreter
345
+ matrix, without installing that optional dependency there. No weak password
346
+ implementation is supplied as a fallback. The password adapter contract is
347
+ `hash(password) -> encoded_hash` and `verify(encoded_hash, password) -> bool`;
348
+ backend/configuration errors must raise, not return a successful identity.
349
+
350
+ ### Administration and account changes
351
+
352
+ `provision(principal, password, scopes)` creates or replaces an account. Replacing
353
+ an account rotates its revision and invalidates all existing sessions/tokens.
354
+ `disable(principal)` disables login and invalidates existing credentials.
355
+ `issue_token(principal, scopes, ttl)` requires a scope subset of the enabled
356
+ account, an explicit TTL no longer than 30 days, and returns a one-time secret plus
357
+ a credential ID for `revoke_token(credential_id)`. These are **trusted administrative
358
+ service methods**, not unauthenticated user operations. The embedding application
359
+ must authorize any management interface it builds around them.
360
+
361
+ The service validates identity/scope structure using the provider contract. It
362
+ never interprets Auton endpoint names or maintenance permissions. Consumers must
363
+ apply the verified scopes to business operations. Newly provisioned passwords
364
+ must have at least 12 characters and no more than 1,024 UTF-8 bytes; no password
365
+ normalization or silent truncation is performed. Applications may impose stronger
366
+ password/enrollment policies before provisioning. Updating Argon2 parameters can
367
+ be handled by explicit credential rotation; automatic rehash migration is not
368
+ implemented in this first adapter.
369
+
370
+ ### Sessions, tokens and bounded work
371
+
372
+ `login(principal, password, peer)` returns a session grant with its secret, CSRF
373
+ secret, expiry and identity. `authenticate_session(secret, csrf, mutation=True)`
374
+ checks the CSRF secret before refreshing idle expiry. Session absolute expiry is
375
+ 8 hours and idle expiry 30 minutes by default, configurable downward at service
376
+ construction. Every request checks the enabled account and its revision.
377
+ `logout(secret)` revokes that session. Rotation/revocation does not undo work
378
+ already authorized or cancel application jobs.
379
+
380
+ Secrets use 32 bytes of OS randomness. Only SHA-256 digests of session/token/CSRF
381
+ secrets are stored; account passwords use the injected password hasher. Raw secrets
382
+ are returned to the caller for delivery, never logged by the service. Grant reprs
383
+ are redacted. `BearerAuthProvider` accepts only explicit Authorization Bearer
384
+ credentials and checks the token on every protected request; there is no Basic
385
+ fallback or implicit cookie/session acceptance.
386
+
387
+ Login work is bounded to two concurrent password verifications per service instance.
388
+ A transactional 60-second fixed window allows 5 attempts per account, 20 per direct
389
+ peer, and 100 globally per store. Successful attempts count too. Unknown accounts
390
+ still perform dummy password verification after admission. Applications should
391
+ also limit login traffic at their trusted ingress; this bounded local policy can
392
+ reject legitimate logins during a distributed attack. Supply the actual socket
393
+ peer or a separately validated trusted-proxy result, never a raw user-controlled
394
+ forwarded header. Each table is capped at 4,096 records by default (configurable
395
+ downward). Expired entries are cleaned opportunistically; active credentials are
396
+ not evicted merely to make room. Capacity exhaustion fails closed.
397
+
398
+ An optional audit callback receives fixed event names and, where known, the
399
+ principal, never passwords, hashes, tokens, headers or private backend errors.
400
+ Events cover account updates/disable, login success/denial/throttling, token issue/
401
+ revocation/denial and session revocation/denial. Routine successful credential
402
+ checks do not generate audit writes. Audit sink errors are logged generically and
403
+ do not alter authentication outcomes; a deployment requiring transactional audit
404
+ must provide a stronger integration rather than assuming this callback is durable.
405
+
406
+ ### Store contract and deployment limits
407
+
408
+ The store supplies `transaction()` yielding an adapter with `get(table, key)`,
409
+ `put(table, key, value)`, `delete(table, key)` and `items(table)`. Values are detached
410
+ copies. Transactions serialize the whole block and roll back on exceptions;
411
+ `items` returns a stable snapshot, and deleting a missing key is harmless. The
412
+ namespaces are `accounts`, `sessions`, `tokens`, `attempts`. Records include account
413
+ revision, scopes and Unix expiry timestamps; use a trusted clock consistent across
414
+ workers. Sharing a store between service instances is an explicit choice and also
415
+ shares rate-limit counters. Durable adapters must preserve atomicity across
416
+ processes, protect stored password hashes and make account changes visible to all
417
+ workers. HTTPdis does not open or close a caller-owned store.
418
+
419
+ `MemoryAuthStore` is an explicitly chosen single-process adapter for development
420
+ and tests. Its data is lost on restart, including accounts, tokens and rate limits;
421
+ it provides **no restart durability or multi-process coordination**.
422
+
423
+ ### Durable SQLite authentication
424
+
425
+ Install `httpdis[auth]` (Sonicprobe >= 0.3.55) to use the existing AnySQL SQLite
426
+ adapter with automatic reconnect disabled. The embedding daemon chooses the
427
+ filename, creates its private parent directory, and owns the store lifecycle:
428
+
429
+ ```python
430
+ from httpdis.auth_sqlite import SQLiteAuthStore
431
+ from httpdis.auth_backend import LocalAuthService, Argon2Passwords
432
+
433
+ store = SQLiteAuthStore('/var/lib/my-daemon/auth/auth.db', timeout=5)
434
+ try:
435
+ service = LocalAuthService(store, Argon2Passwords())
436
+ # Supply service to your provider and trusted administration interface.
437
+ # Stop request workers before closing the store.
438
+ finally:
439
+ store.close()
440
+ ```
441
+
442
+ There is no default filename and no automatic account creation. Existing Basic
443
+ and provider configurations are unaffected. The database must be a local regular
444
+ file, owned by the daemon user with no group/other permissions (created 0600).
445
+ The parent must be owned by that user and not writable by group/others; keep the
446
+ path and its ancestors under trusted administration. Symlinks, hard links and
447
+ replacement of an open store's file are rejected. Use a dedicated authentication
448
+ database, independent of job history. Network filesystems are not supported.
449
+
450
+ Each transaction opens its own AnySQL connection in the calling thread, takes
451
+ `BEGIN IMMEDIATE`, commits on success, and closes on every exit (rolling back
452
+ uncommitted work). `synchronous=FULL`, the DELETE journal and secure deletion are
453
+ selected explicitly. Lock waits are bounded by `timeout` (0 < seconds <= 30).
454
+ Multiple threads/processes can use the same database; create one store per process
455
+ after forking. Failures are surfaced without reconnect/replay or memory fallback.
456
+
457
+ Accounts, sessions, token revocations and rate-limit counters survive restart.
458
+ Passwords remain hashes; session/token/CSRF secrets are not stored in plaintext.
459
+ This is not encryption at rest: protect the database and backups as credentials.
460
+ Stop all writers before copying the database for backup. Only schema version 1
461
+ is accepted; incompatible databases are refused, never silently reset. JSON
462
+ records are bounded to 64 KiB and support the existing four namespaces. Redis
463
+ and automatic schema migrations are not supplied by this adapter.
464
+
465
+ **Browser integration is still pending:** this backend does not expose login/logout
466
+ routes, set cookies, configure HTTPS/CORS, enforce request Origin or provide TOTP.
467
+ The caller must mark every cookie-authenticated mutation for CSRF validation; do
468
+ not expose a cookie provider without the complete browser transport protections.
469
+ Only the token-only provider is supplied in this step. Session/login APIs are
470
+ neutral services ready for the subsequent transport integration.