From dacf93b405033b7c0dc3b0460b82b245f71d5003 Mon Sep 17 00:00:00 2001
From: Matthew Hodgson <matthew@matrix.org>
Date: Thu, 23 Apr 2015 16:15:07 +0100
Subject: [PATCH] oooooops, apparently I forgot to 'git add' these when I
 refactored the spec last month :-/

---
 specification/40_content_repository.rst    | 76 ++++++++++++++++++++++
 specification/41_end_to_end_encryption.rst | 15 +++++
 specification/49_other_non_core_apis.rst   | 14 ++++
 3 files changed, 105 insertions(+)
 create mode 100644 specification/40_content_repository.rst
 create mode 100644 specification/41_end_to_end_encryption.rst
 create mode 100644 specification/49_other_non_core_apis.rst

diff --git a/specification/40_content_repository.rst b/specification/40_content_repository.rst
new file mode 100644
index 00000000..df04605a
--- /dev/null
+++ b/specification/40_content_repository.rst
@@ -0,0 +1,76 @@
+Content repository
+==================
+
+HTTP API
+--------
+
+Uploads are POSTed to a resource which returns a token which is used to GET
+the download.  Uploads are POSTed to the sender's local homeserver, but are
+downloaded from the recipient's local homeserver, which must thus first transfer
+the content from the origin homeserver using the same API (unless the origin
+and destination homeservers are the same).  The upload/download API is::
+
+    => POST /_matrix/media/v1/upload HTTP/1.1
+       Content-Type: <media-type>
+
+       <media>
+
+    <= HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       { "content-uri": "mxc://<server-name>/<media-id>" }
+
+    => GET /_matrix/media/v1/download/<server-name>/<media-id> HTTP/1.1
+
+    <= HTTP/1.1 200 OK
+       Content-Type: <media-type>
+       Content-Disposition: attachment;filename=<upload-filename>
+
+       <media>
+
+Clients can get thumbnails by supplying a desired width and height and
+thumbnailing method::
+
+    => GET /_matrix/media/v1/thumbnail/<server_name>
+            /<media-id>?width=<w>&height=<h>&method=<m> HTTP/1.1
+
+    <= HTTP/1.1 200 OK
+       Content-Type: image/jpeg or image/png
+
+       <thumbnail>
+
+The thumbnail methods are "crop" and "scale". "scale" trys to return an
+image where either the width or the height is smaller than the requested
+size. The client should then scale and letterbox the image if it needs to
+fit within a given rectangle. "crop" trys to return an image where the
+width and height are close to the requested size and the aspect matches
+the requested size. The client should scale the image if it needs to fit
+within a given rectangle.
+
+Homeservers may generate thumbnails for content uploaded to remote
+homeservers themselves or may rely on the remote homeserver to thumbnail
+the content. Homeservers may return thumbnails of a different size to that
+requested. However homeservers should provide exact matches where reasonable.
+Homeservers must never upscale images.
+
+Security
+--------
+
+Clients may try to upload very large files. Homeservers should not store files
+that are too large and should not serve them to clients.
+
+Clients may try to upload very large images. Homeservers should not attempt to
+generate thumbnails for images that are too large.
+
+Remote homeservers may host very large files or images. Homeserver should not
+proxy or thumbnail large files or images from remote homeservers.
+
+Clients may try to upload a large number of files. Homeservers should limit the
+number and total size of media that can be uploaded by clients.
+
+Clients may try to access a large number of remote files through a homeserver.
+Homeservers should restrict the number and size of remote files that it caches.
+
+Clients or remote homeservers may try to upload malicious files targeting
+vulnerabilities in either the homeserver thumbnailing or the client decoders.
+
diff --git a/specification/41_end_to_end_encryption.rst b/specification/41_end_to_end_encryption.rst
new file mode 100644
index 00000000..f793babe
--- /dev/null
+++ b/specification/41_end_to_end_encryption.rst
@@ -0,0 +1,15 @@
+End-to-End Encryption
+=====================
+
+.. TODO-doc
+  - Why is this needed.
+  - Overview of process
+  - Implementation
+
+Matrix optionally supports end-to-end encryption, allowing rooms to be created
+whose conversation contents is not decryptable or interceptable on any of the
+participating homeservers.
+
+End-to-end crypto is still being designed and prototypes - notes on the design
+may be found at https://lwn.net/Articles/634144/
+
diff --git a/specification/49_other_non_core_apis.rst b/specification/49_other_non_core_apis.rst
new file mode 100644
index 00000000..8855ce9e
--- /dev/null
+++ b/specification/49_other_non_core_apis.rst
@@ -0,0 +1,14 @@
+Address book repository
+=======================
+
+.. NOTE::
+  This section is a work in progress.
+  Do we even need it?  Clients can use out-of-band addressbook servers for now;
+  this should definitely not be core.
+
+.. TODO-spec
+  - format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
+  - processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
+    contacts), etc.
+  - Standard json format for contacts? Piggy back off vcards?
+