security-context-v1: Document out of band metadata for flatpak

and specify when the invalid_metadata error will be sent.

Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>

staging/security-context/engines.md

@@ -1,7 +1,8 @@
 # security-context-v1 engines
 
 This document describes how some specific engine implementations populate the
-metadata in security-context-v1.
+metadata in security-context-v1 and provide further metadata with out of band
+mechanisms.
 
 ## [Flatpak]
 
@@ -11,4 +12,7 @@ metadata in security-context-v1.
 * `instance_id` is the Flatpak instance ID of the running sandbox. It is always
   set.
 
+More metadata is stored in `$XDG_RUNTIME_DIR/.flatpak/$instance_id/info`. This
+file will be readable when `wp_security_context_v1.commit` is called.
+
 [Flatpak]: https://flatpak.org/

staging/security-context/security-context-v1.xml

@@ -163,6 +163,11 @@
         Atomically register the new client and attach the security context
         metadata.
 
+        If the provided metadata is inconsistent or does not match with out of
+        band metadata (see
+        https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/security-context/engines.md),
+        the invalid_metadata error may be sent eventually.
+
         It's a protocol error to send any request other than "destroy" after
         this request. In this case, the already_used error is sent.
       </description>