initializeMailbox

Create a new mailbox at a mailbox service: wallet-core generates fresh signing and encryption keys, registers the mailbox with the service and stores the resulting configuration locally.

Request:

The request arguments are a MailboxBaseUrl object.

Response:

On success, the result is the newly created MailboxConfiguration object.

Side effects:

Registers a new mailbox at the mailbox service over the network and stores the configuration and keys locally.

Expected errors:

The caller can handle the following errors inline: WALLET_MAILBOX_UNAVAILABLE, GENERIC_FORBIDDEN, WALLET_RECEIVED_MALFORMED_RESPONSE.

Details:

A fresh key pair is generated on every call, so each call creates a new mailbox identity at the service. The registration is made with an expiration one year in the future. If the mailbox service requires payment for the registration, the operation still succeeds and the returned configuration has payUri set, which the client can use to pay for the registration. GENERIC_FORBIDDEN indicates that the mailbox service refused the registration. WALLET_RECEIVED_MALFORMED_RESPONSE indicates that the service asked for payment but did not say how to pay.

interface MailboxConfiguration {
  // Base URL of the mailbox service.
  mailboxBaseUrl: string;

  // Private EdDSA signing key of the mailbox.
  privateKey: EddsaPrivateKeyString;

  // Private HPKE encryption key of the mailbox.
  privateEncryptionKey: string;

  // Expiration of the current mailbox registration.
  expiration: Timestamp;

  // Mailbox address (hash of the public signing key).
  hAddress: string;

  // Set when the mailbox service requires payment to complete
  // the registration.
  payUri?: TalerUri;
}