initialize-mailbox.rst (1936B)
1 .. ts:op:: initializeMailbox 2 3 Create a new mailbox at a mailbox service: wallet-core generates 4 fresh signing and encryption keys, registers the mailbox with the 5 service and stores the resulting configuration locally. 6 7 **Request:** 8 9 The request arguments are a `MailboxBaseUrl` object. 10 11 **Response:** 12 13 On success, the result is the newly created `MailboxConfiguration` 14 object. 15 16 **Side effects:** 17 18 Registers a new mailbox at the mailbox service over the network 19 and stores the configuration and keys locally. 20 21 **Expected errors:** 22 23 The caller can handle the following errors inline: 24 ``WALLET_MAILBOX_UNAVAILABLE``, ``GENERIC_FORBIDDEN``, 25 ``WALLET_RECEIVED_MALFORMED_RESPONSE``. 26 27 **Details:** 28 29 A fresh key pair is generated on every call, so each call creates 30 a new mailbox identity at the service. The registration is made 31 with an expiration one year in the future. If the mailbox service 32 requires payment for the registration, the operation still 33 succeeds and the returned configuration has ``payUri`` set, which 34 the client can use to pay for the registration. 35 ``GENERIC_FORBIDDEN`` indicates that the mailbox service refused 36 the registration. ``WALLET_RECEIVED_MALFORMED_RESPONSE`` indicates 37 that the service asked for payment but did not say how to pay. 38 39 .. ts:def:: MailboxConfiguration 40 41 interface MailboxConfiguration { 42 // Base URL of the mailbox service. 43 mailboxBaseUrl: string; 44 45 // Private EdDSA signing key of the mailbox. 46 privateKey: EddsaPrivateKeyString; 47 48 // Private HPKE encryption key of the mailbox. 49 privateEncryptionKey: string; 50 51 // Expiration of the current mailbox registration. 52 expiration: Timestamp; 53 54 // Mailbox address (hash of the public signing key). 55 hAddress: string; 56 57 // Set when the mailbox service requires payment to complete 58 // the registration. 59 payUri?: TalerUri; 60 }