NIP-41

Key migration

draft optional author:pablof7z author:fiatjaf author:nvk

This NIP introduces a simple, best-effort, not guaranteed, way in which a user can notify their followers that they have migrated to a new public key in case the current one is compromised.

Basic concepts

kind:1776 whitelists a pubkey.
kind:1777 migrates to a previously whitelisted pubkey.
kind:1776 and kind:1777 MUST be opentimestamped NIP-03.
When a migration event is published, a 60-day period starts in which a user can publish a competing migration event pointing to an earlier kind:1776 event. After this period, clients SHOULD automatically update the user's follow list to the new pubkey.
Relays SHOULD NOT delete kind:1040 nor kind:1776 events from their database upon receiving a kind:5 event.

Flow

Whitelisting a pubkey

The user's active pubkey (e.g. pubkey A) signs an event kind:1776 whitelisting a pubkey that can be used to migrate an identity to.

This should be done ahead of time, perhaps after a user has used Nostr enough for a few days. Clients can choose to prompt the user to "save a recovery kit" or different UXs when they see the user doesn't currently have a kind:1776 published.

The implementation can be done directly on regular clients or microapps to handle this type of thing could be implemented as well.

{
    "pubkey": "pubkey-A",
    "kind": 1776,
    "content": "",
    "tags": [
        [ "p", "pubkey-B" ],
        [ "alt", "pubkey whitelisting event" ]
    ]
}

.content SHOULD be ignored. Users might choose to use it to leave a base64 symmetrically-encrypted message of where they left the new key or anything else.
The event MUST have a single p tag listing the whitelisted pubkey.

Multiple kind:1776 events can exist. All kind:1776 MUST be opentimestamped following NIP-3.

Relays SHOULD NOT delete kind:1040 nor kind:1776 events upon receiving a kind:5 event.

Migrating to a pubkey

When the user needs to change keys they sign an event kind:1777 with the new key and creates a NIP-03 attestation.

{
    "pubkey": "pubkey-B",
    "kind": 1777,
    "content": "I rolled my key using libbitcoin; moving to a new one just in case",
    "tags": [
        [ "p", "pubkey-A" ],
        [ "e", "<kind:1776-event-id>" ],
        [ "proof", "<kind:1040-event-id>" ],
        [ "alt", "pubkey migration event" ],
        [ "relays", "relay1", "relay2" ]
    ]
}

p tag MUST list the previous pubkey
e tag MUST list the kind:1776 event that whitelisted the new pubkey.
proof tag MUST list the kind:1040 event that provides the Opentimestamp data of the kind:1776 event.
relays tag SHOULD list relays where both kind:1776 and kind:1040 events can be found.
.content SHOULD be ignored; users can optionally write a message explaining the migration.

Following the new pubkey

Upon seeing this event, the client MAY choose to display a warning to the user that the identity is migrating to a new key. The client should not take any automated action at this point since the migration could be an attack, but the user could communicate out of band with the user to confirm the migration.

After 60 days of seeing the kind:1777 event, the client SHOULD automatically update the user's follow list to the new pubkey after some verifications: When users who follow the old pubkey see a kind:1777 event they SHOULD:

check kind:1776 and kind:1777 event signatures
check kind:1777's pubkey matches kind:1776's p tag
check kind:1777 is more than 60 days old
check that no competing 1777 event exists pointing to an event with an older valid OTS proof

After validating all these checks clients SHOULD replace the old pubkey in the user's follow list with the new one.

Notes

Rational behind the 60 days delay

This gives enough time for a user to notice a migration request published by an attacker and gives the user enough time to publish a competing migration request pointing to an earlier kind:1776 whitelisting event.

Preventing unpublished evil `kind:1777` attack

Clients should keep track of when a kind:1777 event should take into effect, counting at least 60 days from the time of seeing the event and not trusting the event timestamp. This is to prevent an attacker creating an evil kind:1776, its attestation, and a kind:1777 event with its attestation and not publishing them until the 60 days of the attestation have elapsed.

Preventing poorly-distributed evil `kind:1777` attack

Additionally, clients SHOULD broadcast the kind:1777 events to the relays it normally writes to. This is to prevent an attacker from creating a short-lived NIP-65 relay list where only a subset of users will see an evil kind:1777 event but not widespread enough for the real owner to notice it.

Future Work

Key migration can be done in multiple ways. This is an initial implementation that can work. This mechanism should be extended with other, alternative mechanisms, that can leverage different flows/tradeoffs (e.g. social recovery).

5.1 KiB Raw Permalink Blame History