Invite code format

Earthstar Invite Code Specification v1

(This was extracted from the conversation around Issue #36 )

Goals

1. A short string that includes all the info needed to join a workspace and find its pubs. Give it to your friends.
2. Be extendable for other uses such as Agregore's fetch based API for getting Earthstar content
3. Use a standard format that's easy to parse

Details

Example: earthstar:///?workspace=+gardening.abc&pub=http://pub1.org&pub=https://pub2.org&v=1

Reformatted for easier reading -- don't actually add newlines to your invite codes!

earthstar:///
    ? workspace=+gardening.abc
    & pub=http://pub1.org
    & pub=https://pub2.org
    & v=1

• Three slashes up front, because the traditional URL format is scheme://location/path?query. We're not using the location or path in the invitation, so the slashes pile up.
• Keys can occur more than once e.g. for multiple pubs

How to parse

Parse this as if it was a regular URL. You may need to do a temporary string replace earthstar:/// --> http://example.com/ in order for some parsers to accept it, for example the built-in browser Url API needs that since it has an allowlist for the scheme and earthstar: is not on it.

Query parameters

Use the traditional rules for encoding and parsing query parameters.

• workspace=+gardening.abc -- May occur zero or one times. A workspace address including its + character.
• pub=https://pub1.org -- May occur zero, one, or many times. Include the scheme of the pub URL. For now pub URLs are not allowed to contain their own query parameters until we specify how to safely encode them.
• v=1 -- Invite code specification version, always an integer

The order of parameters is not significant. Recommend putting the workspace first as it's the most salient to the user, and v last.

Intended use

This is not a URL meant for continuous display in a browser; it's an invite code meant to be given to someone, "used", and discarded. The UI should not keep it around after it's used.

Unfortunately invite codes can't be limited by time or number of uses; they remain valid forever.

User interfaces can have a "share" tool that generates invite codes.

• Users SHOULD be able to decide which pubs to include in the code, since some pubs may be secret, only available on localhost, etc.
• Once we eventually have workspace secrets, users SHOULD be able to include or omit the workspace secret. An invite code without a secret will allow people to host the data but not read or write to the workspace.
• The UI MUST explain the privacy consequences of the invite code.

When using an invite code,

• The UI SHOULD show a prompt with an easy-to-understand summary of what is about to happen, including a list of pubs.
• Users SHOULD be able to toggle the new pubs so they can avoid adding some of them.
• The goal is to avoid making network requests to new pubs until users have approved them.

Future plans

More query parameters

• workspaceSecret=bj0q9j0039j -- Zero or one workspace private keys (for invite-only workspaces), encoded in Earthstar-flavored base32. Only useful if workspace is also specified. See #7 for details.
• room=... -- Zero, one, or many addresses of room servers, if we ever have those.
• swarm=... -- Zero, one, or many Hyperswarm discovery keys for finding p2p peers. Normally we'll use a hash of the workspace as the primary discovery key, but you could also make additional private swarms this way
• vouch=... -- Maybe a signature from the person creating the invite, to help track who invited who? Need to think about this one.

The Path part of the URL

earthstar:///path-goes-here/?query

If you want to get a certain Earthstar document by its path, we could eventually put that into the path part of the URL.

The Location part of the URL

earthstar://location/path/?query

I expect the location will never or rarely be used since Earthstar is all about having multiple locations for the same data -- pubs, rooms, swarms. Better to put those in the query parameters so we can have many of them.