mirror of https://codeberg.org/pzp/pzp-invite.git
130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
`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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
``` |