Current Version: 3.1
Test Suite: Not available yet
Implementation report: Not available yet
Author: Cagan Mert ISLEK
TheProtocols is a federated protocol for decentralizing super apps by letting people choose a network and a client they want. TheProtocols is designed to provide most functionality a standard user needs in a daily life.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
All interested parties are invited to provide implementation and bug reports and other comments through email, TheProtocols, X, fediverse, or issue tracker. These will be considered in any future versions of this specification.
This format is used in Resource Pointer object from below.
| Name | URL |
|---|---|
| User | theprotocols://{username}@{network} |
theprotocols://mail:{mailbox}/{id} |
|
| Chat | theprotocols://chat:{id} |
| Note | theprotocols://note:{path} |
| Reminder | theprotocols://reminder:{list}/{title} |
| IoT | theprotocols://iot:{house}/{room}/{device} |
| File | theprotocols://file:{path} |
| Event | theprotocols://event:YYYY-MM-DD/HH:mm/{index} |
| Feed Post | theprotocols://feed:{id} |
theprotocols://part is not necessary but recommended to avoid TheProtocols cause conflicts with other protocols.
| **Resource Pointer** Used for pointing to any resource on web. | ```json { "title": "Example", "url": "https://example.com/index.html", "description": "Lorem ipsum dolor sit amet" } ``` |
|
**Feed Post**
A post listed in feed. `content` is in HTML format and an optional key if this object is in list. `id` must follow FAT32 filename limitation except space is not allowed. |
```json { "title": "Post Title", "datetime": "YYYY-MM-DD HH:mm", "id": "post01", "content": "HTML" } ``` |
|
**Contact**
Extensible object to keep extra data about a person. Addition to the `Relation` and `Socials`, the key-value pairs available in a standard user ID can be added to replace hidden ones. Value of `Relation` must be `"Self"` if the contact is the current user and empty string if relation is not unique. |
```json { "Relation": "", "Socials": [ "https://example.com/@username" ] } ``` |
|
**Reminder**
Standard reminder object. `deadline` and `last_update_status` must be in "YYYY-MM-DD HH:mm" format. `last_update_status` is the most recent time the reminder toggled. `subs` is a list of sub-reminder object. `repeat` must be an interval object. |
```json { "deadline": "", "last_update_status": "2024-01-24 11:28", "repeat": "", "status": true, "subs": [], "title": "Demo Task" } ``` |
|
**Sub-Reminder**
Sub-reminder object. `deadline` must be in "YYYY-MM-DD HH:mm" format. |
```json { "deadline": "", "status": true, "title": "Demo Task" } ``` |
|
**Chat**
Two form object to keep information about two party and multiple party chats. Two party chats only have `last_index` key, other keys are only for multiple party chats. `image` must be an URL. `participants` is a list of TheProtocols addresses of participants. |
```json { "last_index": 0, "image": "", "title": "", "participants": [] } ``` |
|
**Message**
An object to keep information about a message. `date_received` must be in `YYYY-MM-DD HH:mm` format. `body` must be in Markdown format. |
```json { "from": "", "body": "", "date_received": "" } ``` |
|
**Mail**
An object to keep information about a mail. `date_received` must be in `YYYY-MM-DD HH:mm` format. `body` must be in HTML format. `sender` must be the address of sender. `to` and `cc` must be lists of addresses stringified with `;` as deliminator. `hashtag` must only contain lowercase, uppercase, and numbers. |
```json { "subject": "", "date_received": "", "sender": "", "to": "", "cc": "", "hashtag": "", "body": "" } ``` |
|
**Event**
An event object as part of calendar. `starts` and `ends` must be in `YYYY-MM-DD HH:mm` format and in UTC timezone. `country` must be two letter country code. `travel_time` and values in `alerts` list must have unit suffix: m=minute, h=hour, d=day, w=week, mo=month, y=year `repeat` must be an interval object. |
```json { "name": "", "starts": "", "ends": "", "location": { "name": "", "street": 0, "no": 0, "zipcode": "00000", "country": "" }, "alerts": [ "10m", "1h", "1d", "1w", "1mo", "1y" ], "repeat": "", "travel_time": "", "participants": [ "john.doe@example.com" ], "notes": "Markdown", "url": "https://example.com/about/event/index.html", "attachments": [ "https://example.com/about/event/photo.png" ] } ``` |
| **Deleted** Used to inform network to delete a remote object. | ```html </deleted> ``` |
To learn about a network, an HTTPS POST request to /protocols/version is used.
Server must not expect any data to be in body for this request.
Example Response Client Must Expect:
| ```json { "help": "", "os": { "arch": "", "family": "", "name": "", "version": "" }, "rules": { "new_accounts_allowed": true }, "software": { "build": 1, "channel": "", "developer": "", "name": "", "source": "", "version": "" }, "membership_plans": [ { "name": "Free", "storage": 0, }, { "name": "Plus", "storage": 0, }, { "name": "Pro", "storage": 0, }, { "name": "Ultra", "storage": 0, } ], "users": [], "version": "3.1" } ``` |
String: Username of the account users must contact for help Dictionary: Information about OS of the server of the network String: Architecture of OS *(look below)* String: OS Family String: OS Name String: OS Version Dictionary: Rule configuration of the network Bool: If network accepts new users to create account using TheProtocols Dictionary: Information about the server software Integer: Build number of the server software String: Release channel of the server software *(look below)* String: TheProtocols address of the developer String: Name of the server software String: `"Closed"` or URL of the repository of the server software String: Version of the server software Dictionary: Membership Plans String: Name of free plan Integer: Storage for free plan in bytes String: Name of paid plan #1 Integer: Storage for paid plan #1 in bytes String: Name of paid plan #2 Integer: Storage for paid plan #2 in bytes String: Name of paid plan #3 Integer: Storage for paid plan #3 in bytes List: List of usernames of the users String: TheProtocol version server configured |
Architecture of OS must be in official format like: x86, x86_64, AArch64
To create an account on a network these steps must be followed in the order:
/protocols/terms_of_service to view Terms of Service of the network in HTML format. Account creation will assume you accepted./protocols/signup with a JSON with these keys:| ```json { "birthday": "YYYY-MM-DD", "country": "US", "gender": "Male", "name": "Given Name", "password": "Raw Password", "phone_number": "+1 000 000 0000", "postcode": "54050", "timezone": -8, "surname": "FAMILY", "username": "username" } ``` |
String: Birthday in `YYYY-MM-DD` format String: 2-letter Country Code String: Gender *(look below)* String: Given Name String: Raw Password of User String: Phone Number, "+1 000 000 0000" format without spaces String: Postcode of the user Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00") String: Surname in all uppercase String: Username with only using ASCII lowercase and `-` symbol |
Standard
gendervalues are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual. Clients and servers must code to support others before reporting the problem to me via email, GitHub, or HereUS. Clients are designed to assume there is no other possible value and unsupported values can cause problems.
+symbol can also be used in usernames as alternative accounts of the main account. For instance, user@example.com can use user+untrustedapp@example.com for privacy and prevent spam if the server software supports as TheProtocols specification highly recommends.
Client must not expect anything except a status code to learn about is the server was able to create the account.
After creating an account, next step is logging into it. There is two option for that:
Using Credentials to get a Token:
To get a token using credentials, an HTTPS POST request to /protocols/login is used.
Example Body Server Must Expect:
{
"username": "Username",
"password": "Password",
"package": "com.example.app",
"permissions": [
"RSA", // view private RSA key and work with tokens
"HiddenInformation", // see information hidden from public
"Search", // search objects and index
"Feed", // view feed and read posts
"Contacts", // list and view contacts
"ContactsWrite", // add, modify, and delete contacts
"Reminders", // view reminders and lists
"RemindersWrite", // add, modify, and delete reminders and lists
"Chat", // send and receive messages
"Mail", // list, view, move, trash, delete mails
"MailSend", // send mails
"Notes", // view notes
"NotesWrite", // create, edit, and delete notes
"IoT", // view states of IoT devices
"IoT-Full", // full control on IoT connections
"ReadFile", // view filesystem, read files
"WriteFile", // write files, create folders, delete any
"PhotosRead", // view photos
"PhotosModify", // make modifications on photos roll
"Calendar", // view calendar
"Events", // create, edit, and delete events on calendar
"ModifyID", // make modifications on ID
"InterApp" // read data and preferences of all apps
]
}
usernamemust be the username of the user andpasswordmust be the password of the user.
Clients shouldn’t expect server to respect all permissions. Server softwares can let users disable some of the permissions.
Example Response Client Must Expect:
{
"token": ""
}
Using Credentials with Every Request:
For compatibility reasons, old method to login (current_user_username and current_user_password with all requests) will stay until 4.0 release.
Continue with no account: You can use some endpoints without account; however experience can be less personalized. To use the Guest account, do not send “cred” argument which means for endpoints to send blank JSON.
To get identity (including personal information and hidden information) of the current user,
an HTTPS POST request to /protocols/current_user_info is used.
Example Body Server Must Expect:
{
"cred": "token"
}
Example Response Client Must Expect:
| ```json { "birthday": "", "rsa_private_key": "", "rsa_public_key": "", "country": "", "gender": "", "name": "", "phone_number": "", "plus": false, "postcode": "00000", "profile_photo": "", "settings": { "apps": [], "plus_until": 20321108, "theme_color": "blue" }, "social": { "biography": "", "emoji": "", "story": { "content": "", "datetime": 202401011200 } }, "surname": "SURNAME", "timezone": -8 } ``` |
String: Birthday in `YYYY-MM-DD` format String: RSA Private Key String: RSA Public Key String: 2-letter Country Code String: Gender *(look below)* String: Given Name String: Phone Number, "+1 000 000 0000" format without spaces Integer: `0` is free plan, `1` is plus, `2` is pro, and `3` is ultra String: Postcode of the user String: URL of the profile photo of the user Dictionary: Settings of user which not owned by an app List: List of package names keeping data in library of user Integer: When membership of the user ends in YYYYMMDD format String: Theme color preference of user Dictionary: Required keys to create a complete social media profile String: Social media biography with ` String: Emoji to show next to the username Dictionary: Story data for social media String: HTML Content of Story Integer: When story updated in YYYYMMDDHHmm format String: Surname in all uppercase. Integer: Difference of Timezone of User to UTC (ex. -8 is "UTC-08:00") </td> </tr> </table> > Standard `theme_color` values are red, orange, yellow, green, blue, pink, purple, and blank. > blank value means for client to not color the UI. > Standard `gender` values are Male, Female, Lesbian, Gay, Bisexual, Transgender, Queer, Intersexual, Asexual, and Pansexual. > Clients and servers must code to support others before reporting the problem to me via [email](mailto:islekcaganmert@hereus.net), [GitHub](https://github.com/islekcaganmert/TheProtocols), or [HereUS](https://www.hereus.net/user/islekcaganmert@hereus.net). > Clients are designed to assume there is no other possible value and unsupported values can cause problems. > If a server software implementor wants to create a feature like email aliases with privacy feature, the server must hide the data while respecting the standards above. > For instance, while user_info can hide timezone by replacing with `"**"` but current_user_info can only hide by replacing with `0` or other standard compatible placeholder. > Servers can modify count of memberships (`plus key`) available up to 4. > That means servers can disable 1, 2, 3, 1 & 2, 1 & 3, 2 & 3, or all. > The reason why TheProtocols has standard of memberships is these memberships are considered as TheProtocols Network membership by clients and names must be generated from an integer. > `social` key can be removed to disable social media integrations. > But if server sends this key included, value must follow the standard. ### User ID Modifications To modify a value in user id, **HTTPS POST** request to `/protocols/set_user_data` is used. > Networks can be configured to set immutable some of the keys. Client must not expect success everytime. Example Body Server Must Expect: ```json { "cred": "token", "key": "", "data": "" } ``` > `key` must be in file path format. > If the value placed directly in the root, `key` must be the key directly. Client must not expect anything except a status code to learn about is the server was able to save. ### Search To search for an object or a website from index of server, an **HTTPS POST** request to `/protocols/search` is used. Example Body Server Must Expect: ```json { "cred": "token", "key": "" } ``` > `key` is the query string. Network will return every object matching with the key. Response will be a JSON with a single key value pair. Key is `results` and contains a list of resource pointer objects matching with the query. ### Feed TheProtocols allows networks to serve a feed. To get the feed, an **HTTPS POST** request to `/protocols/get_feed` is used. Example Body Server Must Expect: ```json { "cred": "token", } ``` Response will be a JSON with a single key value pair. Key is `feed` and contains a list of feed post objects matching with the query. To get a feed post, an **HTTPS POST** request to `/protocols/get_feed_post` is used. Example Body Server Must Expect: ```json { "cred": "token", "id": "" } ``` > `id` must be the id of the post. Response will be a feed post object. ### Cloud Storage To check status of cloud storage allocated for the user, an **HTTPS POST** request to `/protocols/storage_status` is used. Example Body Server Must Expect: ```json { "cred": "token" } ``` Example Response Client Must Expect: ```json { "total": 0, "used": {} } ``` > `used` can contain unlimited number of key value pairs to address what uses how much space. > Values must be size in byte as integer. > Recommended keys to have in `used` dictionary are > size of user id and profile photo as `id`, > size of folder containing application data as `library_data`, > size of folder containing mails as `mails`, > size of folder containing notes as `notes`, > size of folder containing reminders as `reminders`, > size of folder containing contacts as `contacts`, > size of folder containing cloud storage `documents`, > size of folder containing application preferences as `preferences`, > size of folder containing pictures as `pictures`, > size of folder containing IoT data as `things`, > size of folder containing cold wallet as `token`, > and a key value pair per every other feature. > `total` is total space allocated for the user in byte as integer. To list files on cloud drive, an **HTTPS POST** request to `/protocols/storage_ls` is used. Example Body Server Must Expect: ```json5 { "cred": "token", "path": "/" // root is storage folder } ``` Client must expect a JSON where key is filename and value is a JSON. Example JSON to expect as a value is: ```json5 { "type": "empty", "size": 0, "created": "YYYY-MM-DD HH:mm", "edited": "YYYY-MM-DD HH:mm" } ``` > `type` is same as what `file` command echoes after `: ` > To learn about a specific file, put file path into `path` same as can be done with `ls` command. > Server must not accept `..` To create a folder, an **HTTPS POST** request to '/protocols/storage_new_folder' is used. Example Body Server Must Expect: ```json { "cred": "token", "folder": "" } ``` > `folder` is in format of `/path/to/folder/new_folder` Client must expect no but status code. To remove something, an **HTTPS POST** request to '/protocols/storage_delete' is used. Example Body Server Must Expect: ```json { "cred": "token", "path": "" } ``` > `path` is in format of `/path/to/file` > This can be used for both files and folders. > However, when applied to folders, it has same effect as `rm -rf` Client must expect no but status code. For read/write operations, access to file under `/protocols/storage` is used. For example if file path is `/path/to/file.txt`, `/protocols/storage/{username}/path/to/file.txt` is the path used with request. There is two possibility. While reading, an **HTTPS GET** request is used; for writing, **HTTPS POST** is used. For reading, leave body empty. For writing, add the content to (over)write there. While doing these so, add these headers: ``` Authorization: TheProtocols-Token {your-token-here}` ``` ### Photos To list all photos saved in a day, an **HTTPS POST** request to `/protocols/list_photos` is used. Example Body Server Must Expect: ```json { "cred": "token", "date": "YYYY-mm-dd" } ``` Example Response Client Must Expect: ```json { "previous": "YYYY-mm-dd", "next": "YYYY-mm-dd", "list": [] } ``` > `previous` and `next` are, respectively to their names, closest days with photos saved in. > `list` is list of names of the photos from the day. To get a photo, an **HTTPS POST** request to `/protocols/get_photo` is used. Example Body Server Must Expect: ```json { "cred": "token", "filename": "example.png" } ``` Example Response Client Must Expect: ```json { "filetype": "PNG image data, 24 x 24, 8-bit/color RGBA, non-interlaced", "hex": "...", "hash": "...", "albums": [], "date": "YYYY-mm-dd HH:MM:SS" } ``` To save a photo, an **HTTPS POST** request to `/protocols/save_photo` is used. Example Body Server Must Expect: ```json { "cred": "token", "filetype": "PNG image data, 24 x 24, 8-bit/color RGBA, non-interlaced", "hex": "...", "hash": "..." } ``` > `filetype` is same as second half after splitting what `file` command of Unix returns from `: ` > `hex` is hex of encoded bytes of photo. > `hash` is hashed bytes of photo, not of hex of it. > `albums` are list of names of the albums having this photo inside. Client should not expect anything except status code to know if the network saved. To move a photo to trash or restore from trash, an **HTTPS POST** request to `/protocols/move_photo_trash` is used. Example Body Server Must Expect: ```json { "cred": "token", "filename": "example.png" } ``` Client should not expect anything except status code to know if the photo was moved from/to trash successfully. To list all photos in trash, an **HTTPS POST** request to `/protocols/list_photos_trash` is used. Example Body Server Must Expect: ```json { "cred": "token" } ``` Client should expect list of names of the photos in trash. To delete a photo, an **HTTPS POST** request to `/protocols/delete_photo` is used. Example Body Server Must Expect: ```json { "cred": "token", "filename": "example.png" } ``` Client should not expect anything except status code to know if the photo was deleted successfully. To list albums, an **HTTPS POST** request to `/protocols/list_albums` is used. Example Body Server Must Expect: ```json { "cred": "token" } ``` Client should expect list of names of the albums. To list photos in album, an **HTTPS POST** request to `/protocols/list_photos_album` is used. Example Body Server Must Expect: ```json { "cred": "token", "album": "Example" } ``` Client should expect list of filenames of the photos in the album. To create an album, an **HTTPS POST** request to `/protocols/create_album` is used. Example Body Server Must Expect: ```json { "cred": "token", "name": "Example" } ``` Client should not expect anything except status code to know if the album was created successfully. To add a photo to an album, an **HTTPS POST** request to `/protocols/add_photo_album` is used. Example Body Server Must Expect: ```json { "cred": "token", "album": "Example", "name": "example.png" } ``` Client should not expect anything except status code to know if the photo was added successfully. To remove a photo from an album, an **HTTPS POST** request to `/protocols/remove_photo_album` is used. Example Body Server Must Expect: ```json { "cred": "token", "album": "Example", "name": "example.png" } ``` Client should not expect anything except status code to know if the photo was removed successfully. To delete an album, an **HTTPS POST** request to `/protocols/delete_album` is used. > Photos will remain. To remove an album with all inside, all photos must be deleted before deleting an album. Example Body Server Must Expect: ```json { "cred": "token", "name": "Example" } ``` Client should not expect anything except status code to know if the album was deleted successfully. ### Notes To pull all notes from the network, an **HTTPS POST** request to `/protocols/pull_notes` is used. Example Body Server Must Expect: ```json { "cred": "token" } ``` Response client must expect is a plain JSON. If the value of a key is dictionary, the pair is a folder. If the value of a key is string, the pair is a note. For instance, if there notes folder of a user is `/Users/user/Notes`, and user has a note in `/Users/user/Notes/path/to/note.html`, response should be ```json { "path": { "to": { "note": " Hello, World! " } } } ``` To edit a note, an **HTTPS POST** request to `/protocols/edit_note` is used. Example Body Server Must Expect: ```json { "cred": "token", "path": "", "value": "" } ``` > `path` must be the path of the note to edit. > `value` must be text in HTML format. Client must not expect anything except a status code to learn about is the server was able to save. To delete a note, send deleted object as the new value of the note. ### Reminders To pull reminders from the network, an **HTTPS POST** request to `/protocols/get_reminders` is used. Example Body Server Must Expect: ```json { "cred": "token" } ``` Response client must expect is JSON key value pairs, task list titles as keys and lists of reminder objects as values. To toggle a reminder, reversing `status` value, an **HTTPS POST** request to `/protocols/toggle_reminder` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "", "id": 0 } ``` > `list` must be the name of the list. > `id` must be the index of the reminder in the list. > Note that `id` is not unique and can change, best to pull reminders before editing, toggling, deleting a reminder. Client must not expect anything except a status code to learn about is the server was able to save. To edit a reminder, an **HTTPS POST** request to `/protocols/edit_reminder` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "", "id": 0, "data": "" } ``` > `data` must be a reminder object that dumped to JSON. Client must not expect anything except a status code to learn about is the server was able to save. To delete a reminder, an **HTTPS POST** request to `/protocols/delete_reminder` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "", "id": 0 } ``` Client must not expect anything except a status code to learn about is the server was able to delete. To create a new list, an **HTTPS POST** request to `/protocols/create_reminder_list` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "" } ``` > Value of `list` must follow FAT32 filename limitations. Client must not expect anything except a status code to learn about is the server was able to create. To create a new reminder, an **HTTPS POST** request to `/protocols/create_reminder` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "", "title": "", "deadline": "", "repeat": "" } ``` > Value of `title` must be string. > `deadline` must be in "YYYY-MM-DD HH:mm" format. > 'repeat` must be an interval object. Client must not expect anything except a status code to learn about is the server was able to create. To create a new sub-reminder, an **HTTPS POST** request to `/protocols/create_sub_reminder` is used. Example Body Server Must Expect: ```json { "cred": "token", "list": "", "reminder": "", "title": "", "deadline": "" } ``` > Value of `title` must be string. > `deadline` must be in "YYYY-MM-DD HH:mm" format. Client must not expect anything except a status code to learn about is the server was able to create. ### Tokens > While interacting with tokens, requests must be done to a relay in the token's network which supports TheProtocols. To learn about a token, an **HTTPS POST** request to `/protocols/token/about` is used. Server must not expect any data to be in body for this request. Example Response Client Must Except:
|