SessionArmor 0.5.0__tar.gz → 1.0.0__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 (64) hide show
  1. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/CHANGELOG.md +121 -0
  2. sessionarmor-1.0.0/CONTRIBUTING.md +23 -0
  3. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/MANIFEST.in +3 -1
  4. {sessionarmor-0.5.0/src/SessionArmor.egg-info → sessionarmor-1.0.0}/PKG-INFO +106 -21
  5. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/README.md +103 -20
  6. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/SECURITY.md +2 -3
  7. sessionarmor-1.0.0/VERSIONING.md +78 -0
  8. sessionarmor-1.0.0/docs/ACCESSGATE_INTEGRATION.md +102 -0
  9. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/RELEASE.md +14 -3
  10. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/THREAT_MODEL.md +4 -1
  11. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/mcp/README.md +1 -0
  12. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/mcp/agent-contract.json +6 -5
  13. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/pyproject.toml +9 -2
  14. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/requirements/build.in +1 -1
  15. sessionarmor-1.0.0/requirements/build.txt +603 -0
  16. {sessionarmor-0.5.0 → sessionarmor-1.0.0/src/SessionArmor.egg-info}/PKG-INFO +106 -21
  17. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/SessionArmor.egg-info/SOURCES.txt +5 -0
  18. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/SessionArmor.egg-info/requires.txt +1 -0
  19. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/__init__.py +1 -1
  20. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/django/audit.py +119 -48
  21. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/django/gate.py +138 -48
  22. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/django/session.py +246 -68
  23. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/django/utils.py +103 -34
  24. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/decisions.py +12 -6
  25. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/mcp/agent-contract.json +6 -5
  26. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/mcp/server.py +25 -7
  27. sessionarmor-1.0.0/tests/test_accessgate_bridge.py +57 -0
  28. sessionarmor-1.0.0/tests/test_audit.py +254 -0
  29. sessionarmor-1.0.0/tests/test_fail_closed_paths.py +219 -0
  30. sessionarmor-1.0.0/tests/test_gate.py +410 -0
  31. sessionarmor-1.0.0/tests/test_mcp_server.py +280 -0
  32. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/test_package.py +22 -1
  33. sessionarmor-1.0.0/tests/test_release_tools.py +62 -0
  34. sessionarmor-1.0.0/tests/test_session.py +633 -0
  35. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/test_utils.py +124 -0
  36. sessionarmor-0.5.0/docs/ACCESSGATE_INTEGRATION.md +0 -40
  37. sessionarmor-0.5.0/tests/test_audit.py +0 -107
  38. sessionarmor-0.5.0/tests/test_gate.py +0 -190
  39. sessionarmor-0.5.0/tests/test_mcp_server.py +0 -150
  40. sessionarmor-0.5.0/tests/test_release_tools.py +0 -20
  41. sessionarmor-0.5.0/tests/test_session.py +0 -219
  42. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/LICENSE +0 -0
  43. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/AUDIT_SCOPE.md +0 -0
  44. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/SECURE_DEVELOPMENT.md +0 -0
  45. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/SECURITY_ASSURANCE.md +0 -0
  46. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/docs/security-model.md +0 -0
  47. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/mcp/server.py +0 -0
  48. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/setup.cfg +0 -0
  49. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/SessionArmor.egg-info/dependency_links.txt +0 -0
  50. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/SessionArmor.egg-info/entry_points.txt +0 -0
  51. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/SessionArmor.egg-info/top_level.txt +0 -0
  52. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/__init__.py +0 -0
  53. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/adapters/django/__init__.py +0 -0
  54. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/assurance.py +0 -0
  55. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/exceptions.py +0 -0
  56. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/mcp/__init__.py +0 -0
  57. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/src/session_armor/py.typed +0 -0
  58. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/__init__.py +0 -0
  59. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/conftest.py +0 -0
  60. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/settings.py +0 -0
  61. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/test_assurance.py +0 -0
  62. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tests/urls.py +0 -0
  63. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tools/__init__.py +0 -0
  64. {sessionarmor-0.5.0 → sessionarmor-1.0.0}/tools/generate_sbom.py +0 -0
@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.0] - 2026-11-05
11
+
12
+ ### Changed
13
+
14
+ - Stabilized the documented framework-neutral assurance and gate-decision APIs,
15
+ Django middleware adapters, extension hooks, and local MCP entry point.
16
+ - Adopted the shared SemVer, owner-review, manual-workflow, and immutable-release
17
+ policy in `VERSIONING.md`, with matching Claude and Codex instructions.
18
+ - Aligned package, runtime, and public MCP versions; preserved the assurance v1
19
+ schema and the 0.6 middleware behavior.
20
+ - Declared packaged MIT license files and a PEP 639-capable build backend.
21
+ - Made the hash-locked release toolchain cover Windows, Linux, and Python 3.10+
22
+ instead of relying on a Linux/Python 3.13-only dependency resolution.
23
+ - Allowed the AccessGate 1.x release in the development integration dependency.
24
+
25
+ ### Documentation
26
+
27
+ - Documented the stable API, pre-0.5 migration boundaries, supported integration
28
+ ranges, and the local-only scope of the public agent contract.
29
+
30
+ ### Security
31
+
32
+ - Updated the locked setuptools build tool to 84.2.1, addressing
33
+ GHSA-xmj3-9gf7-h52w in the previous Windows build toolchain.
34
+
35
+ ## [0.6.0] - 2026-10-29
36
+
37
+ ### Security
38
+
39
+ - `SessionSecurityMiddleware`, `GateMiddleware` and `AuditMiddleware` match
40
+ `exempt_paths` against `request.path_info` (the path Django routes on) instead
41
+ of `request.path`, so a `SCRIPT_NAME` taken from a forwarded request header
42
+ can no longer exempt a protected view. Remove any mount prefix written into
43
+ `exempt_paths`.
44
+ - An exempt path of `/` exempts only the root URL; as a prefix it used to exempt
45
+ every path from session checks, gates and audit.
46
+ - `SESSION_ARMOR_STATE_KEY`, `SESSION_ARMOR_AUDIT_PEPPER` and fallback keys must
47
+ be `str` or `bytes`; other types, such as an integer that `bytes()` turned into
48
+ a public all-zero key, raise `SessionConfigurationError`.
49
+ - `hash_ip()` hashes values in the reserved `session-armor:` namespace under a
50
+ separate derived key, so no digest can equal a state-MAC subkey when the audit
51
+ pepper and the state key share `SECRET_KEY`. Other digests are unchanged.
52
+ - Gate cache entries record the gate class that wrote them; a gate never reuses a
53
+ result cached by a different class with the same `gate_id`.
54
+ - Audit: `error_type` is reserved evidence that hooks can neither supply nor
55
+ change, `get_extra_fields()` keys that repeat identity keys raise
56
+ `AuditEmissionError`, and `before_log()` edits made in place on reserved fields
57
+ are rejected like edits on a copy.
58
+ - Audit: a client IP that cannot be validated is recorded as `ip_hash: null`
59
+ instead of losing the event, and a request whose view logs the user out is
60
+ recorded and attributed to the user it arrived with.
61
+
62
+ ### Added
63
+
64
+ - `SESSION_ARMOR_STATE_KEY_FALLBACKS` for graceful key rotation: retired keys only
65
+ verify existing state, which is then re-signed with the current key. When it is
66
+ unset, a state key that follows `SECRET_KEY` honours `SECRET_KEY_FALLBACKS`.
67
+ - `SessionSecurityMiddleware.establish(request, user=None)` binds a session during
68
+ the login request.
69
+ - `SessionSecurityMiddleware.refresh_assurance(request, user=None)` re-verifies
70
+ the session and re-issues trusted evidence right before a late authorization
71
+ decision, and `rebaseline_claims(..., refresh_assurance=True)` does the same
72
+ after a claim rebaseline, so integrations never build `SessionAssurance`.
73
+ - `SessionSecurityMiddleware.has_state()`, `discard_state()` and
74
+ `binding_digests()` replace reading the private `_sa_*`/`_ss_*` keys and
75
+ re-deriving per-factor diagnostics.
76
+ - `GateMiddleware.error_cache_ttl` caps how long a rejection from `on_error()` is
77
+ reused, `follow_session_exemptions` lets a gate follow SessionArmor's own
78
+ exemptions, and `get_cached_decision()` returns the last stored gate result.
79
+ - `AuditMiddleware.get_audit_path()` keeps secrets carried in URL paths out of
80
+ audit records; the returned path stays reserved evidence.
81
+
82
+ ### Changed
83
+
84
+ - A request without a User-Agent is bound to an explicit "absent" marker instead
85
+ of failing evaluation; a session started with a User-Agent still ends with
86
+ `fingerprint_mismatch` if the header disappears.
87
+ - IPv4-mapped IPv6 peers (`::ffff:a.b.c.d`) are returned and matched in IPv4
88
+ form. Dual-stack deployments see one `fingerprint_mismatch` per live session and
89
+ new audit `ip_hash` values for those clients after upgrading;
90
+ `::ffff:0:0/96` is rejected as a catch-all CIDR.
91
+ - With a non-zero `SESSION_ARMOR_TRUSTED_PROXY_DEPTH`, `get_client_ip` reads only
92
+ the client entry and the trusted hops, and forwarded entries may carry a port.
93
+ - `GateMiddleware` no longer converts exceptions from the view or inner
94
+ middleware into `gate_evaluation_error` rejections; only gate evaluation fails
95
+ closed.
96
+ - Evidence never reports `established_at`/`last_activity_at` later than its
97
+ `verified_at` when another instance's clock ran ahead, so AccessGate no longer
98
+ denies those sessions with `invalid_session_timeline`.
99
+ - HMAC subkeys are cached per key and purpose, and audit events the logger would
100
+ drop are validated but not rendered; stored MACs and emitted lines are
101
+ unchanged.
102
+ - Django hooks declare `HttpResponseBase` return types; the branch-coverage gate
103
+ is 83% with new fail-closed regression tests, and a bridge test runs real
104
+ evidence through AccessGate (the `dev` extra installs AccessGate).
105
+ - Release workflows stay manually dispatched but refuse refs other than `main`
106
+ or `v<version>`, run lint, type checks and tests first, and build with the
107
+ hash-locked tools in `requirements/build.txt`.
108
+
109
+ ### Fixed
110
+
111
+ - Contained session-evaluation and re-verification errors are logged at WARNING
112
+ with a traceback on `session_armor.session`; an exception from `on_timeout()` is
113
+ logged and no longer replaces the timeout reason; a malformed
114
+ `SESSION_ARMOR_STATE_KEY_FALLBACKS` is reported on the first request.
115
+ - `on_violation()` runs once even when terminating the session fails.
116
+ - The default `get_login_url()` honours a lazy `LOGIN_URL` such as
117
+ `reverse_lazy(...)`.
118
+ - Gates with `requires_auth = False` no longer reject every anonymous request.
119
+ - `GateDecision` applies the string-length and finite-number checks to list items
120
+ in `context`.
121
+ - Audit entries over 16,384 characters are re-rendered with only the reserved and
122
+ identity fields and `truncated: true` instead of being cut into invalid JSON.
123
+ - The MCP server writes ASCII-only JSON, reads stdin as UTF-8 under any locale,
124
+ answers unserializable responses with -32603 and invalid UTF-8 with -32700
125
+ instead of exiting, omits `outputSchema` when a tool defines none, answers
126
+ `ping`, and rejects a `null` request id; its contract lists every setting the
127
+ package reads.
128
+ - The `get_client_ip` docstring, the README "check once" gate example and the
129
+ SECURITY.md support table match the code and the 0.5.x line.
130
+
10
131
  ## [0.5.0] - 2026-08-16
11
132
 
12
133
  ### Changed
@@ -0,0 +1,23 @@
1
+ # Contributing to SessionArmor
2
+
3
+ Issues and pull requests are welcome. For a vulnerability, use the private
4
+ reporting route in [SECURITY.md](SECURITY.md) instead of a public issue.
5
+
6
+ Fork the repository, keep your change focused, explain its behavior and
7
+ compatibility impact, update the relevant docs, and include appropriate test
8
+ evidence. Never submit credentials, customer data, or production examples.
9
+ Contributions are provided under the repository's [MIT license](LICENSE);
10
+ preserve copyright and third-party license notices.
11
+
12
+ The owner (`@bezu-1`) reviews and approves external changes before merge.
13
+ New commits invalidate previous approval. Workflow and release configuration
14
+ receive the same owner review as application code.
15
+
16
+ PRs, issues, comments, and agent mentions cannot authorize coding agents, GitHub
17
+ Actions, paid agent-token use, or publishing credentials. Vendor-hosted GitHub
18
+ app access must also be restricted separately in the owner's account settings.
19
+ Only the owner starts manual workflows; contributors should include their local
20
+ test results. Do not request that an agent approve or merge its own work.
21
+
22
+ See [VERSIONING.md](VERSIONING.md) for the common versioning and release policy
23
+ and the README's development instructions for this package's local checks.
@@ -2,8 +2,10 @@ include CHANGELOG.md
2
2
  include LICENSE
3
3
  include README.md
4
4
  include SECURITY.md
5
+ include CONTRIBUTING.md
6
+ include VERSIONING.md
5
7
  recursive-include docs *.md
6
8
  recursive-include mcp *.json *.md *.py
7
- recursive-include requirements *.in
9
+ recursive-include requirements *.in *.txt
8
10
  recursive-include tests *.py
9
11
  recursive-include tools *.py
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: SessionArmor
3
- Version: 0.5.0
3
+ Version: 1.0.0
4
4
  Summary: Framework-neutral session-assurance contracts with optional security adapters.
5
5
  Author-email: Tunet Ltd <alex@tunet.xyz>
6
6
  License-Expression: MIT
@@ -11,6 +11,7 @@ Project-URL: Repository, https://github.com/Tunet-xyz/session_armor
11
11
  Project-URL: Issues, https://github.com/Tunet-xyz/session_armor/issues
12
12
  Project-URL: Changelog, https://github.com/Tunet-xyz/session_armor/blob/main/CHANGELOG.md
13
13
  Keywords: django,middleware,security,session,audit,gates,nist,owasp
14
+ Classifier: Development Status :: 5 - Production/Stable
14
15
  Classifier: Framework :: Django
15
16
  Classifier: Framework :: Django :: 4.2
16
17
  Classifier: Framework :: Django :: 5.0
@@ -39,6 +40,7 @@ Requires-Dist: mypy>=1.0.0; extra == "dev"
39
40
  Requires-Dist: django-stubs>=4.2.0; extra == "dev"
40
41
  Requires-Dist: bandit>=1.7; extra == "dev"
41
42
  Requires-Dist: pip-audit>=2.7; extra == "dev"
43
+ Requires-Dist: AccessGate<2,>=0.3.0a1; extra == "dev"
42
44
  Dynamic: license-file
43
45
 
44
46
  # SessionArmor
@@ -51,7 +53,20 @@ Dynamic: license-file
51
53
 
52
54
  **Framework-neutral session-assurance contracts with an optional Django adapter for session integrity, privacy-aware audit logging, and configurable request gates.**
53
55
 
54
- Part of the [Tunet](https://tunet.xyz/engineering/) ecosystem — alongside [SwapLayer](https://github.com/Tunet-xyz/swap_layer) and [InfraGlyph](https://github.com/Tunet-xyz/infra_glyph). See the [SessionArmor product page](https://tunet.xyz/engineering/session-armor/) for the public capability overview.
56
+ Part of the [Tunet](https://tunet.xyz/engineering/) open-source libraries, alongside [AccessGate](https://github.com/Tunet-xyz/access_gate), [GeoCanon](https://github.com/Tunet-xyz/GeoCanon), and [SwapLayer](https://github.com/Tunet-xyz/swap_layer). See the [SessionArmor product page](https://tunet.xyz/engineering/session-armor/) for the public capability overview.
57
+
58
+ ## Version 1.0
59
+
60
+ The documented assurance contracts, typed gate decisions, explicit Django adapter,
61
+ extension hooks, and `sessionarmor-mcp` entry point form the stable 1.x API.
62
+ The dependency-free core supports Python 3.10–3.13; the Django extra supports
63
+ Django 4.2–5.2 (`<6`). Use a Django version still receiving upstream security
64
+ updates. The `session-armor.assurance/v1` schema remains unchanged.
65
+
66
+ Upgrading from 0.5 or 0.6 keeps the explicit imports below. Older integrations
67
+ must move middleware imports to `session_armor.adapters.django`, return
68
+ `GateDecision` from gate hooks, and use the `SESSION_ARMOR_*` settings documented
69
+ here. See the [changelog](https://github.com/Tunet-xyz/session_armor/blob/main/CHANGELOG.md) and [release procedure](https://github.com/Tunet-xyz/session_armor/blob/main/docs/RELEASE.md).
55
70
 
56
71
  ---
57
72
 
@@ -76,7 +91,7 @@ All three are **hookable** — override methods to customize behavior without to
76
91
  - [NIST SP 800-53 AU-3/AU-12](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) (Audit Content/Generation)
77
92
  - [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
78
93
 
79
- SessionArmor adds controls around an existing Django authentication and session setup; it does not replace HTTPS, secure cookie settings, CSRF protection, authorization, MFA, or incident response. Fingerprint binding is a replay signal rather than proof of device identity and can require tuning for mobile or privacy-network traffic. See the [security model](docs/security-model.md) for deployment assumptions, limitations, and a release checklist.
94
+ SessionArmor adds controls around an existing Django authentication and session setup; it does not replace HTTPS, secure cookie settings, CSRF protection, authorization, MFA, or incident response. Fingerprint binding is a replay signal rather than proof of device identity and can require tuning for mobile or privacy-network traffic. See the [security model](https://github.com/Tunet-xyz/session_armor/blob/main/docs/security-model.md) for deployment assumptions, limitations, and a release checklist.
80
95
 
81
96
  ---
82
97
 
@@ -117,6 +132,7 @@ SESSION_ARMOR_CLOCK_SKEW = 60
117
132
  SESSION_ARMOR_LAST_ACTIVE_RESOLUTION = 0
118
133
  SESSION_ARMOR_NO_STORE = True
119
134
  SESSION_ARMOR_STATE_KEY = SECRET_KEY
135
+ SESSION_ARMOR_STATE_KEY_FALLBACKS = None # None: follow SECRET_KEY_FALLBACKS
120
136
  SESSION_ARMOR_AUDIT_PEPPER = SECRET_KEY
121
137
 
122
138
  # Forwarded headers are ignored unless both values are configured.
@@ -130,10 +146,20 @@ SESSION_ARMOR_TRUSTED_PROXY_CIDRS = ()
130
146
  > of `SECRET_KEY`, or to share it across services for cross-log correlation.
131
147
  > If unset, it falls back to `SECRET_KEY`.
132
148
 
149
+ > **Note on key rotation.** `SESSION_ARMOR_STATE_KEY_FALLBACKS` lists retired
150
+ > state keys. They only verify existing session state, which is then re-signed
151
+ > with the current key; they never sign. Left at `None`, a state key that
152
+ > follows `SECRET_KEY` uses Django's `SECRET_KEY_FALLBACKS`, so Django's
153
+ > documented rotation keeps sessions alive. Do not keep a key that may have
154
+ > leaked. Session identifiers (the gate cache scope) change once, so gates
155
+ > re-check once.
156
+
133
157
  > **Note on proxy trust.** The secure default (`DEPTH = 0`) ignores
134
158
  > `X-Forwarded-For`. To use it, configure both the exact number of proxy hops
135
159
  > and their CIDR ranges. Each trusted hop is checked from the socket peer back
136
- > toward the client; malformed chains and catch-all trusted networks are rejected.
160
+ > toward the client; a malformed client entry or hop and catch-all trusted
161
+ > networks are rejected. Entries left of the client are never read, and
162
+ > forwarded entries may carry a port.
137
163
 
138
164
  ## Building a Gate
139
165
 
@@ -157,15 +183,32 @@ class ComplianceGate(GateMiddleware):
157
183
  return redirect('/accept-terms/')
158
184
  ```
159
185
 
186
+ A gate with `requires_trusted_session = True` rejects every path that
187
+ `SessionSecurityMiddleware` exempts, unless its own `exempt_paths` repeat them.
188
+ Set `follow_session_exemptions = True` to let those requests through instead.
189
+
190
+ If `check()` raises, `on_error()` turns the failure into a rejection, and that
191
+ rejection is cached for the full TTL like any other result. Set
192
+ `error_cache_ttl` (seconds) to re-check sooner once a dependency recovers.
193
+
194
+ The page a rejection leads to can read the last result with
195
+ `ComplianceGate.get_cached_decision(request)` or `get_context(request)`; the
196
+ `_gate_*` session keys behind them are private.
197
+
160
198
  ### "Check once" gates
161
199
 
162
200
  For gates that should only kick in once (onboarding, compliance), set
163
- `recheck_after_pass = False`: a passing result stays cached in the session
164
- with no TTL re-checks. To push new requirements to already-passed sessions
165
- (a new document version, a new onboarding step), implement
166
- `get_state_version()` against a shared cache key and bump that key on
167
- publish — every active session re-checks exactly once, with no per-request
168
- database hits:
201
+ `recheck_after_pass = False`: a passing result is then reused with no TTL
202
+ re-checks, for up to `sticky_pass_max_age` seconds and while
203
+ `get_state_version()` returns the version it was cached under. A sticky pass
204
+ needs at least one of the two: with no `sticky_pass_max_age` and a `None`
205
+ version, a pass is never reused and `check()` runs on every request.
206
+ Rejections still re-check on the TTL. To push new requirements to
207
+ already-passed sessions (a new document version, a new onboarding step),
208
+ implement `get_state_version()` against a shared cache key and bump that key
209
+ on publish — every active session re-checks exactly once, with no per-request
210
+ database hits. It must return a non-empty string of at most 256 characters or
211
+ `None`; anything else, an empty string included, fails closed:
169
212
 
170
213
  ```python
171
214
  from django.core.cache import cache
@@ -173,10 +216,12 @@ from django.core.cache import cache
173
216
  class ComplianceGate(GateMiddleware):
174
217
  gate_id = 'compliance'
175
218
  recheck_after_pass = False # Pass once, stay passed
219
+ sticky_pass_max_age = 3600 # Re-check a pass at least hourly, version or not
176
220
 
177
221
  def get_state_version(self, request) -> str | None:
178
- # Bumped by admin tooling when a new document version is published
179
- return cache.get(f'compliance_version:{request.user.platform}', '')
222
+ # Bumped by admin tooling when a new document version is published;
223
+ # None until the key is first set.
224
+ return cache.get(f'compliance_version:{request.user.platform}')
180
225
 
181
226
  def check(self, request) -> GateDecision:
182
227
  return (
@@ -186,10 +231,11 @@ class ComplianceGate(GateMiddleware):
186
231
  )
187
232
  ```
188
233
 
189
- > **Sticky passes and revocation.** With `recheck_after_pass = False`, a pass
190
- > is cached until the session ends, `invalidate()` is called, or the state
191
- > version changes — so it is **not** appropriate for authorization/entitlement
192
- > gates where access may be revoked. For those, use a normal TTL gate, drive
234
+ > **Sticky passes and revocation.** With `recheck_after_pass = False` and a
235
+ > state version but no `sticky_pass_max_age`, a pass is cached until the
236
+ > session ends, `invalidate()` is called, or the state version changes — so it
237
+ > is **not** appropriate for authorization/entitlement gates where access may
238
+ > be revoked. For those, use a normal TTL gate, drive
193
239
  > `get_state_version()`, or set `sticky_pass_max_age` (seconds) to cap how long
194
240
  > a sticky pass may be reused before a forced re-check.
195
241
 
@@ -211,10 +257,34 @@ class MySessionSecurity(SessionSecurityMiddleware):
211
257
  return f'/{platform}/login/' if platform else '/login/'
212
258
 
213
259
  # After a reviewed server-side claim update, use the public API rather than
214
- # writing SessionArmor's private session keys.
215
- MySessionSecurity(lambda request: request).rebaseline_claims(request)
260
+ # writing SessionArmor's private session keys. Pass the updated user when
261
+ # request.user still holds the old claims; refresh_assurance=True also
262
+ # re-verifies and re-issues this request's evidence, so code never builds
263
+ # SessionAssurance itself.
264
+ MySessionSecurity(lambda request: request).rebaseline_claims(
265
+ request, updated_user, refresh_assurance=True
266
+ )
267
+
268
+ # At an authentication boundary (a new sign-in on an existing session), forget
269
+ # the previous state; has_state(session) says whether rebaseline_claims() can run.
270
+ MySessionSecurity.discard_state(request.session)
271
+
272
+ # In the login view, once the session holds the new identity, bind it to the
273
+ # client that logged in. Otherwise the first later request presenting the new
274
+ # cookie sets the binding (with signed cookies, at any time until it expires).
275
+ MySessionSecurity(lambda request: request).establish(request, user)
216
276
  ```
217
277
 
278
+ `exempt_paths` are matched against `request.path_info`, the path Django routes
279
+ on, so leave any deployment mount prefix out of them. Matching respects path
280
+ segments: `/health` exempts `/health` and `/health/live` but not
281
+ `/health-internal`, and `/` exempts only the root URL.
282
+
283
+ To diagnose a `fingerprint_mismatch`, `binding_digests(request)` returns keyed
284
+ digests of each binding factor (`hash_ip(value, length=12)` with the audit
285
+ pepper), so logs can show which factor changed without holding a raw IP or
286
+ User-Agent.
287
+
218
288
  ## AccessGate integration
219
289
 
220
290
  SessionArmor and AccessGate are complementary boundaries. SessionArmor decides
@@ -234,7 +304,10 @@ engine = AuthorizationEngine([
234
304
  ```
235
305
 
236
306
  The assurance policy is deny-only: a trusted session never grants a permission
237
- by itself. See [`docs/ACCESSGATE_INTEGRATION.md`](docs/ACCESSGATE_INTEGRATION.md).
307
+ by itself. When slow work sits between SessionArmor and the authorization
308
+ decision, call `refresh_assurance(request)` just before deciding: it
309
+ re-verifies the session and re-issues the evidence, and can withdraw trust but
310
+ never grant it. See [`docs/ACCESSGATE_INTEGRATION.md`](https://github.com/Tunet-xyz/session_armor/blob/main/docs/ACCESSGATE_INTEGRATION.md).
238
311
 
239
312
  ## Customizing Audit Logging
240
313
 
@@ -252,6 +325,10 @@ class MyAudit(AuditMiddleware):
252
325
  }
253
326
  ```
254
327
 
328
+ `path` is reserved evidence that `before_log()` cannot change. When URL paths
329
+ carry secrets (invitation tokens, one-time codes), override
330
+ `get_audit_path(request)` to return a redacted path instead.
331
+
255
332
  ---
256
333
 
257
334
  ## Development
@@ -275,7 +352,7 @@ mypy src/session_armor
275
352
 
276
353
  ## Public Agent MCP Contract
277
354
 
278
- SessionArmor includes a public agent-operability contract in [`mcp/`](mcp/). It describes how external agents can safely help with middleware ordering, security settings, audit customization, gate design, browser-visible docs, and rollout planning without requiring source-code access or production session data.
355
+ SessionArmor includes a public agent-operability contract in [`mcp/`](https://github.com/Tunet-xyz/session_armor/tree/main/mcp/). It describes how external agents can safely help with middleware ordering, security settings, audit customization, gate design, browser-visible docs, and rollout planning without requiring source-code access or production session data.
279
356
 
280
357
  From a checkout, run the dependency-free contract server with `python mcp/server.py`. After installation, agents can use the packaged stdio command:
281
358
 
@@ -283,6 +360,14 @@ From a checkout, run the dependency-free contract server with `python mcp/server
283
360
  sessionarmor-mcp
284
361
  ```
285
362
 
363
+ This starts a local documentation and draft-generation server using the caller's
364
+ own environment. It does not connect to Tunet's agents, paid accounts, release
365
+ credentials, or production systems, and no hosted maintainer agent is included.
366
+
367
+ ## Contributing and releases
368
+
369
+ See [CONTRIBUTING.md](https://github.com/Tunet-xyz/session_armor/blob/main/CONTRIBUTING.md) for the owner-reviewed contribution process and [VERSIONING.md](https://github.com/Tunet-xyz/session_armor/blob/main/VERSIONING.md) for the shared SemVer and release policy. Public PRs and agent mentions cannot authorize maintainer work; repository jobs require owner dispatch. Vendor-hosted GitHub app access is controlled separately in the owner's account settings.
370
+
286
371
  ## License
287
372
 
288
- MIT — Copyright (c) 2024-2026 Tunet Ltd. See [LICENSE](LICENSE).
373
+ MIT — Copyright (c) 2024-2026 Tunet Ltd. See [LICENSE](https://github.com/Tunet-xyz/session_armor/blob/main/LICENSE).
@@ -8,7 +8,20 @@
8
8
 
9
9
  **Framework-neutral session-assurance contracts with an optional Django adapter for session integrity, privacy-aware audit logging, and configurable request gates.**
10
10
 
11
- Part of the [Tunet](https://tunet.xyz/engineering/) ecosystem — alongside [SwapLayer](https://github.com/Tunet-xyz/swap_layer) and [InfraGlyph](https://github.com/Tunet-xyz/infra_glyph). See the [SessionArmor product page](https://tunet.xyz/engineering/session-armor/) for the public capability overview.
11
+ Part of the [Tunet](https://tunet.xyz/engineering/) open-source libraries, alongside [AccessGate](https://github.com/Tunet-xyz/access_gate), [GeoCanon](https://github.com/Tunet-xyz/GeoCanon), and [SwapLayer](https://github.com/Tunet-xyz/swap_layer). See the [SessionArmor product page](https://tunet.xyz/engineering/session-armor/) for the public capability overview.
12
+
13
+ ## Version 1.0
14
+
15
+ The documented assurance contracts, typed gate decisions, explicit Django adapter,
16
+ extension hooks, and `sessionarmor-mcp` entry point form the stable 1.x API.
17
+ The dependency-free core supports Python 3.10–3.13; the Django extra supports
18
+ Django 4.2–5.2 (`<6`). Use a Django version still receiving upstream security
19
+ updates. The `session-armor.assurance/v1` schema remains unchanged.
20
+
21
+ Upgrading from 0.5 or 0.6 keeps the explicit imports below. Older integrations
22
+ must move middleware imports to `session_armor.adapters.django`, return
23
+ `GateDecision` from gate hooks, and use the `SESSION_ARMOR_*` settings documented
24
+ here. See the [changelog](https://github.com/Tunet-xyz/session_armor/blob/main/CHANGELOG.md) and [release procedure](https://github.com/Tunet-xyz/session_armor/blob/main/docs/RELEASE.md).
12
25
 
13
26
  ---
14
27
 
@@ -33,7 +46,7 @@ All three are **hookable** — override methods to customize behavior without to
33
46
  - [NIST SP 800-53 AU-3/AU-12](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) (Audit Content/Generation)
34
47
  - [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
35
48
 
36
- SessionArmor adds controls around an existing Django authentication and session setup; it does not replace HTTPS, secure cookie settings, CSRF protection, authorization, MFA, or incident response. Fingerprint binding is a replay signal rather than proof of device identity and can require tuning for mobile or privacy-network traffic. See the [security model](docs/security-model.md) for deployment assumptions, limitations, and a release checklist.
49
+ SessionArmor adds controls around an existing Django authentication and session setup; it does not replace HTTPS, secure cookie settings, CSRF protection, authorization, MFA, or incident response. Fingerprint binding is a replay signal rather than proof of device identity and can require tuning for mobile or privacy-network traffic. See the [security model](https://github.com/Tunet-xyz/session_armor/blob/main/docs/security-model.md) for deployment assumptions, limitations, and a release checklist.
37
50
 
38
51
  ---
39
52
 
@@ -74,6 +87,7 @@ SESSION_ARMOR_CLOCK_SKEW = 60
74
87
  SESSION_ARMOR_LAST_ACTIVE_RESOLUTION = 0
75
88
  SESSION_ARMOR_NO_STORE = True
76
89
  SESSION_ARMOR_STATE_KEY = SECRET_KEY
90
+ SESSION_ARMOR_STATE_KEY_FALLBACKS = None # None: follow SECRET_KEY_FALLBACKS
77
91
  SESSION_ARMOR_AUDIT_PEPPER = SECRET_KEY
78
92
 
79
93
  # Forwarded headers are ignored unless both values are configured.
@@ -87,10 +101,20 @@ SESSION_ARMOR_TRUSTED_PROXY_CIDRS = ()
87
101
  > of `SECRET_KEY`, or to share it across services for cross-log correlation.
88
102
  > If unset, it falls back to `SECRET_KEY`.
89
103
 
104
+ > **Note on key rotation.** `SESSION_ARMOR_STATE_KEY_FALLBACKS` lists retired
105
+ > state keys. They only verify existing session state, which is then re-signed
106
+ > with the current key; they never sign. Left at `None`, a state key that
107
+ > follows `SECRET_KEY` uses Django's `SECRET_KEY_FALLBACKS`, so Django's
108
+ > documented rotation keeps sessions alive. Do not keep a key that may have
109
+ > leaked. Session identifiers (the gate cache scope) change once, so gates
110
+ > re-check once.
111
+
90
112
  > **Note on proxy trust.** The secure default (`DEPTH = 0`) ignores
91
113
  > `X-Forwarded-For`. To use it, configure both the exact number of proxy hops
92
114
  > and their CIDR ranges. Each trusted hop is checked from the socket peer back
93
- > toward the client; malformed chains and catch-all trusted networks are rejected.
115
+ > toward the client; a malformed client entry or hop and catch-all trusted
116
+ > networks are rejected. Entries left of the client are never read, and
117
+ > forwarded entries may carry a port.
94
118
 
95
119
  ## Building a Gate
96
120
 
@@ -114,15 +138,32 @@ class ComplianceGate(GateMiddleware):
114
138
  return redirect('/accept-terms/')
115
139
  ```
116
140
 
141
+ A gate with `requires_trusted_session = True` rejects every path that
142
+ `SessionSecurityMiddleware` exempts, unless its own `exempt_paths` repeat them.
143
+ Set `follow_session_exemptions = True` to let those requests through instead.
144
+
145
+ If `check()` raises, `on_error()` turns the failure into a rejection, and that
146
+ rejection is cached for the full TTL like any other result. Set
147
+ `error_cache_ttl` (seconds) to re-check sooner once a dependency recovers.
148
+
149
+ The page a rejection leads to can read the last result with
150
+ `ComplianceGate.get_cached_decision(request)` or `get_context(request)`; the
151
+ `_gate_*` session keys behind them are private.
152
+
117
153
  ### "Check once" gates
118
154
 
119
155
  For gates that should only kick in once (onboarding, compliance), set
120
- `recheck_after_pass = False`: a passing result stays cached in the session
121
- with no TTL re-checks. To push new requirements to already-passed sessions
122
- (a new document version, a new onboarding step), implement
123
- `get_state_version()` against a shared cache key and bump that key on
124
- publish — every active session re-checks exactly once, with no per-request
125
- database hits:
156
+ `recheck_after_pass = False`: a passing result is then reused with no TTL
157
+ re-checks, for up to `sticky_pass_max_age` seconds and while
158
+ `get_state_version()` returns the version it was cached under. A sticky pass
159
+ needs at least one of the two: with no `sticky_pass_max_age` and a `None`
160
+ version, a pass is never reused and `check()` runs on every request.
161
+ Rejections still re-check on the TTL. To push new requirements to
162
+ already-passed sessions (a new document version, a new onboarding step),
163
+ implement `get_state_version()` against a shared cache key and bump that key
164
+ on publish — every active session re-checks exactly once, with no per-request
165
+ database hits. It must return a non-empty string of at most 256 characters or
166
+ `None`; anything else, an empty string included, fails closed:
126
167
 
127
168
  ```python
128
169
  from django.core.cache import cache
@@ -130,10 +171,12 @@ from django.core.cache import cache
130
171
  class ComplianceGate(GateMiddleware):
131
172
  gate_id = 'compliance'
132
173
  recheck_after_pass = False # Pass once, stay passed
174
+ sticky_pass_max_age = 3600 # Re-check a pass at least hourly, version or not
133
175
 
134
176
  def get_state_version(self, request) -> str | None:
135
- # Bumped by admin tooling when a new document version is published
136
- return cache.get(f'compliance_version:{request.user.platform}', '')
177
+ # Bumped by admin tooling when a new document version is published;
178
+ # None until the key is first set.
179
+ return cache.get(f'compliance_version:{request.user.platform}')
137
180
 
138
181
  def check(self, request) -> GateDecision:
139
182
  return (
@@ -143,10 +186,11 @@ class ComplianceGate(GateMiddleware):
143
186
  )
144
187
  ```
145
188
 
146
- > **Sticky passes and revocation.** With `recheck_after_pass = False`, a pass
147
- > is cached until the session ends, `invalidate()` is called, or the state
148
- > version changes — so it is **not** appropriate for authorization/entitlement
149
- > gates where access may be revoked. For those, use a normal TTL gate, drive
189
+ > **Sticky passes and revocation.** With `recheck_after_pass = False` and a
190
+ > state version but no `sticky_pass_max_age`, a pass is cached until the
191
+ > session ends, `invalidate()` is called, or the state version changes — so it
192
+ > is **not** appropriate for authorization/entitlement gates where access may
193
+ > be revoked. For those, use a normal TTL gate, drive
150
194
  > `get_state_version()`, or set `sticky_pass_max_age` (seconds) to cap how long
151
195
  > a sticky pass may be reused before a forced re-check.
152
196
 
@@ -168,10 +212,34 @@ class MySessionSecurity(SessionSecurityMiddleware):
168
212
  return f'/{platform}/login/' if platform else '/login/'
169
213
 
170
214
  # After a reviewed server-side claim update, use the public API rather than
171
- # writing SessionArmor's private session keys.
172
- MySessionSecurity(lambda request: request).rebaseline_claims(request)
215
+ # writing SessionArmor's private session keys. Pass the updated user when
216
+ # request.user still holds the old claims; refresh_assurance=True also
217
+ # re-verifies and re-issues this request's evidence, so code never builds
218
+ # SessionAssurance itself.
219
+ MySessionSecurity(lambda request: request).rebaseline_claims(
220
+ request, updated_user, refresh_assurance=True
221
+ )
222
+
223
+ # At an authentication boundary (a new sign-in on an existing session), forget
224
+ # the previous state; has_state(session) says whether rebaseline_claims() can run.
225
+ MySessionSecurity.discard_state(request.session)
226
+
227
+ # In the login view, once the session holds the new identity, bind it to the
228
+ # client that logged in. Otherwise the first later request presenting the new
229
+ # cookie sets the binding (with signed cookies, at any time until it expires).
230
+ MySessionSecurity(lambda request: request).establish(request, user)
173
231
  ```
174
232
 
233
+ `exempt_paths` are matched against `request.path_info`, the path Django routes
234
+ on, so leave any deployment mount prefix out of them. Matching respects path
235
+ segments: `/health` exempts `/health` and `/health/live` but not
236
+ `/health-internal`, and `/` exempts only the root URL.
237
+
238
+ To diagnose a `fingerprint_mismatch`, `binding_digests(request)` returns keyed
239
+ digests of each binding factor (`hash_ip(value, length=12)` with the audit
240
+ pepper), so logs can show which factor changed without holding a raw IP or
241
+ User-Agent.
242
+
175
243
  ## AccessGate integration
176
244
 
177
245
  SessionArmor and AccessGate are complementary boundaries. SessionArmor decides
@@ -191,7 +259,10 @@ engine = AuthorizationEngine([
191
259
  ```
192
260
 
193
261
  The assurance policy is deny-only: a trusted session never grants a permission
194
- by itself. See [`docs/ACCESSGATE_INTEGRATION.md`](docs/ACCESSGATE_INTEGRATION.md).
262
+ by itself. When slow work sits between SessionArmor and the authorization
263
+ decision, call `refresh_assurance(request)` just before deciding: it
264
+ re-verifies the session and re-issues the evidence, and can withdraw trust but
265
+ never grant it. See [`docs/ACCESSGATE_INTEGRATION.md`](https://github.com/Tunet-xyz/session_armor/blob/main/docs/ACCESSGATE_INTEGRATION.md).
195
266
 
196
267
  ## Customizing Audit Logging
197
268
 
@@ -209,6 +280,10 @@ class MyAudit(AuditMiddleware):
209
280
  }
210
281
  ```
211
282
 
283
+ `path` is reserved evidence that `before_log()` cannot change. When URL paths
284
+ carry secrets (invitation tokens, one-time codes), override
285
+ `get_audit_path(request)` to return a redacted path instead.
286
+
212
287
  ---
213
288
 
214
289
  ## Development
@@ -232,7 +307,7 @@ mypy src/session_armor
232
307
 
233
308
  ## Public Agent MCP Contract
234
309
 
235
- SessionArmor includes a public agent-operability contract in [`mcp/`](mcp/). It describes how external agents can safely help with middleware ordering, security settings, audit customization, gate design, browser-visible docs, and rollout planning without requiring source-code access or production session data.
310
+ SessionArmor includes a public agent-operability contract in [`mcp/`](https://github.com/Tunet-xyz/session_armor/tree/main/mcp/). It describes how external agents can safely help with middleware ordering, security settings, audit customization, gate design, browser-visible docs, and rollout planning without requiring source-code access or production session data.
236
311
 
237
312
  From a checkout, run the dependency-free contract server with `python mcp/server.py`. After installation, agents can use the packaged stdio command:
238
313
 
@@ -240,6 +315,14 @@ From a checkout, run the dependency-free contract server with `python mcp/server
240
315
  sessionarmor-mcp
241
316
  ```
242
317
 
318
+ This starts a local documentation and draft-generation server using the caller's
319
+ own environment. It does not connect to Tunet's agents, paid accounts, release
320
+ credentials, or production systems, and no hosted maintainer agent is included.
321
+
322
+ ## Contributing and releases
323
+
324
+ See [CONTRIBUTING.md](https://github.com/Tunet-xyz/session_armor/blob/main/CONTRIBUTING.md) for the owner-reviewed contribution process and [VERSIONING.md](https://github.com/Tunet-xyz/session_armor/blob/main/VERSIONING.md) for the shared SemVer and release policy. Public PRs and agent mentions cannot authorize maintainer work; repository jobs require owner dispatch. Vendor-hosted GitHub app access is controlled separately in the owner's account settings.
325
+
243
326
  ## License
244
327
 
245
- MIT — Copyright (c) 2024-2026 Tunet Ltd. See [LICENSE](LICENSE).
328
+ MIT — Copyright (c) 2024-2026 Tunet Ltd. See [LICENSE](https://github.com/Tunet-xyz/session_armor/blob/main/LICENSE).
@@ -4,9 +4,8 @@
4
4
 
5
5
  | Version | Supported |
6
6
  | ------- | ------------------ |
7
- | 0.4.x | :white_check_mark: |
8
- | 0.3.x | Security fixes only during migration |
9
- | < 0.3 | :x: |
7
+ | 1.0.x | :white_check_mark: |
8
+ | < 1.0 | :x: |
10
9
 
11
10
  ## Reporting a Vulnerability
12
11