@helia/ipns 10.1.1-b34bc7c7 → 10.2.0

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
@@ -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.