@helia/ipns 10.0.0 → 10.0.1-883ff053

package/dist/src/validator.js

@@ -1,22 +1,59 @@
 import NanoDate from 'timestamp-nano';
-import { InvalidEmbeddedPublicKeyError, RecordExpiredError, SignatureVerificationError, UnsupportedValidityError } from "./errors.js";
-import { IpnsEntry } from "./pb/ipns.js";
-import { ipnsRecordDataForV2Sig } from "./utils.js";
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
+import { InvalidEmbeddedPublicKeyError, RecordExpiredError, RecordTooLargeError, SignatureVerificationError, UnsupportedValidityError } from "./errors.js";
+import { IPNSEntry } from "./pb/ipns.js";
+import { decodeExtensibleData, ipnsRecordDataForV2Sig, isCodec, multihashFromIPNSRoutingKey, validateCborDataMatchesPbData } from "./utils.js";
+/**
+ * Limit valid IPNS record sizes to 10kb
+ */
+const MAX_RECORD_SIZE = 1024 * 10;
 /**
  * Validate the given IPNS record against the given routing key.
  *
+ * Ensure that
+ * - SignatureV2 and Data are present
+ * - ValidityType and Validity are of valid types and have a value
+ * - CBOR data matches protobuf if it's a V1+V2 record
+ *
  * @see https://specs.ipfs.tech/ipns/ipns-record/#routing-record for the binary
  * format of the routing key
  */
-export async function ipnsValidator(record, options) {
-    if (record.publicKey == null) {
-        throw new InvalidEmbeddedPublicKeyError('The record had no public key associated with it');
+export async function ipnsValidator(routingKey, marshalledRecord, keychain, options) {
+    if (marshalledRecord.byteLength > MAX_RECORD_SIZE) {
+        throw new RecordTooLargeError('The record is too large');
+    }
+    const record = IPNSEntry.decode(marshalledRecord);
+    // Check if we have the data field. If we don't, we fail. We've been producing
+    // V1+V2 records for quite a while and we don't support V1-only records during
+    // validation any more
+    if (record.signatureV2 == null) {
+        throw new SignatureVerificationError('Missing signatureV2');
+    }
+    const data = decodeExtensibleData(record.data);
+    const validity = uint8ArrayToString(data.Validity);
+    let publicKey;
+    // 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');
     }
     // Validate Signature V2
     let isValid;
     try {
+        if (record.data == null) {
+            // n.b. decodeExtensibleData would have thrown if record data was missing
+            throw new Error('Missing data');
+        }
         const dataForSignature = ipnsRecordDataForV2Sig(record.data);
-        isValid = await record.publicKey.verify(dataForSignature, record.signatureV2, options);
+        isValid = await publicKey.verify(dataForSignature, record.signatureV2, options);
     }
     catch {
         isValid = false;
@@ -25,14 +62,19 @@ export async function ipnsValidator(record, options) {
         throw new SignatureVerificationError('Record signature verification failed');
     }
     // Validate according to the validity type
-    if (record.validityType === IpnsEntry.ValidityType.EOL) {
-        if (NanoDate.fromString(record.validity).toDate().getTime() < Date.now()) {
+    if (data.ValidityType === IPNSEntry.ValidityType.EOL) {
+        if (NanoDate.fromString(validity).toDate().getTime() < Date.now()) {
             throw new RecordExpiredError('record has expired');
         }
     }
-    else if (record.validityType != null) {
-        throw new UnsupportedValidityError('The validity type is unsupported');
+    else if (data.ValidityType != null) {
+        throw new UnsupportedValidityError(`The validity type ${data.ValidityType} is unsupported`);
+    }
+    if (record.value != null && record.signatureV1 != null) {
+        // V1+V2
+        validateCborDataMatchesPbData(record, data);
     }
+    return record;
 }
 /**
  * Returns the number of milliseconds until the record expires.
@@ -42,13 +84,14 @@ export async function ipnsValidator(record, options) {
  * @returns The number of milliseconds until the record expires, or 0 if the record is already expired.
  */
 export function validFor(record) {
-    if (record.validityType !== IpnsEntry.ValidityType.EOL) {
+    const data = decodeExtensibleData(record.data);
+    if (data.ValidityType !== IPNSEntry.ValidityType.EOL) {
         throw new UnsupportedValidityError();
     }
-    if (record.validity == null) {
+    if (data.Validity == null) {
         throw new UnsupportedValidityError();
     }
-    const validUntil = NanoDate.fromString(record.validity).toDate().getTime();
+    const validUntil = NanoDate.fromString(uint8ArrayToString(data.Validity)).toDate().getTime();
     const now = Date.now();
     if (validUntil < now) {
         return 0;

package/dist/src/validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAA;AACrC,OAAO,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACrI,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAInD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAE,MAAkB,EAAE,OAAsB;IAC7E,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,6BAA6B,CAAC,iDAAiD,CAAC,CAAA;IAC5F,CAAC;IAED,wBAAwB;IACxB,IAAI,OAAO,CAAA;IAEX,IAAI,CAAC;QACH,MAAM,gBAAgB,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC5D,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,KAAK,CAAA;IACjB,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,0BAA0B,CAAC,sCAAsC,CAAC,CAAA;IAC9E,CAAC;IAED,0CAA0C;IAC1C,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;QACvD,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACzE,MAAM,IAAI,kBAAkB,CAAC,oBAAoB,CAAC,CAAA;QACpD,CAAC;IACH,CAAC;SAAM,IAAI,MAAM,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,IAAI,wBAAwB,CAAC,kCAAkC,CAAC,CAAA;IACxE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAE,MAAkB;IAC1C,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;QACvD,MAAM,IAAI,wBAAwB,EAAE,CAAA;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,wBAAwB,EAAE,CAAA;IACtC,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAEtB,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;QACrB,OAAO,CAAC,CAAA;IACV,CAAC;IAED,OAAO,UAAU,GAAG,GAAG,CAAA;AACzB,CAAC"}
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/ipns",
-  "version": "10.0.0",
+  "version": "10.0.1-883ff053",
   "description": "An implementation of IPNS for Helia",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/main/packages/ipns#readme",
@@ -20,22 +20,6 @@
   ],
   "type": "module",
   "types": "./dist/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "*": [
-        "*",
-        "dist/*",
-        "dist/src/*",
-        "dist/src/*/index"
-      ],
-      "src/*": [
-        "*",
-        "dist/*",
-        "dist/src/*",
-        "dist/src/*/index"
-      ]
-    }
-  },
   "files": [
     "src",
     "dist",
@@ -47,16 +31,6 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js",
       "module-sync": "./dist/src/index.js"
-    },
-    "./dns-resolvers": {
-      "types": "./dist/src/dns-resolvers/index.d.ts",
-      "import": "./dist/src/dns-resolvers/index.js",
-      "module-sync": "./dist/src/dns-resolvers/index.js"
-    },
-    "./routing": {
-      "types": "./dist/src/routing/index.d.ts",
-      "import": "./dist/src/routing/index.js",
-      "module-sync": "./dist/src/routing/index.js"
     }
   },
   "scripts": {
@@ -76,7 +50,10 @@
     "test:electron-main": "aegir test -t electron-main"
   },
   "dependencies": {
-    "@helia/interface": "^7.0.0",
+    "@helia/interface": "7.0.0-883ff053",
+    "@ipld/dag-cbor": "^10.0.1",
+    "@ipshipyard/crypto": "^1.1.0",
+    "@ipshipyard/keychain": "^1.0.2",
     "@libp2p/fetch": "^4.1.6",
     "@libp2p/interface": "^3.2.3",
     "@libp2p/kad-dht": "^16.3.2",
@@ -85,7 +62,6 @@
     "@libp2p/utils": "^7.2.2",
     "abort-error": "^1.0.2",
     "any-signal": "^4.2.0",
-    "cborg": "^5.1.1",
     "delay": "^7.0.0",
     "interface-datastore": "^10.0.1",
     "multiformats": "^14.0.0",
@@ -97,9 +73,8 @@
     "uint8arrays": "^6.1.1"
   },
   "devDependencies": {
-    "@ipshipyard/crypto": "^1.1.0",
-    "@ipshipyard/keychain": "^1.0.2",
     "aegir": "^48.0.11",
+    "cborg": "^5.1.5",
     "datastore-core": "^12.0.1",
     "it-drain": "^3.0.12",
     "it-last": "^3.0.11",

package/src/errors.ts

@@ -3,16 +3,6 @@ export class RecordsFailedValidationError extends Error {
   name = 'RecordsFailedValidationError'
 }
 
-export class UnsupportedMultibasePrefixError extends Error {
-  static name = 'UnsupportedMultibasePrefixError'
-  name = 'UnsupportedMultibasePrefixError'
-}
-
-export class UnsupportedMultihashCodecError extends Error {
-  static name = 'UnsupportedMultihashCodecError'
-  name = 'UnsupportedMultihashCodecError'
-}
-
 export class InvalidValueError extends Error {
   static name = 'InvalidValueError'
   name = 'InvalidValueError'

package/src/index.ts

@@ -37,7 +37,6 @@
  * import { createHelia } from 'helia'
  * import { ipns } from '@helia/ipns'
  * import { unixfs } from '@helia/unixfs'
- * import { generateKeyPair } from '@libp2p/crypto/keys'
  *
  * const helia = await createHelia()
  * const name = ipns(helia)
@@ -66,7 +65,6 @@
  * import { createHelia } from 'helia'
  * import { ipns } from '@helia/ipns'
  * import { unixfs } from '@helia/unixfs'
- * import { generateKeyPair } from '@libp2p/crypto/keys'
  *
  * const helia = await createHelia()
  * const name = ipns(helia)
@@ -105,15 +103,13 @@
  * may fail to be published with "Insufficient peers" errors.
  *
  * ```TypeScript
- * import { ipns } from '@helia/ipns'
- * import { pubsub } from '@helia/ipns/routing'
+ * import { ipns, pubSubIPNSRouting } from '@helia/ipns'
  * import { withLibp2p, libp2pDefaults } from '@helia/libp2p'
  * import { unixfs } from '@helia/unixfs'
- * import { generateKeyPair } from '@libp2p/crypto/keys'
  * import { floodsub } from '@libp2p/floodsub'
  * import { createHelia } from 'helia'
  * import type { Helia } from '@helia/interface'
- * import type { PubSub } from '@helia/ipns/routing'
+ * import type { PubSub } from '@helia/ipns'
  * import type { DefaultLibp2pServices } from '@helia/libp2p'
  * import type { FloodSub } from '@libp2p/floodsub'
  * import type { Libp2p } from '@libp2p/interface'
@@ -125,7 +121,7 @@
  *
  * const name = ipns(helia, {
  *  routers: [
- *    pubsub(helia)
+ *    pubSubIPNSRouting(helia)
  *  ]
  * })
  *
@@ -147,10 +143,10 @@ import { CID } from 'multiformats/cid'
 import { IPNSResolver as IPNSResolverClass } from './ipns/resolver.ts'
 import { IPNS as IPNSClass } from './ipns.ts'
 import { localStore } from './local-store.ts'
-import { helia } from './routing/index.ts'
-import { localStoreRouting } from './routing/local-store.ts'
+import { heliaIPNSRouting } from './routing/index.ts'
+import { localStoreIPNSRouting } from './routing/local-store.ts'
 import type { IPNSResolverComponents } from './ipns/resolver.ts'
-import type { IPNSRecord } from './records.ts'
+import type { IPNSEntry } from './pb/ipns.ts'
 import type { IPNSRouting, IPNSRoutingProgressEvents } from './routing/index.ts'
 import type { Routing, HeliaEvents, Keychain, PublicKey } from '@helia/interface'
 import type { ComponentLogger, TypedEventEmitter } from '@libp2p/interface'
@@ -159,14 +155,29 @@ import type { Datastore } from 'interface-datastore'
 import type { MultihashDigest } from 'multiformats/hashes/interface'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
+export * from './routing/index.ts'
+export * from './pb/ipns.ts'
+
+export {
+  multihashFromIPNSRoutingKey,
+  multihashToIPNSRoutingKey
+} from './utils.ts'
+
+export {
+  createIPNSRecord
+} from './records.ts'
+export type {
+  CreateIPNSRecordOptions
+} from './records.ts'
+
 export type PublishProgressEvents =
   ProgressEvent<'ipns:publish:start'> |
-  ProgressEvent<'ipns:publish:success', IPNSRecord> |
+  ProgressEvent<'ipns:publish:success', IPNSEntry> |
   ProgressEvent<'ipns:publish:error', Error>
 
 export type ResolveProgressEvents =
   ProgressEvent<'ipns:resolve:start', unknown> |
-  ProgressEvent<'ipns:resolve:success', IPNSRecord> |
+  ProgressEvent<'ipns:resolve:success', IPNSEntry> |
   ProgressEvent<'ipns:resolve:error', Error>
 
 export type DatastoreProgressEvents =
@@ -177,7 +188,8 @@ export type DatastoreProgressEvents =
 
 export interface PublishOptions extends AbortOptions, ProgressOptions<PublishProgressEvents | IPNSRoutingProgressEvents> {
   /**
-   * Time duration of the signature validity in ms
+   * Time duration of the signature validity in ms - after this many ms have
+   * expired the record will be invalidated.
    *
    * @default 172_800_000
    */
@@ -199,19 +211,47 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
   v1Compatible?: boolean
 
   /**
-   * The TTL of the record in ms
+   * The TTL of the record in ms - after this many ms have expired, resolving
+   * the record will query the routing for an updated version.
+   *
+   * Before this many ms have expired any locally stored copy will be treated as
+   * the latest version and the routing will not be queried.
    *
    * @default 300_000
    */
   ttl?: number
+
+  /**
+   * Extensible data that will be added to the IPNS record data and signed to
+   * verify it's integrity.
+   *
+   * Note that this data will be encoded as DAG-CBOR so it must be valid.
+   *
+   * It is recommended that any custom fields set here are prefixed with `_` to
+   * avoid collision with any mandatory fields added to future versions of the
+   * IPNS specification.
+   *
+   * @see https://specs.ipfs.tech/ipns/ipns-record/#extensible-data-dag-cbor
+   */
+  data?: Record<string, any>
 }
 
-export interface IPNSRecordMetadata {
-  keyName: string
-  lifetime: number
+/**
+ * Extensible data from the record `data` field.
+ *
+ * The wire format of this data is DAG-CBOR.
+ *
+ * @see https://specs.ipfs.tech/ipns/ipns-record/#extensible-data-dag-cbor
+ */
+export interface IPNSRecordData extends Record<string, any> {
+  Value: Uint8Array<ArrayBuffer>
+  Validity: Uint8Array<ArrayBuffer>
+  ValidityType: IPNSEntry.ValidityType
+  Sequence: bigint
+  TTL: bigint
 }
 
-export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingProgressEvents> {
+export interface IPNSResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingProgressEvents> {
   /**
    * Do not query the network for the IPNS record
    *
@@ -225,20 +265,33 @@ export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolvePro
    * @default false
    */
   nocache?: boolean
+
+  /**
+   * If true, ensure the record fields and signature are valid. If false, just
+   * return the record.
+   *
+   * @default true
+   */
+  validate?: boolean
 }
 
-export interface ResolveResult {
+export interface IPNSResolveResult {
   /**
    * The resolved record
    */
-  record: IPNSRecord
+  record: IPNSEntry
+
+  /**
+   * The value contained within the IPNS record
+   */
+  value: string
 }
 
-export interface PublishResult {
+export interface IPNSPublishResult {
   /**
    * The published record
    */
-  record: IPNSRecord
+  record: IPNSEntry
 
   /**
    * The IPNS name that can be used to resolve this record
@@ -253,13 +306,12 @@ export interface PublishResult {
 
 export interface IPNSResolver {
   /**
-   * Accepts a libp2p public key, a CID with the libp2p-key codec and either the
-   * identity hash (for Ed25519 and secp256k1 public keys) or a SHA256 hash (for
-   * RSA public keys), or the multihash of a libp2p-key encoded CID, or a
-   * Ed25519, secp256k1 or RSA PeerId and recursively resolves the IPNS record
-   * corresponding to that key until a value is found.
+   * Accepts a CID with the libp2p-key codec and either the identity hash (for
+   * Ed25519 and secp256k1 public keys) or a SHA256 hash (for RSA public keys),
+   * or the multihash of a libp2p-key encoded CID and recursively resolves the
+   * IPNS record corresponding to that key until a value is found.
    */
-  resolve(key: CID<unknown, 0x72> | MultihashDigest, options?: ResolveOptions): AsyncGenerator<ResolveResult>
+  resolve(key: CID | MultihashDigest, options?: IPNSResolveOptions): AsyncGenerator<IPNSResolveResult>
 }
 
 export interface IPNS {
@@ -298,7 +350,7 @@ export interface IPNS {
    * console.info(result) // { answer: ... }
    * ```
    */
-  publish(keyName: string, value: CID | PublicKey | MultihashDigest | string, options?: PublishOptions): Promise<PublishResult>
+  publish(keyName: string, value: CID | PublicKey | MultihashDigest | string, options?: PublishOptions): Promise<IPNSPublishResult>
 
   /**
    * Accepts a multihash of a public key, a libp2p-key CID containing the
@@ -307,10 +359,10 @@ export interface IPNS {
    * (e.g. the value can be parsed as a string that does not start with
    * `/ipns/`).
    */
-  resolve(name: CID<unknown, 0x72> | PublicKey | MultihashDigest | string, options?: ResolveOptions): AsyncGenerator<ResolveResult>
+  resolve(name: CID | PublicKey | MultihashDigest | string, options?: IPNSResolveOptions): AsyncGenerator<IPNSResolveResult>
 
   /**
-   * Stop republishing of an IPNS record
+   * Stop republishing of an IPNS record.
    *
    * This will delete the last signed IPNS record from the datastore.
    *
@@ -320,9 +372,6 @@ export interface IPNS {
   unpublish(keyName: string, options?: AbortOptions): Promise<void>
 }
 
-export type { IPNSRouting } from './routing/index.ts'
-export type { IPNSRecord } from './records.ts'
-
 export interface IPNSComponents {
   datastore: Datastore
   routing: Routing
@@ -367,8 +416,8 @@ export function ipns (components: IPNSComponents, options: IPNSOptions = {}): IP
 export function ipnsResolver (components: IPNSResolverComponents, options: IPNSResolverOptions = {}): IPNSResolver {
   const store = localStore(components.datastore, components.logger.forComponent('helia:ipns:local-store'))
   const routers = [
-    localStoreRouting(store),
-    helia(components.routing),
+    localStoreIPNSRouting(store),
+    heliaIPNSRouting(components.routing),
     ...(options.routers ?? [])
   ]
 

package/src/ipns/publisher.ts

@@ -1,9 +1,10 @@
 import { base36 } from 'multiformats/bases/base36'
 import { CustomProgressEvent } from 'progress-events'
-import { DEFAULT_LIFETIME_MS, DEFAULT_TTL_NS } from '../constants.ts'
+import { DEFAULT_LIFETIME_MS } from '../constants.ts'
+import { IPNSEntry } from '../pb/ipns.ts'
 import { createIPNSRecord } from '../records.ts'
-import { marshalIPNSRecord, multihashToIPNSRoutingKey, unmarshalIPNSRecord } from '../utils.ts'
-import type { PublishResult, PublishOptions } from '../index.ts'
+import { decodeExtensibleData, multihashToIPNSRoutingKey } from '../utils.ts'
+import type { IPNSPublishResult, PublishOptions } from '../index.ts'
 import type { LocalStore } from '../local-store.ts'
 import type { IPNSRouting } from '../routing/index.ts'
 import type { Keychain, PrivateKey } from '@helia/interface'
@@ -32,7 +33,7 @@ export class IPNSPublisher {
     this.routers = init.routers
   }
 
-  async publish (keyName: string, value: string, options: PublishOptions = {}): Promise<PublishResult> {
+  async publish (keyName: string, value: string, options: PublishOptions = {}): Promise<IPNSPublishResult> {
     try {
       const key = await this.#loadOrCreateKey(keyName, options)
       const digest = key.publicKey.toMultihash()
@@ -42,31 +43,43 @@ export class IPNSPublisher {
       if (await this.localStore.has(routingKey, options)) {
         // if we have published under this key before, increment the sequence number
         const { record } = await this.localStore.get(routingKey, options)
-        const existingRecord = await unmarshalIPNSRecord(routingKey, record, this.keychain, options)
-        sequenceNumber = existingRecord.sequence + 1n
+        const existingRecord = IPNSEntry.decode(record)
+        const data = decodeExtensibleData(existingRecord.data)
+        sequenceNumber = (data.Sequence ?? 0n) + 1n
       }
 
-      // convert ttl from milliseconds to nanoseconds as createIPNSRecord expects
-      const ttlNs = options.ttl != null ? BigInt(options.ttl) * 1_000_000n : DEFAULT_TTL_NS
       const lifetime = options.lifetime ?? DEFAULT_LIFETIME_MS
-      const record = await createIPNSRecord(key, value, sequenceNumber, lifetime, { ...options, ttlNs })
-      const marshaledRecord = marshalIPNSRecord(record)
+      const record = await createIPNSRecord(key, value, sequenceNumber, lifetime, {
+        ...options,
+        // convert ttl from milliseconds to nanoseconds as createIPNSRecord expects
+        ttlNs: options.ttl != null ? BigInt(options.ttl) * 1_000_000n : undefined
+      })
+      const marshaledRecord = IPNSEntry.encode(record)
 
       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: {
+            keyName,
+            lifetime
+          }
+        })
       } 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: {
+              keyName,
+              lifetime
+            }
+          })
         }))
       }
 
       return {
-        record: {
-          ...record,
-          publicKey: key.publicKey
-        },
+        record,
         name: `/ipns/${key.publicKey.toCID().toString(base36)}`,
         publicKey: key.publicKey
       }

package/src/ipns/republisher.ts

@@ -1,9 +1,10 @@
 import { Queue, repeatingTask } from '@libp2p/utils'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import { DEFAULT_REPUBLISH_CONCURRENCY, DEFAULT_REPUBLISH_INTERVAL_MS, DEFAULT_TTL_NS } from '../constants.ts'
+import { IPNSEntry } from '../pb/ipns.ts'
 import { createIPNSRecord } from '../records.ts'
-import { marshalIPNSRecord, unmarshalIPNSRecord } from '../utils.ts'
-import { shouldRepublish } from '../utils.ts'
-import type { IPNSRecord } from '../index.ts'
+import { decodeExtensibleData, shouldRepublish } from '../utils.ts'
+import type { IPNSRecordData } from '../index.ts'
 import type { LocalStore } from '../local-store.ts'
 import type { IPNSRouting } from '../routing/index.ts'
 import type { Keychain, PrivateKey } from '@helia/interface'
@@ -78,7 +79,7 @@ export class IPNSRepublisher {
     })
 
     try {
-      const recordsToRepublish: Array<{ routingKey: Uint8Array, record: IPNSRecord }> = []
+      const recordsToRepublish: Array<{ routingKey: Uint8Array, record: IPNSEntry }> = []
       let listed = 0
 
       // Find all records using the localStore.list method
@@ -91,21 +92,38 @@ export class IPNSRepublisher {
           this.log('no metadata found for record %b, skipping', routingKey)
           continue
         }
-        let ipnsRecord: IPNSRecord
+
+        let ipnsRecord: IPNSEntry
+
         try {
-          ipnsRecord = await unmarshalIPNSRecord(routingKey, record, this.keychain, options)
-        } catch (err: any) {
-          this.log.error('error unmarshaling record - %e', err)
+          ipnsRecord = IPNSEntry.decode(record)
+        } catch (err) {
+          this.log.trace('skipping invalid record %b because could not decode', routingKey)
+          continue
+        }
+
+        if (ipnsRecord.data == null) {
+          this.log.trace('skipping record %b because data was missing', routingKey)
+          continue
+        }
+
+        let data: IPNSRecordData
+
+        try {
+          data = decodeExtensibleData(ipnsRecord.data)
+        } catch {
+          this.log.trace('skipping record %b because could not decode data', routingKey)
           continue
         }
 
         // Only republish records that are within the DHT or record expiry threshold
-        if (!shouldRepublish(ipnsRecord, created)) {
+        if (!shouldRepublish(created, new Date(uint8ArrayToString(data.Validity)))) {
           this.log.trace('skipping record %b within republish threshold', routingKey)
           continue
         }
-        const sequenceNumber = ipnsRecord.sequence + 1n
-        const ttlNs = ipnsRecord.ttl ?? DEFAULT_TTL_NS
+
+        const sequenceNumber = data.Sequence + 1n
+        const ttlNs = data.TTL ?? DEFAULT_TTL_NS
         let privKey: PrivateKey
 
         try {
@@ -116,7 +134,7 @@ export class IPNSRepublisher {
         }
 
         try {
-          const updatedRecord = await createIPNSRecord(privKey, ipnsRecord.value, sequenceNumber, metadata.lifetime, {
+          const updatedRecord = await createIPNSRecord(privKey, uint8ArrayToString(data.Value), sequenceNumber, metadata.lifetime, {
             ...options,
             ttlNs
           })
@@ -137,7 +155,7 @@ export class IPNSRepublisher {
         // Add job to queue to republish the record to all routers
         queue.add(async () => {
           try {
-            const marshaledRecord = marshalIPNSRecord(record)
+            const marshaledRecord = IPNSEntry.encode(record)
             await Promise.all(
               this.routers.map(r => r.put(routingKey, marshaledRecord, options))
             )