Class KeyPackageManager

constructor

• new KeyPackageManager(options: KeyPackageManagerOptions): KeyPackageManager

  Parameters

  • options: KeyPackageManagerOptions

  Returns KeyPackageManager

ReadonlyclientId

add

• add(
      keyPackage: Pick<LocalKeyPackage, "privatePackage" | "publicPackage"> & Partial<
          Pick<LocalKeyPackage, "identifier" | "published">,
      >,
  ): Promise<string>

  Adds a LocalKeyPackage to the store.

  Parameters

  • keyPackage: Pick<LocalKeyPackage, "privatePackage" | "publicPackage"> & Partial<
        Pick<LocalKeyPackage, "identifier" | "published">,
    >

    Must include publicPackage and privatePackage. Optionally include identifier to persist the addressable slot identifier.

  Returns Promise<string>

  The storage key (hex ref string)

clear

• clear(): Promise<void>

  Clears all entries (local and tracked) from the store.

  Returns Promise<void>

count

• count(): Promise<number>

  Returns the number of locally stored key packages.

  Returns Promise<number>

create

• create(options: CreateKeyPackageOptions): Promise<ListedKeyPackage>

  Creates a new key package, stores the private material locally, signs and publishes a kind 30443 addressable event to the specified relays, and records the event.

  The d (slot identifier) is resolved in order:

  1. options.d (explicit)
  2. this.clientId (manager default)
  3. Throws MissingSlotIdentifierError

  Parameters

  • options: CreateKeyPackageOptions

    Creation options, including required relay URLs

  Returns Promise<ListedKeyPackage>

  The stored key package (without private material)

  Throws

  if relays is empty

  Throws

  if no slot identifier can be determined

get

• get(ref: string | Uint8Array<ArrayBufferLike>): Promise<StoredKeyPackage | null>

  Retrieves the full key package from the store.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

  Returns Promise<StoredKeyPackage | null>

getPrivateKey

• getPrivateKey(
      ref: string | Uint8Array<ArrayBufferLike>,
  ): Promise<PrivateKeyPackage | null>

  Retrieves the private key material for a key package. Used internally by MarmotClient when processing Welcome messages.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

    The key package reference

  Returns Promise<PrivateKeyPackage | null>

  The private key package, or null if not found

has

• has(ref: string | Uint8Array<ArrayBufferLike>): Promise<boolean>

  Checks whether a key package exists in local private key storage.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

  Returns Promise<boolean>

list

• list(): Promise<ListedKeyPackage[]>

  Lists all locally stored key packages, each enriched with their published Nostr events.

  Returns Promise<ListedKeyPackage[]>

markUsed

• markUsed(ref: string | Uint8Array<ArrayBufferLike>): Promise<void>

  Marks a key package as used by setting used = true on the stored entry.

  Does nothing if no entry is found for the given ref.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

    The key package reference

  Returns Promise<void>

purge

• purge(
      refs:
          | string
          | Uint8Array<ArrayBufferLike>
          | (string | Uint8Array<ArrayBufferLike>)[],
  ): Promise<void>

  Completely purges one or more key packages: publishes a NIP-09 deletion for all known relay event IDs, removes local private key material, and clears the publish records.

  Parameters

  • refs: string | Uint8Array<ArrayBufferLike> | (string | Uint8Array<ArrayBufferLike>)[]

    One or more key package references (hex string or Uint8Array)

  Returns Promise<void>

remove

• remove(ref: string | Uint8Array<ArrayBufferLike>): Promise<void>

  Removes a key package from local private key storage only.

  Does not publish a relay deletion and does not touch publish records. Use when the key package was never published, or when relay cleanup has already been handled separately.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

    The key package reference to remove

  Returns Promise<void>

rotate

• rotate(
      ref: string | Uint8Array<ArrayBufferLike>,
      options?: RotateKeyPackageOptions,
  ): Promise<ListedKeyPackage>

  Rotates a key package: publishes a new kind 30443 event (reusing the same d slot so relays replace the old event automatically), then removes the old private key material.

  For legacy kind-443 published events on the entry, a NIP-09 deletion is sent before publishing the replacement. Kind-30443 published events do not need explicit deletion — the new event supersedes them on relays.

  Parameters

  • ref: string | Uint8Array<ArrayBufferLike>

    The key package reference of the key package to rotate

  • Optionaloptions: RotateKeyPackageOptions

    Options for the new key package

  Returns Promise<ListedKeyPackage>

  The new stored key package (without private material)

  Throws

  if the key package ref is not found in the local store

  Throws

  if no relay URLs can be determined for the new key package

track

• track(event: NostrEvent): Promise<boolean>

  Observes a Nostr event and, if it is a kind 443 or kind 30443 key package event with a valid i tag (MIP-00 keyPackageRef), records it in the store.

  Parameters

  • event: NostrEvent

    Any Nostr event; non-key-package events are silently ignored

  Returns Promise<boolean>

  true if the event was recorded, false if ignored

watchKeyPackages

• watchKeyPackages(): AsyncGenerator<ListedKeyPackage[]>

  Watches for any change to key packages or their published events.

  Yields the current snapshot on subscription, then re-yields on every subsequent change.

  Returns AsyncGenerator<ListedKeyPackage[]>