@wovin/core 0.0.0-ciao-mobx-955482e8

package/src/ipfs/car.ts

@@ -0,0 +1,291 @@
+import { CarReader, CarWriter } from '@ipld/car'
+import * as dagJson from '@ipld/dag-json'
+import { Logger } from 'besonders-logger'
+import { BlockView, CID } from 'multiformats'
+import { sortApplogsByTs } from '../applog/applog-utils.ts'
+import { Applog, ApplogArrayMaybeEncrypted, CidString } from '../applog/datom-types.ts'
+import { unchunkApplogsBlock } from '../pubsub/snap-push.ts'
+import { SnapBlockLogs, SnapBlockLogsOrChunks, SnapRootBlock } from '../pubsub/pubsub-types.ts'
+import { areCidsEqual, containsCid } from './ipfs-utils.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export type CIDForCar = CID // Exclude<Parameters<(typeof CarWriter)['create']>[0], void>
+export type BlockForCar = Parameters<CarWriter['put']>[0]
+
+export interface BlockStoreish {
+	get(cid: CID): PromiseLike<Uint8Array> // (i) not using decoded version to be similar to blockstore-idb
+}
+
+export interface DecodedCar {
+	rootCID: CID
+	// blocks: Map<CidString, any>
+	blockStore: BlockStoreish
+}
+
+/** Warning: unsorted & maybe encrypted */
+export async function decodePubFromCar(car: CarReader) {
+	const decoded = await getBlocksOfCar(car)
+	return await decodePubFromBlocks(decoded)
+}
+
+export async function decodePubFromBlocks(
+	{ rootCID, blockStore }: DecodedCar,
+	_recursionTrace: CID[] = [],  // DEPRECATED: kept for API compat, unused in iterative version
+	stopAtCID?: CID  // NEW: stop iteration when we hit this CID
+) {
+	if (!rootCID || !blockStore) {
+		throw ERROR('Empty roots/blocks', { rootCID, blockStore })
+	}
+
+	let allApplogs: ApplogArrayMaybeEncrypted = []
+	let firstInfo: { logs: CID[] } | null = null
+	let currentCID: CID | undefined = rootCID
+	const visited = new Set<string>()  // Loop detection (replaces recursionTrace)
+	let applogsCID: CID | null = null  // From first snapshot only
+
+	while (currentCID) {
+		const cidStr = currentCID.toString()
+
+		// Loop detection
+		if (visited.has(cidStr)) {
+			throw ERROR('[decodePubFromBlocks] pub chain has a loop', {
+				currentCID: cidStr,
+				visited: [...visited]
+			})
+		}
+		visited.add(cidStr)
+
+		// Decode current snapshot
+		const root = (await getDecodedBlock(blockStore, currentCID)) as SnapRootBlock
+		VERBOSE(`[decodePubFromBlocks] root:`, cidStr, root, { blockStore })
+		if (!root) {
+			throw ERROR('[decodePubFromBlocks] root not found in blockStore', { blockStore, currentCID: cidStr })
+		}
+
+		// Decode applogs for this snapshot
+		let pubLogsArray: CID[]
+		if (root?.info) {
+			// New(er) format
+			if (!applogsCID) applogsCID = root.applogs  // Save from first snapshot
+			const applogsBlock = (await getDecodedBlock(blockStore, root.applogs)) as SnapBlockLogsOrChunks
+			pubLogsArray = await unchunkApplogsBlock(applogsBlock, blockStore)
+			// Info only from first (most recent) snapshot
+			if (!firstInfo) {
+				firstInfo = (await getDecodedBlock(blockStore, root.info)) as SnapBlockLogs
+				DEBUG(`new format - infoLogs`, firstInfo.logs.map(l => ({ [l.toString()]: l })))
+			}
+			// TODO: verify signatures
+		} else {
+			// Old format
+			pubLogsArray = root.applogs as any as CID[]
+		}
+
+		const resolveLogFromCidLink = async (cidOrLink: CID) => {
+			const cid = cidOrLink
+			const applog = (await getDecodedBlock(blockStore, cid)) as Applog
+			if (!applog) {
+				ERROR(`Could not find applog CID in pub blocks:`, cid.toString(), { cid, root, blockStore })
+				throw new Error(`Could not find applog CID in pub blocks: ${cid.toString()}`)
+			}
+			if ((applog.pv as any) instanceof CID) applog.pv = (applog.pv as any as CID).toV1().toString()
+			return {
+				...applog,
+				cid: cid.toV1().toString(),
+			}
+		}
+
+		const snapshotApplogs = await Promise.all(pubLogsArray.map(resolveLogFromCidLink))
+		allApplogs = allApplogs.concat(snapshotApplogs)
+
+		// Check if we should stop
+		if (!root.prev) {
+			break  // End of chain
+		}
+		if (stopAtCID && areCidsEqual(root.prev, stopAtCID)) {
+			DEBUG('[decodePubFromBlocks] stopping at stopAtCID:', stopAtCID.toString())
+			break  // Reached already-pulled snapshot
+		}
+
+		// Verify prev exists before continuing
+		const prevBytes = await blockStore.get(root.prev)
+		if (!prevBytes) {
+			throw ERROR('[decodePubFromBlocks] prev snapshot missing from blockStore', {
+				currentCID: cidStr,
+				prev: root.prev.toString(),
+				stopAtCID: stopAtCID?.toString(),
+				visited: [...visited]
+			})
+		}
+
+		currentCID = root.prev  // Move to previous snapshot
+	}
+
+	const result = {
+		cid: rootCID,
+		info: firstInfo ? {
+			...firstInfo,
+			logs: await Promise.all(firstInfo.logs.map(async (cidOrLink: CID) => {
+				const cid = cidOrLink
+				const applog = (await getDecodedBlock(blockStore, cid)) as Applog
+				if (!applog) {
+					ERROR(`Could not find info log CID in pub blocks:`, cid.toString(), { cid, blockStore })
+					throw new Error(`Could not find info log CID in pub blocks: ${cid.toString()}`)
+				}
+				if ((applog.pv as any) instanceof CID) applog.pv = (applog.pv as any as CID).toV1().toString()
+				return {
+					...applog,
+					cid: cid.toV1().toString(),
+				}
+			})),
+		} : null,
+		applogsCID,
+		applogs: allApplogs,
+	}
+	DEBUG('[decodePubFromBlocks] result:', result, { rootCID: rootCID.toString(), blockStore, applogs: allApplogs })
+	return result
+}
+
+export async function getBlocksOfCar(car: CarReader) {
+	const rootsFromCar = await car.getRoots()
+	const roots = rootsFromCar.map(c => ((typeof c.toV1 === 'function') ? c : CID.decode(c.bytes)).toV1().toString() as CidString) // HACK
+	const blocks = new Map<CidString, any>()
+	for await (const { cid: cidFromCarblocks, bytes } of car.blocks()) {
+		const cid = (typeof cidFromCarblocks.toV1 === 'function') ? cidFromCarblocks : CID.decode(cidFromCarblocks.bytes)
+		VERBOSE({ cidFromCarblocks, cid })
+		// blocks.set(cid.toV1().toString(), dagJson.decode(bytes)) // HACK: tried using CID as map key, but because it's based on referential equality it's not working
+		blocks.set(cid.toV1().toString(), bytes) // HACK: tried using CID as map key, but because it's based on referential equality it's not working
+	}
+	if (roots.length !== 1) {
+		WARN('Unexpected roots count:', roots)
+	}
+	return {
+		rootCID: CID.parse(roots[0]),
+		blockStore: {
+			get: (cid) => blocks.get(cid.toV1().toString()),
+		},
+	} satisfies DecodedCar
+}
+export async function getDecodedBlock(blockStore: BlockStoreish, cid: CID) {
+	try {
+		var blob = await blockStore.get(cid)
+		if (!blob) {
+			WARN('returning null')
+			return null // I don't think this ever happens actually
+		}
+	} catch (err) {
+		if ((err as any).message === 'Not Found') return null
+		throw err
+	}
+	return dagJson.decode(blob)
+}
+
+// make out in the car... been a while but also sounds nice
+export async function makeCarOut(roots: CIDForCar, blocks: BlockForCar[]) {
+	const { writer, out } = CarWriter.create(Array.isArray(roots) ? roots : [roots])
+
+	// add the blocks to the CAR and close it
+	VERBOSE(`Writing ${blocks.length} blocks to CAR`, { roots, blocks })
+	blocks.forEach(b => writer.put(b))
+	writer.close()
+	// VERBOSE(`Wrote ${blocks.length} blocks to CAR`, writer)
+	return out
+} /** create a new CarWriter, with the encoded block as the root */
+
+// export async function makeCarReader(roots: CIDForCar, blocks: BlockForCar[]) {
+// 	const out = await makeCarOut(roots, blocks)
+
+// 	// create a new CarReader we can hand to web3.storage.putCar
+// 	const reader = await CarReader.fromIterable(out)
+// 	VERBOSE(`CAR reader`, reader)
+// 	return reader
+// } /** create a new CarWriter, with the encoded block as the root */
+
+export async function makeCarBlob(roots: CIDForCar, blocks: BlockForCar[]) {
+	const carOut = await makeCarOut(roots, blocks)
+	const chunks = []
+	for await (const chunk of carOut) {
+		chunks.push(chunk)
+	}
+	const blob = new Blob(chunks)
+	return blob
+}
+export async function carFromBlob(blob: Blob | File): Promise<CarReader> {
+	return CarReader.fromBytes(new Uint8Array(await blob.arrayBuffer()))
+}
+
+function extractCids(value: unknown): CID[] {
+	if (value instanceof CID) return [value]
+	if (Array.isArray(value)) return value.flatMap(extractCids)
+	if (value && typeof value === 'object') return Object.values(value).flatMap(extractCids)
+	return []
+}
+
+const MAX_COLLECT_BLOCKS = 1_000_000
+
+export async function collectDagBlocks(
+	startCID: CID,
+	blockStore: BlockStoreish,
+): Promise<BlockForCar[]> {
+	const visited = new Set<string>()
+	const blocks: BlockForCar[] = []
+	const queue: CID[] = [startCID]
+
+	while (queue.length > 0) {
+		if (blocks.length >= MAX_COLLECT_BLOCKS) {
+			WARN(`[collectDagBlocks] hit ${MAX_COLLECT_BLOCKS} block limit, returning partial result`)
+			break
+		}
+
+		const cid = queue.shift()!
+		const cidStr = cid.toString()
+		if (visited.has(cidStr)) continue
+		visited.add(cidStr)
+
+		let bytes: Uint8Array
+		try {
+			bytes = await blockStore.get(cid)
+		} catch {
+			WARN(`[collectDagBlocks] block not found: ${cidStr}, stopping this branch`)
+			continue
+		}
+		if (!bytes) {
+			WARN(`[collectDagBlocks] block not found: ${cidStr}, stopping this branch`)
+			continue
+		}
+
+		blocks.push({ cid, bytes })
+
+		if (blocks.length % 1000 === 0) {
+			LOG(`[collectDagBlocks] collected ${blocks.length} blocks...`)
+		}
+
+		try {
+			const decoded = dagJson.decode(bytes)
+			const childCids = extractCids(decoded)
+			for (const child of childCids) {
+				if (!visited.has(child.toString())) {
+					queue.push(child)
+				}
+			}
+		} catch {
+			// Not dag-json — leaf block, no children to walk
+		}
+	}
+
+	DEBUG(`[collectDagBlocks] collected ${blocks.length} blocks from ${startCID.toString()}`)
+	return blocks
+}
+
+export function streamReaderToIterable(bodyReader: ReadableStreamDefaultReader<Uint8Array>): AsyncIterable<Uint8Array> {
+	return (async function*() {
+		while (true) {
+			const { done, value } = await bodyReader.read()
+			VERBOSE(`[car] chunk`, { done, value })
+			if (done) {
+				break
+			}
+			yield value
+		}
+	})()
+}

package/src/ipfs/fetch-snapshot-chain.ts

@@ -0,0 +1,135 @@
+import { CarReader } from '@ipld/car'
+import * as dagJson from '@ipld/dag-json'
+import { Logger } from 'besonders-logger'
+import { CID } from 'multiformats/cid'
+import type { SnapRootBlock } from '../pubsub/pubsub-types.ts'
+import { areCidsEqual } from './ipfs-utils.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export interface BlockStoreForFetch {
+    get(cid: CID): Promise<Uint8Array | undefined>
+    put(cid: CID, bytes: Uint8Array): Promise<void>
+}
+
+export interface FetchChainOptions {
+    rootCID: CID
+    stopAtCID?: CID  // Stop when we hit this CID (lastCID from subscription)
+    stopAtCounter?: number  // Stop when we reach this counter (walking backwards)
+    fetchBlock: (cid: CID) => Promise<CarReader>  // dag-scope=block
+    fetchAll: (cid: CID) => Promise<CarReader>    // dag-scope=all
+    maxDepth?: number
+}
+
+export interface FetchChainResult {
+    rootCID: CID
+    blockStore: BlockStoreForFetch
+    /** Serializable blocks array for worker boundary crossing */
+    blocks: [string, Uint8Array][]
+    snapshotCount: number
+    counterRange?: { minCounter: number; maxCounter: number }
+}
+
+/**
+ * Fetches a snapshot chain iteratively, stopping at stopAtCID.
+ * Uses 3 requests per snapshot: root(block), applogs(all), info(all).
+ * This avoids the gateway's dag-scope=all following prev links recursively.
+ */
+export async function fetchSnapshotChainUntil(options: FetchChainOptions): Promise<FetchChainResult> {
+    const { rootCID, stopAtCID, stopAtCounter, fetchBlock, fetchAll, maxDepth = 100 } = options
+    const blockStore = createMemoryBlockStore()
+    const visited = new Set<string>()  // Loop detection for fetch
+    let currentCID: CID | undefined = rootCID
+    let snapshotCount = 0
+    let minCounter = Infinity
+    let maxCounter = -Infinity
+
+    while (currentCID && snapshotCount < maxDepth) {
+        const cidStr = currentCID.toString()
+
+        // Loop detection
+        if (visited.has(cidStr)) {
+            throw ERROR('[fetchSnapshotChain] snapshot chain has a loop', { currentCID: cidStr, visited: [...visited] })
+        }
+        visited.add(cidStr)
+
+        // Check stop condition BEFORE fetching content
+        if (stopAtCID && areCidsEqual(currentCID, stopAtCID)) {
+            DEBUG('[fetchSnapshotChain] reached stopAtCID, stopping', stopAtCID.toString())
+            break  // We've reached the last pulled snapshot - don't fetch it again
+        }
+
+        // 1. Fetch root block only (dag-scope=block)
+        DEBUG('[fetchSnapshotChain] fetching root block', cidStr)
+        const rootCar = await fetchBlock(currentCID)
+        await addCarBlocksToStore(rootCar, blockStore)
+
+        // Parse root to get applogs, info, prev CIDs
+        const rootBytes = await blockStore.get(currentCID)
+        if (!rootBytes) {
+            throw ERROR('[fetchSnapshotChain] root block not in store after fetch', { currentCID: cidStr })
+        }
+        const root = dagJson.decode(rootBytes) as SnapRootBlock
+
+        // Track counter range
+        if (typeof root.prevCounter === 'number') {
+            minCounter = Math.min(minCounter, root.prevCounter)
+            maxCounter = Math.max(maxCounter, root.prevCounter)
+        }
+
+        // Stop condition based on counter
+        if (stopAtCounter !== undefined && typeof root.prevCounter === 'number' && root.prevCounter <= stopAtCounter) {
+            DEBUG('[fetchSnapshotChain] reached stopAtCounter', { stopAtCounter, prevCounter: root.prevCounter })
+            break
+        }
+
+        // 2. Fetch applogs with dag-scope=all (gets applogs block + all linked applog blocks)
+        DEBUG('[fetchSnapshotChain] fetching applogs', root.applogs.toString())
+        const applogsCar = await fetchAll(root.applogs)
+        await addCarBlocksToStore(applogsCar, blockStore)
+
+        // 3. Fetch info with dag-scope=all (gets info block + all linked info log blocks)
+        DEBUG('[fetchSnapshotChain] fetching info', root.info.toString())
+        const infoCar = await fetchAll(root.info)
+        await addCarBlocksToStore(infoCar, blockStore)
+
+        snapshotCount++
+        currentCID = root.prev  // Move to previous snapshot
+    }
+
+    DEBUG('[fetchSnapshotChain] done', { snapshotCount, rootCID: rootCID.toString() })
+    return {
+        rootCID,
+        blockStore,
+        blocks: blockStore.getBlocksArray(),
+        snapshotCount,
+        counterRange: minCounter !== Infinity ? { minCounter, maxCounter } : undefined,
+    }
+}
+
+async function addCarBlocksToStore(car: CarReader, store: BlockStoreForFetch) {
+    for await (const { cid, bytes } of car.blocks()) {
+        const validCid = typeof cid.toV1 === 'function' ? cid : CID.decode(cid.bytes)
+        await store.put(validCid, bytes)
+    }
+}
+
+interface MemoryBlockStoreWithBlocks extends BlockStoreForFetch {
+    /** Get all blocks as serializable array */
+    getBlocksArray(): [string, Uint8Array][]
+}
+
+function createMemoryBlockStore(): MemoryBlockStoreWithBlocks {
+    const blocks = new Map<string, Uint8Array>()
+    return {
+        async get(cid: CID) {
+            return blocks.get(cid.toV1().toString())
+        },
+        async put(cid: CID, bytes: Uint8Array) {
+            blocks.set(cid.toV1().toString(), bytes)
+        },
+        getBlocksArray() {
+            return Array.from(blocks.entries())
+        },
+    }
+}

package/src/ipfs/ipfs-utils.ts

@@ -0,0 +1,132 @@
+import * as dagJson from '@ipld/dag-json'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { Logger } from 'besonders-logger'
+import { CID, digest as Digest } from 'multiformats'
+import { encode as multiformatsEncode } from 'multiformats/block'
+// import { encode } from 'multiformats/block';
+import { Applog, ApplogEncNoCid, ApplogNoCid, ApplogOfSomeSort, CidString, IpnsString, isEncryptedApplog } from '../applog/datom-types.ts'
+
+import { base36 } from 'multiformats/bases/base36'
+import { sha256 as sha265Hasher } from 'multiformats/hashes/sha2'
+
+/* THIS FILE SHOULD NOT DEPEND ON UI STUFF, SO THAT TESTS CAN RUN WITH MINIMAL DEPENDENCIES */
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export const MULTICODEC_IPNS_KEY = 0x72
+
+export function prepareForPub(log: ApplogOfSomeSort, without: string[] = ['cid']) {
+	if (!log) throw ERROR('falsy log', log)
+	let cid = (log as Applog).cid
+	if (isEncryptedApplog(log)) {
+		if (!cid) cid = getCidSync(encodeBlock(log as ApplogEncNoCid).bytes).toString()
+		WARN('preparing an encrypted applog - really?')
+		return { log, cid }
+	}
+	const logWithout = {}
+	for (let [key, val] of Object.entries(log)) {
+		if (val === undefined) {
+			WARN(`log.${key} is undefined, which is not allowed - encoding as null`, log)
+			val = null
+		}
+		if (!without.includes(key)) {
+			logWithout[key] = val // && key === 'pv' ? CID.parse(val) : val //HACK: disabled until clarified: https://discuss.ipfs.tech/t/pin-dag-with-open-ends/17612
+		} else {
+			VERBOSE('excluding app log', { key, val })
+		}
+	}
+	return { log: logWithout as Applog, cid }
+}
+
+export function encodeApplogAndGetCid(log: ApplogNoCid) {
+	return getCidSync(encodeApplog(log).bytes)
+}
+export function encodeApplog(log: ApplogNoCid | ApplogEncNoCid): { bytes: dagJson.ByteView<any>; cid: CID } {
+	return encodeBlock(prepareForPub(log)?.log)
+}
+
+export function getCidSync(bytes: dagJson.ByteView<any>) {
+	// Hacky way to use a sync sha265 lib to create a CID - code inspired by https://github.com/multiformats/js-multiformats#multihash-hashers
+	const hash = sha256(bytes)
+	const digest = Digest.create(sha265Hasher.code, hash)
+	const cid = CID.create(1, dagJson.code, digest)
+	VERBOSE(`[getCidSync]`, { bytes, hash, digest, cid })
+	return cid
+}
+/** encode the json object into an IPLD block */
+export function encodeBlock(jsonObject: any): { bytes: dagJson.ByteView<any>; cid: CID } {
+	DEBUG('[encodeBlock]', jsonObject)
+	try {
+		const byteView = dagJson.encode(jsonObject)
+		return { bytes: byteView, cid: getCidSync(byteView) }
+	} catch (err) {
+		throw ERROR('[encodeBlock] failed to encode:', jsonObject, err)
+	}
+}
+
+export async function encodeBlockOriginal(jsonObject: any) {
+	// HACK re-added this to verify the sync variant is sane
+	const encoded = await multiformatsEncode({ value: jsonObject, codec: dagJson, hasher: sha265Hasher })
+	const syncVariant = encodeBlock(jsonObject)
+	if (syncVariant.cid.toString() !== encoded.cid.toString()) {
+		ERROR(`[encodeBlockOriginal] sync cid mismatch`, { jsonObject, encoded, syncVariant })
+	}
+	return encoded
+}
+
+export function tryParseCID(cidString: CidString) {
+	let cid: CID | null = null
+	let errors = []
+	try {
+		cid = CID.parse(cidString)
+	} catch (err) {
+		VERBOSE(`[retrieveThread] couldn't parse pubID with default base`)
+		errors.push(err)
+	}
+	if (!cid) {
+		try {
+			cid = CID.parse(cidString, base36) // e.g. for IPNS
+		} catch (err) {
+			VERBOSE(`[retrieveThread] couldn't parse pubID with base36`)
+			errors.push(err)
+		}
+	}
+	return {
+		cid,
+		errors: cid ? null : errors, // we only care about errors if we failed to parse
+		isIpns: cid && isIpnsKeyCid(cid),
+	}
+}
+export function isIpnsKeyCid(cid: CID) {
+	return cid.code === MULTICODEC_IPNS_KEY
+}
+
+export function cidToString(cid: CID) {
+	if (cid.code == MULTICODEC_IPNS_KEY) {
+		return toIpnsString(cid)
+	} else {
+		return cid.toString()
+	}
+}
+export function toIpnsString(cid: CID) {
+	if (cid.code !== MULTICODEC_IPNS_KEY) throw ERROR(`Not an IPNS cid (${cid.code}):`, cid.toString())
+	return cid.toString(base36) as IpnsString
+}
+export function ensureValidCIDinstance(cidOrStringA: CID | CidString) {
+	return typeof cidOrStringA === 'string'
+		? CID.parse(cidOrStringA)
+		: typeof cidOrStringA.toV1 != 'function'
+		? CID.decode(cidOrStringA.bytes)
+		: cidOrStringA
+}
+export function areCidsEqual(cidOrStringA: CID | CidString, cidOrStringB: CID | CidString) {
+	if (!cidOrStringA || !cidOrStringB) throw new Error(`[areCidsEqual] invalid params: ${cidOrStringA}, ${cidOrStringB}`)
+	if (cidOrStringA === cidOrStringB) return true // shortcut if both are strings
+	const cidA = ensureValidCIDinstance(cidOrStringA)
+	const cidB = ensureValidCIDinstance(cidOrStringB)
+	return cidA.toV1().toString() === cidB.toV1().toString()
+}
+export function containsCid(list: (CID | CidString)[] | Set<CidString>, needle: CID | CidString) {
+	if (list instanceof Set) return list.has(typeof needle === 'string' ? needle : needle.toV1().toString()) // ? what if the CidString is a different form? (parse and format would cost performance)
+	return list.some(cidOrString => areCidsEqual(cidOrString, needle))
+}

package/src/ipfs.ts

@@ -0,0 +1,3 @@
+export * from './ipfs/car.ts'
+export * from './ipfs/ipfs-utils.ts'
+export * from './ipfs/fetch-snapshot-chain.ts'

package/src/ipns/ipns-record.ts

@@ -0,0 +1,115 @@
+import { createIPNSRecord, marshalIPNSRecord, unmarshalIPNSRecord } from 'ipns'
+import { privateKeyFromRaw } from '@libp2p/crypto/keys'
+import { base36 } from 'multiformats/bases/base36'
+import { base64pad } from 'multiformats/bases/base64'
+import type { CID } from 'multiformats/cid'
+
+export interface SignedIPNSRecord {
+	recordBytes: Uint8Array   // marshalled protobuf, signed — the wire format
+	ipnsName: string          // k51... string
+	value: string             // /ipfs/<cid>
+	sequence: bigint
+}
+
+/** Derive IPNS name string (k51...) from Ed25519 private key bytes */
+export function ipnsNameFromPrivateKey(privKeyBytes: Uint8Array): string {
+	const privKey = privateKeyFromRaw(privKeyBytes)
+	return privKey.publicKey.toCID().toString(base36)
+}
+
+/**
+ * Create a signed IPNS record (protobuf wire format).
+ * Same bytes can be published to any naming service.
+ */
+export async function createSignedIPNSRecord(
+	privateKey: Uint8Array,
+	cid: CID,
+	sequence: bigint,
+	lifetimeMs = 365 * 24 * 60 * 60 * 1000, // 1 year
+): Promise<SignedIPNSRecord> {
+	const privKey = privateKeyFromRaw(privateKey)
+	const value = `/ipfs/${cid.toV1()}`
+	const record = await createIPNSRecord(privKey, value, sequence, lifetimeMs)
+	const recordBytes = marshalIPNSRecord(record)
+	const ipnsName = privKey.publicKey.toCID().toString(base36)
+	return { recordBytes, ipnsName, value, sequence }
+}
+
+export { unmarshalIPNSRecord }
+
+/** A target that can receive a signed IPNS record */
+export interface IPNSPublishTarget {
+	name: string
+	publish(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+}
+
+/**
+ * Resolve current IPNS sequence number from a naming service.
+ * Returns null if the name was never published (404).
+ * Throws on network/server errors.
+ */
+export async function resolveIPNSSequence(
+	nameServiceUrl: string,
+	ipnsName: string,
+): Promise<bigint | null> {
+	const url = `${nameServiceUrl}/name/${ipnsName}`
+	let response: Response
+	try {
+		response = await fetch(url)
+	} catch (err) {
+		throw new Error(`Network error resolving IPNS ${ipnsName}: ${err}`)
+	}
+
+	if (response.status === 404) return null
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} resolving IPNS ${ipnsName}: ${response.statusText}`)
+	}
+
+	const { record, value } = await response.json()
+	if (!record && !value) return null // never published
+
+	// If raw record is available, unmarshal to get sequence
+	if (record) {
+		const bytes = base64pad.baseDecode(record)
+		const entry = unmarshalIPNSRecord(bytes)
+		return entry.sequence
+	}
+
+	// Some servers return value but not raw record — can't get sequence
+	return 0n
+}
+
+/**
+ * Create a signed IPNS record and publish to all configured targets.
+ * Resolves sequence from sequenceServiceUrl, creates record once, fans out.
+ * Throws if ALL targets fail; warns on partial failure.
+ */
+export async function publishIPNSRecord(
+	privateKey: Uint8Array,
+	cid: CID,
+	targets: IPNSPublishTarget[],
+	sequenceServiceUrl = 'https://name.web3.storage',
+): Promise<SignedIPNSRecord> {
+	const ipnsName = ipnsNameFromPrivateKey(privateKey)
+	const currentSeq = await resolveIPNSSequence(sequenceServiceUrl, ipnsName)
+	const sequence = currentSeq != null ? currentSeq + 1n : 0n
+	const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
+
+	const results = await Promise.allSettled(
+		targets.map(t => t.publish(ipnsName, signed.recordBytes))
+	)
+	const failures = results
+		.map((r, i) => ({ r, name: targets[i].name }))
+		.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
+
+	if (failures.length > 0 && failures.length < targets.length) {
+		// Partial failure — log but don't throw
+		for (const { r, name } of failures) {
+			console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
+		}
+	} else if (failures.length === targets.length) {
+		throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`)
+	}
+
+	return signed
+}

package/src/ipns.ts

@@ -0,0 +1 @@
+export * from './ipns/ipns-record.ts'