async-matrix 4.0.0 → 4.0.1

data/lib/async/matrix/e2ee/secret_storage.rb

@@ -12,10 +12,10 @@ require_relative "../key_representation"
 module Async
   module Matrix
     module E2EE
-      # Secrets kept on the server, under a key the server never sees.
-      #
-      # This is where the cross signing keys and the backup key live, so that a new device can reach them.
+      # Secrets the server keeps but cannot read.
       module SecretStorage
+        # They are encrypted under a key the server never sees, and the cross signing keys and the backup key live here, so that a new device can reach them.
+
         # The only algorithm the specification defines.
         ALGORITHM = "m.secret_storage.v1.aes-hmac-sha2"
 
@@ -32,9 +32,9 @@ module Async
         ZERO_MESSAGE = ("\x00" * 32).b
 
         # The key secret storage is encrypted under.
-        #
-        # It never leaves the device: what goes to the server is what it encrypted, and a description which only says how to arrive at it again.
         class Key
+          # It never leaves the device: what goes to the server is what it encrypted, and a description which only says how to arrive at it again.
+
           # @returns [Key] a key of random bytes, which the user keeps.
           def self.generate
             self.new(SecureRandom.bytes(BYTES))
@@ -112,12 +112,11 @@ module Async
 
           # Whether this key is the one a description was written by.
           #
-          # The description carries the code over a known message, so a wrong passphrase is caught before anything is decrypted with it.
-          #
           # @parameter iv [String] the counter from the description.
           # @parameter mac [String] the code from the description.
           # @returns [Boolean] whether they match.
           def correct?(iv:, mac:)
+            # The description carries the code over a known message, so a wrong passphrase is caught before anything is decrypted with it.
             aes, key = self.derive("")
 
             ciphertext = self.cipher(:encrypt, aes, self.class.decode(iv), ZERO_MESSAGE)
@@ -128,12 +127,11 @@ module Async
 
           # What goes into account data to describe this key, so another device can arrive at it.
           #
-          # It carries no key material: a passphrase description says how to derive one, and the check says whether the answer was right.
-          #
           # @parameter name [String] what to call it to the user.
           # @parameter passphrase [Hash | nil] how it was derived, where it was.
           # @returns [Hash] the description.
           def description(name: nil, passphrase: nil)
+            # It carries no key material: a passphrase description says how to derive one, and the check says whether the answer was right.
             aes, key = self.derive("")
             iv = self.class.counter
 
@@ -159,10 +157,9 @@ module Async
 
           # Sixteen random bytes, with the top bit of the counter cleared.
           #
-          # The specification asks for that to work around implementations which disagree about where the counter wraps.
-          #
           # @returns [String] the counter block.
           def self.counter
+            # The specification asks for that to work around implementations which disagree about where the counter wraps.
             SecureRandom.bytes(16).tap do |iv|
               iv.setbyte(8, iv.getbyte(8) & 0x7f)
             end

data/lib/async/matrix/e2ee/secrets.rb

@@ -10,9 +10,9 @@ require_relative "secret_storage"
 module Async
   module Matrix
     module E2EE
-      # The private keys a device holds, and what it would write them to the server as.
+      # The private keys a device holds, and what it writes them to the server as.
       #
-      # It makes no request: a caller hands it the account data, and it answers with what to send.
+      # It makes no request: a caller hands it account data and gets what to send.
       class Secrets
         def initialize
           # The secrets this device has opened, which never leave it in the clear.
@@ -74,16 +74,16 @@ module Async
         # @returns [Boolean] whether it is the right one.
         def opened(key)
           case @description
-          in {iv: String => iv, mac: String => mac} unless key.correct?(iv: iv, mac: mac)
-            Console.warn(self, "That key does not open this storage.", key_id: @key_id)
+          in {iv: String => iv, mac: String => mac}
+            if key.correct?(iv: iv, mac: mac)
+              self.unlocked(key)
+            else
+              Console.warn(self, "That key does not open this storage.", key_id: @key_id)
 
-            false
+              false
+            end
           else
-            @key = key
-
-            self.read_sealed
-
-            true
+            self.unlocked(key)
           end
         end
 
@@ -136,9 +136,13 @@ module Async
         # @returns [String | nil] the secret, or nil where it is not there or does not read.
         def load(name)
           case {open: self.open?, sealed: (@sealed || {})[name]}
-          in {open: true, sealed: Hash => encrypted} if encrypted.key?(@key_id.to_sym)
-            @key.decrypt(name, encrypted[@key_id.to_sym]).tap do |secret|
-              self.accept(name, secret)
+          in {open: true, sealed: Hash => encrypted}
+            if encrypted.key?(@key_id.to_sym)
+              @key.decrypt(name, encrypted[@key_id.to_sym]).tap do |secret|
+                self.accept(name, secret)
+              end
+            else
+              @held[name]
             end
           else
             @held[name]
@@ -161,14 +165,14 @@ module Async
 
         # Whether this is an answer to something we asked, over a channel which proves who sent it.
         #
-        # A secret arriving unbidden is somebody trying their luck, so it is never taken.
-        #
         # @parameter request_id [String] the ID the answer carries.
         # @parameter over [Async::Matrix::Events::Envelope | nil] the event it arrived in.
         # @returns [Boolean] whether to believe it.
         def asked?(request_id, over: nil)
           case {asked: @asked.key?(request_id), over: over}
           # Nothing asked for this, so whoever sent it was not answering us.
+          #
+          # A secret arriving unbidden is somebody trying their luck, so it is never taken.
           in {asked: false}
             false
 
@@ -208,7 +212,21 @@ module Async
 
         private
 
+        # Hold on to the key which opened this storage, and read what was sealed under it.
+        #
+        # @parameter key [SecretStorage::Key] the key.
+        # @returns [Boolean] true, which is what opening it answers.
+        def unlocked(key)
+          @key = key
+
+          self.read_sealed
+
+          true
+        end
+
         # Read everything which was sealed under this storage, now that there is a key for it.
+        #
+        # @returns [Hash] what was sealed, which is what reading it through answers.
         def read_sealed
           (@sealed || {}).each_key do |name|
             self.load(name)

data/lib/async/matrix/e2ee/store.rb

@@ -24,13 +24,12 @@ module Async
 
         # Remember a session another device shared.
         #
-        # Whatever else is known about it is kept too, since a backup or an export carries more than the key.
-        #
         # @parameter room_id [String] the room the session is for.
         # @parameter session_id [String] the ID of the session.
         # @parameter sender [String | nil] the user who shared it.
         # @parameter rest [Hash] what else is known: whether it was imported, what index it begins at.
         def remember(room_id, session_id:, sender:, **rest)
+          # Whatever else is known about it is kept too, since a backup or an export carries more than the key.
           @sessions[[room_id, session_id]] = {sender: sender, at: Time.now, **rest}
         end
 

data/lib/async/matrix/error.rb

@@ -13,6 +13,26 @@ module Async
     class InvalidKeyError < Error
     end
 
+    # Raised when stored state belongs to another device.
+    #
+    # Its cursor acknowledges what that device read, so resuming another's state loses what was addressed to it.
+    class MismatchedAccountError < Error
+      # @parameter expected [Array(String, String)] the user and device the state was written by.
+      # @parameter got [Array(String, String)] the user and device which asked for it.
+      def initialize(expected, got)
+        super("This state belongs to #{expected.join(":")}, not #{got.join(":")}!")
+
+        @expected = expected
+        @got = got
+      end
+
+      # @attribute [Array(String, String)] the user and device the state was written by.
+      attr :expected
+
+      # @attribute [Array(String, String)] the user and device which asked for it.
+      attr :got
+    end
+
     # Represents a Matrix API error, which is reported with a non-2xx status and a body of the form `{"errcode": "M_FORBIDDEN", "error": "..."}`.
     class RequestError < Error
       # @parameter status [Integer] the HTTP status code of the response.

data/lib/async/matrix/events/registry.rb

@@ -78,17 +78,20 @@ module Async
 
         # The framing an event actually arrived in, which may be richer than its type declares.
         #
-        # `m.room.encrypted` travels both as a to-device event and as a room event, so its schema frames it as the lesser of the two. What it arrived as is what decides, or a timeline event would answer nothing about the room it is in.
-        #
         # @parameter declared [Class] the framing the type declares.
         # @parameter value [Hash] the event.
         # @returns [Class] the framing to read it as.
         def framed(declared, value)
-          case value
-          in {state_key: String} if declared == Envelope
-            StateEvent
-          in {event_id: String} if declared == Envelope
-            RoomEvent
+          # `m.room.encrypted` travels both as a to-device event and as a room event, so its schema frames it as the lesser of the two. What it arrived as is what decides, or a timeline event would answer nothing about the room it is in.
+          if declared == Envelope
+            case value
+            in {state_key: String}
+              StateEvent
+            in {event_id: String}
+              RoomEvent
+            else
+              declared
+            end
           else
             declared
           end

data/lib/async/matrix/representation.rb

@@ -5,7 +5,9 @@
 
 require "async/rest/representation"
 
+require_relative "operations"
 require_relative "redacted"
+require_relative "schema"
 require_relative "wrapper/json"
 
 module Async
@@ -14,13 +16,59 @@ module Async
     class Representation < Async::REST::Representation[Wrapper::JSON]
       include Redacted
 
-      # What a pattern reads, which is the document the homeserver answered with.
+      # The specification version this document was read against, which a versioned class answers for itself.
+      #
+      # @returns [String | nil] the version, or nil where this document came from no version's class.
+      def version
+        nil
+      end
+
+      # What the specification asks of this document, which anybody may ask.
+      #
+      # @parameter operation [String | nil] the operation ID, where the path names more than one.
+      # @parameter method [String | nil] the HTTP method, which says which operation a shared path is.
+      # @parameter status [Integer] which of the operation's responses this is.
+      # @returns [Array(String)] what was wrong with it, which is empty where nothing was.
+      def errors(operation: nil, method: nil, status: 200)
+        # A version which describes neither the path nor the operation asks nothing of it.
+        case self.described(operation: operation, method: method)
+        in [Schema => schema, String => named]
+          schema.errors_in_response(named, self.value, status: status)
+        else
+          []
+        end
+      end
+
+      # @parameter operation [String | nil] the operation ID.
+      # @parameter method [String | nil] the HTTP method.
+      # @parameter status [Integer] which response this is.
+      # @returns [Boolean] whether the document answers what the specification asks.
+      def valid?(operation: nil, method: nil, status: 200)
+        self.errors(operation: operation, method: method, status: status).empty?
+      end
+
+      # The same as {#errors}, raising rather than answering.
       #
-      # So a response is matched where it arrives, rather than having to be taken apart first. `[]` cannot do this, because `async-rest` already uses it to derive a sub-resource.
+      # @parameter operation [String | nil] the operation ID.
+      # @parameter method [String | nil] the HTTP method.
+      # @parameter status [Integer] which response this is.
+      # @returns [Representation] this document, so that it can be used where it is read.
+      def validate(operation: nil, method: nil, status: 200)
+        found = self.errors(operation: operation, method: method, status: status)
+
+        unless found.empty?
+          raise InvalidDocumentError.new(operation || self.resource.path, self.version, found)
+        end
+
+        self
+      end
+
+      # What a pattern reads, which is the document the homeserver answered with.
       #
       # @parameter keys [Array(Symbol) | nil] the names a pattern asked for.
       # @returns [Hash] the value.
       def deconstruct_keys(keys)
+        # So a response is matched where it arrives, rather than having to be taken apart first. `[]` cannot do this, because `async-rest` already uses it to derive a sub-resource.
         case self.value
         in Hash => value
           value
@@ -28,6 +76,52 @@ module Async
           {}
         end
       end
+
+      private
+
+      # Which operation this document is a response to, which the path says unless two of them share it.
+      #
+      # @parameter operation [String | nil] the operation ID, where it was given.
+      # @parameter method [String | nil] the HTTP method.
+      # @returns [Array(Schema, String) | nil] the schema and the operation ID.
+      def described(operation: nil, method: nil)
+        version = self.version
+
+        if version
+          case operation
+          in String => named
+            self.schema_with(named, version)&.then{|schema| [schema, named]}
+          in nil
+            Schema.operation_for(self.api_name, version, self.resource.path, method: method)
+          end
+        else
+          nil
+        end
+      end
+
+      # The concept whose schema holds the named operation, since a name says nothing about where it lives.
+      #
+      # @parameter operation [String] the operation ID.
+      # @parameter version [String] the specification version.
+      # @returns [Schema | nil] the schema, or nil where this version names no such operation.
+      def schema_with(operation, version)
+        api = self.api_name
+
+        Schema.concepts(api, version).lazy.filter_map do |concept|
+          schema = Schema.for(api, concept, version)
+
+          if schema.operations.key?(operation)
+            schema
+          end
+        end.first
+      end
+
+      # The API this document belongs to, as its schemas are named: `ClientServer` keeps its schemas in `client_server`.
+      #
+      # @returns [String] the API.
+      def api_name
+        Operations.underscore(self.class.namespace.name.split("::").last).to_s
+      end
     end
   end
 end