Contact Operations – Registry – RevokeInstallation

[jac18281828]

Discussed in #14

^{Originally posted by jac18281828 December 22, 2023}
Initial discussion is here

Device installation is supported by GrantInstallation. This may be reversed by the endpoint described below.

JSON-RPC Endpoint Documentation

Request:

• Method: POST
• URL: /rpc/v1/revokeInstallation
• Headers:
  • Content-Type: application/json
• Body:
  • JSON Object:
    • jsonrpc: "2.0"
    • method: "revokeInstallation"
    • params: Array (optional parameters as required)
    • id: Request identifier (integer or string)

Endpoint: revokeInstallation

Description

The revokeInstallation endpoint is responsible for removing the contact bundle for the XMTP device installation. The request must be made to a valid did with an XMTP profile.

Request

The request for this endpoint should contain the necessary information to authenticate and validate the installation request including the wallet signed payload

Parameters:

• DID (string): Unique XMTP identifier for the user requesting the revocation.
• name (bytes32): Unique identifier naming bundled contents. NOTE 32 byte maximum
• value (bytes): Installation bundle bytes payload
• V (int): signature V
• R (bytes): signature R
• S (bytes): signature S

Example Request:

{
  "jsonrpc": "2.0",
  "method": "revokeInstallation",
  "params": {
    "did": "12345",
    "name": "xmtp/contact_installation",
    "value": "#######",
    "signature": {
      "V": "12345",
      "R": "valueR",
      "S": "valueS"
    }
  },
  "id": 1
}

Response

The response will indicate whether the installation is revoked and may include additional information or instructions.

Result Fields:

• status (string): The status of the request, e.g., 'completed'.
• message (string, optional): Additional information or reason for the decision.
• tx (string, optional): transaction receipt

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "completed",
    "message": "Installation revoked.",
    "tx": "<receipt>"
  },
  "id": 1
}

Error Handling

In case of an error, the response will include an error object with details.

Error Object Fields:

• code (integer): Numeric code representing the error type.
• message (string): Description of the error.

Example Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 403,
    "message": "User not authorized for installation."
  },
  "id": 1
}

Security Considerations

All requests to revokeInstallation must be made over a secure channel. Ensure that user and application IDs are validated, and proper authentication mechanisms are in place to prevent unauthorized requests.

[insipx]

(bytes32): Unique identifier naming bundled contents. NOTE 32 byte maximum

I think we have a choice here concerning how opinionated we want to be w.r.t attribute names. libxmtp doesn't need to know the exact format (i.e /did/pub/x25519/enc/base64, specifying a service: /did/svc/xmtp) in order to grant/revoke an installation -- we could instead expose a simpler endpoint that doesn't require specifying this and handle the name formats in the gateway which will reduce the complexity from libxmtp end

WDYT?

[jac18281828]

(bytes32): Unique identifier naming bundled contents. NOTE 32 byte maximum

I think we have a choice here concerning how opinionated we want to be w.r.t attribute names. libxmtp doesn't need to know the exact format (i.e /did/pub/x25519/enc/base64, specifying a service: /did/svc/xmtp) in order to grant/revoke an installation -- we could instead expose a simpler endpoint that doesn't require specifying this and handle the name formats in the gateway which will reduce the complexity from libxmtp end

WDYT?

Does it make sense to change the 'name' field to an installation type that supports a fixed set of proper values? Maybe only one value to start? it is important to note that far in the future when a user wishes to revoke their installation the client with have to provide the correct type in order for the revocation to work. Because it is based on a signature the process is slightly fragile and must be exactly correct. We don't want to push that fragility on the client but the client should have the option to change over time.

[insipx]

I think there's room here to better define how we will map xmtp installation keys to the ethr:did registry, while maintaining backwards-compatibility with client libraries.

Instead of accepting a generic [u8; 32] parameter as a name, as suggested by jac, we could have an enum with a set of different keytypes for the client,

#[non_exhaustive]
pub enum XMTPKeyType {
    Installation,
    Push,
    ...
}

More key types can be added over time and client breakage because of server changes is kept to a minimum via shared type libraries

Additionally, we need to add a mechanism for filtering attribute key types to ensure the keys resulting from a DID resolution are the installation keys for XMTP, and not some other use (ex public ssh ed25519 key). To start, I think we can just commit all our key attribute names with an extra xmtp identifier, to make its use obvious:

did/pub/xmtp/ed25519/sigAuth/hex and did/pub/xmtp/x25519/enc/hex

(where ed25519 are just signature keys, and x25519 are encryption keys)

we could also go a step further and do something like did/pub/xmtp/ed25519/inst/hex, using inst for installation

[jac18281828]

#[non_exhaustive]
pub enum XMTPKeyType {
    Installation,
    Push,
    ...
}

I agree this makes sense for this set of operations. If we wish to support some type of 'arbitrary' profile information we can expose that through a different api.