medre-adapter-matrix 0.1.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.
- medre_adapter_matrix-0.1.0/LICENSE +21 -0
- medre_adapter_matrix-0.1.0/MANIFEST.in +1 -0
- medre_adapter_matrix-0.1.0/PKG-INFO +442 -0
- medre_adapter_matrix-0.1.0/README.md +421 -0
- medre_adapter_matrix-0.1.0/docs/schemas/README.md +61 -0
- medre_adapter_matrix-0.1.0/docs/schemas/examples/matrix-durable-checkpoint-example.json +4 -0
- medre_adapter_matrix-0.1.0/docs/schemas/examples/matrix-native-metadata-example.json +47 -0
- medre_adapter_matrix-0.1.0/docs/schemas/matrix-durable-checkpoint.schema.json +18 -0
- medre_adapter_matrix-0.1.0/docs/schemas/matrix-embedded-metadata.schema.json +364 -0
- medre_adapter_matrix-0.1.0/docs/schemas/matrix-native-metadata.schema.json +451 -0
- medre_adapter_matrix-0.1.0/docs/schemas/matrix-oauth-credentials.schema.json +96 -0
- medre_adapter_matrix-0.1.0/docs/schemas/v0.1.0.freeze.json +10 -0
- medre_adapter_matrix-0.1.0/pyproject.toml +85 -0
- medre_adapter_matrix-0.1.0/setup.cfg +4 -0
- medre_adapter_matrix-0.1.0/setup.py +75 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/fakes/matrix.py +496 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/__init__.py +9 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/adapter.py +2093 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/attribution.py +252 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/auth.py +360 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/bridge_context.py +8 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/cli.py +523 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/cli_contrib.py +320 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/client_lifecycle.py +46 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/codec.py +430 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/compat.py +45 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/device_trust.py +221 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/durable_sync.py +297 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/e2ee_bootstrap.py +189 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/errors.py +180 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/event_shape.py +351 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/identity.py +846 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/metadata.py +208 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth.py +624 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_approval.py +155 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_cli.py +179 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_session.py +297 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/outbound.py +255 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/plugin.py +72 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/provision.py +508 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/py.typed +0 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/relations.py +201 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/renderer.py +1344 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/runtime.py +88 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/sample.py +17 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/session.py +3483 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/signing_cli.py +161 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/signing_recovery.py +135 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/stopped_declaration.py +194 -0
- medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/styling.py +230 -0
- medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix.py +395 -0
- medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_credentials.py +109 -0
- medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_destinations.py +13 -0
- medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_errors.py +7 -0
- medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_runtime.py +20 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/PKG-INFO +442 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/SOURCES.txt +156 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/dependency_links.txt +1 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/entry_points.txt +2 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/requires.txt +12 -0
- medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/top_level.txt +1 -0
- medre_adapter_matrix-0.1.0/tests/test_discovery_matrix.py +17 -0
- medre_adapter_matrix-0.1.0/tests/test_distribution_license.py +67 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_adapter.py +1292 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_auto_join.py +197 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_delivery.py +217 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_startup.py +727 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_alpha_run_session.py +456 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_attachment_ingress.py +540 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_attribution.py +538 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_auth_live.py +47 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_auth_login.py +625 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_behavior_reference.py +774 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_boundaries.py +1011 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_bridge_context.py +301 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_cli.py +42 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_client_lifecycle.py +81 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_codec.py +394 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_config.py +821 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_contract_docs.py +53 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_credentials_storage.py +81 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_auth.py +567 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_identity.py +513 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_runtime.py +172 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_sdk_contract.py +149 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_decrypted_event_sdk_contract.py +125 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_default_prefix.py +99 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust.py +951 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust_docker.py +846 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust_sdk_contract.py +192 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_durable_admission_boundary.py +81 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_durable_batches.py +895 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_durable_review.py +166 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_durable_runtime_live.py +324 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_e2ee_live.py +310 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_embedding_modes.py +140 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_event_shape.py +963 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_fake_bridge.py +1193 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_formatted_body.py +323 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_health_lifecycle.py +436 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_health_reasons.py +68 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_identity_continuity_sdk.py +174 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_invite_registration.py +66 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_lifecycle.py +587 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_live.py +1245 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_metadata.py +139 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_native_health.py +290 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_native_lifecycle.py +920 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_oauth.py +572 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_lock.py +75 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_redirects.py +137 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_sdk_contract.py +100 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_setup.py +692 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_outbound_envelope.py +139 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_pipeline.py +688 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_provision.py +584 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_rate_limit_ownership.py +109 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_reaction_described_delivery.py +324 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_reaction_key.py +83 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_relations.py +132 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_resume_room_state.py +41 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_room_policy.py +379 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_send_idempotency.py +974 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_send_media.py +983 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session.py +1450 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_config.py +340 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_coverage.py +452 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_e2ee.py +919 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_event_shape.py +324 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_media_transfer.py +637 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_recovery.py +1175 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_session_sync_boundary.py +530 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_signing_recovery.py +530 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_startup_admission.py +158 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_startup_grace.py +304 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_storage_roundtrip.py +396 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_store_lifecycle_sdk.py +67 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_styling.py +209 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_sync_checkpoint_ownership.py +529 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_sync_recovery_sdk_contract.py +78 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_target_selection_rules.py +472 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_thread_reply_intent.py +49 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_trust_review_regressions.py +110 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_typing.py +168 -0
- medre_adapter_matrix-0.1.0/tests/test_matrix_unbound_reply.py +103 -0
- medre_adapter_matrix-0.1.0/tests/test_native_destination.py +30 -0
- medre_adapter_matrix-0.1.0/tests/test_native_setup.py +64 -0
- medre_adapter_matrix-0.1.0/tests/test_offline_sample.py +31 -0
- medre_adapter_matrix-0.1.0/tests/test_optional_e2ee_readiness.py +124 -0
- medre_adapter_matrix-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
- medre_adapter_matrix-0.1.0/tests/test_plugin_api_version.py +10 -0
- medre_adapter_matrix-0.1.0/tests/test_provider_contract.py +53 -0
- medre_adapter_matrix-0.1.0/tests/test_rendering_boundaries.py +256 -0
- medre_adapter_matrix-0.1.0/tests/test_runtime_preparation.py +78 -0
- medre_adapter_matrix-0.1.0/tests/test_schema_freeze_010.py +146 -0
- medre_adapter_matrix-0.1.0/tests/test_schema_wheel_resources.py +151 -0
- medre_adapter_matrix-0.1.0/tests/test_stopped_capture_sdk.py +301 -0
- medre_adapter_matrix-0.1.0/tests/test_stopped_declaration.py +120 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jeremiah K.
|
|
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 @@
|
|
|
1
|
+
recursive-include docs/schemas *
|
|
@@ -0,0 +1,442 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: medre-adapter-matrix
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: matrix transport adapter for MEDRE
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Classifier: Typing :: Typed
|
|
7
|
+
Requires-Python: >=3.12
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Dist: medre<0.2.0,>=0.1.0
|
|
11
|
+
Requires-Dist: mindroom-nio[e2e]==1.3.0
|
|
12
|
+
Provides-Extra: test
|
|
13
|
+
Requires-Dist: pytest==9.2.0; extra == "test"
|
|
14
|
+
Requires-Dist: pytest-asyncio==1.5.0; extra == "test"
|
|
15
|
+
Requires-Dist: pytest-timeout==2.4.0; extra == "test"
|
|
16
|
+
Requires-Dist: jsonschema==4.26.0; extra == "test"
|
|
17
|
+
Requires-Dist: packaging==26.3; extra == "test"
|
|
18
|
+
Provides-Extra: e2e
|
|
19
|
+
Requires-Dist: mindroom-nio[e2e]==1.3.0; extra == "e2e"
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# medre-adapter-matrix
|
|
23
|
+
|
|
24
|
+
**Matrix provider for MEDRE.** This separately installed distribution owns its
|
|
25
|
+
transport SDK, configuration, native codec and offline fake. MEDRE core owns
|
|
26
|
+
routing, storage, lifecycle and delivery evidence.
|
|
27
|
+
|
|
28
|
+
## Install from Git
|
|
29
|
+
|
|
30
|
+
Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
|
|
31
|
+
a first trial, MEDRE can manage this provider in its persistent tool environment:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
|
|
35
|
+
medre adapters install matrix
|
|
36
|
+
medre adapters
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Matrix requires Python 3.12+ and includes its durable SQLite/crypto backend.
|
|
40
|
+
The `matrix[e2e]` spelling remains a compatible installation alias.
|
|
41
|
+
The released mindroom-nio store requires POSIX file leases; Windows
|
|
42
|
+
production sessions require a provider release with Windows lease support.
|
|
43
|
+
|
|
44
|
+
On Windows, the package-changing command prints a uv command to run **after**
|
|
45
|
+
`medre.exe` exits, rather than replacing an executable still in use.
|
|
46
|
+
The `main` branch is useful for trials; pin exact core and adapter commits for
|
|
47
|
+
repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
|
|
48
|
+
for fake smoke, guided route creation and native setup. Use the
|
|
49
|
+
[adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
|
|
50
|
+
for a locked uv deployment project, private Git, local checkouts, index sources,
|
|
51
|
+
and the same-environment requirement. Neither MEDRE nor the provider installs
|
|
52
|
+
packages during runtime startup.
|
|
53
|
+
|
|
54
|
+
## Startup readiness
|
|
55
|
+
|
|
56
|
+
After authentication and configured room joins, startup waits up to
|
|
57
|
+
`initial_sync_timeout_seconds` (45 seconds by default) for the first acknowledged
|
|
58
|
+
sync. A pending long poll is logged as startup progress. Login alone never
|
|
59
|
+
establishes healthy readiness. On expiry, startup returns with degraded health
|
|
60
|
+
and the existing sync owner keeps recovering; a later acknowledgement publishes
|
|
61
|
+
healthy current state automatically. Native sync failure or reconnect exits
|
|
62
|
+
the wait immediately with its actual health.
|
|
63
|
+
|
|
64
|
+
Set the wait to `0` to report pending health immediately. The runtime's
|
|
65
|
+
`adapter_start_timeout_seconds` bounds the complete adapter start, including
|
|
66
|
+
login, joins, and this wait. Allow additional runtime budget for slow services;
|
|
67
|
+
its cancellation still closes the partially started session. See
|
|
68
|
+
[durable sync](docs/spec/durable-sync.md#startup-readiness) for the contract.
|
|
69
|
+
|
|
70
|
+
## Message presentation
|
|
71
|
+
|
|
72
|
+
Supported Matrix HTML maps to bounded canonical text spans when its visible text
|
|
73
|
+
matches the plain body. Outbound content escapes text and links and keeps relay
|
|
74
|
+
attribution outside source styles. Unsupported or inconsistent markup retains
|
|
75
|
+
plain presentation. See the [presentation contract](docs/spec/relay-attribution.md#text-presentation)
|
|
76
|
+
for reply, edit, truncation, and block-boundary behavior.
|
|
77
|
+
|
|
78
|
+
## Browser-approved Matrix login
|
|
79
|
+
|
|
80
|
+
For an OAuth-enabled homeserver, authorize MEDRE from your browser instead of
|
|
81
|
+
providing its account password. The provider includes the crypto backend;
|
|
82
|
+
select the adapter whose persistent device store should be prepared:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
medre adapter matrix auth login --oauth \
|
|
86
|
+
--user @relay:example.org --adapter-id matrix
|
|
87
|
+
medre adapter matrix auth status
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Use the configured adapter key for `--adapter-id`. The command displays the
|
|
91
|
+
verification address and a short code. Approve only the login you initiated.
|
|
92
|
+
Homeserver discovery follows Matrix delegation; `--homeserver` can select an
|
|
93
|
+
explicit server. `--client-id` supports an existing public client registration
|
|
94
|
+
when dynamic registration is unavailable. Without `--adapter-id`, the command
|
|
95
|
+
only establishes credentials and does not load the E2EE SDK.
|
|
96
|
+
|
|
97
|
+
Keep credentials out of the runtime YAML so its missing authentication fields
|
|
98
|
+
resolve from MEDRE's credential sidecar. Runtime requests automatically renew
|
|
99
|
+
OAuth tokens, including SDK retry attempts. Repeating the login command resumes
|
|
100
|
+
the saved device session and retries signing instead of allocating another
|
|
101
|
+
device. Password options cannot be combined with `--oauth`.
|
|
102
|
+
|
|
103
|
+
The browser may request a separate signing-key approval. A matching account
|
|
104
|
+
identity is reused across devices; a missing local identity for an account that
|
|
105
|
+
already has signing keys requires restoring the original store. Deliberately
|
|
106
|
+
replacing lost or conflicting account keys requires `--reset-cross-signing`:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
medre adapter matrix auth login --oauth --adapter-id matrix --reset-cross-signing
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
A reset can require other clients to verify the account identity again. It is
|
|
113
|
+
not part of routine login. Signing failures retain OAuth credentials and E2EE
|
|
114
|
+
state so setup can be retried. Own-device signing does not verify other users
|
|
115
|
+
or restore historical encrypted room keys.
|
|
116
|
+
|
|
117
|
+
Stop bridges using this account before changing sessions. To revoke a saved
|
|
118
|
+
password or OAuth session and then authenticate again, use:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
medre adapter matrix auth logout
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Logout preserves the crypto store and account-signing sidecar. Back them up
|
|
125
|
+
securely together. Password login remains available on supporting homeservers
|
|
126
|
+
through the existing interactive or `--password-stdin` commands.
|
|
127
|
+
|
|
128
|
+
## Packaging and provenance
|
|
129
|
+
|
|
130
|
+
This distribution registers the `medre.adapters` entry point and retains the
|
|
131
|
+
import namespace `medre.adapters.matrix`. Its original adapter source history
|
|
132
|
+
was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
|
|
133
|
+
Git author and committer identities remain preserved. Runtime configuration and
|
|
134
|
+
adapter discovery do not depend on this repository's distribution name.
|
|
135
|
+
|
|
136
|
+
## Restart and offline messages
|
|
137
|
+
|
|
138
|
+
The SDK persists captured responses, crypto state, recovery and its upstream
|
|
139
|
+
cursor. MEDRE admits committed records before acknowledging their SDK batch.
|
|
140
|
+
Restart replays unacknowledged records through native-ID deduplication. History
|
|
141
|
+
provenance and recovery losses remain explicit; neither a saved cursor nor a
|
|
142
|
+
connected client establishes successful delivery.
|
|
143
|
+
|
|
144
|
+
Inbound events whose origin server timestamp predates the adapter's start by
|
|
145
|
+
more than `startup_backlog_suppress_seconds` (default 60 seconds, `0` disables)
|
|
146
|
+
are startup history and are suppressed on every delivery path — live sync,
|
|
147
|
+
durable catch-up, or gap recovery — using the same transport-neutral
|
|
148
|
+
`should_suppress_startup_backlog` policy the Meshtastic adapter applies. The
|
|
149
|
+
check precedes decode, so messages, reactions, and edits are equally covered,
|
|
150
|
+
and suppressed events count under `inbound_suppressed_stale` in diagnostics.
|
|
151
|
+
The window covers homeserver federation lag and minor clock drift so events
|
|
152
|
+
sent moments before startup still flow.
|
|
153
|
+
|
|
154
|
+
## Ownership and imports
|
|
155
|
+
|
|
156
|
+
This distribution owns Matrix's transport implementation, configuration models,
|
|
157
|
+
runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
|
|
158
|
+
and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
|
|
159
|
+
storage, evidence, configuration orchestration, and installed-package discovery.
|
|
160
|
+
|
|
161
|
+
| Surface | Adapter-owned import |
|
|
162
|
+
| --------------- | ---------------------------------------------------------- |
|
|
163
|
+
| Config models | `medre.config.adapters.matrix` |
|
|
164
|
+
| Runtime wrapper | `medre.config.adapters.matrix_runtime.MatrixRuntimeConfig` |
|
|
165
|
+
| SDK-free fake | `medre.adapters.fakes.matrix.FakeMatrixAdapter` |
|
|
166
|
+
|
|
167
|
+
Import the runtime wrapper from this distribution directly. Core has no named
|
|
168
|
+
wrapper compatibility bridge or transport SDK extras. The supported MEDRE
|
|
169
|
+
interface range and native SDK pins are declared in this project's
|
|
170
|
+
`pyproject.toml`; use a matching core revision during pre-release development.
|
|
171
|
+
Community adapter authors can use their own distribution names, import packages,
|
|
172
|
+
and hosting sources with the same `medre.adapters` entry-point contract.
|
|
173
|
+
|
|
174
|
+
MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
|
|
175
|
+
not relicense installed dependencies. Their license terms still apply to any
|
|
176
|
+
combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
|
|
177
|
+
|
|
178
|
+
## Offline samples and diagnostics
|
|
179
|
+
|
|
180
|
+
This distribution contributes native fake values and an opaque conversation
|
|
181
|
+
address to `medre config sample`. Core includes only installed contributors;
|
|
182
|
+
a single contributor gets two fake instances for offline routing. Native
|
|
183
|
+
packet simulation methods remain adapter-specific. Run-session canonical
|
|
184
|
+
callback injection uses `AdapterContract.publish_inbound(event)`.
|
|
185
|
+
|
|
186
|
+
`medre adapters check --config bridge.yaml` distinguishes missing distributions
|
|
187
|
+
from broken/conflicting entry points. Basic CLI help and unrelated healthy
|
|
188
|
+
providers remain available when another provider fails discovery.
|
|
189
|
+
|
|
190
|
+
Matrix configures the core-owned `medre adapter matrix` parser. Optional CLI
|
|
191
|
+
registration failures are reported as `broken CLI contribution` without
|
|
192
|
+
disabling generic help, preflight, healthy commands, or runtime discovery.
|
|
193
|
+
|
|
194
|
+
Durable sync restores the SDK's persisted membership and encryption projection.
|
|
195
|
+
A fresh store obtains its initial state from the homeserver; existing stores keep
|
|
196
|
+
their device identity and pending batches. See the
|
|
197
|
+
[durable sync contract](docs/spec/durable-sync.md) for adoption and rollback limits.
|
|
198
|
+
|
|
199
|
+
Stopped-state maintenance derives this adapter's capture inventory from a
|
|
200
|
+
provider-owned declaration shipped in this distribution; the durable store and
|
|
201
|
+
token sidecar are declared honestly rather than guessed. See the
|
|
202
|
+
[stopped-state declaration contract](docs/spec/stopped-state.md).
|
|
203
|
+
|
|
204
|
+
Matrix event `content.medre` carries versioned canonical provenance and selected
|
|
205
|
+
metadata. `metadata_embedding_mode` is destination-specific: `off` omits the
|
|
206
|
+
MEDRE namespace, `minimal` carries event/actor identity, `safe` adds native
|
|
207
|
+
message references and normalized metadata, and `full` also includes provider
|
|
208
|
+
native and custom metadata. Full mode exports those details deliberately;
|
|
209
|
+
configuration and SDK objects are never embedded.
|
|
210
|
+
|
|
211
|
+
Outbound Matrix content carries no legacy `meshtastic_*` fields; the embedded
|
|
212
|
+
MEDRE namespace is the only relay metadata surface, and selecting
|
|
213
|
+
`metadata_embedding_mode: off` yields content without it. Embedded provenance
|
|
214
|
+
is an untrusted relay hint, not delivery evidence or authorization to operate
|
|
215
|
+
on another message. The wire contract is
|
|
216
|
+
[matrix-embedded-metadata.schema.json](docs/schemas/matrix-embedded-metadata.schema.json).
|
|
217
|
+
|
|
218
|
+
## Tests
|
|
219
|
+
|
|
220
|
+
Protocol and SDK contract tests live in this repository with adapter-owned
|
|
221
|
+
helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
|
|
222
|
+
following from this repository in a fresh virtual environment, with a matching
|
|
223
|
+
MEDRE checkout at any location. Set `MEDRE_CORE` to that checkout path.
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
# SDK-free fake tier: core dev supplies test tooling; skip this adapter's SDK deps.
|
|
227
|
+
python -m pip install -e "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}[dev]"
|
|
228
|
+
python -m pip install --no-deps -e .
|
|
229
|
+
python -m pytest -q
|
|
230
|
+
|
|
231
|
+
# Native SDK tier: this distribution supplies its own SDK pins.
|
|
232
|
+
python -m pip install -e '.[test,e2e]'
|
|
233
|
+
python -m pytest -v -m "matrix_sdk and not local_integration and not soak and not live and not hardware and not docker"
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The default pytest selection excludes SDK, service, hardware, local integration,
|
|
237
|
+
and soak tiers. Installing SDKs afterward leaves the same environment SDK-enabled;
|
|
238
|
+
use a fresh environment for a new SDK-free proof.
|
|
239
|
+
|
|
240
|
+
## Fake smoke sources
|
|
241
|
+
|
|
242
|
+
The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
|
|
243
|
+
a canonical event with its own adapter instance ID. After installing all
|
|
244
|
+
providers referenced by a fake bridge config, exercise a source with:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Use the configured instance ID, which may differ from the transport name. Each
|
|
251
|
+
normal smoke tests one source; inspect `source_candidates` and
|
|
252
|
+
`coverage_scope: single_source` in its report. Eligible sources must have started
|
|
253
|
+
and provide the helper. A pass requires delivery for every matched configured
|
|
254
|
+
route target, including targets unavailable after construction or startup.
|
|
255
|
+
Factory errors fail the smoke and trigger runtime cleanup. The result proves
|
|
256
|
+
fake direct-pipeline behavior; native callbacks and recipient delivery have
|
|
257
|
+
separate qualification tiers.
|
|
258
|
+
|
|
259
|
+
## Coordinated CI
|
|
260
|
+
|
|
261
|
+
The repository CI installs MEDRE core and this adapter. Its fake job omits
|
|
262
|
+
native SDK dependencies; its SDK job installs this distribution's declared pins.
|
|
263
|
+
CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
|
|
264
|
+
`MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
|
|
265
|
+
candidate pair with a one-run dispatch and a full core commit SHA:
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
|
|
269
|
+
gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA -f sdk_ref=FULL_SDK_COMMIT_SHA
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Record both revisions with the result. The candidate run does not replace the
|
|
273
|
+
adapter PR's checks against core `main`. Follow the
|
|
274
|
+
[coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
|
|
275
|
+
for dependency order and merged compatibility pins.
|
|
276
|
+
|
|
277
|
+
A manual `sdk_ref` selects a full commit from `jeremiah-k/mindroom-nio` for
|
|
278
|
+
installed-SDK jobs. The candidate is installed within the locked core constraints;
|
|
279
|
+
its package version must satisfy the adapter's declared dependency. CI checks
|
|
280
|
+
package consistency and installed-source provenance, and records the exact SDK
|
|
281
|
+
commit. Default jobs retain the released SDK pin. Candidate-source runs qualify
|
|
282
|
+
an experiment; they do not change deployment dependencies or compatibility pins.
|
|
283
|
+
|
|
284
|
+
Core's compatibility matrix tests each selected adapter at the exact commit
|
|
285
|
+
recorded in its manifest, along with cross-adapter behavior. In a coordinated
|
|
286
|
+
checkout containing the selected sibling repos, run from MEDRE:
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
python scripts/ci/adapter_matrix.py --check-local
|
|
290
|
+
# Once all adapter changes are committed:
|
|
291
|
+
python scripts/ci/adapter_matrix.py --sync-local
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
The helper validates clean sibling checkouts and their entry points, and compares
|
|
295
|
+
Python distribution names using normalized case/separator spelling. Synchronizing
|
|
296
|
+
updates the manifest atomically without fetching or installing packages. Review
|
|
297
|
+
the manifest diff, merge adapter commits into their default branches first, then publish
|
|
298
|
+
the core pin update and run `python scripts/ci/adapter_matrix.py --check-merged`. A failed write preserves the original manifest and cleans up the temporary
|
|
299
|
+
file. Deployment projects should separately lock their chosen complete
|
|
300
|
+
package graph.
|
|
301
|
+
|
|
302
|
+
Standalone CI records the exact core and adapter SHAs tested against its
|
|
303
|
+
configured core baseline. MEDRE core CI qualifies the pinned compatibility
|
|
304
|
+
pair; a standalone green result does not qualify another core revision.
|
|
305
|
+
SDK qualification extras come from the selected core compatibility manifest,
|
|
306
|
+
while SDK versions remain authoritative in this adapter's package metadata.
|
|
307
|
+
|
|
308
|
+
## Provider contract and quality
|
|
309
|
+
|
|
310
|
+
The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
|
|
311
|
+
documents every hook, its loading phase, and the minimal fake constructor/event
|
|
312
|
+
calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
|
|
313
|
+
Conformance tests use `medre.testing`; SDK pin checks read this distribution's
|
|
314
|
+
installed metadata while this repository chooses its SDK qualification extras.
|
|
315
|
+
The fake constructor and explicit-keyword event factory are checked in the
|
|
316
|
+
SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
|
|
317
|
+
|
|
318
|
+
This repository declares its own Ruff/Black policy. CI checks all Python source
|
|
319
|
+
and tests, plus commit whitespace, alongside the fake/native qualification tiers.
|
|
320
|
+
The native adapter package includes its own `py.typed` marker.
|
|
321
|
+
|
|
322
|
+
## Default relay attribution
|
|
323
|
+
|
|
324
|
+
Matrix output defaults to `[sender/origin]: message`, preserving the full sender
|
|
325
|
+
name. An absent origin renders `[sender]: message`. Set `relay_prefix: ""` to
|
|
326
|
+
disable attribution or supply a custom generic template. Omitted/null selects
|
|
327
|
+
the automatic policy; MMRelay wire metadata keeps the original unprefixed text.
|
|
328
|
+
|
|
329
|
+
## Device verification
|
|
330
|
+
|
|
331
|
+
E2EE setup uses the adapter's persistent store and checks its own device's
|
|
332
|
+
server-visible signing chain. A fresh device uploads its keys before reusing
|
|
333
|
+
the account signing identity; ordinary login does not require rotating that
|
|
334
|
+
identity. Keep the E2EE store when renewing credentials. A cross-signing reset
|
|
335
|
+
replaces account identity material and can require verification in other clients.
|
|
336
|
+
|
|
337
|
+
## Peer-device verification policy
|
|
338
|
+
|
|
339
|
+
`verification_policy` is an optional peer-device **send authorization** gate.
|
|
340
|
+
The `permissive` default sends encrypted messages without scanning the local
|
|
341
|
+
peer-device trust store or emitting trust-gap warnings. This is normal bridge
|
|
342
|
+
operation for trusted rooms, not a trust verdict or a delivery receipt.
|
|
343
|
+
Own-device cross-signing is handled independently during identity setup and
|
|
344
|
+
runtime verification and does not establish trust in other users' devices.
|
|
345
|
+
|
|
346
|
+
Operators may explicitly select `strict`: then encrypted sends require an
|
|
347
|
+
affirmative local nio trust view for every recipient device, complete room
|
|
348
|
+
membership, and SDK enforcement with `ignore_unverified_devices=False`.
|
|
349
|
+
Unknown/unverified peers cause a retryable, pre-handoff refusal. MEDRE does
|
|
350
|
+
not currently offer an operator peer-verification workflow, and verification
|
|
351
|
+
performed in a different Matrix client does not automatically populate
|
|
352
|
+
MEDRE's local device store. Do not enable `strict` unless local peer trust
|
|
353
|
+
can be established independently. No automatic verification or plaintext
|
|
354
|
+
downgrade occurs.
|
|
355
|
+
|
|
356
|
+
The policy applies only to encrypted sends — crypto active and the room
|
|
357
|
+
affirmatively encrypted. Plaintext delivery, ephemeral typing, and redactions
|
|
358
|
+
are outside its scope. For the opt-in gate, a recipient missing from the
|
|
359
|
+
local device store counts as a trust gap. The default does not inspect that
|
|
360
|
+
store. The adapter's own current device is handled by cross-signing, not
|
|
361
|
+
peer-device authorization.
|
|
362
|
+
|
|
363
|
+
Pre-release decision note: `permissive` is the default for compatibility, and
|
|
364
|
+
`strict` is NOT scheduled to become the default until a separate,
|
|
365
|
+
independently qualified peer-verification workflow exists. Flipping that
|
|
366
|
+
default is a deliberate, separately reviewed change; do not rely on the
|
|
367
|
+
current default for assurance.
|
|
368
|
+
|
|
369
|
+
Neither mode proves delivery. A refused send is never delivered, but an
|
|
370
|
+
encrypted send that passes the policy — even to fully verified devices — is
|
|
371
|
+
only homeserver acceptance of the Megolm ciphertext. It is not a delivery
|
|
372
|
+
receipt: nobody can observe from the send whether a peer device received,
|
|
373
|
+
decrypted, or read the message.
|
|
374
|
+
|
|
375
|
+
## Transient typing
|
|
376
|
+
|
|
377
|
+
Routes can explicitly opt in with `forward_typing: true` when both endpoints
|
|
378
|
+
support typing and map concrete conversations. The adapter projects Matrix's
|
|
379
|
+
complete ephemeral user lists into core actor leases, excludes its own relay
|
|
380
|
+
user, and sends the aggregate indicator as the configured relay account.
|
|
381
|
+
|
|
382
|
+
Typing is separate from message encryption and discloses activity even in
|
|
383
|
+
encrypted rooms. The same configured-room, joined-room and encryption-safety
|
|
384
|
+
guards apply to outbound requests. Indicators use finite native timeouts and
|
|
385
|
+
best-effort clears; they create no canonical event, outbox row or receipt.
|
|
386
|
+
Unchanged composition can expire after core's 30-second freshness bound unless
|
|
387
|
+
another native observation arrives. Message forwarding alone does not opt in. The [typing contract](docs/spec/transient-typing.md)
|
|
388
|
+
defines native scope and live-sync behavior.
|
|
389
|
+
|
|
390
|
+
## Encryption readiness
|
|
391
|
+
|
|
392
|
+
Install the Matrix provider with its declared dependencies. The durable SDK
|
|
393
|
+
requires its SQLite crypto backend even with encryption_mode: plaintext;
|
|
394
|
+
plaintext policy continues refusing encrypted-room delivery. Missing backend
|
|
395
|
+
dependencies fail production startup instead of silently selecting ordinary sync.
|
|
396
|
+
|
|
397
|
+
Encryption readiness and own-device cross-signing are separate diagnostics.
|
|
398
|
+
Installing dependencies or authenticating does not recover lost account signing
|
|
399
|
+
keys. Runtime never resets that identity. To inspect the actual selected store:
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
medre adapter matrix auth status --adapter-id matrix --config ~/medre/bridge.yaml
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
If a signing file exists but cannot be read, check ownership/read permissions
|
|
406
|
+
first. Preserve a private backup before manually moving a confirmed unusable
|
|
407
|
+
file aside; import refuses replacement. Rerun status after the destination is
|
|
408
|
+
absent. SDK/path inspection failures require diagnosis before assuming keys are
|
|
409
|
+
missing.
|
|
410
|
+
|
|
411
|
+
If the signing file is missing, stop the bridge and locate an existing SDK
|
|
412
|
+
account-signing JSON for the same Matrix account (for example in an MMRelay
|
|
413
|
+
store or a backup). Do not copy tokens or device databases between applications.
|
|
414
|
+
Validate and import that backup using the existing MEDRE credentials:
|
|
415
|
+
|
|
416
|
+
```bash
|
|
417
|
+
medre adapter matrix auth restore-signing --adapter-id matrix \
|
|
418
|
+
--config ~/medre/bridge.yaml \
|
|
419
|
+
--from ~/.mmrelay/matrix/store/@bot:example.com_cross_signing.json
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
The command verifies the token's account/device and matches the backup's keys
|
|
423
|
+
against the existing server identity before writing anything. Publication
|
|
424
|
+
requires an absent destination and filesystem hard-link support; an existing
|
|
425
|
+
file is never replaced. The source backup remains unchanged. A post-publication
|
|
426
|
+
filesystem error can leave the complete file present: inspect status before
|
|
427
|
+
retrying. Restart the bridge to sign its own device using the restored keys.
|
|
428
|
+
A readable local file alone does not prove server/device verification. Import
|
|
429
|
+
restores account-signing keys, not historical encrypted-room message keys.
|
|
430
|
+
|
|
431
|
+
Ordinary login preserves account signing keys and cannot reconstruct missing
|
|
432
|
+
private material. Only when no matching backup exists should an operator
|
|
433
|
+
consider authenticated login with --reset-cross-signing; it replaces the account
|
|
434
|
+
identity and requires verification again in other clients. Stop the running
|
|
435
|
+
bridge before using `medre diagnostics --refresh-health`, which opens adapters.
|
|
436
|
+
|
|
437
|
+
The opt-in `test_matrix_durable_runtime_live.py` proof takes explicit local
|
|
438
|
+
homeserver accounts through environment variables. It runs the real MEDRE
|
|
439
|
+
runtime with durable storage and a fake destination across a restart, and
|
|
440
|
+
fails when native ingress fails. `MATRIX_ENCRYPTED=1` selects genuine Megolm
|
|
441
|
+
traffic; use fresh account/device stores for each independent run. The core
|
|
442
|
+
Synapse Docker starter can provision the isolated accounts.
|