Merge branch 'main' of https://github.com/polyphony-chat/docs

Author: bitfl0wer

.github/ISSUE_TEMPLATE/docs-mkdocs-issue-report.md

@@ -0,0 +1,14 @@
+---
+name: docs/mkdocs issue report
+about: Report a bug or an issue concerning the website generated with mkdocs-material.
+title: "[docs]"
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.

.github/ISSUE_TEMPLATE/polyproto--specification-api-documentation-issue-report.md

@@ -0,0 +1,11 @@
+---
+name: 'polyproto: Specification/API documentation issue report'
+about: Report a bug or mistake concerning the polyproto specification document or
+  API documentation.
+title: "[p2spec]"
+labels: ''
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/typespec-project-issue-report.md

@@ -0,0 +1,10 @@
+---
+name: TypeSpec project issue report
+about: Report a bug, an issue or an inconsistency with the TypeSpec (.tsp) projects.
+title: "[typespec]"
+labels: ''
+assignees: ''
+
+---
+
+

.vscode/ltex.dictionary.en-US.txt

@@ -22,3 +22,7 @@ NLnet
 OpenAPI
 TypeSpec
 Protobuf
+gzipped
+RawR
+OID
+apidocs

.vscode/ltex.hiddenFalsePositives.en-US.txt

@@ -56,3 +56,13 @@
 {"rule":"MORFOLOGIK_RULE_EN_US","sentence":"^\\QSee \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q\nFederation ID - A unique identifier; In public contexts, usually **actor@**subdomain.example.com, where bolded parts are required and non-bolded parts are optional.\\E$"}
 {"rule":"ADMIT_ENJOY_VB","sentence":"^\\QThe following sections are dedicated to documenting best practices to consider when implementing polyproto.\\E$"}
 {"rule":"ADMIT_ENJOY_VB","sentence":"^\\QThe following subsections are dedicated to documenting best practices to consider when implementing polyproto.\\E$"}
+{"rule":"MORFOLOGIK_RULE_EN_US","sentence":"^\\QThe data is a gzipped tarball archive (.tar.gz) named \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q, where\\E$"}
+{"rule":"ADMIT_ENJOY_VB","sentence":"^\\QIt is also recommended to back up the encrypted private identity keys in some other secure location.\\E$"}
+{"rule":"EN_A_VS_AN","sentence":"^\\QCommunicating the body size limit is done by adding an \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q header to the response.\\E$"}
+{"rule":"ANY_BODY","sentence":"^\\QIf this header is not present or has a value of \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q, clients should assume that there is no body size limit.\\E$"}
+{"rule":"EN_A_VS_AN","sentence":"^\\QThe session ID is an \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q \\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q chosen by the actor requesting the ID-Cert.\\E$"}
+{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Server Certificate Change Actor Receive Received when the server's certificate changed.\\E$"}
+{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Hello Actor Receive Received upon establishing a connection.\\E$"}
+{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q New Session Actor Receive Received by all sessions except the new one.\\E$"}
+{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Actor Certificate Invalidation Actor Send/Receive Received by server when an actor certificate has been invalidated.\\E$"}
+{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Message Actor Receive Received when a message is sent to the actor.\\E$"}

api/build/core-openapi3.yaml

@@ -8,6 +8,7 @@ using Routes;
 using FederatedIdentity;
 using Services;
 using Migration;
+using ResourceAddressingWithRelativeRoots;
 
 namespace polyproto.core;
 
@@ -113,4 +114,102 @@ namespace models {
             content: T
         }[];
     }
+
+    model MessageBatchExample extends MessageBatch<string> {}
+
+    /** The data is a gzipped tarball (.tar.gz) named `export1234567890-user@subdomain.example.com`, where
+     *   - `export[numbers]` is the word `export` with 20 random digits appended to it
+     *   - `user` is the actors' name
+     *   - `subdomain.example.com` is the FQDN of the server the actor is registered on.
+     *   This file archive contains a file `messages.p2mb` which is a JSON file containing [message batches](https://docs.polyphony.chat/Protocol%20Specifications/core/#721-message-batches)
+     *   of all messages sent by the user. If the server where the data export was requested from has
+     *   [RawR](https://docs.polyphony.chat/Protocol%20Specifications/core/#731-resource-addressing-with-relative-roots) enabled, the file archive will contain a
+     *   folder named `rawr`. This folder contains all RawR content uploaded by the actor to that server.
+     *   The files in this folder are named after the resource ID given to the resource. File extensions are only
+     *   added if they were known to the server. An example file name might be
+     *   `2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`, referencing the file
+     *   which was hosted at `<server_url>/.p2/core/resource/2c851bfb6daffa944fa1723c7bd4d362ffbc9defe292f2daaf05e895989d179b.jxl`.
+     *   In addition, the folder `rawr` contains a file named `access_properties.p2al`. This JSON
+     *   file contains a data structure mapping each resource ID to an access properties object.
+     *   In particular, the file is structured as an array containing objects. Each object has a key which is equal
+     *   to the resource ID of a resource in the `rawr` directory and a value which is an object
+     *   representing the access properties. An example of the contents of this file is given below:
+     * 
+```json
+[
+    {
+        "2062a23e2a25b226ca4c546fec5ec06e0df9648281f45da8b5aaabebdf66cf4c.jxl": {
+        "private": false,
+        "allowlist": ["user1@example.com", "instance.example.com"],
+        "denylist": ["user2@example.com", "otherinstance@example.com"]
+        }
+    },
+    {
+        "a9144379a161e1fcf6b07801b70db6d6c481933bd634fe2409eb713723ab1a0a": {
+        "private": true,
+        "allowlist": ["user1@example.com"],
+        "denylist": []
+        }
+    }
+]
+```
+     * 
+     *   If the server where the data export was requested from is the actors' home server, the
+     *   archive will contain a folder `certs` and a file `crypt_certs.p2epk`. `certs` will contain all ID-Certs
+     *   the server has stored of the actor. The ID-Certs will be stored in
+     *   [ASCII PEM format](https://web.archive.org/web/20250107131731/https://learn.microsoft.com/en-us/azure/iot-hub/reference-x509-certificates#:~:text=ASN.1%20encoding.-,ascii%20pem%20format,-A%20PEM%20certificate).
+     *   The file `crypt_certs.p2epk` contains all [encrypted private key material](https://docs.polyphony.chat/Protocol%20Specifications/core/#63-private-key-loss-prevention-and-private-key-recovery)
+     *   that the actor has uploaded to the server. Just like `messages.p2mb`, `crypt_certs.p2epk` is a standard
+     *   JSON file.
+     */
+    model P2Export {}
+
+    /**
+     * `ResourceAccessProperties` define which actors may access an uploaded resource. Actors and
+     * entire instances can have access granted or revoked.
+     */
+    model ResourceAccessProperties {
+        @doc("Whether the resource should be private by default. Private resources can only be accessed by the uploader and by instances and actors declared in the `allowlist`.")
+        private: boolean = false;
+        @doc("A list of actors and/or instances allowed to access this resource.")
+        @example(#["[email protected]", "instance.example.com"])
+        allowlist?: string[];
+        @doc("A list of actors and/or instances who cannot have access to this resource.")
+        @example(#["[email protected]", "other_instance.example.com"])
+        denylist?: string[];
+    }
+
+    /**
+     * When querying the server for a list of resources uploaded by you, you can optionally request
+     * the resulting list to be sorted in a specific way. These are the four options you have.
+     */
+    enum ResourceListSorting {
+        SizeAsc,
+        SizeDesc,
+        NewestFirst,
+        OldestFirst
+    }
+
+    /**
+     * A cacheable response to an ID-Cert request.
+     */
+    model CacheableIDCert {
+        @doc("The requested ID-Cert in ASCII PEM format.")
+        @example("------BEGIN CERTIFICATE------...")
+        idCertPem: string,
+        @doc("UNIX timestamp that specifies when this specific id_cert has been marked as invalidated by the server. An ID-Cert is considered invalidated, if the server or actor choose to revoke the validity of the ID-Cert before the lifetime of the certificate was scheduled to end. If this property does not exist, the ID-Cert has not been invalidated.")
+        @example(1736610000)
+        invalidatedAt?: uint64,
+        @doc("UNIX timestamp that specifies the time from which this cache entry may be treated as valid.")
+        @example(1736606402)
+        cacheNotValidBefore: uint64,
+        @doc("UNIX timestamp that specifies a time until which this cache entry may be treated as valid.")
+        @example(1736613602)
+        cacheNotValidAfter: uint64,
+        @doc("Signature generated by the home server. This signature can be verified using the home servers' public identity key. A server generates the `cacheSignature` by concatenating the serial number of the ID-Cert in question with the `cacheValidNotBefore` timestamp and the `cacheValidNotAfter` timestamp, then generating the signature of the resulting concatenated string using the private identity key of the server. Clients must reject certificates of which the `cacheSignature` can not be verified to be correct.")
+        @example("7ab2bbde7fe43c7481a3a61031546bab16bc1a8735b2f0cdd519958c7f2f99f8")
+        @minLength(32)
+        @maxLength(32)
+        cacheSignature: string
+    }
 }