@helia/ipns 10.1.1-b34bc7c7 → 10.2.0

package/dist/typedoc-urls.json

@@ -0,0 +1,90 @@
+{
+  "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",
+  "InvalidEmbeddedPublicKeyError": "https://ipfs.github.io/helia/classes/_helia_ipns.InvalidEmbeddedPublicKeyError.html",
+  "InvalidRecordDataError": "https://ipfs.github.io/helia/classes/_helia_ipns.InvalidRecordDataError.html",
+  "InvalidTopicError": "https://ipfs.github.io/helia/classes/_helia_ipns.InvalidTopicError.html",
+  "InvalidValueError": "https://ipfs.github.io/helia/classes/_helia_ipns.InvalidValueError.html",
+  "RecordExpiredError": "https://ipfs.github.io/helia/classes/_helia_ipns.RecordExpiredError.html",
+  "RecordNotFoundError": "https://ipfs.github.io/helia/classes/_helia_ipns.RecordNotFoundError.html",
+  "RecordObsoleteError": "https://ipfs.github.io/helia/classes/_helia_ipns.RecordObsoleteError.html",
+  "RecordsFailedValidationError": "https://ipfs.github.io/helia/classes/_helia_ipns.RecordsFailedValidationError.html",
+  "RecordTooLargeError": "https://ipfs.github.io/helia/classes/_helia_ipns.RecordTooLargeError.html",
+  "SignatureCreationError": "https://ipfs.github.io/helia/classes/_helia_ipns.SignatureCreationError.html",
+  "SignatureVerificationError": "https://ipfs.github.io/helia/classes/_helia_ipns.SignatureVerificationError.html",
+  "UnsupportedValidityError": "https://ipfs.github.io/helia/classes/_helia_ipns.UnsupportedValidityError.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",
+  "RepublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.RepublishOptions.html",
+  ".:RepublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.RepublishOptions.html",
+  "RepublishResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.RepublishResult.html",
+  ".:RepublishResult": "https://ipfs.github.io/helia/interfaces/_helia_ipns.RepublishResult.html",
+  "UnpublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.UnpublishOptions.html",
+  ".:UnpublishOptions": "https://ipfs.github.io/helia/interfaces/_helia_ipns.UnpublishOptions.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",
+  "UpkeepPolicy": "https://ipfs.github.io/helia/types/_helia_ipns.UpkeepPolicy.html",
+  ".:UpkeepPolicy": "https://ipfs.github.io/helia/types/_helia_ipns.UpkeepPolicy.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",
+  "isLocalStoreRouting": "https://ipfs.github.io/helia/functions/_helia_ipns.isLocalStoreRouting.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",
+  "routerName": "https://ipfs.github.io/helia/functions/_helia_ipns.routerName.html"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/ipns",
-  "version": "10.1.1-b34bc7c7",
+  "version": "10.2.0",
   "description": "An implementation of IPNS for Helia",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/main/packages/ipns#readme",
@@ -50,7 +50,7 @@
     "test:electron-main": "aegir test -t electron-main"
   },
   "dependencies": {
-    "@helia/interface": "7.1.1-b34bc7c7",
+    "@helia/interface": "^7.1.1",
     "@ipld/dag-cbor": "^10.0.1",
     "@ipshipyard/crypto": "^1.1.0",
     "@ipshipyard/keychain": "^1.0.2",

package/src/errors.ts

@@ -1,3 +1,5 @@
+import type { IPNSEntry } from './pb/ipns.ts'
+
 export class RecordsFailedValidationError extends Error {
   static name = 'RecordsFailedValidationError'
   name = 'RecordsFailedValidationError'
@@ -18,6 +20,22 @@ export class RecordNotFoundError extends Error {
   name = 'RecordNotFoundError'
 }
 
+export class RecordObsoleteError extends Error {
+  static name = 'RecordObsoleteError'
+  name = 'RecordObsoleteError'
+  /**
+   * The more suitable record that made the one being imported or republished
+   * obsolete.
+   */
+  readonly record: IPNSEntry
+
+  constructor (message: string, record: IPNSEntry) {
+    super(message)
+
+    this.record = record
+  }
+}
+
 export class SignatureCreationError extends Error {
   static name = 'SignatureCreationError'
   name = 'SignatureCreationError'

package/src/index.ts

@@ -135,6 +135,46 @@
  *   console.info(result.record.value)
  * }
  * ```
+ *
+ * @example Republishing an existing IPNS record
+ *
+ * It is sometimes useful to be able to republish an existing IPNS record
+ * without needing the private key. This allows you to extend the availability
+ * of a record that was created elsewhere.
+ *
+ * There should be only one republisher per IPNS key. Multiple machines
+ * republishing the same key flood the routers with redundant writes.
+ *
+ * ```TypeScript
+ * import { createHelia } from 'helia'
+ * import { ipns } from '@helia/ipns'
+ * import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
+ * import { defaultLogger } from 'birnam'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const name = ipns(helia)
+ *
+ * const ipnsName = 'k51qzi5uqu5dktsyfv7xz8h631pri4ct7osmb43nibxiojpttxzoft6hdyyzg4'
+ * const parsedCid: CID<unknown, 114, 0 | 18, 1> = CID.parse(ipnsName)
+ * const delegatedClient = delegatedRoutingV1HttpApiClient({
+ *   url: 'https://delegated-ipfs.dev'
+ * })({
+ *   logger: defaultLogger()
+ * })
+ * const record = await delegatedClient.getIPNS(parsedCid)
+ *
+ * // import the record into the local store (validates and stores it locally,
+ * // but does not publish it to the routers)
+ * await name.import(parsedCid, record)
+ *
+ * // start republishing it; throws RecordObsoleteError if the routers
+ * // already have a newer record for this key
+ * const { record: latestRecord } = await name.republish(parsedCid)
+ *
+ * // stop republishing a key
+ * await name.unpublish(parsedCid)
+ * ```
  */
 
 import { CID } from 'multiformats/cid'
@@ -155,6 +195,7 @@ import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
 export * from './routing/index.ts'
 export * from './pb/ipns.ts'
+export * from './errors.ts'
 
 export {
   multihashFromIPNSRoutingKey,
@@ -184,6 +225,14 @@ export type DatastoreProgressEvents =
   ProgressEvent<'ipns:routing:datastore:list'> |
   ProgressEvent<'ipns:routing:datastore:error', Error>
 
+/**
+ * The automated upkeep policy for a stored IPNS record. `republish()` accepts
+ * every policy except `reissue`, which needs the private key to re-sign.
+ *
+ * These strings must match the `Upkeep` enum values in `pb/metadata.proto`.
+ */
+export type UpkeepPolicy = 'reissue' | 'rebroadcast' | 'none'
+
 export interface PublishOptions extends AbortOptions, ProgressOptions<PublishProgressEvents | IPNSRoutingProgressEvents> {
   /**
    * Time duration of the signature validity in ms - after this many ms have
@@ -219,6 +268,17 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
    */
   ttl?: number
 
+  /**
+   * Automated record upkeep policy.
+   *
+   * - `reissue`: re-sign the record with a new validity
+   * - `rebroadcast`: re-publish the existing record until it expires
+   * - `none`: disable automated publishing
+   *
+   * @default 'reissue'
+   */
+  upkeep?: UpkeepPolicy
+
   /**
    * Extensible data that will be added to the IPNS record data and signed to
    * verify it's integrity.
@@ -273,6 +333,43 @@ export interface IPNSResolveOptions extends AbortOptions, ProgressOptions<Resolv
   validate?: boolean
 }
 
+export interface RepublishOptions extends AbortOptions, ProgressOptions<IPNSRoutingProgressEvents> {
+  /**
+   * Skip resolution of latest record before republishing.
+   *
+   * It's important to resolve the latest record before republishing to routers
+   *
+   * Resolution should only be skipped when confident the latest record is
+   * already known.
+   *
+   * @default false
+   */
+  skipResolution?: boolean
+
+  /**
+   * Automated record upkeep policy.
+   *
+   * Defaults to `rebroadcast` since `republish()` cannot sign new records
+   * without the private key.
+   *
+   * - `rebroadcast`: re-publish the existing record until it expires
+   * - `none`: disable automated publishing
+   *
+   * @default 'rebroadcast'
+   */
+  upkeep?: Exclude<UpkeepPolicy, 'reissue'>
+}
+
+export interface UnpublishOptions extends AbortOptions {
+  /**
+   * Also delete the record from the local store, so the node stops serving it
+   * immediately instead of keeping it until it expires.
+   *
+   * @default false
+   */
+  removeRecord?: boolean
+}
+
 export interface IPNSResolveResult {
   /**
    * The resolved record
@@ -302,6 +399,18 @@ export interface IPNSPublishResult {
   publicKey: PublicKey
 }
 
+export interface RepublishResult {
+  /**
+   * The published record
+   */
+  record: IPNSEntry
+
+  /**
+   * The public key that the record is published under
+   */
+  publicKey: PublicKey
+}
+
 export interface IPNSResolver {
   /**
    * Accepts a CID with the libp2p-key codec and either the identity hash (for
@@ -345,7 +454,7 @@ export interface IPNS {
    *   signal: AbortSignal.timeout(5_000)
    * })
    *
-   * console.info(result) // { answer: ... }
+   * console.info(result) // { record, name, publicKey }
    * ```
    */
   publish(keyName: string, value: CID | PublicKey | MultihashDigest | string, options?: PublishOptions): Promise<IPNSPublishResult>
@@ -357,17 +466,46 @@ export interface IPNS {
    * (e.g. the value can be parsed as a string that does not start with
    * `/ipns/`).
    */
-  resolve(name: CID | PublicKey | MultihashDigest | string, options?: IPNSResolveOptions): AsyncGenerator<IPNSResolveResult>
+  resolve(name: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options?: IPNSResolveOptions): AsyncGenerator<IPNSResolveResult>
+
+  /**
+   * Stop automatically republishing an IPNS record
+   *
+   * By default this removes only the republishing metadata, keeping the record
+   * in the datastore so it is still served until it expires. Pass
+   * `removeRecord: true` to also delete the record so the node stops serving it.
+   * If a key name is passed, the key remains in the keychain.
+   */
+  unpublish(key: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options?: UnpublishOptions): Promise<void>
+
+  /**
+   * Republish the record already in the local store, setting its upkeep policy.
+   *
+   * Sets the record's upkeep policy to `options.upkeep` (default `rebroadcast`)
+   * so the background republisher keeps it available on the routers.
+   *
+   * @throws {NotFoundError} when there is no local record to republish
+   * @throws {RecordObsoleteError} when the routers already have a newer record
+   */
+  republish(key: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options?: RepublishOptions): Promise<RepublishResult>
 
   /**
-   * Stop republishing of an IPNS record.
+   * Import an existing IPNS record into the local store without publishing it.
+   *
+   * The record is validated and stored so this node serves it on a GET, but it
+   * is not broadcast to the routers. A newly imported record (for a key with no
+   * existing upkeep policy) is not automatically republished; call `republish`
+   * with an upkeep policy to start keeping it alive.
    *
-   * This will delete the last signed IPNS record from the datastore.
+   * Overwrites an older record already stored under this key, or rejects with
+   * `RecordObsoleteError` if the stored record is newer. Importing never changes
+   * the key's upkeep metadata, so a key that already has an upkeep policy keeps
+   * it and continues to be republished automatically.
    *
-   * Note that the record may still be resolved by other peers until it expires
-   * or is otherwise no longer valid.
+   * @throws {RecordExpiredError} (or another validation error) when the record fails validation
+   * @throws {RecordObsoleteError} when the stored record is more suitable than the one being imported
    */
-  unpublish(keyName: string, options?: AbortOptions): Promise<void>
+  import(key: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, record: IPNSEntry | Uint8Array, options?: AbortOptions): Promise<void>
 }
 
 export interface IPNSComponents {

package/src/ipns/publisher.ts

@@ -2,9 +2,10 @@ import { base36 } from 'multiformats/bases/base36'
 import { CustomProgressEvent } from 'progress-events'
 import { DEFAULT_LIFETIME_MS } from '../constants.ts'
 import { IPNSEntry } from '../pb/ipns.ts'
+import { Upkeep } from '../pb/metadata.ts'
 import { createIPNSRecord } from '../records.ts'
 import { decodeExtensibleData, multihashToIPNSRoutingKey } from '../utils.ts'
-import type { IPNSPublishResult, PublishOptions } from '../index.ts'
+import type { IPNSPublishResult, PublishOptions, UnpublishOptions } from '../index.ts'
 import type { LocalStore } from '../local-store.ts'
 import type { IPNSRouting } from '../routing/index.ts'
 import type { Keychain, PrivateKey, PublicKey } from '@helia/interface'
@@ -58,25 +59,14 @@ export class IPNSPublisher {
       })
       const marshaledRecord = IPNSEntry.encode(record)
 
+      const metadata = { keyName, lifetime, upkeep: Upkeep[options.upkeep ?? 'reissue'] }
       if (options.offline === true) {
         // only store record locally
-        await this.localStore.put(routingKey, marshaledRecord, {
-          ...options,
-          metadata: {
-            keyName,
-            lifetime
-          }
-        })
+        await this.localStore.put(routingKey, marshaledRecord, { ...options, metadata })
       } else {
         // publish record to routing (including the local store)
         await Promise.all(this.routers.map(async r => {
-          await r.put(routingKey, marshaledRecord, {
-            ...options,
-            metadata: {
-              keyName,
-              lifetime
-            }
-          })
+          await r.put(routingKey, marshaledRecord, { ...options, metadata })
         }))
       }
 
@@ -108,10 +98,22 @@ export class IPNSPublisher {
     }
   }
 
-  async unpublish (keyName: string, options?: AbortOptions): Promise<void> {
-    const key = await this.keychain.exportKey(keyName, options)
-    const digest = key.publicKey.toMultihash()
-    const routingKey = multihashToIPNSRoutingKey(digest)
-    await this.localStore.delete(routingKey, options)
+  async unpublish (keyName: string | MultihashDigest, options?: UnpublishOptions): Promise<void> {
+    if (typeof keyName === 'string') {
+      const key = await this.keychain.exportKey(keyName, options)
+      keyName = key.publicKey.toMultihash()
+    }
+
+    const routingKey = multihashToIPNSRoutingKey(keyName)
+
+    if (options?.removeRecord === true) {
+      // delete the record and its metadata so this node stops serving it
+      await this.localStore.delete(routingKey, options)
+      return
+    }
+
+    // remove only the metadata so the record is still served but no longer
+    // automatically republished; it expires naturally at its validity
+    await this.localStore.deleteMetadata(routingKey, options)
   }
 }