@wovin/core 0.2.2 → 0.3.2

package/src/ipns/ipns-record.ts

@@ -5,9 +5,9 @@ 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>
+	recordBytes: Uint8Array // marshalled protobuf, signed — the wire format
+	ipnsName: string // k51... string
+	value: string // /ipfs/<cid>
 	sequence: bigint
 }
 
@@ -37,16 +37,31 @@ export async function createSignedIPNSRecord(
 
 export { unmarshalIPNSRecord }
 
-/** A target that can receive a signed IPNS record */
+/**
+ * A target that can receive a signed IPNS record, advertise its current
+ * sequence, or both.
+ *
+ * - `publish` is called by `publishIPNSRecord` to actually store the record
+ *   on the target's backing service. Targets without `publish` are skipped
+ *   during the fan-out (e.g. a sequence-only source).
+ * - `resolveSequence` is consulted by `publishIPNSRecord` to compute the
+ *   next IPNS sequence. The first target to return a value (including
+ *   `null` for "never published") wins. Throw to indicate a transient
+ *   error — the caller will try the next target.
+ *
+ * Most real targets (e.g. a storage connector) provide both. A simple
+ * "track sequence in localStorage" target only needs `resolveSequence`.
+ */
 export interface IPNSPublishTarget {
 	name: string
-	publish(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+	publish?(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+	resolveSequence?(ipnsName: string): Promise<bigint | null>
 }
 
 /**
- * Resolve current IPNS sequence number from a naming service.
+ * Resolve the current IPNS sequence from a generic naming service.
  * Returns null if the name was never published (404).
- * Throws on network/server errors.
+ * Throws on network/server errors so the caller can try a different target.
  */
 export async function resolveIPNSSequence(
 	nameServiceUrl: string,
@@ -75,41 +90,155 @@ export async function resolveIPNSSequence(
 		return entry.sequence
 	}
 
-	// Some servers return value but not raw record — can't get sequence
+	// Server only returned a value, no raw record — can't know the exact sequence.
+	// Most services still accept this as "previous published"; treat as seq=0n.
 	return 0n
 }
 
+/** Regex to detect Kubo IPNS sequence conflict in error messages */
+const SEQ_CONFLICT_RE = /existing IPNS record has sequence (\d+) >= new record sequence (\d+)/
+
+/**
+ * Options for {@link publishIPNSRecord}.
+ */
+export interface PublishIPNSRecordOptions {
+	/**
+	 * Max number of times to bump the sequence on "existing >= new" conflict.
+	 * Defaults to 3. Each bump re-signs the record with a higher sequence
+	 * and retries all targets.
+	 */
+	maxSequenceBumps?: number
+}
+
 /**
  * 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.
+ *
+ * Sequence resolution: walks `targets` in order asking each one with a
+ * `resolveSequence` method. The first target to successfully return a value
+ * (including `null` for "never published") determines the next sequence.
+ * If every target throws or none supports `resolveSequence`, falls back to 0n.
+ *
+ * Publish fan-out: only targets with a `publish` method are called.
+ * Throws if every publish-capable target fails; partial failures are logged.
+ *
+ * **Sequence-coherence retry:** if a publish target rejects with the Kubo
+ * "existing IPNS record has sequence X >= new record sequence Y" error,
+ * the function parses `X`, bumps the sequence to `max(X + 1n, Y + 1n)`,
+ * re-signs the record, and retries (up to `maxSequenceBumps` times).
+ * This is the "increment and clobber" mechanism that recovers from
+ * sequence drift without requiring server-side `--force` support.
  */
 export async function publishIPNSRecord(
 	privateKey: Uint8Array,
 	cid: CID,
 	targets: IPNSPublishTarget[],
-	sequenceServiceUrl = 'https://name.web3.storage',
+	options?: PublishIPNSRecordOptions,
 ): 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)
+	const maxBumps = options?.maxSequenceBumps ?? 3
+
+	const publishTargets = targets.filter(t => typeof t.publish === 'function')
+	if (publishTargets.length === 0) {
+		throw new Error('No publish-capable targets supplied to publishIPNSRecord')
+	}
+
+	let sequence: bigint | undefined
+	let bumpFloor: bigint | undefined
+
+	for (let attempt = 0; ; attempt++) {
+		// Compute next sequence on first pass or after a conflict bump
+		if (sequence === undefined) {
+			sequence = await pickNextSequence(ipnsName, targets)
+		}
+		if (bumpFloor !== undefined) {
+			// bumpFloor was set on previous attempt from a conflict error
+			if (bumpFloor > sequence) sequence = bumpFloor
+			bumpFloor = undefined
+		}
+
+		const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
+
+		const results = await Promise.allSettled(
+			publishTargets.map(t => t.publish!(ipnsName, signed.recordBytes)),
+		)
+		const failures = results
+			.map((r, i) => ({ r, name: publishTargets[i].name }))
+			.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
+
+		// All succeeded — done
+		if (failures.length === 0) {
+			return signed
+		}
+
+		// Check if any failure is a sequence conflict we can recover from
+		const conflictReasons = failures.filter(({ r }) =>
+			SEQ_CONFLICT_RE.test(typeof r.reason === 'string' ? r.reason : String(r.reason)),
+		)
+
+		if (conflictReasons.length > 0 && attempt < maxBumps) {
+			// Parse the highest existing sequence from each conflict error
+			let bump = sequence
+			for (const { r } of conflictReasons) {
+				const msg = typeof r.reason === 'string' ? r.reason : String(r.reason)
+				const m = msg.match(SEQ_CONFLICT_RE)
+				if (m) {
+					const existing = BigInt(m[1])
+					if (existing >= bump) bump = existing + 1n
+				}
+			}
+			if (bump > sequence) {
+				console.warn(
+					`[publishIPNSRecord] Sequence conflict: server seq ${bump - 1n} >= current ${sequence}, ` +
+					`bumping to ${bump} (attempt ${attempt + 1}/${maxBumps})`,
+				)
+				sequence = bump
+				continue
+			}
 		}
-	} else if (failures.length === targets.length) {
-		throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`)
+
+		// Partial failure (some targets succeeded) — log and return the signed record
+		if (failures.length < publishTargets.length) {
+			for (const { r, name } of failures) {
+				console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
+			}
+			return signed
+		}
+
+		// Every publish-capable target failed and we cannot recover
+		if (conflictReasons.length > 0) {
+			throw new Error(
+				`IPNS sequence conflict not resolved after ${Math.min(attempt + 1, maxBumps)} bumps. ` +
+				`All publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`,
+			)
+		}
+		throw new Error(
+			`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`,
+		)
 	}
+}
 
-	return signed
+/**
+ * Walk targets, asking each to resolve the current IPNS sequence. First success wins.
+ * Falls back to 0n if no target can answer.
+ */
+async function pickNextSequence(
+	ipnsName: string,
+	targets: IPNSPublishTarget[],
+): Promise<bigint> {
+	const capable = targets.filter(t => typeof t.resolveSequence === 'function')
+	if (capable.length === 0) {
+		return 0n
+	}
+
+	for (const target of capable) {
+		try {
+			const current = await target.resolveSequence!(ipnsName)
+			return current == null ? 0n : current + 1n
+		} catch (err) {
+			console.warn(`[publishIPNSRecord] target '${target.name}' sequence resolve failed:`, err)
+		}
+	}
+
+	console.warn(`[publishIPNSRecord] no target could resolve sequence for ${ipnsName} — starting at 0n`)
+	return 0n
 }

package/src/ipns/ipns-w3name.ts

@@ -0,0 +1,207 @@
+import type { IPNSPublishTarget } from '@wovin/core/ipns'
+import { Logger } from 'besonders-logger'
+import { base64pad } from 'multiformats/bases/base64'
+import { resolveIPNSSequence, unmarshalIPNSRecord } from './ipns-record.ts'
+import { CID } from 'multiformats/cid'
+import * as W3Name from 'w3name'
+
+const { WARN, LOG, DEBUG, ERROR } = Logger.setup(Logger.INFO)
+
+/**
+ * Try to resolve IPNS name to get existing revision.
+ * Returns null if record doesn't exist (404).
+ * Throws on network errors or server errors.
+ *
+ * This does a custom HTTP check first to distinguish 404 from network errors,
+ * then delegates to W3Name.resolve() for validation if record exists.
+ */
+async function tryResolveIPNS(ipns: W3Name.WritableName): Promise<W3Name.Revision | null> {
+	const url = `https://name.web3.storage/name/${ipns.toString()}`
+
+	let response: Response
+	try {
+		response = await fetch(url, { signal: AbortSignal.timeout(30_000) })
+	} catch (err) {
+		// Network error (no connection, DNS failure, etc.)
+		throw ERROR('[w3name] Network error resolving IPNS:', err)
+	}
+
+	// 404 = record never published
+	if (response.status === 404) {
+		DEBUG('[w3name] IPNS record not found (never published):', ipns.toString())
+		return null
+	}
+
+	// Other HTTP errors (5xx server error, etc.)
+	if (!response.ok) {
+		throw ERROR(`[w3name] HTTP ${response.status} resolving IPNS:`, response.statusText)
+	}
+
+	// Success - use W3Name.resolve to get validated Revision
+	// (We could parse the record ourselves, but W3Name does validation/signature checks)
+	const existing = await W3Name.resolve(ipns)
+	return existing
+}
+
+/**
+ * Publish CID to IPNS, automatically handling increment vs v0.
+ * Returns the revision for further processing (e.g., Kubo integration).
+ */
+export async function publishIPNS(ipnsPrivateKey: Uint8Array, cid: CID): Promise<W3Name.Revision> {
+	const TIMEOUT_MS = 30_000
+	const timeout = new Promise<never>((_, reject) =>
+		setTimeout(() => reject(new Error(`publishIPNS timed out after ${TIMEOUT_MS}ms`)), TIMEOUT_MS),
+	)
+	return Promise.race([_publishIPNSImpl(ipnsPrivateKey, cid), timeout])
+}
+
+async function _publishIPNSImpl(ipnsPrivateKey: Uint8Array, cid: CID): Promise<W3Name.Revision> {
+	const value = `/ipfs/${cid}`
+	const ipns = await W3Name.from(ipnsPrivateKey)
+
+	let revision: W3Name.Revision
+	const existing = await tryResolveIPNS(ipns)
+
+	if (existing) {
+		// Record exists - increment sequence number
+		revision = await W3Name.increment(existing, value)
+		DEBUG('[w3name] incrementing revision for', ipns.toString())
+	} else {
+		// First publish - use v0
+		revision = await W3Name.v0(ipns, value)
+		DEBUG('[w3name] creating initial revision for', ipns.toString())
+	}
+
+	await W3Name.publish(revision, ipns.key)
+	DEBUG('[w3name] published', cid.toString(), 'to', ipns.toString())
+
+	return revision // Return for Kubo integration or other uses
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// zt.ax naming service target (primary)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the current IPNS sequence from a zt.ax-compatible naming service.
+ *
+ * The naming service API uses the simple W3NameRecord format:
+ *   `GET <baseUrl>/<ipnsName>` → `{ value: "/ipfs/<cid>", seq?: number, validity?: string }`
+ *
+ * Also supports the legacy w3name record format (`{ record: "<base64>", value: "..." }`)
+ * for backward compatibility with hybrid services.
+ */
+export async function resolveZtaxSequence(
+	baseUrl: string,
+	ipnsName: string,
+): Promise<bigint | null> {
+	const url = `${baseUrl.replace(/\/+$/, '')}/${ipnsName}`
+	let response: Response
+	try {
+		response = await fetch(url)
+	} catch (err) {
+		throw new Error(`Network error resolving sequence from ${baseUrl}: ${err}`)
+	}
+
+	if (response.status === 404) return null
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} resolving sequence from ${baseUrl}: ${response.statusText}`)
+	}
+
+	const body: Record<string, unknown> = await response.json()
+
+	// Format 1: simple W3NameRecord with seq number
+	if (typeof body.seq === 'number') {
+		return BigInt(body.seq)
+	}
+
+	// Format 2: legacy w3name record with base64-encoded protobuf
+	if (typeof body.record === 'string') {
+		try {
+			const bytes = base64pad.baseDecode(body.record)
+			const entry = unmarshalIPNSRecord(bytes)
+			return entry.sequence
+		} catch {
+			WARN('[resolveZtaxSequence] failed to unmarshal record for', ipnsName)
+			return null
+		}
+	}
+
+	// No sequence info — treat as never published or zero
+	return null
+}
+
+/**
+ * Create an IPNSPublishTarget that publishes to a zt.ax naming service.
+ *
+ * Uses HTTP POST to publish signed IPNS records and HTTP GET to resolve
+ * the current sequence number, following the same wire format as the
+ * standard w3name API but at a configurable base URL.
+ *
+ * The naming service is expected to support:
+ *   - `POST <baseUrl>/<ipnsName>` — publish signed IPNS record (base64-encoded body)
+ *   - `GET  <baseUrl>/<ipnsName>` — resolve current record (`{ value, seq?, record? }`)
+ *
+ * @param baseUrl - Base URL of the naming service (default: https://ipfs.zt.ax)
+ */
+export function ztaxTarget(baseUrl = 'https://ipfs.zt.ax'): IPNSPublishTarget {
+	const cleanBase = baseUrl.replace(/\/+$/, '')
+	return {
+		name: 'zt.ax',
+		async publish(ipnsName: string, recordBytes: Uint8Array) {
+			const url = `${cleanBase}/${ipnsName}`
+			DEBUG(`[ztaxTarget] POST ${url}`)
+			const res = await fetch(url, {
+				method: 'POST',
+				body: base64pad.baseEncode(recordBytes),
+			})
+			if (!res.ok) {
+				let detail = ''
+				try {
+					const body = await res.json() as Record<string, unknown>
+					detail = body.message ? ` — ${body.message}` : ''
+				} catch {
+					detail = res.statusText ? ` — ${res.statusText}` : ''
+				}
+				throw new Error(`zt.ax HTTP ${res.status}${detail}`)
+			}
+		},
+		async resolveSequence(ipnsName: string): Promise<bigint | null> {
+			return resolveZtaxSequence(cleanBase, ipnsName)
+		},
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// w3name naming service target (deprecated — read‑only backup)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create an IPNSPublishTarget for the w3name service.
+ *
+ * @deprecated w3name is shut down for publishing. This target is kept as a
+ * read‑only backup for sequence resolution only (no publish method).
+ * Use {@link ztaxTarget} for all publishing.
+ *
+ * @param serviceUrl - Base URL of the w3name-compatible service (default: https://name.web3.storage)
+ */
+export function w3nameTarget(serviceUrl = 'https://name.web3.storage'): IPNSPublishTarget {
+	return {
+		name: 'w3name',
+		// No publish() — w3name is read-only; publishing goes through ztaxTarget
+		async resolveSequence(ipnsName: string): Promise<bigint | null> {
+			return resolveIPNSSequence(serviceUrl, ipnsName)
+		},
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function generateIpnsKey() {
+	return W3Name.create() // Returns W3Name.WritableName type
+}
+
+export async function getW3NamePublic(pk: Uint8Array) {
+	const ipns = await W3Name.from(pk)
+	return ipns.toString()
+}