gavvahar-access-kit 1.0.1__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.
- gavvahar_access_kit-1.0.1/.gitignore +27 -0
- gavvahar_access_kit-1.0.1/LICENSE +21 -0
- gavvahar_access_kit-1.0.1/PKG-INFO +308 -0
- gavvahar_access_kit-1.0.1/README.md +274 -0
- gavvahar_access_kit-1.0.1/pyproject.toml +47 -0
- gavvahar_access_kit-1.0.1/src/access_kit/__init__.py +0 -0
- gavvahar_access_kit-1.0.1/src/access_kit/_http.py +54 -0
- gavvahar_access_kit-1.0.1/src/access_kit/_redis.py +43 -0
- gavvahar_access_kit-1.0.1/src/access_kit/budget.py +167 -0
- gavvahar_access_kit-1.0.1/src/access_kit/errors.py +9 -0
- gavvahar_access_kit-1.0.1/src/access_kit/health.py +42 -0
- gavvahar_access_kit-1.0.1/src/access_kit/http.py +62 -0
- gavvahar_access_kit-1.0.1/src/access_kit/jobs.py +206 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/__init__.py +0 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/core.py +77 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/factory.py +23 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/http.py +68 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/providers.py +95 -0
- gavvahar_access_kit-1.0.1/src/access_kit/llm/types.py +56 -0
- gavvahar_access_kit-1.0.1/src/access_kit/logging.py +97 -0
- gavvahar_access_kit-1.0.1/src/access_kit/notify.py +110 -0
- gavvahar_access_kit-1.0.1/src/access_kit/privacy.py +45 -0
- gavvahar_access_kit-1.0.1/src/access_kit/py.typed +0 -0
- gavvahar_access_kit-1.0.1/src/access_kit/ratelimit.py +94 -0
- gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/__init__.py +0 -0
- gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/errors.py +25 -0
- gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/fetcher.py +147 -0
- gavvahar_access_kit-1.0.1/src/access_kit/safe_fetch/ipcheck.py +59 -0
- gavvahar_access_kit-1.0.1/src/access_kit/session.py +124 -0
- gavvahar_access_kit-1.0.1/src/access_kit/settings.py +30 -0
- gavvahar_access_kit-1.0.1/src/access_kit/testing/__init__.py +0 -0
- gavvahar_access_kit-1.0.1/src/access_kit/testing/fakes.py +35 -0
- gavvahar_access_kit-1.0.1/src/access_kit/testing/fixtures.py +18 -0
- gavvahar_access_kit-1.0.1/src/access_kit/testing/ssrf_cases.py +59 -0
- gavvahar_access_kit-1.0.1/src/access_kit/turnstile.py +61 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
.lh
|
|
2
|
+
.env
|
|
3
|
+
.vscode
|
|
4
|
+
.giga
|
|
5
|
+
.cursor
|
|
6
|
+
.cursorrules
|
|
7
|
+
AGENTS.md
|
|
8
|
+
copilot-instructions.md
|
|
9
|
+
CLAUDE.md
|
|
10
|
+
node_modules
|
|
11
|
+
.venv
|
|
12
|
+
.claude
|
|
13
|
+
|
|
14
|
+
__pycache__/
|
|
15
|
+
*.py[cod]
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
.mypy_cache/
|
|
18
|
+
.ruff_cache/
|
|
19
|
+
.coverage
|
|
20
|
+
htmlcov/
|
|
21
|
+
.tox/
|
|
22
|
+
**/dist/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
*.tgz
|
|
25
|
+
|
|
26
|
+
web/test-results/
|
|
27
|
+
web/playwright-report/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nihar Gavva
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: gavvahar-access-kit
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Shared backend toolkit for ClearRead and SoundSight
|
|
5
|
+
Project-URL: Documentation, https://github.com/gavvahar/access-kit/blob/main/docs/api.md
|
|
6
|
+
Project-URL: Issues, https://github.com/gavvahar/access-kit/issues
|
|
7
|
+
Project-URL: Repository, https://github.com/gavvahar/access-kit
|
|
8
|
+
Author: Nihar Gavva
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: accessibility,fastapi,redis,ssrf
|
|
12
|
+
Requires-Python: >=3.15
|
|
13
|
+
Requires-Dist: fastapi<1,>=0.115
|
|
14
|
+
Requires-Dist: httpx<1,>=0.28
|
|
15
|
+
Requires-Dist: pydantic-settings<3,>=2.7
|
|
16
|
+
Requires-Dist: pydantic<3,>=2.9
|
|
17
|
+
Requires-Dist: redis<9,>=5
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
20
|
+
Requires-Dist: fakeredis[lua]>=2.26; extra == 'dev'
|
|
21
|
+
Requires-Dist: httpx<1,>=0.28; extra == 'dev'
|
|
22
|
+
Requires-Dist: mypy>=1.14; extra == 'dev'
|
|
23
|
+
Requires-Dist: pre-commit>=4; extra == 'dev'
|
|
24
|
+
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest-cov>=6; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
27
|
+
Requires-Dist: ruff>=0.9; extra == 'dev'
|
|
28
|
+
Requires-Dist: tox>=4.24; extra == 'dev'
|
|
29
|
+
Provides-Extra: testing
|
|
30
|
+
Requires-Dist: fakeredis[lua]>=2.26; extra == 'testing'
|
|
31
|
+
Requires-Dist: pytest-asyncio>=0.25; extra == 'testing'
|
|
32
|
+
Requires-Dist: pytest>=8; extra == 'testing'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# access-kit Python
|
|
36
|
+
|
|
37
|
+
Typed backend primitives for ClearRead and SoundSight. Use the latest stable Python 3 release.
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
The PyPI distribution is `gavvahar-access-kit`; Python imports use `access_kit`.
|
|
42
|
+
The prepared Python release is `1.0.1` (publication status is in the roadmap).
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
python -m pip install 'gavvahar-access-kit==1.0.1'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
From the repository root:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
python -m pip install -e './python[dev]'
|
|
52
|
+
pytest
|
|
53
|
+
mypy
|
|
54
|
+
python -m build python
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Settings
|
|
58
|
+
|
|
59
|
+
Subclass `access_kit.settings.AccessKitSettings` for application-specific fields.
|
|
60
|
+
Process environment is loaded case-insensitively. Required fields:
|
|
61
|
+
|
|
62
|
+
| Variable | Validation |
|
|
63
|
+
| ----------------- | ------------------------------ |
|
|
64
|
+
| `APP_NAME` | Nonempty string |
|
|
65
|
+
| `PUBLIC_BASE_URL` | HTTP or HTTPS URL |
|
|
66
|
+
| `REDIS_URL` | Redis DSN |
|
|
67
|
+
| `SESSION_SECRET` | Secret, at least 32 characters |
|
|
68
|
+
| `IP_HASH_SALT` | Secret, at least 32 characters |
|
|
69
|
+
|
|
70
|
+
`ENV` is `dev`, `test`, or `prod` (default `dev`).
|
|
71
|
+
`TRUST_CLOUDFLARE_HEADERS` defaults to false. Enable it only when the origin
|
|
72
|
+
accepts verified Cloudflare connections and configure trusted proxy networks in
|
|
73
|
+
`client_ip`; a header alone never establishes proxy trust.
|
|
74
|
+
|
|
75
|
+
Dotenv loading is opt-in: `Settings(_env_file=".env")`.
|
|
76
|
+
Secret fields are redacted in representations; do not log full settings objects,
|
|
77
|
+
validation error dictionaries, connection URLs, or raw input.
|
|
78
|
+
|
|
79
|
+
The configuration uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
|
|
80
|
+
|
|
81
|
+
## Health
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
from fastapi import FastAPI
|
|
85
|
+
from access_kit.health import health_router
|
|
86
|
+
|
|
87
|
+
app = FastAPI()
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
async def database_ready() -> bool:
|
|
91
|
+
# Replace with the app's asynchronous database ping.
|
|
92
|
+
return True
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
app.include_router(health_router({"database": database_ready}, timeout=2.0))
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Checks run concurrently. Any exception, timeout, or return value other than
|
|
99
|
+
`True` yields HTTP 503. A healthy response is:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{ "status": "ok", "checks": { "database": "ok" } }
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Responses use `Cache-Control: no-store` and never contain exception messages.
|
|
106
|
+
Check names are public: use names such as `database`, not connection strings.
|
|
107
|
+
Checks must use asynchronous I/O and cooperate with cancellation. Timeouts cannot
|
|
108
|
+
interrupt blocking code. Without checks, `/healthz` is a liveness endpoint.
|
|
109
|
+
|
|
110
|
+
HTTP status handling follows [FastAPI's response API](https://fastapi.tiangolo.com/advanced/additional-status-codes/).
|
|
111
|
+
|
|
112
|
+
## Logging and request IDs
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
import logging
|
|
116
|
+
from access_kit.logging import request_id_middleware, setup_logging
|
|
117
|
+
|
|
118
|
+
setup_logging(settings)
|
|
119
|
+
app = request_id_middleware(app)
|
|
120
|
+
logging.info("request_done", extra={"status_code": 200, "duration_ms": 12})
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Wrap the complete ASGI app so error responses also receive `X-Request-ID`.
|
|
124
|
+
IDs are generated on the server and isolated between concurrent requests.
|
|
125
|
+
`get_request_id()` returns the current ID and resets after the request.
|
|
126
|
+
|
|
127
|
+
The default JSON handler keeps constant event names, safe numeric fields, known
|
|
128
|
+
HTTP methods/provider names, and validated request IDs. It drops bodies, headers,
|
|
129
|
+
URLs, IPs, arbitrary metadata, formatted arguments, exception text, and tracebacks.
|
|
130
|
+
Use constant event names: never put user text in an event name. Configure logging
|
|
131
|
+
at process startup, before installing additional handlers. Separate log handlers
|
|
132
|
+
installed by an app must apply their own equivalent redaction.
|
|
133
|
+
|
|
134
|
+
## Privacy and anonymous sessions
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from access_kit.privacy import client_ip, hash_ip
|
|
138
|
+
from access_kit.session import session_middleware
|
|
139
|
+
|
|
140
|
+
app = session_middleware(app, secret=settings.session_secret.get_secret_value())
|
|
141
|
+
# Inside a request handler:
|
|
142
|
+
# peer = client_ip(request)
|
|
143
|
+
# identifier = hash_ip(peer, settings.ip_hash_salt.get_secret_value()) if peer else None
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`client_ip` ignores forwarding headers by default. Cloudflare extraction requires
|
|
147
|
+
both `trust_cloudflare=True` and explicit `trusted_proxies` CIDRs. The ASGI client
|
|
148
|
+
address must be the actual socket peer; unconditional upstream proxy-header
|
|
149
|
+
rewriting would undermine that check. Keep proxy networks current in the app.
|
|
150
|
+
Malformed or duplicate Cloudflare headers fall back to the verified peer.
|
|
151
|
+
|
|
152
|
+
`hash_ip` uses HMAC-SHA256 and a 32-byte minimum salt, normalizing equivalent IPv6
|
|
153
|
+
and mapped IPv4 literals. The application owns retention/deletion; there is no
|
|
154
|
+
generic SQL deletion helper. Rotating the salt changes identifiers.
|
|
155
|
+
|
|
156
|
+
Use `Depends(get_session_id)` from `access_kit.session` to read the anonymous ID.
|
|
157
|
+
Cookies are HMAC-signed, expire after one year, and use HttpOnly, Secure,
|
|
158
|
+
SameSite=Lax, and Path=/. Pass `secure=False` only for local HTTP development.
|
|
159
|
+
Tampered or expired cookies are replaced without raising a request error.
|
|
160
|
+
|
|
161
|
+
`rotate_session(request)` changes the current ID before response headers are sent.
|
|
162
|
+
Stateless rotation does not revoke old signed cookies. Apps that need revocation
|
|
163
|
+
must reject the old ID in their data store. The cookie is not authentication or
|
|
164
|
+
CSRF protection.
|
|
165
|
+
|
|
166
|
+
## Safe fetching
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from pathlib import Path
|
|
170
|
+
from access_kit.safe_fetch.fetcher import make_fetcher
|
|
171
|
+
|
|
172
|
+
fetch, download = make_fetcher(max_bytes=5_000_000, total_timeout=15)
|
|
173
|
+
result = await fetch("https://example.com/document")
|
|
174
|
+
# result.url, result.content, result.content_type, result.status_code
|
|
175
|
+
await download("https://example.com/document", Path("document.html"))
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
HTTP(S) URLs may use only ports 80 or 443, with no credentials or local names.
|
|
179
|
+
Every DNS answer must be public; mixed public/private answers are rejected.
|
|
180
|
+
The validated numeric IP is used as the socket target, with the original Host
|
|
181
|
+
and TLS verification hostname preserved. Each redirect gets a new client and
|
|
182
|
+
fresh validation, including rejection of HTTPS-to-HTTP downgrades. Proxy settings,
|
|
183
|
+
ambient cookies, automatic redirects, and HTTP retries are disabled.
|
|
184
|
+
|
|
185
|
+
The default media types are HTML, XHTML, plain text, and JSON. Supply an explicit
|
|
186
|
+
`allowed_content_types=frozenset({...})` for other content. Content encoding must
|
|
187
|
+
be identity to avoid decompression bombs. Announced and streamed byte counts are
|
|
188
|
+
bounded, and the total timeout includes DNS, redirects, and body reads.
|
|
189
|
+
|
|
190
|
+
Downloads write to a temporary file and publish atomically after success. Existing
|
|
191
|
+
paths are never overwritten. Failures and cancellation remove temporary files.
|
|
192
|
+
Disk writes are synchronous in bounded chunks; network deadlines cannot interrupt
|
|
193
|
+
blocking filesystem operations. File types and fetched HTML remain untrusted:
|
|
194
|
+
apps must sanitize content and enforce suitable rendering/download policies.
|
|
195
|
+
|
|
196
|
+
Errors live in `access_kit.safe_fetch.errors`: `BlockedDestination`, `TooLarge`,
|
|
197
|
+
`BadContentType`, `TooManyRedirects`, `FetchTimeout`, and their base `FetchError`.
|
|
198
|
+
Error messages omit submitted URLs and response bodies.
|
|
199
|
+
|
|
200
|
+
IP pinning uses HTTPX's documented
|
|
201
|
+
[`sni_hostname` extension](https://www.python-httpx.org/advanced/extensions/).
|
|
202
|
+
The regression suite tests actual HTTPX/httpcore socket arguments and TLS names,
|
|
203
|
+
not only mocked responses. Reusable attack URLs live in
|
|
204
|
+
`access_kit.testing.ssrf_cases.SSRF_CASES`; redirect, rebinding, cancellation,
|
|
205
|
+
streaming-limit, and TLS tests are maintained in `python/tests/test_safe_fetch.py`.
|
|
206
|
+
|
|
207
|
+
## LLM providers and strict JSON
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
from typing import TypedDict
|
|
211
|
+
from access_kit.llm.factory import provider_from_settings
|
|
212
|
+
|
|
213
|
+
Summary = TypedDict("Summary", {"summary": str})
|
|
214
|
+
provider = provider_from_settings(settings)
|
|
215
|
+
result, tokens = await provider["complete_json"]("Summarize the document.", "Document content", Summary)
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Configure `LLM_PROVIDER` (`anthropic`, `ollama`, or `omniroute`) and `LLM_MODEL`
|
|
219
|
+
explicitly. Remote models and credentials are never selected implicitly.
|
|
220
|
+
`LLM_API_KEY` is a redacted secret. `LLM_BASE_URL` overrides the trusted provider
|
|
221
|
+
endpoint. Ollama defaults to `http://localhost:11434/v1`; OmniRoute requires an
|
|
222
|
+
explicit base URL and API key. Remote endpoints must use HTTPS; HTTP is allowed
|
|
223
|
+
only on loopback. Provider endpoint configuration is trusted app configuration,
|
|
224
|
+
not a place to pass user-submitted URLs.
|
|
225
|
+
|
|
226
|
+
Direct factories live in `access_kit.llm.providers`. Both adapters expose a dict
|
|
227
|
+
with `complete_text`, `complete_json`, provider name, model, and an input limit.
|
|
228
|
+
They use the [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages/create)
|
|
229
|
+
and [Ollama's OpenAI-compatible Chat Completions API](https://docs.ollama.com/api/openai-compatibility).
|
|
230
|
+
Models are always caller-selected. The input limit is enforced as a conservative
|
|
231
|
+
UTF-8 byte cap plus 1,024 bytes of framing allowance, not a tokenizer or a billing
|
|
232
|
+
estimate. The provider remains responsible for its actual model context limit.
|
|
233
|
+
|
|
234
|
+
`complete_json` validates with a Pydantic TypeAdapter in strict mode. It retries
|
|
235
|
+
invalid JSON/schema responses twice by default; fences and string-to-integer
|
|
236
|
+
coercion are not accepted. Retry limits are configurable from zero to five.
|
|
237
|
+
Transport failures, refusals, truncation, and tool calls fail explicitly.
|
|
238
|
+
HTTP responses are bounded to one MB and have a total timeout; HTTP retries and
|
|
239
|
+
redirect following are disabled. Injected HTTPX clients remain caller-owned.
|
|
240
|
+
|
|
241
|
+
`Usage` contains `input_tokens`, `output_tokens`, `total_tokens`, and `complete`.
|
|
242
|
+
Anthropic cached input tokens are included. JSON retries and explicit provider
|
|
243
|
+
fallbacks accumulate usage across failed attempts. Errors also carry `.usage`.
|
|
244
|
+
`complete=False` means some usage could not be established, for example after a
|
|
245
|
+
connection reset. Do not interpret unknown usage as zero spending.
|
|
246
|
+
|
|
247
|
+
`with_fallback([...])` in `access_kit.llm.core` is opt-in: it sends the prompt to
|
|
248
|
+
each configured provider in order until one succeeds. If every provider fails,
|
|
249
|
+
`LLMFallbackError` retains sanitized errors and accumulated known usage.
|
|
250
|
+
Weighted rate limiting and daily budgets are available as explicit protection
|
|
251
|
+
modules. Provider factories do not silently apply a cap: reserve a verified upper
|
|
252
|
+
bound before dispatch, including every possible retry and fallback attempt.
|
|
253
|
+
|
|
254
|
+
## Consumer test helpers
|
|
255
|
+
|
|
256
|
+
Install `gavvahar-access-kit[testing]` for pytest/fakeredis support. Fixtures are opt-in:
|
|
257
|
+
|
|
258
|
+
```python
|
|
259
|
+
# conftest.py
|
|
260
|
+
pytest_plugins = ["access_kit.testing.fixtures"]
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
The async `fake_redis` fixture closes its in-memory client after each test.
|
|
264
|
+
`fake_llm` in `access_kit.testing.fakes` returns `(provider, calls)` and runs the
|
|
265
|
+
same JSON validation and retry logic as real providers. Supply strings or
|
|
266
|
+
`LLMError` instances as deterministic responses; exhausted responses fail clearly.
|
|
267
|
+
The call records retain prompts in test memory and must not be used in production.
|
|
268
|
+
|
|
269
|
+
All Python `__init__.py` files are empty. Import from named modules rather than
|
|
270
|
+
package-level re-exports. Read the installed version with
|
|
271
|
+
`importlib.metadata.version("access-kit")`.
|
|
272
|
+
|
|
273
|
+
## Release acceptance
|
|
274
|
+
|
|
275
|
+
The library core and a consumer-style FastAPI integration test are implemented.
|
|
276
|
+
ClearRead's Phase 1 pipeline is not present in its current template repository,
|
|
277
|
+
so the planned `py-v0.1.0` consuming-app acceptance check is still pending.
|
|
278
|
+
The protection and progress modules are implemented and tested locally; real
|
|
279
|
+
consuming-app acceptance and authenticated registry uploads remain pending.
|
|
280
|
+
See [the roadmap](https://github.com/gavvahar/access-kit/blob/main/docs/roadmap.md).
|
|
281
|
+
|
|
282
|
+
## Protection, delivery, and job progress
|
|
283
|
+
|
|
284
|
+
`ratelimit`, `turnstile`, `budget`, and `notify` are documented with configuration,
|
|
285
|
+
error handling and operating constraints in [the protection guide](https://github.com/gavvahar/access-kit/blob/main/docs/protection.md).
|
|
286
|
+
`jobs` provides owner-scoped worker progress and a FastAPI SSE response helper;
|
|
287
|
+
see [job integration](https://github.com/gavvahar/access-kit/blob/main/docs/jobs.md). Public infrastructure exceptions live in
|
|
288
|
+
`access_kit.errors`. Storage failure must deny protected work.
|
|
289
|
+
|
|
290
|
+
Install `[testing]` or `[dev]` to run Redis Lua scripts with fakeredis. On the
|
|
291
|
+
latest Python, a native Lua wheel may need the compiler toolchain supplied by
|
|
292
|
+
`environment.yml`; no sudo is required. The real Redis CI check independently
|
|
293
|
+
exercises concurrent budget admission, weighted limits and job event replay.
|
|
294
|
+
The [API inventory](https://github.com/gavvahar/access-kit/blob/main/docs/api.md) covers every supported module; the
|
|
295
|
+
[architecture decisions](https://github.com/gavvahar/access-kit/blob/main/docs/decisions.md) explain ownership and lifecycle.
|
|
296
|
+
|
|
297
|
+
## Bounded HTTP requests
|
|
298
|
+
|
|
299
|
+
Wrap an ASGI app with `access_kit.http.body_limit(app, max_bytes=1_000_000,
|
|
300
|
+
read_timeout=15)` before exposing JSON/document endpoints. Oversized declared or
|
|
301
|
+
streamed bodies receive 413 before framework parsing. Duplicate/invalid/mismatched
|
|
302
|
+
Content-Length receives 400; body-read timeout receives 408. Non-HTTP scopes pass
|
|
303
|
+
through. Valid bodies replay once, then preserve the original disconnect stream.
|
|
304
|
+
This buffers bounded requests; use a separate design for streaming uploads.
|
|
305
|
+
|
|
306
|
+
`provider_from_settings` accepts explicit `max_tokens`, `max_input_tokens`,
|
|
307
|
+
`timeout` and `json_retries` overrides. Consumer budgets can reserve the true
|
|
308
|
+
upper bound across those bounded attempts instead of guessing factory defaults.
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
# access-kit Python
|
|
2
|
+
|
|
3
|
+
Typed backend primitives for ClearRead and SoundSight. Use the latest stable Python 3 release.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
The PyPI distribution is `gavvahar-access-kit`; Python imports use `access_kit`.
|
|
8
|
+
The prepared Python release is `1.0.1` (publication status is in the roadmap).
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
python -m pip install 'gavvahar-access-kit==1.0.1'
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
From the repository root:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
python -m pip install -e './python[dev]'
|
|
18
|
+
pytest
|
|
19
|
+
mypy
|
|
20
|
+
python -m build python
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Settings
|
|
24
|
+
|
|
25
|
+
Subclass `access_kit.settings.AccessKitSettings` for application-specific fields.
|
|
26
|
+
Process environment is loaded case-insensitively. Required fields:
|
|
27
|
+
|
|
28
|
+
| Variable | Validation |
|
|
29
|
+
| ----------------- | ------------------------------ |
|
|
30
|
+
| `APP_NAME` | Nonempty string |
|
|
31
|
+
| `PUBLIC_BASE_URL` | HTTP or HTTPS URL |
|
|
32
|
+
| `REDIS_URL` | Redis DSN |
|
|
33
|
+
| `SESSION_SECRET` | Secret, at least 32 characters |
|
|
34
|
+
| `IP_HASH_SALT` | Secret, at least 32 characters |
|
|
35
|
+
|
|
36
|
+
`ENV` is `dev`, `test`, or `prod` (default `dev`).
|
|
37
|
+
`TRUST_CLOUDFLARE_HEADERS` defaults to false. Enable it only when the origin
|
|
38
|
+
accepts verified Cloudflare connections and configure trusted proxy networks in
|
|
39
|
+
`client_ip`; a header alone never establishes proxy trust.
|
|
40
|
+
|
|
41
|
+
Dotenv loading is opt-in: `Settings(_env_file=".env")`.
|
|
42
|
+
Secret fields are redacted in representations; do not log full settings objects,
|
|
43
|
+
validation error dictionaries, connection URLs, or raw input.
|
|
44
|
+
|
|
45
|
+
The configuration uses [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/).
|
|
46
|
+
|
|
47
|
+
## Health
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from fastapi import FastAPI
|
|
51
|
+
from access_kit.health import health_router
|
|
52
|
+
|
|
53
|
+
app = FastAPI()
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
async def database_ready() -> bool:
|
|
57
|
+
# Replace with the app's asynchronous database ping.
|
|
58
|
+
return True
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
app.include_router(health_router({"database": database_ready}, timeout=2.0))
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Checks run concurrently. Any exception, timeout, or return value other than
|
|
65
|
+
`True` yields HTTP 503. A healthy response is:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{ "status": "ok", "checks": { "database": "ok" } }
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Responses use `Cache-Control: no-store` and never contain exception messages.
|
|
72
|
+
Check names are public: use names such as `database`, not connection strings.
|
|
73
|
+
Checks must use asynchronous I/O and cooperate with cancellation. Timeouts cannot
|
|
74
|
+
interrupt blocking code. Without checks, `/healthz` is a liveness endpoint.
|
|
75
|
+
|
|
76
|
+
HTTP status handling follows [FastAPI's response API](https://fastapi.tiangolo.com/advanced/additional-status-codes/).
|
|
77
|
+
|
|
78
|
+
## Logging and request IDs
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
import logging
|
|
82
|
+
from access_kit.logging import request_id_middleware, setup_logging
|
|
83
|
+
|
|
84
|
+
setup_logging(settings)
|
|
85
|
+
app = request_id_middleware(app)
|
|
86
|
+
logging.info("request_done", extra={"status_code": 200, "duration_ms": 12})
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Wrap the complete ASGI app so error responses also receive `X-Request-ID`.
|
|
90
|
+
IDs are generated on the server and isolated between concurrent requests.
|
|
91
|
+
`get_request_id()` returns the current ID and resets after the request.
|
|
92
|
+
|
|
93
|
+
The default JSON handler keeps constant event names, safe numeric fields, known
|
|
94
|
+
HTTP methods/provider names, and validated request IDs. It drops bodies, headers,
|
|
95
|
+
URLs, IPs, arbitrary metadata, formatted arguments, exception text, and tracebacks.
|
|
96
|
+
Use constant event names: never put user text in an event name. Configure logging
|
|
97
|
+
at process startup, before installing additional handlers. Separate log handlers
|
|
98
|
+
installed by an app must apply their own equivalent redaction.
|
|
99
|
+
|
|
100
|
+
## Privacy and anonymous sessions
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from access_kit.privacy import client_ip, hash_ip
|
|
104
|
+
from access_kit.session import session_middleware
|
|
105
|
+
|
|
106
|
+
app = session_middleware(app, secret=settings.session_secret.get_secret_value())
|
|
107
|
+
# Inside a request handler:
|
|
108
|
+
# peer = client_ip(request)
|
|
109
|
+
# identifier = hash_ip(peer, settings.ip_hash_salt.get_secret_value()) if peer else None
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`client_ip` ignores forwarding headers by default. Cloudflare extraction requires
|
|
113
|
+
both `trust_cloudflare=True` and explicit `trusted_proxies` CIDRs. The ASGI client
|
|
114
|
+
address must be the actual socket peer; unconditional upstream proxy-header
|
|
115
|
+
rewriting would undermine that check. Keep proxy networks current in the app.
|
|
116
|
+
Malformed or duplicate Cloudflare headers fall back to the verified peer.
|
|
117
|
+
|
|
118
|
+
`hash_ip` uses HMAC-SHA256 and a 32-byte minimum salt, normalizing equivalent IPv6
|
|
119
|
+
and mapped IPv4 literals. The application owns retention/deletion; there is no
|
|
120
|
+
generic SQL deletion helper. Rotating the salt changes identifiers.
|
|
121
|
+
|
|
122
|
+
Use `Depends(get_session_id)` from `access_kit.session` to read the anonymous ID.
|
|
123
|
+
Cookies are HMAC-signed, expire after one year, and use HttpOnly, Secure,
|
|
124
|
+
SameSite=Lax, and Path=/. Pass `secure=False` only for local HTTP development.
|
|
125
|
+
Tampered or expired cookies are replaced without raising a request error.
|
|
126
|
+
|
|
127
|
+
`rotate_session(request)` changes the current ID before response headers are sent.
|
|
128
|
+
Stateless rotation does not revoke old signed cookies. Apps that need revocation
|
|
129
|
+
must reject the old ID in their data store. The cookie is not authentication or
|
|
130
|
+
CSRF protection.
|
|
131
|
+
|
|
132
|
+
## Safe fetching
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from pathlib import Path
|
|
136
|
+
from access_kit.safe_fetch.fetcher import make_fetcher
|
|
137
|
+
|
|
138
|
+
fetch, download = make_fetcher(max_bytes=5_000_000, total_timeout=15)
|
|
139
|
+
result = await fetch("https://example.com/document")
|
|
140
|
+
# result.url, result.content, result.content_type, result.status_code
|
|
141
|
+
await download("https://example.com/document", Path("document.html"))
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
HTTP(S) URLs may use only ports 80 or 443, with no credentials or local names.
|
|
145
|
+
Every DNS answer must be public; mixed public/private answers are rejected.
|
|
146
|
+
The validated numeric IP is used as the socket target, with the original Host
|
|
147
|
+
and TLS verification hostname preserved. Each redirect gets a new client and
|
|
148
|
+
fresh validation, including rejection of HTTPS-to-HTTP downgrades. Proxy settings,
|
|
149
|
+
ambient cookies, automatic redirects, and HTTP retries are disabled.
|
|
150
|
+
|
|
151
|
+
The default media types are HTML, XHTML, plain text, and JSON. Supply an explicit
|
|
152
|
+
`allowed_content_types=frozenset({...})` for other content. Content encoding must
|
|
153
|
+
be identity to avoid decompression bombs. Announced and streamed byte counts are
|
|
154
|
+
bounded, and the total timeout includes DNS, redirects, and body reads.
|
|
155
|
+
|
|
156
|
+
Downloads write to a temporary file and publish atomically after success. Existing
|
|
157
|
+
paths are never overwritten. Failures and cancellation remove temporary files.
|
|
158
|
+
Disk writes are synchronous in bounded chunks; network deadlines cannot interrupt
|
|
159
|
+
blocking filesystem operations. File types and fetched HTML remain untrusted:
|
|
160
|
+
apps must sanitize content and enforce suitable rendering/download policies.
|
|
161
|
+
|
|
162
|
+
Errors live in `access_kit.safe_fetch.errors`: `BlockedDestination`, `TooLarge`,
|
|
163
|
+
`BadContentType`, `TooManyRedirects`, `FetchTimeout`, and their base `FetchError`.
|
|
164
|
+
Error messages omit submitted URLs and response bodies.
|
|
165
|
+
|
|
166
|
+
IP pinning uses HTTPX's documented
|
|
167
|
+
[`sni_hostname` extension](https://www.python-httpx.org/advanced/extensions/).
|
|
168
|
+
The regression suite tests actual HTTPX/httpcore socket arguments and TLS names,
|
|
169
|
+
not only mocked responses. Reusable attack URLs live in
|
|
170
|
+
`access_kit.testing.ssrf_cases.SSRF_CASES`; redirect, rebinding, cancellation,
|
|
171
|
+
streaming-limit, and TLS tests are maintained in `python/tests/test_safe_fetch.py`.
|
|
172
|
+
|
|
173
|
+
## LLM providers and strict JSON
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from typing import TypedDict
|
|
177
|
+
from access_kit.llm.factory import provider_from_settings
|
|
178
|
+
|
|
179
|
+
Summary = TypedDict("Summary", {"summary": str})
|
|
180
|
+
provider = provider_from_settings(settings)
|
|
181
|
+
result, tokens = await provider["complete_json"]("Summarize the document.", "Document content", Summary)
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Configure `LLM_PROVIDER` (`anthropic`, `ollama`, or `omniroute`) and `LLM_MODEL`
|
|
185
|
+
explicitly. Remote models and credentials are never selected implicitly.
|
|
186
|
+
`LLM_API_KEY` is a redacted secret. `LLM_BASE_URL` overrides the trusted provider
|
|
187
|
+
endpoint. Ollama defaults to `http://localhost:11434/v1`; OmniRoute requires an
|
|
188
|
+
explicit base URL and API key. Remote endpoints must use HTTPS; HTTP is allowed
|
|
189
|
+
only on loopback. Provider endpoint configuration is trusted app configuration,
|
|
190
|
+
not a place to pass user-submitted URLs.
|
|
191
|
+
|
|
192
|
+
Direct factories live in `access_kit.llm.providers`. Both adapters expose a dict
|
|
193
|
+
with `complete_text`, `complete_json`, provider name, model, and an input limit.
|
|
194
|
+
They use the [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages/create)
|
|
195
|
+
and [Ollama's OpenAI-compatible Chat Completions API](https://docs.ollama.com/api/openai-compatibility).
|
|
196
|
+
Models are always caller-selected. The input limit is enforced as a conservative
|
|
197
|
+
UTF-8 byte cap plus 1,024 bytes of framing allowance, not a tokenizer or a billing
|
|
198
|
+
estimate. The provider remains responsible for its actual model context limit.
|
|
199
|
+
|
|
200
|
+
`complete_json` validates with a Pydantic TypeAdapter in strict mode. It retries
|
|
201
|
+
invalid JSON/schema responses twice by default; fences and string-to-integer
|
|
202
|
+
coercion are not accepted. Retry limits are configurable from zero to five.
|
|
203
|
+
Transport failures, refusals, truncation, and tool calls fail explicitly.
|
|
204
|
+
HTTP responses are bounded to one MB and have a total timeout; HTTP retries and
|
|
205
|
+
redirect following are disabled. Injected HTTPX clients remain caller-owned.
|
|
206
|
+
|
|
207
|
+
`Usage` contains `input_tokens`, `output_tokens`, `total_tokens`, and `complete`.
|
|
208
|
+
Anthropic cached input tokens are included. JSON retries and explicit provider
|
|
209
|
+
fallbacks accumulate usage across failed attempts. Errors also carry `.usage`.
|
|
210
|
+
`complete=False` means some usage could not be established, for example after a
|
|
211
|
+
connection reset. Do not interpret unknown usage as zero spending.
|
|
212
|
+
|
|
213
|
+
`with_fallback([...])` in `access_kit.llm.core` is opt-in: it sends the prompt to
|
|
214
|
+
each configured provider in order until one succeeds. If every provider fails,
|
|
215
|
+
`LLMFallbackError` retains sanitized errors and accumulated known usage.
|
|
216
|
+
Weighted rate limiting and daily budgets are available as explicit protection
|
|
217
|
+
modules. Provider factories do not silently apply a cap: reserve a verified upper
|
|
218
|
+
bound before dispatch, including every possible retry and fallback attempt.
|
|
219
|
+
|
|
220
|
+
## Consumer test helpers
|
|
221
|
+
|
|
222
|
+
Install `gavvahar-access-kit[testing]` for pytest/fakeredis support. Fixtures are opt-in:
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
# conftest.py
|
|
226
|
+
pytest_plugins = ["access_kit.testing.fixtures"]
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
The async `fake_redis` fixture closes its in-memory client after each test.
|
|
230
|
+
`fake_llm` in `access_kit.testing.fakes` returns `(provider, calls)` and runs the
|
|
231
|
+
same JSON validation and retry logic as real providers. Supply strings or
|
|
232
|
+
`LLMError` instances as deterministic responses; exhausted responses fail clearly.
|
|
233
|
+
The call records retain prompts in test memory and must not be used in production.
|
|
234
|
+
|
|
235
|
+
All Python `__init__.py` files are empty. Import from named modules rather than
|
|
236
|
+
package-level re-exports. Read the installed version with
|
|
237
|
+
`importlib.metadata.version("access-kit")`.
|
|
238
|
+
|
|
239
|
+
## Release acceptance
|
|
240
|
+
|
|
241
|
+
The library core and a consumer-style FastAPI integration test are implemented.
|
|
242
|
+
ClearRead's Phase 1 pipeline is not present in its current template repository,
|
|
243
|
+
so the planned `py-v0.1.0` consuming-app acceptance check is still pending.
|
|
244
|
+
The protection and progress modules are implemented and tested locally; real
|
|
245
|
+
consuming-app acceptance and authenticated registry uploads remain pending.
|
|
246
|
+
See [the roadmap](https://github.com/gavvahar/access-kit/blob/main/docs/roadmap.md).
|
|
247
|
+
|
|
248
|
+
## Protection, delivery, and job progress
|
|
249
|
+
|
|
250
|
+
`ratelimit`, `turnstile`, `budget`, and `notify` are documented with configuration,
|
|
251
|
+
error handling and operating constraints in [the protection guide](https://github.com/gavvahar/access-kit/blob/main/docs/protection.md).
|
|
252
|
+
`jobs` provides owner-scoped worker progress and a FastAPI SSE response helper;
|
|
253
|
+
see [job integration](https://github.com/gavvahar/access-kit/blob/main/docs/jobs.md). Public infrastructure exceptions live in
|
|
254
|
+
`access_kit.errors`. Storage failure must deny protected work.
|
|
255
|
+
|
|
256
|
+
Install `[testing]` or `[dev]` to run Redis Lua scripts with fakeredis. On the
|
|
257
|
+
latest Python, a native Lua wheel may need the compiler toolchain supplied by
|
|
258
|
+
`environment.yml`; no sudo is required. The real Redis CI check independently
|
|
259
|
+
exercises concurrent budget admission, weighted limits and job event replay.
|
|
260
|
+
The [API inventory](https://github.com/gavvahar/access-kit/blob/main/docs/api.md) covers every supported module; the
|
|
261
|
+
[architecture decisions](https://github.com/gavvahar/access-kit/blob/main/docs/decisions.md) explain ownership and lifecycle.
|
|
262
|
+
|
|
263
|
+
## Bounded HTTP requests
|
|
264
|
+
|
|
265
|
+
Wrap an ASGI app with `access_kit.http.body_limit(app, max_bytes=1_000_000,
|
|
266
|
+
read_timeout=15)` before exposing JSON/document endpoints. Oversized declared or
|
|
267
|
+
streamed bodies receive 413 before framework parsing. Duplicate/invalid/mismatched
|
|
268
|
+
Content-Length receives 400; body-read timeout receives 408. Non-HTTP scopes pass
|
|
269
|
+
through. Valid bodies replay once, then preserve the original disconnect stream.
|
|
270
|
+
This buffers bounded requests; use a separate design for streaming uploads.
|
|
271
|
+
|
|
272
|
+
`provider_from_settings` accepts explicit `max_tokens`, `max_input_tokens`,
|
|
273
|
+
`timeout` and `json_retries` overrides. Consumer budgets can reserve the true
|
|
274
|
+
upper bound across those bounded attempts instead of guessing factory defaults.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "gavvahar-access-kit"
|
|
7
|
+
version = "1.0.1"
|
|
8
|
+
description = "Shared backend toolkit for ClearRead and SoundSight"
|
|
9
|
+
keywords = ["accessibility", "fastapi", "ssrf", "redis"]
|
|
10
|
+
readme = "README.md"
|
|
11
|
+
requires-python = ">=3.15"
|
|
12
|
+
license = "MIT"
|
|
13
|
+
license-files = ["LICENSE"]
|
|
14
|
+
authors = [{ name = "Nihar Gavva" }]
|
|
15
|
+
dependencies = [
|
|
16
|
+
"fastapi>=0.115,<1",
|
|
17
|
+
"pydantic-settings>=2.7,<3",
|
|
18
|
+
"pydantic>=2.9,<3",
|
|
19
|
+
"httpx>=0.28,<1",
|
|
20
|
+
"redis>=5,<9",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[project.optional-dependencies]
|
|
24
|
+
testing = ["fakeredis[lua]>=2.26", "pytest>=8", "pytest-asyncio>=0.25"]
|
|
25
|
+
dev = [
|
|
26
|
+
"build>=1.2",
|
|
27
|
+
"fakeredis[lua]>=2.26",
|
|
28
|
+
"httpx>=0.28,<1",
|
|
29
|
+
"mypy>=1.14",
|
|
30
|
+
"pytest>=8",
|
|
31
|
+
"pytest-asyncio>=0.25",
|
|
32
|
+
"pytest-cov>=6",
|
|
33
|
+
"ruff>=0.9",
|
|
34
|
+
"tox>=4.24",
|
|
35
|
+
"pre-commit>=4",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Documentation = "https://github.com/gavvahar/access-kit/blob/main/docs/api.md"
|
|
40
|
+
Issues = "https://github.com/gavvahar/access-kit/issues"
|
|
41
|
+
Repository = "https://github.com/gavvahar/access-kit"
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.wheel]
|
|
44
|
+
packages = ["src/access_kit"]
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.sdist]
|
|
47
|
+
include = ["src", "README.md", "LICENSE", "pyproject.toml"]
|
|
File without changes
|