ipfs direct

Author: tung@cloud.phamthanh.me

docs/direct-ipfs-plan.md

@@ -0,0 +1,62 @@
+# Implementation Plan: Offline-First Direct IPFS (Helia)
+
+This plan outlines the implementation of a direct, client-side IPFS node within FeatherNote using **Helia**. The focus is on a lightweight, serverless, and offline-first synchronization strategy.
+
+## 1. Goal
+Enable true decentralized synchronization by running an IPFS node directly in the browser. This eliminates the need for third-party services like Pinata or self-hosted RPC endpoints, allowing the app to function entirely offline and sync when a connection is available.
+
+## 2. Technical Stack
+- **Helia**: A modular, lightweight IPFS implementation for JS.
+- **Blockstore-IDB / Datastore-IDB**: To persist IPFS data in the browser's IndexedDB.
+- **Helia JSON**: For efficient handling of note objects as IPFS blocks.
+- **libp2p**: Configured with WebRTC and WebSockets for browser-to-browser and browser-to-node connectivity.
+
+## 3. Core Logic: The "Index File" Approach
+Instead of relying on an external metadata API, the app will maintain a local IPFS state:
+1.  **Local Index (`.feathernote.json`)**: A JSON file containing:
+    - Map of `noteId` -> `noteCid`
+    - `updatedAt` timestamp
+    - `deletedNoteIds` list
+2.  **Root CID**: The CID of the latest version of this index file.
+3.  **Persistence**: The Root CID is stored in the app's encrypted settings. When the settings sync (via S3, Git, etc.), other devices receive the Root CID and can "pull" the data from the IPFS network.
+
+## 4. Offline-First Strategy
+- **Local Cache**: IPFS blocks are stored in IndexedDB. Adding a note to IPFS while offline will still generate a valid CID and update the local index.
+- **Deferred Syncing**: When the app regains connectivity, the Helia node will:
+    - Connect to bootstrap nodes/relays.
+    - Announce the Root CID to the network.
+    - Fetch any missing blocks required by a newer Root CID received from settings.
+
+## 5. Proposed Changes
+
+### A. IPFS Module (`src/ipfs.js`)
+- **Initialization**: Logic to start Helia with IndexedDB persistence.
+- **`addNoteToHelia(note)`**: 
+    - Convert note to JSON block -> get `noteCid`.
+    - Update the local Index file -> get `newRootCid`.
+    - Persist `newRootCid` to app settings.
+- **`getNoteFromHelia(noteCid)`**: Retrieve and parse JSON from the IPFS network/local cache.
+- **`syncIndex(remoteRootCid)`**: 
+    - Fetch the remote index.
+    - Compare with local index.
+    - Download missing note CIDs.
+
+### B. UI & Settings (`src/index.html`, `src/index.js`)
+- **Toggle**: "Enable Direct IPFS Node".
+- **Status Indicator**: Show if the node is starting, online (connected to peers), or offline.
+- **Root CID Display**: Read-only field showing the current state's hash.
+
+### C. Integration (`src/helpers.js`)
+- **Sync Flow**: Modify the `synchronize` function to check the local Helia node for updates if enabled.
+- **Conflict Resolution**: Use the `updatedAt` field within the `.feathernote.json` index to determine the latest global state.
+
+## 6. Connectivity Requirements
+Since browsers cannot accept direct incoming connections, we will use:
+- **Public Gateways**: To fetch the index if no direct peers are found.
+- **Circuit Relays**: To allow browser nodes to talk to each other through a middleman.
+- **WST (Websocket-Star)** or **WebRTC-Star**: For peer discovery.
+
+## 7. Verification Plan
+1.  **Offline Add**: Disable network, add a note, and verify it exists in the local IPFS blockstore (via CID).
+2.  **Local Peer Sync**: Open two different browsers on the same machine and verify they can sync notes via the local node.
+3.  **Persistence**: Refresh the page and ensure the Helia node recovers its previous state from IndexedDB.

src/helpers.js

@@ -377,7 +377,7 @@ async function syncDeletedNoteIds({deletedNoteIds, credentials, gitCredentials,
 	if (gdriveStore?.connected) {
 		remoteLists.push(await _GLOBAL.downloadDeletedNotesFromGoogleDrive());
 	}
-	if (credentials?.pinataJwt || credentials?.pinataApiKey) {
+	if (credentials?.useDirectIpfs || credentials?.pinataJwt || credentials?.pinataApiKey) {
 		remoteLists.push(await window.downloadDeletedNotesFromIPFS(credentials));
 	}
 
@@ -422,7 +422,7 @@ async function syncDeletedNoteIds({deletedNoteIds, credentials, gitCredentials,
 		if (gdriveStore?.connected) {
 			uploadPromises.push(_GLOBAL.uploadDeletedNotesToGoogleDrive(finalIdArray));
 		}
-		if (credentials?.pinataJwt || credentials?.pinataApiKey) {
+		if (credentials?.useDirectIpfs || credentials?.pinataJwt || credentials?.pinataApiKey) {
 			uploadPromises.push(window.uploadDeletedNotesToIPFS(finalIdArray, credentials));
 		}
 		await Promise.allSettled(uploadPromises);
@@ -442,7 +442,7 @@ async function synchronize({notes, deletedNoteIds, isSilent, credentials, nostrP
 			}
 		}
 
-		if (!credentials.secretAccessKey && !gitCredentials?.repoUrl && !gdriveStore?.connected && !credentials.pinataJwt && !credentials.pinataApiKey) return {
+		if (!credentials.secretAccessKey && !gitCredentials?.repoUrl && !gdriveStore?.connected && !credentials.pinataJwt && !credentials.pinataApiKey && !credentials.useDirectIpfs) return {
 			success: false,
 			error: 'No sync provider configured (S3, Git, IPFS, or GDrive)',
 		};
@@ -743,7 +743,7 @@ async function uploadNote({note, credentials, nostrPrivateKey, nostrRelays, gitC
 	const shouldUploadToNostr = nostrPrivateKey && (!nostrMap.has(note.id) || localDate > new Date(nostrMap.get(note.id).updatedAt || nostrMap.get(note.id).createdAt));
 	const shouldUploadToGit = gitCredentials?.repoUrl && typeof _GLOBAL.uploadNoteToGit === 'function' && (!gitMap.has(note.id) || localDate > new Date(gitMap.get(note.id).updatedAt || gitMap.get(note.id).createdAt));
 	const shouldUploadToGDrive = gdriveStore?.connected && typeof _GLOBAL.uploadNoteToGoogleDrive === 'function' && (!gdriveMap.has(note.id) || localDate > new Date(gdriveMap.get(note.id).updatedAt || gdriveMap.get(note.id).createdAt));
-	const shouldUploadToIPFS = (credentials.pinataJwt || credentials.pinataApiKey) && typeof _GLOBAL.uploadNoteToIPFS === 'function' && (!ipfsMap.has(note.id) || localDate > new Date(ipfsMap.get(note.id).updatedAt));
+	const shouldUploadToIPFS = (credentials.useDirectIpfs || credentials.pinataJwt || credentials.pinataApiKey) && typeof _GLOBAL.uploadNoteToIPFS === 'function' && (!ipfsMap.has(note.id) || localDate > new Date(ipfsMap.get(note.id).updatedAt));
 
 	await Promise.allSettled([
 		shouldUploadToS3 ? uploadNoteToS3(note, credentials) : null,
@@ -796,7 +796,7 @@ async function listNotes({credentials, nostrPrivateKey, nostrRelays, lastSync, g
 	}
 
 	let ipfsNotesPromise;
-	if ((credentials?.pinataJwt || credentials?.pinataApiKey) && typeof window.listNotesInIPFS === 'function') {
+	if ((credentials?.useDirectIpfs || credentials?.pinataJwt || credentials?.pinataApiKey) && typeof window.listNotesInIPFS === 'function') {
 		ipfsNotesPromise = window.listNotesInIPFS(credentials);
 	} else {
 		ipfsNotesPromise = Promise.resolve([]);
@@ -958,7 +958,7 @@ async function deleteNoteFromRemotes({noteId, credentials, nostrPrivateKey, nost
 		promises.push(_GLOBAL.deleteNoteFromGit(remoteMeta?.path || noteId, gitCredentials));
 	}
 
-	if ((credentials?.pinataJwt || credentials?.pinataApiKey) && typeof window.deleteNoteFromIPFS === 'function') {
+	if ((credentials?.useDirectIpfs || credentials?.pinataJwt || credentials?.pinataApiKey) && typeof window.deleteNoteFromIPFS === 'function') {
 		promises.push(window.deleteNoteFromIPFS(noteId, credentials));
 	}
 

src/index.html

@@ -379,6 +379,14 @@ <h3 class="text-lg font-bold">Settings <span class="text-sm" x-text="'v.'+appVer
 						<label for="ipfs-gateway" class="text-right">IPFS Gateway</label>
 						<input id="ipfs-gateway" x-model="ipfsGateway" class="col-span-3 border p-1" placeholder="https://gateway.pinata.cloud/ipfs/" />
 					</div>
+					<div class="grid grid-cols-4 items-center gap-2">
+						<label for="use-direct-ipfs" class="text-right">Direct IPFS</label>
+						<input id="use-direct-ipfs" type="checkbox" x-model="useDirectIpfs" class="col-span-3 h-4 w-4" />
+					</div>
+					<div class="grid grid-cols-4 items-center gap-2" x-show="useDirectIpfs">
+						<label for="ipfs-root-cid" class="text-right">Root CID</label>
+						<input id="ipfs-root-cid" x-model="ipfsRootCid" class="col-span-3 border p-1 bg-gray-100" placeholder="Index File CID..." readonly />
+					</div>
 				</fieldset>
 
 				<fieldset class="col-span-2 lg:col-span-1 grid gap-2 border-t pt-4 text-sm">
@@ -489,7 +497,7 @@ <h4 class="text-sm font-bold" x-text="toast.title"></h4>
 <script defer src="/s3.js?v=___VERSION___"></script>
 <script defer src="/nostr.js?v=___VERSION___"></script>
 <script defer src="/gdrive.js?v=___VERSION___"></script>
-<script defer src="/ipfs.js?v=___VERSION___"></script>
+<script type="module" src="/ipfs.js?v=___VERSION___"></script>
 <script defer src="/helpers.js?v=___VERSION___"></script>
 <script defer src="/index.js?v=___VERSION___" fetchpriority="high"></script>
 

src/index.js

@@ -155,6 +155,15 @@ document.addEventListener('alpine:init', () => { Alpine.data('mainApp', () => ({
 
 	// --- Main App Init ---
 	init() {
+		// Set up global helper for IPFS root CID updates
+		window.updateIpfsRootCid = async (newCid) => {
+			if (!newCid || newCid === this.ipfsRootCid) return;
+			console.log(`Updating IPFS Root CID to: ${newCid}`);
+			this.ipfsRootCid = newCid;
+			// Trigger a save to persist the new CID in encrypted settings
+			await this.handleSave(true); 
+		};
+
 		// Check hash early to prioritize editor loading
 		if (window.location.hash === '#new_note') {
 			this.createNewNote();
@@ -2367,6 +2376,8 @@ document.addEventListener('alpine:init', () => { Alpine.data('mainApp', () => ({
 	pinataApiKey: '',
 	pinataSecretApiKey: '',
 	ipfsGateway: '',
+	useDirectIpfs: true,
+	ipfsRootCid: '',
 
 	aiApiKey: '',
 	aiApiRoute: '',
@@ -2403,6 +2414,8 @@ document.addEventListener('alpine:init', () => { Alpine.data('mainApp', () => ({
 		this.pinataApiKey = decrypted.pinataApiKey || '';
 		this.pinataSecretApiKey = decrypted.pinataSecretApiKey || '';
 		this.ipfsGateway = decrypted.ipfsGateway || '';
+		this.useDirectIpfs = decrypted.useDirectIpfs !== undefined ? !!decrypted.useDirectIpfs : true;
+		this.ipfsRootCid = decrypted.ipfsRootCid || '';
 		this.aiApiKey = decrypted.aiApiKey || '';
 		this.aiApiRoute = decrypted.aiApiRoute || '';
 		this.aiModel = decrypted.aiModel || '';
@@ -2419,9 +2432,9 @@ document.addEventListener('alpine:init', () => { Alpine.data('mainApp', () => ({
 		this.gitEmail = decrypted.gitEmail || '';
 	},
 
-	async handleSave() {
+	async handleSave(isAutoSave = false) {
 		this.isSavingSettings = true;
-		localStorage.setItem('feathernote-nostr-relays', this.nostrRelays);
+		if (!isAutoSave) localStorage.setItem('feathernote-nostr-relays', this.nostrRelays);
 
 		// Get existing settings to preserve the secret key if not changed
 		const storedData = await getEncryptedSettingsDB();
@@ -2444,6 +2457,8 @@ document.addEventListener('alpine:init', () => { Alpine.data('mainApp', () => ({
 			pinataApiKey: this.pinataApiKey,
 			pinataSecretApiKey: this.pinataSecretApiKey,
 			ipfsGateway: this.ipfsGateway,
+			useDirectIpfs: this.useDirectIpfs,
+			ipfsRootCid: this.ipfsRootCid,
 			aiApiKey: this.aiApiKey,
 			aiApiRoute: this.aiApiRoute,
 			aiModel: this.aiModel,