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.
- httpdis-0.6.30/PKG-INFO +470 -0
- httpdis-0.6.30/README.md +423 -0
- httpdis-0.6.30/RELEASE +1 -0
- httpdis-0.6.30/VERSION +1 -0
- httpdis-0.6.30/httpdis/auth_backend.py +320 -0
- httpdis-0.6.30/httpdis/auth_sqlite.py +207 -0
- httpdis-0.6.30/httpdis/authentication.py +76 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/config.py +1 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/ext/httpdis_json.py +11 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/httpdis.py +361 -209
- httpdis-0.6.30/httpdis.egg-info/PKG-INFO +470 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/SOURCES.txt +7 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/requires.txt +6 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/setup.py +2 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/setup.yml +2 -2
- httpdis-0.6.30/tests/test_auth_backend.py +250 -0
- httpdis-0.6.30/tests/test_auth_sqlite.py +222 -0
- httpdis-0.6.30/tests/test_authentication_provider.py +188 -0
- httpdis-0.6.30/tests/test_context.py +290 -0
- httpdis-0.6.28/PKG-INFO +0 -173
- httpdis-0.6.28/README.md +0 -130
- httpdis-0.6.28/RELEASE +0 -1
- httpdis-0.6.28/VERSION +0 -1
- httpdis-0.6.28/httpdis.egg-info/PKG-INFO +0 -173
- {httpdis-0.6.28 → httpdis-0.6.30}/LICENSE +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/MANIFEST.in +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/__init__.py +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis/ext/__init__.py +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/dependency_links.txt +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/httpdis.egg-info/top_level.txt +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/pyproject.toml +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/requirements.txt +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/setup.cfg +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/tests/test_body_limits.py +0 -0
- {httpdis-0.6.28 → httpdis-0.6.30}/tests/test_httpdis.py +0 -0
httpdis-0.6.30/PKG-INFO
ADDED
|
@@ -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.
|