Module nip17_keys 

NIP-17 ephemeral wrap-key vault.

NIP-59 gift-wraps each DM with a fresh ephemeral keypair whose secret is normally discarded immediately after signing. We retain it so the user can later publish an author-signed NIP-09 deletion against the kind-1059 wrap event — actually removing the message from inbox relays rather than relying on “throw the keys away and hope”.

Encryption-at-rest is handled by Vector’s per-account database envelope: ChaCha20 if the account has a password, plaintext if it doesn’t (passwordless accounts are unencrypted by design).

Structs

ResendPayload

Everything needed to republish a failed DM’s recipient wrap verbatim.

StoredWrapKey

Enums

WrapRole

Role of a stored wrap key. Recorded so the deletion path can label audit logs and so a future feature could selectively retain/purge by role (e.g. “drop self-send keys after N days”).

Functions

clear_resend_payload

Drop the republishable body once delivery is confirmed (the key row stays for NIP-09 delete). Keyed by rumor id so both the recipient and any retry rows for the message are cleared together.

get_resend_payload_by_pending

Load the republishable recipient wrap for a failed message (its id is the local pending id). None when nothing retained — the caller then falls back to a fresh send. Only rows with a body (still unconfirmed) match.

get_wrap_keys_for_rumor

Fetch every retained wrap key (recipient + self + retry) for a given inner rumor id. Used at delete time to construct one NIP-09 per wrap.

has_wrap_keys_for_rumor

Cheap existence check: do we hold any retained wrap key for this rumor id? Used by the UI to gate the delete-message control so we don’t tease users with a button we can’t actually fulfil.

prune_stale_resend_payloads

Backstop: null retained bodies older than max_age_secs so a pile of never-retried reds can’t grow unbounded. The key row (NIP-09) survives. Returns how many bodies were reaped.

purge_wrap_keys

Drop wrap-key rows after the corresponding NIP-09 deletions have been broadcast. Caller passes the wrap event ids it actually deleted so partial-success scenarios don’t accidentally drop keys still useful for retry.

stash_resend_payload

Attach the republishable body to an existing recipient wrap-key row. Called right after store_wrap_key on the first send attempt.

store_wrap_key

Persist a retained ephemeral wrap secret. Idempotent on wrap_event_id so retries that land the same wrap won’t duplicate.