@helia/ipns 10.1.1 → 10.2.0

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/ipns.ts

@@ -139,7 +139,7 @@ export namespace IPNSEntry {
         }
 
         return obj
-      }, function * (reader, prefix, length, opts = {}) {
+      }, function * (reader, length, prefix, opts = {}) {
         const end = length == null ? reader.len : reader.pos + length
 
         if (prefix !== '.') {

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;
 }

package/src/pb/metadata.ts

@@ -1,10 +1,29 @@
-import { decodeMessage, encodeMessage, message, streamMessage } from 'protons-runtime'
+import { decodeMessage, encodeMessage, enumeration, message, streamMessage } from 'protons-runtime'
 import type { Codec, DecodeOptions } from 'protons-runtime'
 import type { Uint8ArrayList } from 'uint8arraylist'
 
+export enum Upkeep {
+  reissue = 'reissue',
+  rebroadcast = 'rebroadcast',
+  none = 'none'
+}
+
+enum __UpkeepValues {
+  reissue = 0,
+  rebroadcast = 1,
+  none = 2
+}
+
+export namespace Upkeep {
+  export const codec = (): Codec<Upkeep> => {
+    return enumeration<Upkeep>(__UpkeepValues)
+  }
+}
+
 export interface IPNSPublishMetadata {
   keyName: string
   lifetime: number
+  upkeep: Upkeep
 }
 
 export namespace IPNSPublishMetadata {
@@ -27,13 +46,19 @@ export namespace IPNSPublishMetadata {
           w.uint32(obj.lifetime)
         }
 
+        if (obj.upkeep != null && __UpkeepValues[obj.upkeep] !== 0) {
+          w.uint32(24)
+          Upkeep.codec().encode(obj.upkeep, w)
+        }
+
         if (opts.lengthDelimited !== false) {
           w.ldelim()
         }
       }, (reader, length, opts = {}) => {
         const obj: any = {
           keyName: '',
-          lifetime: 0
+          lifetime: 0,
+          upkeep: Upkeep.reissue
         }
 
         const end = length == null ? reader.len : reader.pos + length
@@ -50,6 +75,10 @@ export namespace IPNSPublishMetadata {
               obj.lifetime = reader.uint32()
               break
             }
+            case 3: {
+              obj.upkeep = Upkeep.codec().decode(reader)
+              break
+            }
             default: {
               reader.skipType(tag & 7)
               break
@@ -58,7 +87,7 @@ export namespace IPNSPublishMetadata {
         }
 
         return obj
-      }, function * (reader, prefix, length, opts = {}) {
+      }, function * (reader, length, prefix, opts = {}) {
         const end = length == null ? reader.len : reader.pos + length
 
         if (prefix !== '.') {
@@ -87,6 +116,13 @@ export namespace IPNSPublishMetadata {
               }
               break
             }
+            case 3: {
+              yield {
+                field: `${prefix}upkeep`,
+                value: Upkeep.codec().decode(reader)
+              }
+              break
+            }
             default: {
               reader.skipType(tag & 7)
               break
@@ -117,6 +153,11 @@ export namespace IPNSPublishMetadata {
     value: number
   }
 
+  export interface IPNSPublishMetadataUpkeepFieldEvent {
+    field: '.upkeep'
+    value: Upkeep
+  }
+
   export function encode (obj: Partial<IPNSPublishMetadata>): Uint8Array<ArrayBuffer> {
     return encodeMessage(obj, IPNSPublishMetadata.codec())
   }
@@ -125,7 +166,7 @@ export namespace IPNSPublishMetadata {
     return decodeMessage(buf, IPNSPublishMetadata.codec(), opts)
   }
 
-  export function stream (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<IPNSPublishMetadata>): Generator<IPNSPublishMetadataKeyNameFieldEvent | IPNSPublishMetadataLifetimeFieldEvent> {
+  export function stream (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<IPNSPublishMetadata>): Generator<IPNSPublishMetadataKeyNameFieldEvent | IPNSPublishMetadataLifetimeFieldEvent | IPNSPublishMetadataUpkeepFieldEvent> {
     return streamMessage(buf, IPNSPublishMetadata.codec(), opts)
   }
 }

package/src/routing/index.ts

@@ -6,7 +6,14 @@ import type { AbortOptions } from '@libp2p/interface'
 import type { ProgressOptions } from 'progress-events'
 
 export interface IPNSRoutingPutOptions extends AbortOptions, ProgressOptions {
-  metadata?: IPNSPublishMetadata
+  metadata?: Partial<IPNSPublishMetadata>
+
+  /**
+   * Overwrite an identical stored record instead of keeping the existing one,
+   * re-stamping its local timestamp. Passed on republish/rebroadcast so the
+   * record is not re-selected for republishing every cycle.
+   */
+  overwrite?: boolean
 }
 
 export interface IPNSRoutingGetOptions extends AbortOptions, ProgressOptions {
@@ -23,6 +30,28 @@ export interface IPNSRouting {
   get(routingKey: Uint8Array, options?: IPNSRoutingGetOptions): Promise<Uint8Array>
 }
 
+/**
+ * Return a printable name for a router, falling back to `CustomRouting()` when
+ * the router does not set its own `toString`.
+ */
+export function routerName (router: IPNSRouting): string {
+  if (router.toString === Object.prototype.toString) {
+    return 'CustomRouting()'
+  }
+
+  const name = router.toString()
+
+  if (typeof name !== 'string' || name === '') {
+    return 'CustomRouting()'
+  }
+
+  return name
+}
+
+export function isLocalStoreRouting (router: IPNSRouting): boolean {
+  return String(router) === 'LocalStoreRouting()'
+}
+
 export type { DatastoreProgressEvents }
 export type { HeliaRoutingProgressEvents }
 export type { PubSubProgressEvents }

package/src/utils.ts

@@ -281,6 +281,25 @@ export function normalizeKey (key?: PublicKey | CID | MultihashDigest | string):
   throw new InvalidValueError('Value must be a valid IPNS path starting with /')
 }
 
+/**
+ * Normalize a key identifier for unpublish: CID/PublicKey/multihash become a
+ * MultihashDigest, a keychain key name stays a string.
+ */
+export function normalizeKeyName (keyName: CID<unknown, 0x72> | PublicKey | MultihashDigest | string): MultihashDigest | string {
+  // a CID/PublicKey/MultihashDigest is always an IPNS name, let it throw if invalid
+  if (typeof keyName !== 'string') {
+    return normalizeKey(keyName).digest
+  }
+
+  try {
+    // a string may be an IPNS name...
+    return normalizeKey(keyName).digest
+  } catch {
+    // ...otherwise treat it as a keychain key name
+    return keyName
+  }
+}
+
 export function validateCborDataMatchesPbData (entry: IPNSEntry, data: IPNSRecordData): void {
   if (!uint8ArrayEquals(data.Value, entry.value ?? new Uint8Array(0))) {
     throw new SignatureVerificationError('Field "value" did not match between protobuf and CBOR')

package/src/validator.ts

@@ -1,4 +1,5 @@
 import NanoDate from 'timestamp-nano'
+import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import { InvalidEmbeddedPublicKeyError, RecordExpiredError, RecordTooLargeError, SignatureVerificationError, UnsupportedValidityError } from './errors.ts'
 import { IPNSEntry } from './pb/ipns.ts'
@@ -40,24 +41,7 @@ export async function ipnsValidator (routingKey: Uint8Array, marshalledRecord: U
   const data = decodeExtensibleData(record.data)
   const validity = uint8ArrayToString(data.Validity)
 
-  let publicKey: PublicKey | undefined
-
-  // try to extract public key from routing key
-  const routingMultihash = multihashFromIPNSRoutingKey(routingKey)
-
-  // identity hash
-  if (isCodec(routingMultihash, 0x0)) {
-    publicKey = await keychain.loadPublicKeyFromProtobuf(routingMultihash.digest, options)
-  }
-
-  // otherwise try to load key from message
-  if (publicKey == null && record.publicKey != null) {
-    publicKey = await keychain.loadPublicKeyFromProtobuf(record.publicKey, options)
-  }
-
-  if (publicKey == null) {
-    throw new InvalidEmbeddedPublicKeyError('Could not extract public key from IPNS record or routing key')
-  }
+  const publicKey = await extractPublicKey(routingKey, record, keychain, options)
 
   // Validate Signature V2
   let isValid
@@ -95,6 +79,34 @@ export async function ipnsValidator (routingKey: Uint8Array, marshalledRecord: U
   return record
 }
 
+/**
+ * Extract the public key that signed an IPNS record, either from an
+ * identity-hashed routing key or from the key embedded in the record.
+ */
+export async function extractPublicKey (routingKey: Uint8Array, record: IPNSEntry, keychain: Keychain, options?: AbortOptions): Promise<PublicKey> {
+  const routingMultihash = multihashFromIPNSRoutingKey(routingKey)
+
+  // identity hash, the routing key is the public key
+  if (isCodec(routingMultihash, 0x0)) {
+    return keychain.loadPublicKeyFromProtobuf(routingMultihash.digest, options)
+  }
+
+  // otherwise the record must embed the public key, and that key must correspond
+  // to the routing key, otherwise the record was paired with a routing key it was
+  // not signed for
+  if (record.publicKey != null) {
+    const publicKey = await keychain.loadPublicKeyFromProtobuf(record.publicKey, options)
+
+    if (!uint8ArrayEquals(publicKey.toMultihash().bytes, routingMultihash.bytes)) {
+      throw new InvalidEmbeddedPublicKeyError('Embedded public key does not match the routing key')
+    }
+
+    return publicKey
+  }
+
+  throw new InvalidEmbeddedPublicKeyError('Could not extract public key from IPNS record or routing key')
+}
+
 /**
  * Returns the number of milliseconds until the record expires.
  * If the record is already expired, returns 0.