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 local storage. Delegates to KeyPackageStore.add.

  Parameters

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

  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.identifier (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

ensurePublished

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

  Ensures this client has at least one unused, current KeyPackage published, so peers can always invite it. A no-op (returning the existing unused current KeyPackage) when one already exists; otherwise creates and publishes a fresh one to options.relays via create. Idempotent — safe to call on every startup.

  Stored entries flagged nonCurrent (D-09) — for example a KeyPackage published by a pre-v2 release that lacks a valid 0x8009 proof — are skipped and left stored as-is; nothing is deleted and no relay deletion event is published. Their kind-30443 events therefore stay discoverable on relays, and a peer's invite that picks one will fail, until purge publishes a NIP-09 deletion for them — call it explicitly when migrating.

  Parameters

  • options: CreateKeyPackageOptions

  Returns Promise<ListedKeyPackage>

  The existing unused current KeyPackage, or the freshly created one.

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. Entries lacking a valid current account identity proof (0x8009) carry nonCurrent: true (D-09) — see ensurePublished.

  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.

  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

selectForWelcome

• selectForWelcome(welcome: Welcome): Promise<WelcomeKeyPackageCandidate[]>

  Selects the locally-held key packages that could receive a given Welcome, ordered with the RFC 9420 KeyPackageRef matches first.

  Filters to packages whose ciphersuite matches the Welcome and for which local private material is held, computes whether each package's ref matches one of the Welcome's encrypted secrets, and returns the matching packages before the non-matching ones so GroupsManager.joinFromWelcome tries the most likely candidate first. This is the TypeScript analog of the private key-bundle lookup the darkmatter engine performs inside do_join_welcome.

  Parameters

  • welcome: Welcome

    The decoded MLS Welcome message.

  Returns Promise<WelcomeKeyPackageCandidate[]>

  Candidate key packages in priority order (may be empty).

track

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

  Observes a Nostr event and, if it is a kind 30443 key package event that passes the trust boundary (SEC-01/WIRE-01/WIRE-02), records it in the store. Non-key-package events are silently ignored. Events that fail the boundary — invalid signature, non-singleton/invalid d/i/ mls_protocol_version, an over-long or not-current KeyPackage Lifetime, an undecodable body, or an i tag that does not match the recomputed ref — are rejected: a rejected event is emitted with a typed RejectReason (except for the last two, which the underlying KeyPackageStore.addPublished chokepoint throws on and this method converts to a false return without an emit).

  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 or rejected

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[]>