@helia/ipns 10.1.0 → 10.1.1-2ab3bfc6

package/src/pb/ipns.ts

@@ -142,69 +142,77 @@ export namespace IPNSEntry {
       }, function * (reader, length, prefix, opts = {}) {
         const end = length == null ? reader.len : reader.pos + length
 
+        if (prefix !== '.') {
+          yield {
+            field: prefix.endsWith('.') ? prefix.substring(0, prefix.length - 1) : prefix,
+            type: 'start',
+            message: 'IPNSEntry'
+          }
+        }
+
         while (reader.pos < end) {
           const tag = reader.uint32()
 
           switch (tag >>> 3) {
             case 1: {
               yield {
-                field: `${prefix}.value`,
+                field: `${prefix}value`,
                 value: reader.bytes()
               }
               break
             }
             case 2: {
               yield {
-                field: `${prefix}.signatureV1`,
+                field: `${prefix}signatureV1`,
                 value: reader.bytes()
               }
               break
             }
             case 3: {
               yield {
-                field: `${prefix}.validityType`,
+                field: `${prefix}validityType`,
                 value: IPNSEntry.ValidityType.codec().decode(reader)
               }
               break
             }
             case 4: {
               yield {
-                field: `${prefix}.validity`,
+                field: `${prefix}validity`,
                 value: reader.bytes()
               }
               break
             }
             case 5: {
               yield {
-                field: `${prefix}.sequence`,
+                field: `${prefix}sequence`,
                 value: reader.uint64()
               }
               break
             }
             case 6: {
               yield {
-                field: `${prefix}.ttl`,
+                field: `${prefix}ttl`,
                 value: reader.uint64()
               }
               break
             }
             case 7: {
               yield {
-                field: `${prefix}.publicKey`,
+                field: `${prefix}publicKey`,
                 value: reader.bytes()
               }
               break
             }
             case 8: {
               yield {
-                field: `${prefix}.signatureV2`,
+                field: `${prefix}signatureV2`,
                 value: reader.bytes()
               }
               break
             }
             case 9: {
               yield {
-                field: `${prefix}.data`,
+                field: `${prefix}data`,
                 value: reader.bytes()
               }
               break
@@ -215,6 +223,14 @@ export namespace IPNSEntry {
             }
           }
         }
+
+        if (prefix !== '.') {
+          yield {
+            field: prefix.endsWith('.') ? prefix.substring(0, prefix.length - 1) : prefix,
+            type: 'end',
+            message: 'IPNSEntry'
+          }
+        }
       })
     }
 
@@ -222,47 +238,47 @@ export namespace IPNSEntry {
   }
 
   export interface IPNSEntryValueFieldEvent {
-    field: '$.value'
+    field: '.value'
     value: Uint8Array<ArrayBuffer>
   }
 
   export interface IPNSEntrySignatureV1FieldEvent {
-    field: '$.signatureV1'
+    field: '.signatureV1'
     value: Uint8Array<ArrayBuffer>
   }
 
   export interface IPNSEntryValidityTypeFieldEvent {
-    field: '$.validityType'
+    field: '.validityType'
     value: IPNSEntry.ValidityType
   }
 
   export interface IPNSEntryValidityFieldEvent {
-    field: '$.validity'
+    field: '.validity'
     value: Uint8Array<ArrayBuffer>
   }
 
   export interface IPNSEntrySequenceFieldEvent {
-    field: '$.sequence'
+    field: '.sequence'
     value: bigint
   }
 
   export interface IPNSEntryTtlFieldEvent {
-    field: '$.ttl'
+    field: '.ttl'
     value: bigint
   }
 
   export interface IPNSEntryPublicKeyFieldEvent {
-    field: '$.publicKey'
+    field: '.publicKey'
     value: Uint8Array<ArrayBuffer>
   }
 
   export interface IPNSEntrySignatureV2FieldEvent {
-    field: '$.signatureV2'
+    field: '.signatureV2'
     value: Uint8Array<ArrayBuffer>
   }
 
   export interface IPNSEntryDataFieldEvent {
-    field: '$.data'
+    field: '.data'
     value: Uint8Array<ArrayBuffer>
   }
 

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
@@ -61,30 +90,53 @@ export namespace IPNSPublishMetadata {
       }, function * (reader, length, prefix, opts = {}) {
         const end = length == null ? reader.len : reader.pos + length
 
+        if (prefix !== '.') {
+          yield {
+            field: prefix.endsWith('.') ? prefix.substring(0, prefix.length - 1) : prefix,
+            type: 'start',
+            message: 'IPNSPublishMetadata'
+          }
+        }
+
         while (reader.pos < end) {
           const tag = reader.uint32()
 
           switch (tag >>> 3) {
             case 1: {
               yield {
-                field: `${prefix}.keyName`,
+                field: `${prefix}keyName`,
                 value: reader.string()
               }
               break
             }
             case 2: {
               yield {
-                field: `${prefix}.lifetime`,
+                field: `${prefix}lifetime`,
                 value: reader.uint32()
               }
               break
             }
+            case 3: {
+              yield {
+                field: `${prefix}upkeep`,
+                value: Upkeep.codec().decode(reader)
+              }
+              break
+            }
             default: {
               reader.skipType(tag & 7)
               break
             }
           }
         }
+
+        if (prefix !== '.') {
+          yield {
+            field: prefix.endsWith('.') ? prefix.substring(0, prefix.length - 1) : prefix,
+            type: 'end',
+            message: 'IPNSPublishMetadata'
+          }
+        }
       })
     }
 
@@ -92,15 +144,20 @@ export namespace IPNSPublishMetadata {
   }
 
   export interface IPNSPublishMetadataKeyNameFieldEvent {
-    field: '$.keyName'
+    field: '.keyName'
     value: string
   }
 
   export interface IPNSPublishMetadataLifetimeFieldEvent {
-    field: '$.lifetime'
+    field: '.lifetime'
     value: number
   }
 
+  export interface IPNSPublishMetadataUpkeepFieldEvent {
+    field: '.upkeep'
+    value: Upkeep
+  }
+
   export function encode (obj: Partial<IPNSPublishMetadata>): Uint8Array<ArrayBuffer> {
     return encodeMessage(obj, IPNSPublishMetadata.codec())
   }
@@ -109,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.

package/dist/typedoc-urls.json

@@ -1,68 +0,0 @@
-{
-  "codec": "https://ipfs.github.io/helia/functions/_helia_ipns.IPNSEntry.ValidityType.codec.html",
-  "ValidityType": "https://ipfs.github.io/helia/enums/_helia_ipns.IPNSEntry.ValidityType.html",
-  "IPNSEntryDataFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryDataFieldEvent.html",
-  "IPNSEntryPublicKeyFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryPublicKeyFieldEvent.html",
-  "IPNSEntrySequenceFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntrySequenceFieldEvent.html",
-  "IPNSEntrySignatureV1FieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntrySignatureV1FieldEvent.html",
-  "IPNSEntrySignatureV2FieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntrySignatureV2FieldEvent.html",
-  "IPNSEntryTtlFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryTtlFieldEvent.html",
-  "IPNSEntryValidityFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryValidityFieldEvent.html",
-  "IPNSEntryValidityTypeFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryValidityTypeFieldEvent.html",
-  "IPNSEntryValueFieldEvent": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.IPNSEntryValueFieldEvent.html",
-  "decode": "https://ipfs.github.io/helia/functions/_helia_ipns.IPNSEntry.decode.html",
-  "encode": "https://ipfs.github.io/helia/functions/_helia_ipns.IPNSEntry.encode.html",
-  "stream": "https://ipfs.github.io/helia/functions/_helia_ipns.IPNSEntry.stream.html",
-  "CreateIPNSRecordOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.CreateIPNSRecordOptions.html",
-  "IPNS": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNS.html",
-  ".:IPNS": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNS.html",
-  "IPNSComponents": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSComponents.html",
-  ".:IPNSComponents": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSComponents.html",
-  "IPNSEntry": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSEntry.html",
-  "IPNSOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSOptions.html",
-  ".:IPNSOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSOptions.html",
-  "IPNSPublishResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSPublishResult.html",
-  ".:IPNSPublishResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSPublishResult.html",
-  "IPNSRecordData": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSRecordData.html",
-  ".:IPNSRecordData": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSRecordData.html",
-  "IPNSResolveOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolveOptions.html",
-  ".:IPNSResolveOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolveOptions.html",
-  "IPNSResolver": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolver.html",
-  ".:IPNSResolver": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolver.html",
-  "IPNSResolveResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolveResult.html",
-  ".:IPNSResolveResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolveResult.html",
-  "IPNSResolverOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolverOptions.html",
-  ".:IPNSResolverOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSResolverOptions.html",
-  "IPNSRouting": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSRouting.html",
-  "IPNSRoutingGetOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSRoutingGetOptions.html",
-  "IPNSRoutingPutOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.IPNSRoutingPutOptions.html",
-  "PublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PublishOptions.html",
-  ".:PublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PublishOptions.html",
-  "PublishResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PublishResult.html",
-  "PubSub": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubSub.html",
-  "PubSubEvents": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubSubEvents.html",
-  "PubSubMessage": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubSubMessage.html",
-  "PubsubRoutingComponents": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubsubRoutingComponents.html",
-  "PubSubSubscription": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubSubSubscription.html",
-  "PubSubSubscriptionChangeData": "https://ipfs.github.io/helia/interfaces/_helia_ipns.PubSubSubscriptionChangeData.html",
-  "DatastoreProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.DatastoreProgressEvents.html",
-  ".:DatastoreProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.DatastoreProgressEvents.html",
-  "HeliaRoutingProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.HeliaRoutingProgressEvents.html",
-  "IPNSRoutingProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.IPNSRoutingProgressEvents.html",
-  "PublishProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.PublishProgressEvents.html",
-  ".:PublishProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.PublishProgressEvents.html",
-  "PubSubProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.PubSubProgressEvents.html",
-  "ResolveProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.ResolveProgressEvents.html",
-  ".:ResolveProgressEvents": "https://ipfs.github.io/helia/types/_helia_ipns.ResolveProgressEvents.html",
-  "createIPNSRecord": "https://ipfs.github.io/helia/functions/_helia_ipns.createIPNSRecord.html",
-  "heliaIPNSRouting": "https://ipfs.github.io/helia/functions/_helia_ipns.heliaIPNSRouting.html",
-  "ipns": "https://ipfs.github.io/helia/functions/_helia_ipns.ipns.html",
-  ".:ipns": "https://ipfs.github.io/helia/functions/_helia_ipns.ipns.html",
-  "ipnsResolver": "https://ipfs.github.io/helia/functions/_helia_ipns.ipnsResolver.html",
-  ".:ipnsResolver": "https://ipfs.github.io/helia/functions/_helia_ipns.ipnsResolver.html",
-  "ipnsSelector": "https://ipfs.github.io/helia/functions/_helia_ipns.ipnsSelector.html",
-  "ipnsValidator": "https://ipfs.github.io/helia/functions/_helia_ipns.ipnsValidator.html",
-  "multihashFromIPNSRoutingKey": "https://ipfs.github.io/helia/functions/_helia_ipns.multihashFromIPNSRoutingKey.html",
-  "multihashToIPNSRoutingKey": "https://ipfs.github.io/helia/functions/_helia_ipns.multihashToIPNSRoutingKey.html",
-  "pubSubIPNSRouting": "https://ipfs.github.io/helia/functions/_helia_ipns.pubSubIPNSRouting.html"
-}