pzp-invite/protospec.md

pzp://invite URIs are followed by any number of "commands", where each command has a name plus a fixed-length list of arguments.

Inviting a new user to the network

Invite URL:

pzp://invite/join/HOSTFORMAT/HOST/TRANSPORT/PORT/TRANSFORM/CREDENTIALS/follow/ALICE_ID/promise.follow/account.ALICE_ID/ALICE_TOKEN

made of 3 "commands":

• join/HOSTFORMAT/HOST/TRANSPORT/PORT/TRANSFORM/CREDENTIALS
  • Meaning "join" this hub at this address, claiming this token to become a member
  • HOSTFORMAT is ip4 or ip6 or dns
  • HOST is the host address
  • TRANSPORT is tcp (or others to be supported in the future)
  • PORT is the port number
  • TRANSFORM is shse (or others to be supported in the future)
  • CREDENTIALS is PUBKEY.TOKEN where PUBKEY is the hub's public key and TOKEN is the hub membership token to claim
• follow/ALICE_ID
  • Meaning that you should follow Alice
• promise.follow/account.ALICE_ID/ALICE_TOKEN
  • Meaning that Alice (ALICE_ID the account, not any single pubkey) promised to follow you back if you claim ALICE_TOKEN

sequenceDiagram

participant A as Alice
participant H as Hub
participant B as Bob

note over A: creates aliceToken<br />for follow promise
A->>A: publishes self-encrypted<br/>msg about aliceToken
A->>H: ask for hub token
activate H
H->>H: create hubToken
H-->>A: hubToken
deactivate H
A->>B: Externally: send invite URL
B->>H: HTTP: open URL
activate H
H-->>B: HTML with PZP invite URI
deactivate H
B->>B: open PZP app
note over B: parse URI and detect 3 commands
note over B: execute command "join"
B->>H: connect with hubToken in SHSe
activate H
H->>H: add Bob as member
H-->>B: OK
deactivate H
note over B: execute command "follow"
B->>B: follow aliceID
B->>H: muxrpc: connect to anyone online<br />and try to replicate aliceID
H-->>B: OK
note over B: execute command "promise.follow"
alt If some pubkey of aliceID is online
  B->>A: connect with SHS
  activate A
  B->>A: muxrpc: promise.follow(aliceToken, bobID)
  A->>A: detect aliceToken,<br />apply followback on bobID,<br />delete aliceToken
  A-->>B: OK
  deactivate A
end

Inviting a new device to my account

Invite URL:

pzp://invite/join/HOSTFORMAT/HOST/TRANSPORT/PORT/TRANSFORM/CREDENTIALS/tunnel-connect/HUB_PUBKEY/OLD_PUBKEY/promise.account-add/peer.PUBKEY/OLD_TOKEN/promise.account-internal-encryption-key/peer.PUBKEY/OLD_TOKEN

made of 3 "commands":

• join/HOSTFORMAT/HOST/TRANSPORT/PORT/TRANSFORM/CREDENTIALS
  • Meaning "join" this hub at this address, claiming this token to become a member
  • HOSTFORMAT is ip4 or ip6 or dns
  • HOST is the host address
  • TRANSPORT is tcp (or others to be supported in the future)
  • PORT is the port number
  • TRANSFORM is shse (or others to be supported in the future)
  • CREDENTIALS is PUBKEY.TOKEN where PUBKEY is the hub's public key and TOKEN is the hub membership token to claim
• tunnel-connect/HUB_PUBKEY/OLD_PUBKEY
  • Meaning that you should connect to the old device via a tunnel in the hub
• promise.account-add/peer.PUBKEY/OLD_TOKEN TODO implement with peer.PUBKEY
  • Meaning that the old device promised to add your pubkey if you claim OLD_TOKEN
• promise.account-internal-encryption-key/peer.PUBKEY/OLD_TOKEN TODO implement
  • Meaning that the old device promised to send you the internal encryption key

sequenceDiagram

participant O as Old device
participant H as Hub
participant N as New device

note over N: instruct user to create<br />an invite on the old
note over O: creates oToken<br />with account-add perm
O->>H: ask for hub token
activate H
H->>H: create hubToken
H-->>O: hubToken
deactivate H
O->>N: Externally: send invite URL or URI
N->>N: input URL or URI
note over N: parse URI and detect 3 commands
note over N: execute command "join"
N->>H: connect with hubToken in SHSe
activate H
H->>H: add New as member
H-->>N: OK
deactivate H
note over N: execute command "tunnel-connect"
alt If old pubkey is online
  N->>O: connect with SHS
  activate O
  note over N: execute command "promise.account-add"
  N->>N: consent = sign(":account-add:ACCOUNT_ID", new privkey)
  N->>O: muxrpc: promise.accountAdd(oToken, new pubkey, consent)
  O->>O: detect oToken,<br />apply account-add on New,<br />delete oToken
  O-->>N: OK
  deactivate O
else If Old is offline
  N->>O: connect with SHS
  O-->>N: Failure
end