@helia/ipns 10.1.1-b34bc7c7 → 10.2.0

package/src/ipns/republisher.ts

@@ -1,15 +1,24 @@
+import { NotFoundError } from '@libp2p/interface'
 import { Queue, repeatingTask } from '@libp2p/utils'
+import NanoDate from 'timestamp-nano'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import { DEFAULT_REPUBLISH_CONCURRENCY, DEFAULT_REPUBLISH_INTERVAL_MS, DEFAULT_TTL_NS } from '../constants.ts'
+import { RecordObsoleteError } from '../errors.ts'
 import { IPNSEntry } from '../pb/ipns.ts'
+import { Upkeep } from '../pb/metadata.ts'
 import { createIPNSRecord } from '../records.ts'
-import { decodeExtensibleData, shouldRepublish } from '../utils.ts'
-import type { IPNSRecordData } from '../index.ts'
+import { isLocalStoreRouting, routerName } from '../routing/index.ts'
+import { ipnsSelector } from '../selector.ts'
+import { decodeExtensibleData, multihashToIPNSRoutingKey, shouldRepublish } from '../utils.ts'
+import { extractPublicKey, ipnsValidator } from '../validator.ts'
+import { findRoutingRecords } from './resolver.ts'
+import type { IPNSRecordData, RepublishOptions, RepublishResult } from '../index.ts'
 import type { LocalStore } from '../local-store.ts'
-import type { IPNSRouting } from '../routing/index.ts'
+import type { IPNSRouting, IPNSRoutingPutOptions } from '../routing/index.ts'
 import type { Keychain, PrivateKey } from '@helia/interface'
 import type { AbortOptions, ComponentLogger, Logger } from '@libp2p/interface'
 import type { RepeatingTask } from '@libp2p/utils'
+import type { MultihashDigest } from 'multiformats'
 
 export interface IPNSRepublisherComponents {
   logger: ComponentLogger
@@ -79,7 +88,8 @@ export class IPNSRepublisher {
     })
 
     try {
-      const recordsToRepublish: Array<{ routingKey: Uint8Array, record: IPNSEntry }> = []
+      const recordsToReissue: Array<{ routingKey: Uint8Array, record: IPNSEntry }> = []
+      const recordsToRebroadcast: Array<{ routingKey: Uint8Array, record: IPNSEntry }> = []
       let listed = 0
 
       // Find all records using the localStore.list method
@@ -87,23 +97,31 @@ export class IPNSRepublisher {
         listed++
 
         if (metadata == null) {
-          // Skip if no metadata is found from before we started
-          // storing metadata or for records republished without a key
+          // no metadata: an imported record not yet given an upkeep policy, or a
+          // record stored before we tracked metadata
           this.log('no metadata found for record %b, skipping', routingKey)
           continue
         }
 
+        if (metadata.upkeep === Upkeep.none) {
+          // Skip republishing, disabled for this record
+          this.log('republishing is disabled for record %b, skipping', routingKey)
+          continue
+        }
+
         let ipnsRecord: IPNSEntry
 
         try {
           ipnsRecord = IPNSEntry.decode(record)
         } catch (err) {
-          this.log.trace('skipping invalid record %b because could not decode', routingKey)
+          // the record was valid when stored, so a decode failure now means
+          // on-disk corruption or a format change worth surfacing
+          this.log.error('skipping stored record %b, could not decode it - %e', routingKey, err)
           continue
         }
 
         if (ipnsRecord.data == null) {
-          this.log.trace('skipping record %b because data was missing', routingKey)
+          this.log.error('skipping stored record %b, its data is missing', routingKey)
           continue
         }
 
@@ -111,17 +129,40 @@ export class IPNSRepublisher {
 
         try {
           data = decodeExtensibleData(ipnsRecord.data)
-        } catch {
-          this.log.trace('skipping record %b because could not decode data', routingKey)
+        } catch (err) {
+          this.log.error('skipping stored record %b, could not decode its data - %e', routingKey, err)
+          continue
+        }
+
+        let recordExpiry: Date
+
+        try {
+          recordExpiry = NanoDate.fromString(uint8ArrayToString(data.Validity)).toDate()
+        } catch (err) {
+          this.log.error('skipping stored record %b, could not parse its validity - %e', routingKey, err)
           continue
         }
 
         // Only republish records that are within the DHT or record expiry threshold
-        if (!shouldRepublish(created, new Date(uint8ArrayToString(data.Validity)))) {
+        if (!shouldRepublish(created, recordExpiry)) {
           this.log.trace('skipping record %b within republish threshold', routingKey)
           continue
         }
 
+        if (metadata.upkeep === Upkeep.rebroadcast) {
+          // only re-broadcast records that are still valid: an expired record
+          // cannot be revived without re-signing, which the rebroadcast policy
+          // has no key for
+          if (recordExpiry.getTime() <= Date.now()) {
+            this.log.trace('skipping expired record %b for rebroadcast', routingKey)
+            continue
+          }
+
+          recordsToRebroadcast.push({ routingKey, record: ipnsRecord })
+          continue
+        }
+
+        // Upkeep.reissue: re-sign the record with a new validity
         const sequenceNumber = data.Sequence + 1n
         const ttlNs = data.TTL ?? DEFAULT_TTL_NS
         let privKey: PrivateKey
@@ -138,36 +179,151 @@ export class IPNSRepublisher {
             ...options,
             ttlNs
           })
-          recordsToRepublish.push({
+
+          recordsToReissue.push({
             routingKey,
             record: updatedRecord
           })
         } catch (err: any) {
-          this.log.error('error creating updated IPNS record for %s - %e', routingKey, err)
+          this.log.error('error creating updated IPNS record for %b - %e', routingKey, err)
           continue
         }
       }
 
-      this.log(`found ${recordsToRepublish.length}/${listed} records to republish`)
+      this.log(`reissuing ${recordsToReissue.length} and rebroadcasting ${recordsToRebroadcast.length} of ${listed} records`)
+
+      // reissue: re-publish the re-signed record as-is. the jobs run
+      // fire-and-forget, so catch any failure (including a local-store write
+      // that #publishToRouters surfaces) rather than leaving an unhandled rejection
+      for (const { routingKey, record } of recordsToReissue) {
+        queue.add(async () => this.#publishToRouters(routingKey, IPNSEntry.encode(record), options), options)
+          .catch((err: any) => { this.log.error('failed to reissue record %b - %e', routingKey, err) })
+      }
 
-      // Republish each record
-      for (const { routingKey, record } of recordsToRepublish) {
-        // Add job to queue to republish the record to all routers
+      // rebroadcast: resolve the latest record from the network and re-broadcast
+      // whichever of the local and network records is most suitable, so we adopt
+      // a newer record rather than pushing a stale local copy
+      for (const { routingKey, record } of recordsToRebroadcast) {
         queue.add(async () => {
-          try {
-            const marshaledRecord = IPNSEntry.encode(record)
-            await Promise.all(
-              this.routers.map(r => r.put(routingKey, marshaledRecord, options))
-            )
-          } catch (err: any) {
-            this.log.error('error republishing record - %e', err)
-          }
+          const { records } = await findRoutingRecords(this.routers, routingKey, this.keychain, this.log, options)
+          const candidates = [record, ...records]
+          const best = candidates[ipnsSelector(routingKey, candidates)]
+
+          await this.#publishToRouters(routingKey, IPNSEntry.encode(best), { ...options, overwrite: true })
         }, options)
+          .catch((err: any) => { this.log.error('failed to rebroadcast record %b - %e', routingKey, err) })
       }
     } catch (err: any) {
       this.log.error('error during republish - %e', err)
     }
+  }
+
+  /**
+   * Persist the record to the local store first, throwing if that fails: it
+   * holds the record and its upkeep policy, so that failure must surface rather
+   * than be swallowed. Then broadcast to the network routers best-effort,
+   * logging any that fail.
+   */
+  async #publishToRouters (routingKey: Uint8Array, marshaledRecord: Uint8Array, putOptions: IPNSRoutingPutOptions): Promise<void> {
+    const localStoreRouter = this.routers.find(isLocalStoreRouting)
+
+    if (localStoreRouter != null) {
+      await localStoreRouter.put(routingKey, marshaledRecord, putOptions)
+      this.log('published record %b to %s', routingKey, routerName(localStoreRouter))
+    }
+
+    await Promise.all(
+      this.routers
+        .filter(router => router !== localStoreRouter)
+        .map(async (router) => {
+          try {
+            await router.put(routingKey, marshaledRecord, putOptions)
+            this.log('published record %b to %s', routingKey, routerName(router))
+          } catch (err) {
+            this.log.error('failed to publish record %b to %s - %e', routingKey, routerName(router), err)
+          }
+        })
+    )
+  }
+
+  async republish (key: MultihashDigest, options: RepublishOptions = {}): Promise<RepublishResult> {
+    const routingKey = multihashToIPNSRoutingKey(key)
+
+    // read the record we hold for this key directly, it was validated when it
+    // was imported or published, and reading it through resolve() would recurse
+    // and rewrite the local store
+    let record: Uint8Array<ArrayBuffer>
+
+    try {
+      ({ record } = await this.localStore.get(routingKey, options))
+    } catch (err: any) {
+      if (err.name !== 'NotFoundError') {
+        throw err
+      }
+
+      throw new NotFoundError('No local record found to republish - import it first')
+    }
+
+    // re-validate: a record that was valid when stored can have expired since
+    const localRecord = await ipnsValidator(routingKey, record, this.keychain, options)
+
+    // unless we are told not to look, check whether the routing already has a
+    // more suitable record; if so, back off
+    if (options.skipResolution !== true) {
+      const { records } = await findRoutingRecords(this.routers, routingKey, this.keychain, this.log, options)
+      const candidates = [localRecord, ...records]
+      const best = ipnsSelector(routingKey, candidates)
+
+      if (best !== 0) {
+        throw new RecordObsoleteError('A newer record is already published for this key', candidates[best])
+      }
+    }
+
+    const metadata = {
+      upkeep: Upkeep[options.upkeep ?? 'rebroadcast']
+    }
+
+    // a publish that fails on every router does not throw; use onProgress to see
+    // which routers worked and watch the logs
+    await this.#publishToRouters(routingKey, record, {
+      ...options,
+      overwrite: true,
+      metadata
+    })
+
+    return {
+      record: localRecord,
+      publicKey: await extractPublicKey(routingKey, localRecord, this.keychain, options)
+    }
+  }
+
+  async import (key: MultihashDigest, record: IPNSEntry | Uint8Array, options?: AbortOptions): Promise<void> {
+    const routingKey = multihashToIPNSRoutingKey(key)
+    const entry = record instanceof Uint8Array ? IPNSEntry.decode(record) : record
+    const marshaledRecord = IPNSEntry.encode(entry)
+
+    // validate the record, throws if it is invalid (bad signature, expired, etc)
+    await ipnsValidator(routingKey, marshaledRecord, this.keychain, options)
+
+    // do not downgrade a record we already hold
+    try {
+      const { record: existingBytes } = await this.localStore.get(routingKey, options)
+      const existing = IPNSEntry.decode(existingBytes)
+
+      // if the record we already have wins the selector, the incoming one is obsolete
+      if (ipnsSelector(routingKey, [entry, existing]) !== 0) {
+        throw new RecordObsoleteError('A newer record is already stored for this key', existing)
+      }
+    } catch (err: any) {
+      // holding no record for this key is the normal case, everything else
+      // (the RecordObsoleteError above included) is a real failure
+      if (err.name !== 'NotFoundError') {
+        throw err
+      }
+    }
 
-    await queue.onIdle(options) // Wait for all jobs to complete
+    // store the record locally only, without metadata, so it is served but not
+    // automatically republished until republish() gives it an upkeep policy
+    await this.localStore.put(routingKey, marshaledRecord, options)
   }
 }

package/src/ipns/resolver.ts

@@ -2,6 +2,7 @@ import { base36 } from 'multiformats/bases/base36'
 import { DEFAULT_TTL_NS } from '../constants.ts'
 import { InvalidValueError, RecordNotFoundError, RecordsFailedValidationError } from '../errors.ts'
 import { IPNSEntry } from '../pb/ipns.ts'
+import { isLocalStoreRouting, routerName } from '../routing/index.ts'
 import { ipnsSelector } from '../selector.ts'
 import { multihashToIPNSRoutingKey, normalizeKey, IPNS_STRING_PREFIX, ipnsRecordValueToString, decodeExtensibleData } from '../utils.ts'
 import { ipnsValidator } from '../validator.ts'
@@ -9,7 +10,7 @@ import type { IPNSResolveOptions, IPNSResolveResult } from '../index.ts'
 import type { LocalStore } from '../local-store.ts'
 import type { IPNSRouting } from '../routing/index.ts'
 import type { Routing, Keychain } from '@helia/interface'
-import type { ComponentLogger, Logger } from '@libp2p/interface'
+import type { AbortOptions, ComponentLogger, Logger } from '@libp2p/interface'
 import type { Datastore } from 'interface-datastore'
 import type { MultihashDigest } from 'multiformats/hashes/interface'
 
@@ -135,42 +136,15 @@ export class IPNSResolver {
 
     this.log('did not have record locally')
 
-    let foundInvalid = 0
-    const errors: Error[] = []
-
-    await Promise.all(
-      this.routers.map(async (router) => {
-        let marshaledIPNSRecord: Uint8Array
-
-        try {
-          marshaledIPNSRecord = await router.get(routingKey, {
-            ...options,
-            validate: false
-          })
-        } catch (err: any) {
-          this.log.error('error finding IPNS record using router %s - %e', router.toString(), err)
-          errors.push(err)
-
-          return
-        }
-
-        try {
-          let record: IPNSEntry
-
-          if (options.validate === false) {
-            record = IPNSEntry.decode(marshaledIPNSRecord)
-          } else {
-            record = await ipnsValidator(routingKey, marshaledIPNSRecord, this.keychain, options)
-          }
-
-          records.push(record)
-        } catch (err) {
-          // we found a record, but the validator rejected it
-          foundInvalid++
-          this.log.error('error validating IPNS record from router %s - %e', router.toString(), err)
-        }
-      })
+    const { records: networkRecords, foundInvalid } = await findRoutingRecords(
+      this.routers,
+      routingKey,
+      this.keychain,
+      this.log,
+      options,
+      options.validate !== false
     )
+    records.push(...networkRecords)
 
     if (records.length === 0) {
       if (foundInvalid > 0) {
@@ -187,3 +161,47 @@ export class IPNSResolver {
     return record
   }
 }
+
+/**
+ * Query the network routers for the records stored under a routing key, plus a
+ * count of records that were fetched but failed validation/decoding. Does not
+ * touch the local store; the caller selects the record it wants with
+ * `ipnsSelector`. Records are validated unless `validate` is false, in which
+ * case they are returned decoded without validation.
+ */
+export async function findRoutingRecords (routers: IPNSRouting[], routingKey: Uint8Array, keychain: Keychain, log: Logger, options: AbortOptions = {}, validate = true): Promise<{ records: IPNSEntry[], foundInvalid: number }> {
+  const records: IPNSEntry[] = []
+  let foundInvalid = 0
+
+  await Promise.all(
+    routers.map(async (router) => {
+      // the local store is not the network
+      if (isLocalStoreRouting(router)) {
+        return
+      }
+
+      let marshaledRecord: Uint8Array
+
+      try {
+        marshaledRecord = await router.get(routingKey, { ...options, validate: false })
+      } catch (err: any) {
+        log.error('error finding IPNS record using router %s - %e', routerName(router), err)
+        return
+      }
+
+      try {
+        // when the caller opts out of validation, return the record as decoded
+        const record = validate
+          ? await ipnsValidator(routingKey, marshaledRecord, keychain, options)
+          : IPNSEntry.decode(marshaledRecord)
+
+        records.push(record)
+      } catch (err) {
+        foundInvalid++
+        log.error('error reading IPNS record from router %s - %e', routerName(router), err)
+      }
+    })
+  )
+
+  return { records, foundInvalid }
+}

package/src/ipns.ts

@@ -7,9 +7,9 @@ import { localStore } from './local-store.ts'
 import { heliaIPNSRouting } from './routing/helia.ts'
 import { localStoreIPNSRouting } from './routing/local-store.ts'
 import { ipnsSelector } from './selector.ts'
-import { normalizeKey, normalizeValue } from './utils.ts'
+import { normalizeKey, normalizeKeyName, normalizeValue } from './utils.ts'
 import { ipnsValidator } from './validator.ts'
-import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, PublishOptions, IPNSResolveOptions, IPNSResolveResult } from './index.ts'
+import type { IPNSComponents, IPNS as IPNSInterface, IPNSOptions, IPNSPublishResult, PublishOptions, RepublishOptions, RepublishResult, IPNSResolveOptions, IPNSResolveResult, UnpublishOptions } from './index.ts'
 import type { LocalStore } from './local-store.ts'
 import type { IPNSRouting } from './routing/index.ts'
 import type { PublicKey } from '@helia/interface'
@@ -42,12 +42,12 @@ export class IPNS implements IPNSInterface, Startable {
       routers: this.routers,
       localStore: this.localStore
     })
-    this.republisher = new IPNSRepublisher(components, {
+    this.resolver = new IPNSResolver(components, {
       ...init,
       routers: this.routers,
       localStore: this.localStore
     })
-    this.resolver = new IPNSResolver(components, {
+    this.republisher = new IPNSRepublisher(components, {
       ...init,
       routers: this.routers,
       localStore: this.localStore
@@ -103,15 +103,29 @@ export class IPNS implements IPNSInterface, Startable {
     return this.publisher.publish(keyName, normalizeValue(value), options)
   }
 
-  async * resolve (key: PublicKey | CID | MultihashDigest | string, options: IPNSResolveOptions = {}): AsyncGenerator<IPNSResolveResult> {
+  async * resolve (key: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options: IPNSResolveOptions = {}): AsyncGenerator<IPNSResolveResult> {
     const { digest } = normalizeKey(key)
 
     yield * this.resolver.resolve(digest, options)
   }
 
-  async unpublish (keyName: string, options?: AbortOptions): Promise<void> {
+  async unpublish (keyName: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options?: UnpublishOptions): Promise<void> {
+    keyName = normalizeKeyName(keyName)
+
     return this.publisher.unpublish(keyName, options)
   }
+
+  async republish (keyName: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options: RepublishOptions = {}): Promise<RepublishResult> {
+    const { digest } = normalizeKey(keyName)
+
+    return this.republisher.republish(digest, options)
+  }
+
+  async import (key: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, record: IPNSEntry | Uint8Array, options?: AbortOptions): Promise<void> {
+    const { digest } = normalizeKey(key)
+
+    return this.republisher.import(digest, record, options)
+  }
 }
 
 function isLibp2p (obj?: any): obj is Libp2p {

package/src/local-store.ts

@@ -3,7 +3,7 @@ import { CustomProgressEvent } from 'progress-events'
 import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { withArrayBuffer } from 'uint8arrays/with-array-buffer'
-import { IPNSPublishMetadata } from './pb/metadata.ts'
+import { IPNSPublishMetadata, Upkeep } from './pb/metadata.ts'
 import { dhtRoutingKey, DHT_RECORD_PREFIX, ipnsMetadataKey } from './utils.ts'
 import type { DatastoreProgressEvents, IPNSRoutingGetOptions, IPNSRoutingPutOptions } from './routing/index.ts'
 import type { AbortOptions, Logger } from '@libp2p/interface'
@@ -37,12 +37,67 @@ export interface LocalStore {
   get(routingKey: Uint8Array, options?: IPNSRoutingGetOptions): Promise<GetResult>
   has(routingKey: Uint8Array, options?: AbortOptions): Promise<boolean>
   delete(routingKey: Uint8Array, options?: AbortOptions): Promise<void>
+  /**
+   * Delete only the IPNS metadata for a record, leaving the record itself in
+   * place so it is still served but no longer automatically republished
+   */
+  deleteMetadata(routingKey: Uint8Array, options?: AbortOptions): Promise<void>
   /**
    * List all IPNS records in the datastore
    */
   list(options?: ListOptions): AsyncIterable<ListResult>
 }
 
+/**
+ * Merge a (possibly partial) metadata update into any metadata already stored
+ * for the routing key, so fields that are not being changed are preserved.
+ *
+ * Throws if the existing metadata cannot be read (rather than silently
+ * overwriting it and dropping keyName/lifetime), or if the resulting policy
+ * needs a keyName it does not have.
+ */
+async function mergeMetadata (datastore: Datastore, routingKey: Uint8Array, incoming: Partial<IPNSPublishMetadata>, options?: AbortOptions): Promise<Partial<IPNSPublishMetadata>> {
+  let metadata = incoming
+
+  try {
+    // merge into any existing metadata so a partial update (e.g. republish
+    // setting only `upkeep`) preserves keyName/lifetime instead of wiping them
+    const existing = IPNSPublishMetadata.decode(await datastore.get(ipnsMetadataKey(routingKey), options))
+    metadata = { ...existing, ...incoming }
+  } catch (err: any) {
+    if (err.name !== 'NotFoundError') {
+      // the stored metadata is unreadable, surface it rather than silently
+      // overwriting and dropping keyName/lifetime
+      throw err
+    }
+  }
+
+  // the reissue upkeep policy re-signs the record, which needs the key, so
+  // refuse to persist that policy without a keyName
+  if (metadata.upkeep === Upkeep.reissue && (metadata.keyName == null || metadata.keyName === '')) {
+    throw new Error('a keyName is required to reissue a record')
+  }
+
+  return metadata
+}
+
+/**
+ * Read the stored upkeep metadata for a routing key, if any. A record with no
+ * metadata is normal (imported, or unpublished), so that is not an error; only
+ * an actual decode/corruption failure is logged.
+ */
+async function readMetadata (datastore: Datastore, routingKey: Uint8Array, log: Logger, options?: AbortOptions): Promise<IPNSPublishMetadata | undefined> {
+  try {
+    return IPNSPublishMetadata.decode(await datastore.get(ipnsMetadataKey(routingKey), options))
+  } catch (err: any) {
+    if (err.name !== 'NotFoundError') {
+      log.error('error deserializing metadata for %b - %e', routingKey, err)
+    }
+
+    return undefined
+  }
+}
+
 /**
  * Read/write IPNS records to the datastore as DHT records.
  *
@@ -55,18 +110,20 @@ export function localStore (datastore: Datastore, log: Logger): LocalStore {
       try {
         const key = dhtRoutingKey(routingKey)
 
-        // don't overwrite existing, identical records as this will affect the
-        // TTL
-        try {
-          const existingBuf = await datastore.get(key)
-          const existingRecord = Record.deserialize(existingBuf)
+        if (options.overwrite !== true) {
+          // don't overwrite existing, identical records as this will affect the
+          // TTL
+          try {
+            const existingBuf = await datastore.get(key)
+            const existingRecord = Record.deserialize(existingBuf)
 
-          if (uint8ArrayEquals(existingRecord.value, marshalledRecord)) {
-            return
-          }
-        } catch (err: any) {
-          if (err.name !== 'NotFoundError') {
-            throw err
+            if (uint8ArrayEquals(existingRecord.value, marshalledRecord)) {
+              return
+            }
+          } catch (err: any) {
+            if (err.name !== 'NotFoundError') {
+              throw err
+            }
           }
         }
 
@@ -78,8 +135,10 @@ export function localStore (datastore: Datastore, log: Logger): LocalStore {
         batch.put(key, record.serialize())
 
         if (options.metadata != null) {
-          // derive the datastore key for the IPNS metadata from the same routing key
-          batch.put(ipnsMetadataKey(routingKey), IPNSPublishMetadata.encode(options.metadata))
+          // merge into any existing metadata (preserving keyName/lifetime on a
+          // partial update) and validate the result before writing it
+          const metadata = await mergeMetadata(datastore, routingKey, options.metadata, options)
+          batch.put(ipnsMetadataKey(routingKey), IPNSPublishMetadata.encode(metadata))
         }
         await batch.commit(options)
       } catch (err: any) {
@@ -117,6 +176,9 @@ export function localStore (datastore: Datastore, log: Logger): LocalStore {
       batch.delete(ipnsMetadataKey(routingKey))
       await batch.commit(options)
     },
+    async deleteMetadata (routingKey, options): Promise<void> {
+      await datastore.delete(ipnsMetadataKey(routingKey), options)
+    },
     async * list (options: ListOptions = {}): AsyncIterable<ListResult> {
       try {
         options.onProgress?.(new CustomProgressEvent('ipns:routing:datastore:list'))
@@ -134,14 +196,7 @@ export function localStore (datastore: Datastore, log: Logger): LocalStore {
             const routingKeyBase32 = keyString.substring(DHT_RECORD_PREFIX.length)
             const routingKey = uint8ArrayFromString(routingKeyBase32, 'base32')
 
-            const metadataKey = ipnsMetadataKey(routingKey)
-            let metadata: IPNSPublishMetadata | undefined
-            try {
-              const metadataBuf = await datastore.get(metadataKey, options)
-              metadata = IPNSPublishMetadata.decode(metadataBuf)
-            } catch (err: any) {
-              log.error('Error deserializing metadata for %s - %e', routingKeyBase32, err)
-            }
+            const metadata = await readMetadata(datastore, routingKey, log, options)
 
             yield {
               routingKey,

package/src/pb/metadata.proto

@@ -1,9 +1,19 @@
 syntax = "proto3";
 
+enum Upkeep {
+  reissue = 0; // Re-sign the record with a new validity (key must be in keychain)
+  rebroadcast = 1; // Re-publish the record as is (while it is still valid)
+  none = 2; // Disables automated republishing for the record
+}
+
 message IPNSPublishMetadata {
   // The name of the key that was used to publish the record
   string keyName = 1;
 
   // Lifetime is the duration of the signature validity in milliseconds
+  // Relevant for Upkeep.reissue
   uint32 lifetime = 2;
+
+  // Republishing policy
+  Upkeep upkeep = 3;
 }