@helia/ipns 9.2.0 → 9.2.1-1361bfa5

package/src/pb/ipns.ts

@@ -0,0 +1,280 @@
+import { decodeMessage, encodeMessage, enumeration, message, streamMessage } from 'protons-runtime'
+import type { Codec, DecodeOptions } from 'protons-runtime'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface IpnsEntry {
+  value?: Uint8Array
+  signatureV1?: Uint8Array
+  validityType?: IpnsEntry.ValidityType
+  validity?: Uint8Array
+  sequence?: bigint
+  ttl?: bigint
+  publicKey?: Uint8Array
+  signatureV2?: Uint8Array
+  data?: Uint8Array
+}
+
+export namespace IpnsEntry {
+  export enum ValidityType {
+    EOL = 'EOL'
+  }
+
+  enum __ValidityTypeValues {
+    EOL = 0
+  }
+
+  export namespace ValidityType {
+    export const codec = (): Codec<ValidityType> => {
+      return enumeration<ValidityType>(__ValidityTypeValues)
+    }
+  }
+
+  let _codec: Codec<IpnsEntry>
+
+  export const codec = (): Codec<IpnsEntry> => {
+    if (_codec == null) {
+      _codec = message<IpnsEntry>((obj, w, opts = {}) => {
+        if (opts.lengthDelimited !== false) {
+          w.fork()
+        }
+
+        if (obj.value != null) {
+          w.uint32(10)
+          w.bytes(obj.value)
+        }
+
+        if (obj.signatureV1 != null) {
+          w.uint32(18)
+          w.bytes(obj.signatureV1)
+        }
+
+        if (obj.validityType != null) {
+          w.uint32(24)
+          IpnsEntry.ValidityType.codec().encode(obj.validityType, w)
+        }
+
+        if (obj.validity != null) {
+          w.uint32(34)
+          w.bytes(obj.validity)
+        }
+
+        if (obj.sequence != null) {
+          w.uint32(40)
+          w.uint64(obj.sequence)
+        }
+
+        if (obj.ttl != null) {
+          w.uint32(48)
+          w.uint64(obj.ttl)
+        }
+
+        if (obj.publicKey != null) {
+          w.uint32(58)
+          w.bytes(obj.publicKey)
+        }
+
+        if (obj.signatureV2 != null) {
+          w.uint32(66)
+          w.bytes(obj.signatureV2)
+        }
+
+        if (obj.data != null) {
+          w.uint32(74)
+          w.bytes(obj.data)
+        }
+
+        if (opts.lengthDelimited !== false) {
+          w.ldelim()
+        }
+      }, (reader, length, opts = {}) => {
+        const obj: any = {}
+
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1: {
+              obj.value = reader.bytes()
+              break
+            }
+            case 2: {
+              obj.signatureV1 = reader.bytes()
+              break
+            }
+            case 3: {
+              obj.validityType = IpnsEntry.ValidityType.codec().decode(reader)
+              break
+            }
+            case 4: {
+              obj.validity = reader.bytes()
+              break
+            }
+            case 5: {
+              obj.sequence = reader.uint64()
+              break
+            }
+            case 6: {
+              obj.ttl = reader.uint64()
+              break
+            }
+            case 7: {
+              obj.publicKey = reader.bytes()
+              break
+            }
+            case 8: {
+              obj.signatureV2 = reader.bytes()
+              break
+            }
+            case 9: {
+              obj.data = reader.bytes()
+              break
+            }
+            default: {
+              reader.skipType(tag & 7)
+              break
+            }
+          }
+        }
+
+        return obj
+      }, function * (reader, length, prefix, opts = {}) {
+        const end = length == null ? reader.len : reader.pos + length
+
+        while (reader.pos < end) {
+          const tag = reader.uint32()
+
+          switch (tag >>> 3) {
+            case 1: {
+              yield {
+                field: `${prefix}.value`,
+                value: reader.bytes()
+              }
+              break
+            }
+            case 2: {
+              yield {
+                field: `${prefix}.signatureV1`,
+                value: reader.bytes()
+              }
+              break
+            }
+            case 3: {
+              yield {
+                field: `${prefix}.validityType`,
+                value: IpnsEntry.ValidityType.codec().decode(reader)
+              }
+              break
+            }
+            case 4: {
+              yield {
+                field: `${prefix}.validity`,
+                value: reader.bytes()
+              }
+              break
+            }
+            case 5: {
+              yield {
+                field: `${prefix}.sequence`,
+                value: reader.uint64()
+              }
+              break
+            }
+            case 6: {
+              yield {
+                field: `${prefix}.ttl`,
+                value: reader.uint64()
+              }
+              break
+            }
+            case 7: {
+              yield {
+                field: `${prefix}.publicKey`,
+                value: reader.bytes()
+              }
+              break
+            }
+            case 8: {
+              yield {
+                field: `${prefix}.signatureV2`,
+                value: reader.bytes()
+              }
+              break
+            }
+            case 9: {
+              yield {
+                field: `${prefix}.data`,
+                value: reader.bytes()
+              }
+              break
+            }
+            default: {
+              reader.skipType(tag & 7)
+              break
+            }
+          }
+        }
+      })
+    }
+
+    return _codec
+  }
+
+  export interface IpnsEntryValueFieldEvent {
+    field: '$.value'
+    value: Uint8Array
+  }
+
+  export interface IpnsEntrySignatureV1FieldEvent {
+    field: '$.signatureV1'
+    value: Uint8Array
+  }
+
+  export interface IpnsEntryValidityTypeFieldEvent {
+    field: '$.validityType'
+    value: IpnsEntry.ValidityType
+  }
+
+  export interface IpnsEntryValidityFieldEvent {
+    field: '$.validity'
+    value: Uint8Array
+  }
+
+  export interface IpnsEntrySequenceFieldEvent {
+    field: '$.sequence'
+    value: bigint
+  }
+
+  export interface IpnsEntryTtlFieldEvent {
+    field: '$.ttl'
+    value: bigint
+  }
+
+  export interface IpnsEntryPublicKeyFieldEvent {
+    field: '$.publicKey'
+    value: Uint8Array
+  }
+
+  export interface IpnsEntrySignatureV2FieldEvent {
+    field: '$.signatureV2'
+    value: Uint8Array
+  }
+
+  export interface IpnsEntryDataFieldEvent {
+    field: '$.data'
+    value: Uint8Array
+  }
+
+  export function encode (obj: Partial<IpnsEntry>): Uint8Array<ArrayBuffer> {
+    return encodeMessage(obj, IpnsEntry.codec())
+  }
+
+  export function decode (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<IpnsEntry>): IpnsEntry {
+    return decodeMessage(buf, IpnsEntry.codec(), opts)
+  }
+
+  export function stream (buf: Uint8Array | Uint8ArrayList, opts?: DecodeOptions<IpnsEntry>): Generator<IpnsEntryValueFieldEvent | IpnsEntrySignatureV1FieldEvent | IpnsEntryValidityTypeFieldEvent | IpnsEntryValidityFieldEvent | IpnsEntrySequenceFieldEvent | IpnsEntryTtlFieldEvent | IpnsEntryPublicKeyFieldEvent | IpnsEntrySignatureV2FieldEvent | IpnsEntryDataFieldEvent> {
+    return streamMessage(buf, IpnsEntry.codec(), opts)
+  }
+}

package/src/pb/metadata.ts

@@ -101,7 +101,7 @@ export namespace IPNSPublishMetadata {
     value: number
   }
 
-  export function encode (obj: Partial<IPNSPublishMetadata>): Uint8Array {
+  export function encode (obj: Partial<IPNSPublishMetadata>): Uint8Array<ArrayBuffer> {
     return encodeMessage(obj, IPNSPublishMetadata.codec())
   }
 

package/src/records.ts

@@ -0,0 +1,273 @@
+import { logger } from '@libp2p/logger'
+import NanoDate from 'timestamp-nano'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { SignatureCreationError } from './errors.ts'
+import { IpnsEntry } from './pb/ipns.ts'
+import { createCborData, ipnsRecordDataForV1Sig, ipnsRecordDataForV2Sig, marshalIPNSRecord } from './utils.ts'
+import type { PrivateKey, PublicKey } from '@helia/interface'
+import type { AbortOptions } from 'abort-error'
+import type { Key } from 'interface-datastore/key'
+
+const log = logger('ipns')
+const DEFAULT_TTL_NS = 5 * 60 * 1e+9 // 5 Minutes or 300 Seconds, as suggested by https://specs.ipfs.tech/ipns/ipns-record/#ttl-uint64
+
+export const namespace = '/ipns/'
+export const namespaceLength = namespace.length
+
+export interface IPNSRecordV1V2 {
+  /**
+   * value of the record
+   */
+  value: string
+
+  /**
+   * signature of the record
+   */
+  signatureV1: Uint8Array
+
+  /**
+   * Type of validation being used
+   */
+  validityType: IpnsEntry.ValidityType
+
+  /**
+   * expiration datetime for the record in RFC3339 format
+   */
+  validity: string
+
+  /**
+   * number representing the version of the record
+   */
+  sequence: bigint
+
+  /**
+   * ttl in nanoseconds
+   */
+  ttl?: bigint
+
+  /**
+   * the public portion of the key that signed this record
+   */
+  publicKey: PublicKey
+
+  /**
+   * the v2 signature of the record
+   */
+  signatureV2: Uint8Array
+
+  /**
+   * extensible data
+   */
+  data: Uint8Array
+
+  /**
+   * The marshalled record
+   */
+  bytes: Uint8Array
+}
+
+export interface IPNSRecordV2 {
+  /**
+   * value of the record
+   */
+  value: string
+
+  /**
+   * the v2 signature of the record
+   */
+  signatureV2: Uint8Array
+
+  /**
+   * Type of validation being used
+   */
+  validityType: IpnsEntry.ValidityType
+
+  /**
+   * If the validity type is EOL, this is the expiration datetime for the record
+   * in RFC3339 format
+   */
+  validity: string
+
+  /**
+   * number representing the version of the record
+   */
+  sequence: bigint
+
+  /**
+   * ttl in nanoseconds
+   */
+  ttl?: bigint
+
+  /**
+   * the public portion of the key that signed this record
+   */
+  publicKey: PublicKey
+
+  /**
+   * extensible data
+   */
+  data: Uint8Array
+
+  /**
+   * The marshalled record
+   */
+  bytes: Uint8Array
+}
+
+export type IPNSRecord = IPNSRecordV1V2 | IPNSRecordV2
+
+export interface IPNSRecordData {
+  Value: Uint8Array
+  Validity: Uint8Array
+  ValidityType: IpnsEntry.ValidityType
+  Sequence: bigint
+  TTL: bigint
+}
+
+export interface IDKeys {
+  routingPubKey: Key
+  pkKey: Key
+  routingKey: Key
+  ipnsKey: Key
+}
+
+export interface CreateOptions extends AbortOptions {
+  ttlNs?: number | bigint
+  v1Compatible?: boolean
+}
+
+export interface CreateV2OrV1Options extends AbortOptions {
+  v1Compatible: true
+}
+
+export interface CreateV2Options extends AbortOptions {
+  v1Compatible: false
+}
+
+const defaultCreateOptions: CreateOptions = {
+  v1Compatible: true,
+  ttlNs: DEFAULT_TTL_NS
+}
+
+/**
+ * Creates a new IPNS record and signs it with the given private key.
+ * The IPNS Record validity should follow the [RFC3339]{@link https://www.ietf.org/rfc/rfc3339.txt} with nanoseconds precision.
+ * Note: This function does not embed the public key. If you want to do that, use `EmbedPublicKey`.
+ *
+ * The passed value can be a CID, a PublicKey or an arbitrary string path e.g. `/ipfs/...` or `/ipns/...`.
+ *
+ * CIDs will be converted to v1 and stored in the record as a string similar to: `/ipfs/${cid}`
+ * PublicKeys will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
+ * String paths will be stored in the record as-is, but they must start with `"/"`
+ *
+ * @param {PrivateKey} privateKey - the private key for signing the record.
+ * @param {CID | PublicKey | string} value - content to be stored in the record.
+ * @param {number | bigint} seq - number representing the current version of the record.
+ * @param {number} lifetime - lifetime of the record (in milliseconds).
+ * @param {CreateOptions} options - additional create options.
+ */
+export async function createIPNSRecord (privateKey: PrivateKey, value: string, seq: number | bigint, lifetime: number, options?: CreateV2OrV1Options): Promise<IPNSRecordV1V2>
+export async function createIPNSRecord (privateKey: PrivateKey, value: string, seq: number | bigint, lifetime: number, options: CreateV2Options): Promise<IPNSRecordV2>
+export async function createIPNSRecord (privateKey: PrivateKey, value: string, seq: number | bigint, lifetime: number, options: CreateOptions): Promise<IPNSRecordV1V2>
+export async function createIPNSRecord (privateKey: PrivateKey, value: string, seq: number | bigint, lifetime: number, options: CreateOptions = defaultCreateOptions): Promise<IPNSRecord> {
+  // Validity in ISOString with nanoseconds precision and validity type EOL
+  const expirationDate = new NanoDate(Date.now() + Number(lifetime))
+  const validityType = IpnsEntry.ValidityType.EOL
+  const ttlNs = BigInt(options.ttlNs ?? DEFAULT_TTL_NS)
+
+  return _create(privateKey, value, seq, validityType, expirationDate.toString(), ttlNs, options)
+}
+
+/**
+ * Same as create(), but instead of generating a new Date, it receives the intended expiration time
+ * WARNING: nano precision is not standard, make sure the value in seconds is 9 orders of magnitude lesser than the one provided.
+ *
+ * The passed value can be a CID, a PublicKey or an arbitrary string path e.g. `/ipfs/...` or `/ipns/...`.
+ *
+ * CIDs will be converted to v1 and stored in the record as a string similar to: `/ipfs/${cid}`
+ * PublicKeys will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
+ * String paths will be stored in the record as-is, but they must start with `"/"`
+ *
+ * @param {PrivateKey} privateKey - the private key for signing the record.
+ * @param {CID | PublicKey | string} value - content to be stored in the record.
+ * @param {number | bigint} seq - number representing the current version of the record.
+ * @param {string} expiration - expiration datetime for record in the [RFC3339]{@link https://www.ietf.org/rfc/rfc3339.txt} with nanoseconds precision.
+ * @param {CreateOptions} options - additional creation options.
+ */
+export async function createIPNSRecordWithExpiration (privateKey: PrivateKey, value: string, seq: number | bigint, expiration: string, options?: CreateV2OrV1Options): Promise<IPNSRecordV1V2>
+export async function createIPNSRecordWithExpiration (privateKey: PrivateKey, value: string, seq: number | bigint, expiration: string, options: CreateV2Options): Promise<IPNSRecordV2>
+export async function createIPNSRecordWithExpiration (privateKey: PrivateKey, value: string, seq: number | bigint, expiration: string, options: CreateOptions): Promise<IPNSRecordV1V2>
+export async function createIPNSRecordWithExpiration (privateKey: PrivateKey, value: string, seq: number | bigint, expiration: string, options: CreateOptions = defaultCreateOptions): Promise<IPNSRecord> {
+  const expirationDate = NanoDate.fromString(expiration)
+  const validityType = IpnsEntry.ValidityType.EOL
+  const ttlNs = BigInt(options.ttlNs ?? DEFAULT_TTL_NS)
+
+  return _create(privateKey, value, seq, validityType, expirationDate.toString(), ttlNs, options)
+}
+
+const _create = async (privateKey: PrivateKey, value: string, seq: number | bigint, validityType: IpnsEntry.ValidityType, validity: string, ttl: bigint, options: CreateOptions = defaultCreateOptions): Promise<IPNSRecord> => {
+  seq = BigInt(seq)
+  const isoValidity = uint8ArrayFromString(validity)
+  const data = createCborData(value, validityType, isoValidity, seq, ttl)
+  const sigData = ipnsRecordDataForV2Sig(data)
+  const signatureV2 = await privateKey.sign(sigData, options)
+  const publicKey = shouldEmbedPublicKey(privateKey.publicKey) ? privateKey.publicKey : undefined
+  let record: any
+
+  if (options.v1Compatible === true) {
+    const signatureV1 = await signLegacyV1(privateKey, value, validityType, isoValidity)
+
+    record = {
+      value,
+      signatureV1,
+      validity,
+      validityType,
+      sequence: seq,
+      ttl,
+      signatureV2,
+      data,
+      publicKey
+    }
+  } else {
+    record = {
+      value,
+      validity,
+      validityType,
+      sequence: seq,
+      ttl,
+      signatureV2,
+      data,
+      publicKey
+    }
+  }
+
+  record.bytes = marshalIPNSRecord(record)
+
+  return record
+}
+
+export { unmarshalIPNSRecord } from './utils.ts'
+export { marshalIPNSRecord } from './utils.ts'
+export { multihashToIPNSRoutingKey } from './utils.ts'
+export { multihashFromIPNSRoutingKey } from './utils.ts'
+
+/**
+ * Sign ipns record data using the legacy V1 signature scheme
+ */
+const signLegacyV1 = async (privateKey: PrivateKey, value: string, validityType: IpnsEntry.ValidityType, validity: Uint8Array, options?: AbortOptions): Promise<Uint8Array> => {
+  try {
+    const dataForSignature = ipnsRecordDataForV1Sig(value, validityType, validity)
+
+    return await privateKey.sign(dataForSignature, options)
+  } catch (error: any) {
+    log.error('record signature creation failed', error)
+    throw new SignatureCreationError('Record signature creation failed')
+  }
+}
+
+/**
+ * Returns true if the public key multihash is not an identity hash
+ */
+function shouldEmbedPublicKey (key: PublicKey): boolean {
+  return key.toMultihash().code !== 0
+}

package/src/routing/pubsub.ts

@@ -4,9 +4,6 @@ import { PeerSet } from '@libp2p/peer-collections'
 import { Queue } from '@libp2p/utils'
 import { anySignal } from 'any-signal'
 import delay from 'delay'
-import { multihashToIPNSRoutingKey } from 'ipns'
-import { ipnsSelector } from 'ipns/selector'
-import { ipnsValidator } from 'ipns/validator'
 import { CustomProgressEvent } from 'progress-events'
 import { raceSignal } from 'race-signal'
 import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
@@ -14,9 +11,13 @@ import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import { InvalidTopicError } from '../errors.ts'
 import { localStore } from '../local-store.ts'
-import { IPNS_STRING_PREFIX } from '../utils.ts'
+import { multihashToIPNSRoutingKey } from '../records.ts'
+import { ipnsSelector } from '../selector.ts'
+import { IPNS_STRING_PREFIX, unmarshalIPNSRecord } from '../utils.ts'
+import { ipnsValidator } from '../validator.ts'
 import type { GetOptions, IPNSRouting, PutOptions } from './index.ts'
 import type { LocalStore } from '../local-store.ts'
+import type { Keychain } from '@helia/interface'
 import type { Fetch } from '@libp2p/fetch'
 import type { PeerId, PublicKey, TypedEventTarget, ComponentLogger, Startable, AbortOptions, Metrics, Libp2p } from '@libp2p/interface'
 import type { Datastore } from 'interface-datastore'
@@ -62,6 +63,7 @@ export interface PubSub extends TypedEventTarget<PubSubEvents> {
 export interface PubsubRoutingComponents {
   datastore: Datastore
   logger: ComponentLogger
+  keychain: Keychain
   metrics?: Metrics
   libp2p: Pick<Libp2p<{ pubsub: PubSub, fetch?: Fetch }>, 'peerId' | 'register' | 'unregister' | 'services'>
 }
@@ -105,6 +107,7 @@ export class PubSubRouting implements IPNSRouting, Startable {
   private readonly fetchPeers: PeerSet
   private shutdownController: AbortController
   private fetchTopologyId?: string
+  private keychain: Keychain
 
   constructor (components: PubsubRoutingComponents, init: PubsubRoutingInit = {}) {
     this.subscriptions = new Set()
@@ -115,6 +118,7 @@ export class PubSubRouting implements IPNSRouting, Startable {
     this.libp2p = components.libp2p
     this.fetchConcurrency = init.fetchConcurrency ?? 8
     this.fetchDelay = init.fetchDelay ?? 0
+    this.keychain = components.keychain
 
     // default libp2p-fetch timeout is 10 seconds - we should have an existing
     // connection to the peer so this can be shortened
@@ -235,23 +239,25 @@ export class PubSubRouting implements IPNSRouting, Startable {
   }
 
   async #handleRecord (topic: string, routingKey: Uint8Array, marshalledRecord: Uint8Array, publish: boolean, options?: AbortOptions): Promise<Uint8Array> {
-    await ipnsValidator(routingKey, marshalledRecord)
+    const record = await unmarshalIPNSRecord(routingKey, marshalledRecord, this.keychain, options)
+    await ipnsValidator(record, options)
     this.shutdownController.signal.throwIfAborted()
 
     if (await this.localStore.has(routingKey)) {
-      const { record: currentRecord } = await this.localStore.get(routingKey, options)
+      const { record: marshaledCurrentRecord } = await this.localStore.get(routingKey, options)
+      const currentRecord = await unmarshalIPNSRecord(routingKey, marshaledCurrentRecord, this.keychain, options)
 
-      if (uint8ArrayEquals(currentRecord, marshalledRecord)) {
+      if (uint8ArrayEquals(marshaledCurrentRecord, record.bytes)) {
         log.trace('found identical record for %m', routingKey)
-        return currentRecord
+        return currentRecord.bytes
       }
 
-      const records = [currentRecord, marshalledRecord]
+      const records = [currentRecord, record]
       const index = ipnsSelector(routingKey, records)
 
       if (index === 0) {
         log.trace('found old record for %m', routingKey)
-        return currentRecord
+        return currentRecord.bytes
       }
     }
 
@@ -364,6 +370,7 @@ export class PubSubRouting implements IPNSRouting, Startable {
    */
   cancel (key: PublicKey | MultihashDigest<0x00 | 0x12>): void {
     const digest = isPublicKey(key) ? key.toMultihash() : key
+    // @ ts-expect-error @libp2p/crypto needs new multiformats
     const routingKey = multihashToIPNSRoutingKey(digest)
     const topic = keyToTopic(routingKey)
 

package/src/selector.ts

@@ -0,0 +1,55 @@
+import NanoDate from 'timestamp-nano'
+import { IpnsEntry } from './pb/ipns.ts'
+import type { IPNSRecord } from './records.ts'
+
+/**
+ * Selects the latest valid IPNS record from an array of marshalled IPNS records.
+ *
+ * Records are sorted by:
+ * 1. Sequence number (higher takes precedence)
+ * 2. Validity time for EOL records with same sequence number (longer lived record takes precedence)
+ *
+ * @param key - The routing key for the IPNS record
+ * @param data - Array of marshalled IPNS records to select from
+ * @returns The index of the most valid record from the input array
+ */
+export function ipnsSelector (key: Uint8Array, data: IPNSRecord[]): number {
+  const entries = data.map((record, index) => ({
+    record,
+    index
+  }))
+
+  entries.sort((a, b) => {
+    // Before we'd sort based on the signature version. Unmarshal now fails if
+    // a record does not have SignatureV2, so that is no longer needed. V1-only
+    // records haven't been issues in a long time.
+
+    const aSeq = a.record.sequence
+    const bSeq = b.record.sequence
+
+    // choose later sequence number
+    if (aSeq > bSeq) {
+      return -1
+    } else if (aSeq < bSeq) {
+      return 1
+    }
+
+    if (a.record.validityType === IpnsEntry.ValidityType.EOL && b.record.validityType === IpnsEntry.ValidityType.EOL) {
+      // choose longer lived record if sequence numbers the same
+      const recordAValidityDate = NanoDate.fromString(a.record.validity).toDate()
+      const recordBValidityDate = NanoDate.fromString(b.record.validity).toDate()
+
+      if (recordAValidityDate.getTime() > recordBValidityDate.getTime()) {
+        return -1
+      }
+
+      if (recordAValidityDate.getTime() < recordBValidityDate.getTime()) {
+        return 1
+      }
+    }
+
+    return 0
+  })
+
+  return entries[0].index
+}