From d18d8d55dfe360bef88d666f6fa73aee9528168d Mon Sep 17 00:00:00 2001
From: networkException <git@nwex.de>
Date: Fri, 23 Aug 2024 01:39:54 +0200
Subject: [PATCH] README: Initial commit

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ca087f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# matrix-media-event-decrypt
+
+Decrypt [matrix] media manually using event JSON obtained from a client.
+
+Sometimes decrypting media fails for unknown reasons or your homeserver isn't able
+to federate in media from another server. If you were still able to receive the media
+event and (if encrypted) see the decrypted JSON, this tool might be able to help you
+download and decrypt the content.
+
+## Building
+
+A simple `cargo run --release --` should be all it takes. If not and on systems with an
+implementation of the Nix Package Manager (such as [lix](https://lix.systems)) you can
+install any required dependencies (probably only openssl) by running `nix-shell` first.
+
+## Usage
+
+Running the binary without any arguments will prompt you to paste the JSON of the media
+event you want to retrieve the contents of. On Element Web / Desktop this is the message
+context menu > View Source > Decrypted / Original Event Source.
+
+On other clients you might need to fiddle around with the JSON a little, important is
+that it looks something like this:
+
+```jsonc
+{
+    "content": {
+        "body": "something.jpg",
+        "msgtype": "m.image",
+        "m.mentions": {},
+        "url": "mxc://nwex.de/undefined",
+        // A bunch more
+    },
+    // A bunch more
+}
+```
+
+Confirm by hitting <kbd>Ctrl</kbd>+<kbd>D</kbd> or <kbd>Enter</kbd> and wait for the magic to
+happen. You might be prompted to enter an access token if the server requires authentication
+to fetch the media. For convenience, this tool ignores the [matrix] specification and doesn't
+always use authenticated endpoints if support is advertised, instead just trying if it can get
+away without a token.
+
+You can customize the server to download media from by passing `--server matrix.org`, for example.
+
+## Contributing
+
+For convenience this project is hosted on my personal git server without public registrations
+enabled. If you want to contribute feel free to reach out via the various platforms listed on
+[my website](https://nwex.de/).