Differences

This shows you the differences between two versions of the page.

--- pawsd:protocol [2026/04/07 17:50] – Verb 2: Query services winter
+++ pawsd:protocol [2026/04/29 17:25] (current) – [Verb 4098 (0x1002): Fetch contact] formatting winter
@@ Line 90: / Line 90: @@
 ===== Verb 1: Fetch service =====
-The client asks the server for a particular service. Even if the service exists, the server may not have it, in which case it should respond "resource not found" (and should **not** perform any lookups of its own to try to find it).
+The client asks the server for a particular service. Even if the service exists, the server may not have it, in which case it may respond "resource not found". If the server is acting as an authoritative daemon this is likely what it should do; however, caching daemons might instead wish to forward the request onto other servers in an attempt to find the service, then return their eventual response back to the original client, while caching it in the process.
 Request payload:
@@ Line 253: / Line 253: @@
 The response payload is identical to the //Start authentication// verb.
+===== Verb 4098 (0x1002): Fetch contact =====
+The client sends a zone's public key to be looked up in the authenticated user's contact list. ("Contacts" are PawSD's way of storing local names and trust levels, roughly analogous to a phone's contact list (hence the name), browser bookmarks, etc.)
+Request payload:
+^ Field             ^ Length   ^ Type   ^
+| auth token        | 32 bytes | [32]u8 |
+| public key type   | 2 bytes  | enum   |
+| public key length | 2 bytes  | u16    |
+| public key        | varies   | [_]u8  |
+The server will either respond "resource not found" if that zone is not in the contact list, or otherwise:
+^ Field             ^ Length  ^ Type                                      ^
+| local name length | 2 bytes | u16                                       |
+| local name        | varies  | UTF-8 string                              |
+| trust level       | 1 byte  | enum                                      |
+| introducer zone   | varies  | key type, length, key OR constant 0 (u16) |
+The trust level can be one of the following values:
+  * 0 = **distrusted**: the user has explicitly marked the zone as evil
+  * 1 = **neutral**: default value in the absence of any other indication of trust
+  * 2 = **introduced**: implicitly trusted due to being pointed to by another zone's edge record, where that other zone' trust level is either introduced or trusted
+  * 3 = **trusted**: the user has explicitly marked the zone as trusted (e.g. due to in-person verification)
+The introducer zone field may be set to the public key of a zone that points to the requested zone, as an explanation for the trust level being "introduced". It may also be set even if the trust level is something else. If the key type is instead set to 0 this indicates that no length or key data will follow, representing the lack of any introducer.
+===== Verb 4099 (0x1003): Put contact =====
+The client sends a zone's public key, local name, trust level and optionally an introducer zone, to be stored by the server in the authenticated user's contacts. If the zone in question was already in the contacts, its entry will be modified to the new information.
+Request payload:
+^ Field             ^ Length   ^ Type                                      ^
+| auth token        | 32 bytes | [32]u8                                    |
+| public key type   | 2 bytes  | enum                                      |
+| public key length | 2 bytes  | u16                                       |
+| public key        | varies   | [_]u8                                     |
+| local name length | 2 bytes  | u16                                       |
+| local name        | varies   | UTF-8 string                              |
+| trust level       | 1 byte   | enum                                      |
+| introducer zone   | varies   | key type, length, key OR constant 0 (u16) |
+Response payload:
+^ Field    ^ Length ^ Type    |
+| updated? | 1 byte | boolean |
+"updated?" being true (1) indicates that the contact entry already existed before this request was processed; false (0) means it was a new addition.
+===== Verb 4100 (0x1004): Remove contact =====
+The client sends a zone's public key, to be removed from the authenticated user's contact list.
+Request payload:
+^ Field             ^ Length   ^ Type   ^
+| auth token        | 32 bytes | [32]u8 |
+| public key type   | 2 bytes  | enum   |
+| public key length | 2 bytes  | u16    |
+| public key        | varies   | [_]u8  |
+Response payload is empty. A successful status code indicates that the contact was deleted, whereas if the contact didn't exist in the first place, the status should be "resource not found".