├── mod.ts ├── .gitignore ├── deps.ts ├── formats ├── server_settings │ └── SPEC_1.0.md └── about │ └── SPEC_1.0.md ├── README.md └── LICENSE /mod.ts: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store -------------------------------------------------------------------------------- /deps.ts: -------------------------------------------------------------------------------- 1 | export * as Earthstar from "https://deno.land/x/earthstar@v10.0.0-beta.8/mod.ts"; 2 | -------------------------------------------------------------------------------- /formats/server_settings/SPEC_1.0.md: -------------------------------------------------------------------------------- 1 | # Server settings format 2 | 3 |
4 |
Namespace
`server-settings`
5 |
Version
1.0
6 |
7 | 8 | This is an application format for describing the configuration of an Earthstar 9 | server's hosted shares. 10 | 11 | More settings may be added in future versions. 12 | 13 | ## Hosted shares 14 | 15 | Earthstar peers must know which shares to store and replicate ahead of time. 16 | 17 | This application format represents each share for a server to host with a single 18 | document. A share can also be hosted temporarily by using an ephemeral document. 19 | 20 | ### Hosted share document path 21 | 22 | The path format is: 23 | 24 | ``` 25 | /server-settings/1.0/shares/{HASH_OF_SHARE}/{HOST_TYPE} 26 | ``` 27 | 28 | - Where `HASH_OF_SHARE` MUST be a base32 string of the SHA-256 hash of the 29 | share's public address, prepended with `b`. 30 | - And `HOST_TYPE` is `host` if the setting is not temporary, and `host!` if the 31 | setting is temporary. 32 | 33 | ### Hosted share document fields 34 | 35 | - The `text` property of the document MUST be the public address of the share to 36 | be hosted **OR** an empty string, indicating that this share should no longer 37 | be hosted. 38 | - If the hosted share setting is temporary, the `deleteAfter` field must be the 39 | timestamp in microseconds for when the share should be hosted until. 40 | 41 | ### Interpreting hosted documents 42 | 43 | Because they have different paths, it is possible for an ephemeral hosted share 44 | document and non-ephemeral hosted share document to co-exist at the same time: 45 | 46 | ``` 47 | /server-settings/1.0/shares/babcd/host! 48 | /server-settings/1.0/shares/babcd/host 49 | ``` 50 | 51 | The documents may also have different values (e.g. one may be empty and one may 52 | be defined). 53 | 54 | In this scenario we follow OR logic: 55 | 56 | - If both documents have an empty text field, the share must not be hosted. 57 | - If either document has the share address in its text field, the share must be 58 | hosted. 59 | - If both documents have the share address in their text fields, the share must 60 | be hosted. 61 | 62 | ## Notes 63 | 64 | A hash of the hosted share's address is used in the path so that a setting which 65 | is later removed (by wiping the `text` property of the document) does not leave 66 | an unremovable history of which shares the server has hosted. 67 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Earthstar application formats 2 | 3 | Application formats are ways of representing certain kinds of organised data 4 | (e.g. profile info, chat messages, server settings) as Earthstar documents. 5 | 6 | For example, a user's display name should be kept on a document with the path 7 | `/about/1.0/displayName`, or their avatar at `/about/1.0/avatar.jpg`. 8 | 9 | Having coordinated standards for how to store and retrieve documents means 10 | users' data can be reused across many different applications (e.g. the same 11 | avatar across many apps). 12 | 13 | It also makes it easier to build different clients acting on the same kinds of 14 | data — e.g. chatrooms, calendars, or lists — which will hopefully counteract 15 | centralisation around slow-moving, hard-to-modify monolithic clients. 16 | 17 | ## Formats 18 | 19 | - **About**. Personal information associated with author keypairs. 20 | - **Server settings**. Configure which shares an Earthstar server should host. 21 | 22 | ## Contributing a format 23 | 24 | ### Namespace 25 | 26 | Each application format must have a separate namespace, e.g. `about`, or 27 | `server-settings`. 28 | 29 | This namespace must be used as the first path segment of any paths related to 30 | the application format: 31 | 32 | ``` 33 | /about/1.0/~@gwil.b63a5eqlqqkv5im37s6vebgf3ledhkyt63gzt4ylvcyatlxmrprma/displayName` 34 | 35 | /chat/1.0/messages/1394832504 36 | ``` 37 | 38 | ### Version number 39 | 40 | Each application format's second path segment must be a version number, made up 41 | of `{MAJOR_VERSION}.{MINOR_VERSION}`. Both `MAJOR_VERSION` and `MINOR_VERSION` 42 | must be positive integers. 43 | 44 | Valid version numbers: `1.0`, `2.0`, `2.1` 45 | 46 | Invalid version numbers: `1.0.0`, `2.b`, `latest`. 47 | 48 | A separate file should be used for each version of the application format in 49 | this repo, e.g. `/application formats/my_application format/1.0.ts` 50 | 51 | #### Determining minor or major version updates 52 | 53 | If a application format is updated in such a way where all documents created by 54 | previous versions of the application format are still included in the new 55 | application format, the new version is a minor update (e.g. `1.0` → `1.1`). 56 | 57 | If a application format is updated in such a way where documents created or read 58 | by the previous version of the application format are no longer included in the 59 | new application format, the new version is a major update (e.g. `1.0` → `2.0`) 60 | with breaking changes. 61 | 62 | ### Application format specification 63 | 64 | Because implementations can contain bugs and applications' needs vary, a written 65 | specification is required. 66 | 67 | The written specification must be a markdown file with a title with with the 68 | format `SPEC_{VERSION}.md`. 69 | 70 | The specification MUST detail the application format's namespace and version. 71 | 72 | The specification MUST describe the purpose of the application format and how 73 | documents following its application format should be interpreted. 74 | 75 | The specification MUST describe how to author documents conformant with its 76 | application format, e.g. how paths should be formatted, valid values for fields 77 | like `text`. 78 | 79 | ### Example code 80 | 81 | An application format MAY provide a module of functions which assist in the 82 | reading and writing of application format-conformant documents. 83 | 84 | ### Proposal submission 85 | 86 | A pull request with a valid specification should be made to the 87 | [application-formats repository](https://github.com/earthstar-project/application-formats). 88 | -------------------------------------------------------------------------------- /formats/about/SPEC_1.0.md: -------------------------------------------------------------------------------- 1 | # About format 2 | 3 |
4 |
Namespace
`about`
5 |
Version
1.0
6 |
7 | 8 | This is an application format for describing personal information (e.g. display 9 | names, avatars, bios) associated with particular author keypairs. 10 | 11 | ## Keypair association 12 | 13 | Personal information should only be publishable and modifiable by the holder of 14 | a specific keypair. 15 | 16 | Therefore, each documents following this format is prefixed with the following: 17 | 18 | `/about/1.0/~{KEYPAIR_ADDRESS}` 19 | 20 | Where `KEYPAIR_ADDRESS` is the full public address of the keypair associated 21 | with this document, e.g. 22 | `@suzy.bo5sotcncvkr7p4c3lnexxpb4hjqi5tcxcov5b4irbnnz2teoifua`. 23 | 24 | The presence of an author keypair prefixed with a tilde in a path invokes path 25 | ownership, and only this keypair will be able to write to these paths. 26 | 27 | ## Display names 28 | 29 | Author keypairs begin with a shortname to make the keypair easier to identify, 30 | e.g. `suzy`. These shortnames cannot be changed and are always four characters 31 | long. This makes them unsuitable for most names and the fluctuating nature of 32 | identity. 33 | 34 | Therefore it is desirable to have a free-form display name which can be changed 35 | at any time, and which can differ between each share. 36 | 37 | ### Display name document path 38 | 39 | The path format of a display name document is: 40 | 41 | ``` 42 | `/about/1.0/~{KEYPAIR_ADDRESS}/displayName 43 | ``` 44 | 45 | ### Display name document fields 46 | 47 | The `text` property of the document is the display name the keypair's owner 48 | wishes to use. It can be any UTF-8 string. 49 | 50 | ## Avatars 51 | 52 | An image can be associated with an author keypair. 53 | 54 | ### Avatar document path 55 | 56 | The path format of a display name document is: 57 | 58 | ``` 59 | `/about/1.0/~{KEYPAIR_ADDRESS}`/avatar.{IMAGE_EXTENSION} 60 | ``` 61 | 62 | where `IMAGE_EXTENSION` MUST be the file extension of an image format (e.g. 63 | `gif`, `jpg`, `png`) which allows clients to know how to interpret the 64 | attachment data for this document. 65 | 66 | ### Avatar document fields 67 | 68 | - The `text` property of the document MUST be a textual description of the 69 | avatar image's contents, for use with screenreaders etc. 70 | - The attachment of the document MUST be an image file. 71 | - The image SHOULD have a 1:1 aspect ratio. 72 | - The image SHOULD NOT be larger than 1,000,000 bytes. These images may be 73 | presented in interfaces where they are rendered alongside many other 74 | avatars, and which may impact the performance of rendering. 75 | 76 | ## Status 77 | 78 | A status message (e.g. "Away from keyboard") can optionally be associated with 79 | an author keypair. 80 | 81 | ## Status document path 82 | 83 | The path format of a status document is: 84 | 85 | ``` 86 | `/about/1.0/~{KEYPAIR_ADDRESS}`/status 87 | ``` 88 | 89 | ## Status document fields 90 | 91 | The `text` property of the document is the status message the author wishes to 92 | associate with their keypair. It can be any UTF-8 string. The status message 93 | SHOULD be equal or less to 128 characters. 94 | 95 | ## Biography 96 | 97 | Some biographical information can optionally be associated with an author 98 | keypair. 99 | 100 | ## Biography document path 101 | 102 | The path format of a biography document is: 103 | 104 | ``` 105 | `/about/1.0/~{KEYPAIR_ADDRESS}`/bio 106 | ``` 107 | 108 | ## Status document fields 109 | 110 | The `text` property of the document is the biography message the author wishes 111 | to associate with their keypair. It can be any UTF-8 string of any length. 112 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU LESSER GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright © 2007 Free Software Foundation, Inc. 5 | 6 | Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 7 | 8 | This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. 9 | 10 | 0. Additional Definitions. 11 | As used herein, “this License” refers to version 3 of the GNU Lesser General Public License, and the “GNU GPL” refers to version 3 of the GNU General Public License. 12 | 13 | “The Library” refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. 14 | 15 | An “Application” is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. 16 | 17 | A “Combined Work” is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the “Linked Version”. 18 | 19 | The “Minimal Corresponding Source” for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. 20 | 21 | The “Corresponding Application Code” for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. 22 | 23 | 1. Exception to Section 3 of the GNU GPL. 24 | You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. 25 | 26 | 2. Conveying Modified Versions. 27 | If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: 28 | 29 | a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or 30 | b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. 31 | 3. Object Code Incorporating Material from Library Header Files. 32 | The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: 33 | 34 | a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. 35 | b) Accompany the object code with a copy of the GNU GPL and this license document. 36 | 4. Combined Works. 37 | You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: 38 | 39 | a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. 40 | b) Accompany the Combined Work with a copy of the GNU GPL and this license document. 41 | c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. 42 | d) Do one of the following: 43 | 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. 44 | 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. 45 | e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) 46 | 5. Combined Libraries. 47 | You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: 48 | 49 | a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. 50 | b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 51 | 6. Revised Versions of the GNU Lesser General Public License. 52 | The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. 53 | 54 | Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. 55 | 56 | If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library. 57 | 58 | --------------------------------------------------------------------------------