Mostly decentralized protocol, returning hints about how connections could be established to users

Short summary

The user signs up with a provider, providers are similar to a DNS server. They inform programs and users about how to contact eachother.

As an example setup, we have fier@https#fier.me/hldns#443 trying to contact user@https#example.com/hldns#443.

1. fier@https#fier.me/hldns#443 sends a request to https://fier.me:443/hldns, requesting the info of user@https#example.com/hldns#443.
2. https://fier.me:443/hldns verifies the legitimacy of the client, and then contacts https://example.com:443/hldns, requesting the info of user@https#example.com/hldns#443.
3. https://example.com:443/hldns confirms the legitimacy of the server, and then returns the data of user@https#example.com/hldns#443 to the requesting server
4. https://fier.me:443/hldns returns the information to fier@https#fier.me/hldns#443, who initially sent out the request.

The return is a JSON, containing information about how they could be contacted. As an example:

{
	"entries": [
		{
			"protocol": "mp-tcp",
			"services": ["chat", "stream"],
			"protocol_info": {
				"address": "example.com",
				"port": 1337,
				"service_prefix": "main."
			}
		}
	]
}

This signifies that they may be contacted over mp-tcp, at address example.com and port 1337. If the client is provides the service chat or stream, and supports this protocol, it may use this entry to start contacting this user.

API

Mind your MAY, SHOULDs and MUSTs! :)

Primitives

Username

Usernames must be formatted like this: NAME@PROTOCOL#ADDRESS#PORT

• NAME: User's name
• PROTOCOL: http/https - Under which protocol to speak to the server
• ADDRESS: URL at which the API is reachable (may be fier.me, api.fier.me, fier.me/api, 0.0.0.0/whatever, etc...)
• PORT is the HTTP(S) server's port

General notes

• Server must accept ASCII and UTF-8 encoded text/json bodies
• All requests use HTTP's POST
• All requests must return UTF-8 encoded text/json
• Clients should handle malformed server output, failing gracefully
• The server must not return more information than what is defined in this document
• All successful queries must return 200 OK

Error return

• Allowed statuses:
  • 301 Moved Permanently: API moved. Client will either offer the user to change the full name of the requested user to encompass the new API URL, or change it automatically
  • 400 Bad Request: Input JSON malformed
  • 403 Forbidden: Access denied
  • 404 Not Found: Missing user - You may always use 403 instead, to prevent pruning of users
  • 413 Content Too Large: Request too long
  • 429 Too Many Requests: Try again later
  • Other statuses may be used, but all non-200 codes must be treated as errors in the client.

The return body may contain this json, detailing more information:

{
	"source": "internal/external"
	"error_message": "..."
}

• source"": Either internal or external. Whether the error came from the first party (server that was contacted by the client) or third party (another server contacted by the server).
• error_message"": Human readable error string.

Endpoints

user_info_get

Retrieve the contact info of someone

Input body:

{
	"user": "NAME@PROTOCOL#ADDRESS#PORT",
	"token": "...",
	"target": "NAME@PROTOCOL#ADDRESS#PORT"
}

• user"": Optional. User requesting the information
• token"": Optional. User's password. Must only be sent by the client, if a user is defined. DO NOT send to other servers
• target"": The user of which to get the information

It is up to the servers to detect, whether to transmit the request to another server from the target name. It is also up to the servers to detect fakers (by verifying hostname with the IP, for example).

If the server detects fakers, it must be transparent about it and report it back as such. This helps the community detect flaws in security.

Output body:

{
	"moved": "NAME@PROTOCOL#ADDRESS#PORT",
	"entries": [
		{
			"protocol": "...",
			"services": [...],
			"protocol_data": {
				...
			}
		},
		...
	]
}

• moved"": Optional. May be set if the user now has a different account. It is up to the client to decide how to handle this information, but it should be handled. If the user has not moved, it must not be set.
• entries{}: A list of different entries under which the user is reachable
  • protocol"": Protocol, under which this entry is reachable
  • services[]: Services, that can be used in this entry, they must be strings
  • protocol_data{}: The protocol-specific data, may contain anything

user_info_set

Set user's contact info

Input body:

{
	"user": "user",
	"token": "...",
	"data": "{\"entries\": [...]}"
}

Output body:

{}