nodio-cli 1.0.12 → 1.1.0

package/.env.example

@@ -4,3 +4,8 @@ NODIO_HEARTBEAT_INTERVAL_MS=30000
 NODIO_OFFLINE_AFTER_MISSES=3
 NODIO_MIN_REPLICAS=5
 NODIO_EMERGENCY_REPLICA_FLOOR=2
+NODIO_RELAY_POLL_INTERVAL_MS=1000
+NODIO_WALLET_PRIVATE_KEY=
+NODIO_WALLET_ADDRESS=
+FILECOIN_NETWORK=calibration
+FILECOIN_RPC_URL=https://api.calibration.node.glif.io/rpc/v1

package/README.md

@@ -122,6 +122,5 @@ npm run start:cli -- download \
 - `POST /api/shards/placement-plan`
 - `GET /api/files/:fileId/manifest`
 
-## Next Step
-
-Add authentication between user CLI, central server, and donor nodes for production security.
+## Next Step( )
+Integrating with nodio-drive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodio-cli",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "description": "Nodio distributed storage network",
   "main": "src/server/index.js",
   "type": "commonjs",
@@ -24,11 +24,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@filoz/synapse-sdk": "^0.41.0",
     "axios": "^1.11.0",
     "commander": "^14.0.1",
-    "dotenv": "^17.2.2",
+    "cors": "^2.8.5",
+    "dotenv": "^17.4.2",
     "express": "^5.1.0",
     "mongoose": "^8.18.0",
-    "uuid": "^13.0.0"
+    "uuid": "^13.0.0",
+    "viem": "^2.48.11"
   }
 }

package/scripts/backupDirect.js

@@ -0,0 +1,58 @@
+(async () => {
+  try {
+    require('dotenv').config();
+    const axios = require('axios');
+    const { privateKeyToAccount } = require('viem/accounts');
+    const { http } = require('viem');
+    const { calibration } = require('@filoz/synapse-core/chains');
+
+    const synapseSdk = await import('@filoz/synapse-sdk');
+    const Synapse = synapseSdk?.Synapse || synapseSdk?.default?.Synapse || synapseSdk?.default;
+    if (!Synapse || typeof Synapse.create !== 'function') {
+      throw new Error('Synapse.create not available');
+    }
+
+    const server = process.argv[2] || 'http://127.0.0.1:4000';
+    const fileId = process.argv[3];
+    if (!fileId) throw new Error('Usage: node backupDirect.js <serverUrl> <fileId>');
+
+    const privateKey = process.env.NODIO_WALLET_PRIVATE_KEY;
+    if (!privateKey) throw new Error('NODIO_WALLET_PRIVATE_KEY not set');
+
+    const rpcUrl = process.env.FILECOIN_RPC_URL || 'https://api.calibration.node.glif.io/rpc/v1';
+    const account = privateKeyToAccount(privateKey);
+
+    console.log('Init Synapse...');
+    const synapse = await Synapse.create({ chain: calibration, transport: http(rpcUrl), account, source: null, withCDN: false });
+    if (!synapse.storage || typeof synapse.storage.upload !== 'function') throw new Error('storage.upload not available');
+
+    console.log('Fetching manifest...');
+    const manifestResp = await axios.get(`${server}/api/files/${fileId}/manifest`);
+    const manifest = manifestResp.data;
+    const shards = manifest.shards || [];
+
+    const encryptedShardBuffers = [];
+    for (const shard of shards) {
+      const replica = (shard.replicas || [])[0];
+      if (!replica || !replica.url) throw new Error('no replica url');
+      const url = `${replica.url.replace(/\/+$/, '')}/shards/${shard.shardId}`;
+      const resp = await axios.get(url, { responseType: 'arraybuffer' });
+      encryptedShardBuffers.push(Buffer.from(resp.data));
+    }
+
+    const payload = Buffer.concat(encryptedShardBuffers);
+    console.log('Calling synapse.storage.upload (this may take a while)...');
+    try {
+      const result = await synapse.storage.upload(payload, { copies: 2 });
+      console.log('upload result:', result);
+    } catch (err) {
+      console.error('synapse.storage.upload error:', err);
+      if (err && err.cause) console.error('cause:', err.cause);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(error && error.stack ? error.stack : error);
+    process.exit(1);
+  }
+})();

package/scripts/backupFromLayer1.js

@@ -0,0 +1,72 @@
+(async () => {
+  try {
+    require('dotenv').config();
+    const axios = require('axios');
+    const path = require('path');
+    const fs = require('fs');
+    const { uploadToFilecoin } = require('../services/filecoin');
+
+    const server = process.argv[2] || process.env.NODIO_SERVER_URL || 'http://127.0.0.1:4000';
+    const fileId = process.argv[3];
+    if (!fileId) {
+      throw new Error('Usage: node backupFromLayer1.js <serverUrl> <fileId>');
+    }
+
+    console.log('Fetching manifest for', fileId);
+    const manifestResp = await axios.get(`${server}/api/files/${fileId}/manifest`, { timeout: 20000 });
+    const manifest = manifestResp.data;
+    const shards = manifest.shards || [];
+
+    const encryptedShardBuffers = [];
+
+    for (const shard of shards) {
+      const replicas = shard.replicas || [];
+      let fetched = null;
+      for (const replica of replicas) {
+        if (!replica.url) continue;
+        try {
+          const url = `${replica.url.replace(/\/+$/, '')}/shards/${shard.shardId}`;
+          const resp = await axios.get(url, { responseType: 'arraybuffer', timeout: 20000 });
+          const buf = Buffer.from(resp.data);
+          // simple checksum check
+          const crypto = require('crypto');
+          const sha = crypto.createHash('sha256').update(buf).digest('hex');
+          if (sha === shard.checksum) {
+            fetched = buf;
+            break;
+          }
+        } catch (err) {
+          console.warn('replica fetch failed', replica.nodeId, replica.url, err.message);
+        }
+      }
+
+      if (!fetched) {
+        throw new Error(`failed to fetch shard ${shard.shardId} from any replica`);
+      }
+
+      encryptedShardBuffers.push(fetched);
+    }
+
+    const encryptedFileBuffer = Buffer.concat(encryptedShardBuffers);
+    console.log('Uploading to Filecoin (this may take a while)...');
+    const cid = await uploadToFilecoin(encryptedFileBuffer, fileId);
+    console.log('uploadToFilecoin returned cid=', cid);
+    if (!cid) {
+      throw new Error('uploadToFilecoin failed or returned null');
+    }
+
+    try {
+      await axios.post(`${server}/api/files/${fileId}/filecoin`, { filecoinCid: cid, filecoinBackedUp: true });
+      console.log('Persisted CID to server');
+    } catch (err) {
+      console.warn('Failed to persist CID to server:', err.message || err);
+    }
+
+    console.log('Done');
+    process.exit(0);
+  } catch (error) {
+    console.error('error:', error.message || error);
+    if (error.stack) console.error(error.stack);
+    process.exit(1);
+  }
+})();

package/scripts/decodeAndReconstruct.js

@@ -0,0 +1,130 @@
+(async () => {
+  try {
+    require('dotenv').config();
+    const axios = require('axios');
+    const fs = require('fs/promises');
+    const path = require('path');
+    const { sha256Hex, decryptAes256Gcm } = require('../src/common/crypto');
+
+    const server = process.argv[2] || 'http://127.0.0.1:4000';
+    const fileId = process.argv[3];
+    const keyBase64 = process.argv[4];
+
+    if (!fileId) {
+      console.error('Usage: node scripts/decodeAndReconstruct.js <serverUrl> <fileId> [keyBase64]');
+      process.exit(2);
+    }
+
+    console.log('Fetching manifest...');
+    const resp = await axios.get(`${server}/api/files/${fileId}/manifest`);
+    const manifest = resp.data || {};
+    const orderedShards = [...(manifest.shards || [])].sort((a, b) => a.order - b.order);
+
+    const rawPath = path.resolve(`./${fileId}.filecoin.raw`);
+    console.log('Reading raw payload from', rawPath);
+    const raw = await fs.readFile(rawPath);
+
+    let decoded = raw;
+    if (raw.length >= 8) {
+      const header = raw.subarray(0, 8);
+      const originalLength = Number(header.readBigUInt64BE(0));
+      const start = 8;
+      const end = start + originalLength;
+      if (originalLength >= 0 && end <= raw.length) {
+        decoded = raw.subarray(start, end);
+        console.log('Found 8-byte header; extracted original payload length', originalLength);
+      } else {
+        console.log('8-byte header present but length invalid; using full buffer');
+      }
+    } else {
+      console.log('No 8-byte header found; using full buffer');
+    }
+
+    const decodedPath = path.resolve(`./${fileId}.filecoin.decoded.raw`);
+    await fs.writeFile(decodedPath, decoded);
+    console.log('Wrote decoded payload to', decodedPath);
+
+    if (!orderedShards || orderedShards.length === 0) {
+      console.warn('No shard metadata in manifest; stopping after decode');
+      process.exit(0);
+    }
+
+    const sizes = orderedShards.map((s) => Number(s.sizeBytes || s.size || 0));
+    const totalSizes = sizes.reduce((a, b) => a + b, 0);
+    if (totalSizes > decoded.length) {
+      console.warn('Sum of shard sizes > decoded payload length; attempting best-effort split');
+    }
+
+    // split by sizes
+    const shards = [];
+    let offset = 0;
+    for (let i = 0; i < sizes.length; i++) {
+      const size = sizes[i] || 0;
+      const end = Math.min(offset + size, decoded.length);
+      const slice = decoded.subarray(offset, end);
+      shards.push(slice);
+      offset = end;
+    }
+    if (offset < decoded.length) {
+      console.warn('Extra bytes present after shard split; saved as remainder');
+      await fs.writeFile(path.resolve(`./${fileId}.filecoin.remainder.raw`), decoded.subarray(offset));
+    }
+
+    for (let i = 0; i < shards.length; i++) {
+      const shard = shards[i];
+      const shardPath = path.resolve(`./${fileId}.shard.${i}.enc`);
+      await fs.writeFile(shardPath, shard);
+      const expectedChecksum = orderedShards[i]?.checksum;
+      if (expectedChecksum) {
+        const actual = sha256Hex(shard);
+        console.log(`shard ${i}: wrote ${shardPath} size=${shard.length} checksum match=${actual === expectedChecksum}`);
+      } else {
+        console.log(`shard ${i}: wrote ${shardPath} size=${shard.length}`);
+      }
+    }
+
+    if (!keyBase64) {
+      console.log('No key provided; stopping after saving encrypted shards. To decrypt, re-run with keyBase64 as third arg.');
+      process.exit(0);
+    }
+
+    const keyBuffer = Buffer.from(keyBase64, 'base64');
+    if (keyBuffer.length !== 32) {
+      throw new Error('Provided keyBase64 does not decode to 32 bytes');
+    }
+
+    const decryptedParts = [];
+
+    const encryptionShards = (manifest.file && manifest.file.metadata && manifest.file.metadata.encryption && manifest.file.metadata.encryption.shards) || [];
+    const shardMetaMap = new Map((encryptionShards || []).map((s) => [s.shardId, s]));
+
+    for (let i = 0; i < shards.length; i++) {
+      const topShard = orderedShards[i];
+      if (!topShard) throw new Error(`missing top-level shard metadata for index ${i}`);
+      const shardMeta = shardMetaMap.get(topShard.shardId);
+      if (!shardMeta) throw new Error(`missing encryption metadata for shard ${topShard.shardId}`);
+      const iv = shardMeta.iv;
+      const authTag = shardMeta.authTag;
+      const encryptedBuffer = shards[i];
+      try {
+        const plain = decryptAes256Gcm(encryptedBuffer, keyBuffer, iv, authTag);
+        decryptedParts.push(plain);
+        console.log(`shard ${i}: decrypted ok size=${plain.length}`);
+      } catch (err) {
+        console.error(`shard ${i}: decryption failed: ${err.message}`);
+        throw err;
+      }
+    }
+
+    const reconstructed = Buffer.concat(decryptedParts);
+    const originalName = manifest.file?.originalName || `${fileId}.reconstructed`;
+    const outPath = path.resolve(`./${originalName}`);
+    await fs.writeFile(outPath, reconstructed);
+    console.log('Wrote reconstructed file to', outPath, 'size=', reconstructed.length);
+
+    process.exit(0);
+  } catch (err) {
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+  }
+})();

package/scripts/downloadFromFilecoin.js

@@ -0,0 +1,37 @@
+(async () => {
+  try {
+    require('dotenv').config();
+    const axios = require('axios');
+    const fs = require('fs/promises');
+    const path = require('path');
+
+    const server = process.argv[2] || 'http://127.0.0.1:4000';
+    const fileId = process.argv[3];
+    if (!fileId) {
+      console.error('Usage: node scripts/downloadFromFilecoin.js <serverUrl> <fileId>');
+      process.exit(2);
+    }
+
+    const { retrieveFromFilecoin } = require('../services/filecoin');
+
+    console.log('Fetching manifest...');
+    const resp = await axios.get(`${server}/api/files/${fileId}/manifest`);
+    const manifest = resp.data || {};
+    const cid = manifest.file && manifest.file.filecoinCid;
+    if (!cid) {
+      throw new Error('filecoinCid not present on manifest');
+    }
+
+    console.log('Retrieving from Filecoin...', cid);
+    const buf = await retrieveFromFilecoin(cid);
+    if (!buf) throw new Error('retrieveFromFilecoin returned no data');
+
+    const outPath = path.resolve(`./${fileId}.filecoin.raw`);
+    await fs.writeFile(outPath, buf);
+    console.log('Saved filecoin payload to', outPath);
+    process.exit(0);
+  } catch (err) {
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+  }
+})();

package/scripts/fundSynapse.js

@@ -0,0 +1,57 @@
+(async () => {
+  try {
+    require('dotenv').config();
+    const { http } = require('viem');
+    const { privateKeyToAccount } = require('viem/accounts');
+    const { calibration } = require('@filoz/synapse-core/chains');
+
+    const synapseSdk = await import('@filoz/synapse-sdk');
+    const Synapse = synapseSdk?.Synapse || synapseSdk?.default?.Synapse || synapseSdk?.default;
+    if (!Synapse || typeof Synapse.create !== 'function') {
+      throw new Error('Synapse.create not available from @filoz/synapse-sdk');
+    }
+
+    const privateKey = process.env.NODIO_WALLET_PRIVATE_KEY;
+    if (!privateKey) {
+      throw new Error('NODIO_WALLET_PRIVATE_KEY must be set in environment');
+    }
+
+    const rpcUrl = process.env.FILECOIN_RPC_URL || 'https://api.calibration.node.glif.io/rpc/v1';
+
+    const account = privateKeyToAccount(privateKey);
+
+    console.log('Initializing Synapse client (calibration)...');
+    const synapse = await Synapse.create({
+      chain: calibration,
+      transport: http(rpcUrl),
+      account,
+      source: null,
+      withCDN: false
+    });
+
+    if (!synapse.payments || typeof synapse.payments.fundSync !== 'function') {
+      throw new Error('Payments service not available on Synapse client');
+    }
+
+    // 3 USDFC with 18 decimals
+    const amount = BigInt('3000000000000000000');
+
+    console.log(`Submitting fund request for ${amount.toString()} (3 USDFC)...`);
+
+    const result = await synapse.payments.fundSync({ amount });
+
+    console.log('Fund transaction submitted.');
+    console.log('Hash:', result.hash);
+    console.log('Receipt:', result.receipt ? {
+      blockNumber: result.receipt.blockNumber,
+      transactionHash: result.receipt.transactionHash,
+      status: result.receipt.status
+    } : null);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('[fundSynapse] error:', error && error.message ? error.message : error);
+    if (error && error.stack) console.error(error.stack);
+    process.exit(1);
+  }
+})();

package/services/filecoin.js

@@ -0,0 +1,315 @@
+const dotenv = require('dotenv');
+const { formatUnits, http } = require('viem');
+const { privateKeyToAccount } = require('viem/accounts');
+const { calibration: filecoinCalibration } = require('@filoz/synapse-core/chains');
+let synapseSdkPromise = null;
+
+dotenv.config();
+
+let synapseClientPromise = null;
+const FILECOIN_MIN_PAYLOAD_BYTES = 127;
+function resolveSynapseFactory(sdk) {
+  const candidate = sdk?.default || sdk;
+
+  if (candidate?.createSynapse && typeof candidate.createSynapse === 'function') {
+    return candidate.createSynapse;
+  }
+
+  if (candidate?.Synapse?.create && typeof candidate.Synapse.create === 'function') {
+    return candidate.Synapse.create.bind(candidate.Synapse);
+  }
+
+  if (candidate?.Synapse && typeof candidate.Synapse === 'function') {
+    return async (options) => new candidate.Synapse(options);
+  }
+
+  if (typeof candidate === 'function') {
+    return async (options) => new candidate(options);
+  }
+
+  throw new Error('synapse sdk factory not found');
+}
+
+async function getSynapseSdk() {
+  if (!synapseSdkPromise) {
+    synapseSdkPromise = import('@filoz/synapse-sdk');
+  }
+
+  return synapseSdkPromise;
+}
+
+function normalizeCid(value) {
+  if (!value) {
+    return null;
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  // Handle CID objects (has toString() method)
+  if (value && typeof value.toString === 'function' && (value.constructor?.name === 'CID' || value.asCID)) {
+    return value.toString();
+  }
+
+  if (typeof value.cid === 'string') {
+    return value.cid;
+  }
+
+  if (value.cid && typeof value.cid.toString === 'function') {
+    return value.cid.toString();
+  }
+
+  if (typeof value.pieceCid === 'string') {
+    return value.pieceCid;
+  }
+
+  if (value.pieceCid && typeof value.pieceCid.toString === 'function') {
+    return value.pieceCid.toString();
+  }
+
+  if (typeof value.id === 'string') {
+    return value.id;
+  }
+
+  return null;
+}
+
+function normalizeBuffer(value) {
+  if (!value) {
+    return null;
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+
+  if (value.data && Buffer.isBuffer(value.data)) {
+    return value.data;
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value);
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer);
+  }
+
+  if (typeof value === 'string') {
+    return Buffer.from(value, 'base64');
+  }
+
+  if (value.data && typeof value.data === 'string') {
+    return Buffer.from(value.data, 'base64');
+  }
+
+  return null;
+}
+
+function normalizeBalance(value) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  if (typeof value === 'bigint') {
+    return Number(value) / 1_000_000;
+  }
+
+  if (typeof value === 'object') {
+    if (value.formatted) {
+      const parsed = Number(value.formatted);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    if (value.value !== undefined) {
+      return normalizeBalance(value.value);
+    }
+  }
+
+  return null;
+}
+
+function encodeFilecoinPayload(fileBuffer) {
+  const payloadLength = Buffer.byteLength(fileBuffer);
+  const header = Buffer.alloc(8);
+  header.writeBigUInt64BE(BigInt(payloadLength));
+
+  const wrapped = Buffer.concat([header, fileBuffer]);
+  if (wrapped.length >= FILECOIN_MIN_PAYLOAD_BYTES) {
+    return wrapped;
+  }
+
+  return Buffer.concat([wrapped, Buffer.alloc(FILECOIN_MIN_PAYLOAD_BYTES - wrapped.length)]);
+}
+
+function decodeFilecoinPayload(fileBuffer) {
+  if (!Buffer.isBuffer(fileBuffer) || fileBuffer.length < 8) {
+    return fileBuffer;
+  }
+
+  try {
+    const originalLength = Number(fileBuffer.readBigUInt64BE(0));
+    const start = 8;
+    const end = start + originalLength;
+    if (originalLength >= 0 && end <= fileBuffer.length) {
+      return fileBuffer.subarray(start, end);
+    }
+  } catch {
+    return fileBuffer;
+  }
+
+  return fileBuffer;
+}
+
+async function buildSynapseClient() {
+  const privateKey = process.env.NODIO_WALLET_PRIVATE_KEY;
+  if (!privateKey) {
+    throw new Error('NODIO_WALLET_PRIVATE_KEY is not set');
+  }
+
+  const rpcUrl =
+    process.env.FILECOIN_RPC_URL
+    || 'https://api.calibration.node.glif.io/rpc/v1';
+
+  if (!rpcUrl) {
+    throw new Error('FILECOIN_RPC_URL is not set');
+  }
+
+  const account = privateKeyToAccount(privateKey);
+
+  const synapseSdk = await getSynapseSdk();
+  const Synapse = synapseSdk?.Synapse || synapseSdk?.default?.Synapse || synapseSdk?.default;
+
+  if (!Synapse || typeof Synapse.create !== 'function') {
+    throw new Error('synapse sdk Synapse.create not found');
+  }
+
+  return Synapse.create({
+    chain: filecoinCalibration,
+    transport: http(rpcUrl),
+    account,
+    source: null,
+    withCDN: false
+  });
+}
+
+async function getSynapseClient() {
+  if (!synapseClientPromise) {
+    synapseClientPromise = buildSynapseClient();
+  }
+
+  return synapseClientPromise;
+}
+
+async function uploadToFilecoin(fileBuffer, fileId) {
+  if (!fileBuffer) {
+    throw new Error('file buffer is required');
+  }
+
+  const client = await getSynapseClient();
+  const label = fileId ? String(fileId) : undefined;
+  const payload = encodeFilecoinPayload(Buffer.isBuffer(fileBuffer) ? fileBuffer : Buffer.from(fileBuffer));
+
+  if (!client || !client.storage || typeof client.storage.upload !== 'function') {
+    console.warn('[filecoin] storage.upload not available on synapse client');
+    return null;
+  }
+
+  const maxAttempts = 3;
+  const baseBackoffMs = 500;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const result = await client.storage.upload(payload, { copies: 2, name: label });
+      return normalizeCid(result);
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[filecoin] storage.upload attempt ${attempt}/${maxAttempts} failed: ${msg}`);
+      if (err && err.cause) {
+        console.warn(`[filecoin]   cause: ${err.cause.message || err.cause}`);
+      }
+      if (attempt === maxAttempts) {
+        console.error('[filecoin] storage.upload failed - max attempts reached');
+        return null;
+      }
+      // exponential backoff
+      const wait = baseBackoffMs * (2 ** (attempt - 1));
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => setTimeout(resolve, wait));
+    }
+  }
+  return null;
+}
+
+async function retrieveFromFilecoin(cid) {
+  try {
+    if (!cid) {
+      throw new Error('cid is required');
+    }
+
+    const client = await getSynapseClient();
+
+    if (typeof client.retrieve === 'function') {
+      const result = await client.retrieve(cid);
+      return decodeFilecoinPayload(normalizeBuffer(result));
+    }
+
+    if (client.storage?.retrieve && typeof client.storage.retrieve === 'function') {
+      const result = await client.storage.retrieve(cid);
+      return decodeFilecoinPayload(normalizeBuffer(result));
+    }
+
+    if (client.storage?.download && typeof client.storage.download === 'function') {
+      const result = await client.storage.download({ pieceCid: cid });
+      return decodeFilecoinPayload(normalizeBuffer(result));
+    }
+
+    if (client.file?.retrieve && typeof client.file.retrieve === 'function') {
+      const result = await client.file.retrieve(cid);
+      return decodeFilecoinPayload(normalizeBuffer(result));
+    }
+
+    if (typeof client.fetch === 'function') {
+      const result = await client.fetch(cid);
+      return decodeFilecoinPayload(normalizeBuffer(result));
+    }
+
+    console.warn('[filecoin] retrieve method not found on synapse client');
+    return null;
+  } catch (error) {
+    console.error('[filecoin] retrieve failed', error.message);
+    return null;
+  }
+}
+
+async function getWalletBalance() {
+  try {
+    const client = await getSynapseClient();
+
+    if (client?.payments && typeof client.payments.walletBalance === 'function') {
+      const balance = await client.payments.walletBalance({ token: 'USDFC' });
+      return Number.parseFloat(formatUnits(balance, 18));
+    }
+
+    console.warn('[filecoin] balance method not found on synapse client');
+    return null;
+  } catch (error) {
+    console.error('[filecoin] balance check failed', error.message);
+    return null;
+  }
+}
+
+module.exports = {
+  uploadToFilecoin,
+  retrieveFromFilecoin,
+  getWalletBalance
+};

package/src/server/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 const express = require('express');
+const cors = require('cors');
 const mongoose = require('mongoose');
 const { getServerConfig } = require('./config');
 const { buildRoutes } = require('./routes');
 const { NodeModel } = require('./models');
 const { markNodeOfflineAndRecover } = require('./services');
+const { getWalletBalance } = require('../../services/filecoin');
 
 async function startServer() {
   const config = getServerConfig();
@@ -12,6 +14,27 @@ async function startServer() {
   await mongoose.connect(config.mongoUri);
 
   const app = express();
+  const corsAllowlist = new Set([
+    'https://nodio.me',
+    'https://drive.nodio.me',
+    'https://effective-space-rotary-phone-wrv6xg64p7w72wj-3000.app.github.dev'
+  ]);
+
+  const corsOptions = {
+    origin(origin, callback) {
+      if (!origin || corsAllowlist.has(origin)) {
+        callback(null, true);
+        return;
+      }
+      callback(new Error('Not allowed by CORS'));
+    },
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    optionsSuccessStatus: 200
+  };
+
+  app.use(cors(corsOptions));
+  app.options(/.*/, cors(corsOptions));
   app.use(express.json({ limit: '10mb' }));
   app.use('/api', buildRoutes(config));
 
@@ -50,6 +73,26 @@ async function startServer() {
   app.listen(config.port, () => {
     console.log(`Nodio central server listening on port ${config.port}`);
   });
+
+  const dailyMs = 24 * 60 * 60 * 1000;
+  const checkBalance = async () => {
+    const balance = await getWalletBalance();
+    if (balance !== null && balance < 2) {
+      console.warn(`[filecoin] USDFC balance low: ${balance}`);
+    }
+  };
+
+  setTimeout(() => {
+    checkBalance().catch((error) => {
+      console.error('[filecoin] balance check failed', error.message);
+    });
+  }, 5000);
+
+  setInterval(() => {
+    checkBalance().catch((error) => {
+      console.error('[filecoin] balance check failed', error.message);
+    });
+  }, dailyMs);
 }
 
 startServer().catch((error) => {

package/src/server/models.js

@@ -23,6 +23,8 @@ const fileSchema = new mongoose.Schema(
     sizeBytes: { type: Number, required: true, min: 0 },
     shardCount: { type: Number, required: true, min: 1 },
     cipher: { type: String, required: true, default: 'aes-256-gcm' },
+    filecoinCid: { type: String, default: null },
+    filecoinBackedUp: { type: Boolean, default: false },
     metadata: { type: mongoose.Schema.Types.Mixed, default: {} }
   },
   { timestamps: true }

package/src/server/routes.js

@@ -541,11 +541,48 @@ function buildRoutes(config) {
     }
   });
 
+  router.post('/files/:fileId/filecoin', async (req, res, next) => {
+    try {
+      const { fileId } = req.params;
+      const { filecoinCid, filecoinBackedUp } = req.body;
+
+      if (!fileId) {
+        return res.status(400).json({ error: 'fileId is required' });
+      }
+      if (!filecoinCid) {
+        return res.status(400).json({ error: 'filecoinCid is required' });
+      }
+
+      const file = await FileModel.findOneAndUpdate(
+        { fileId },
+        {
+          $set: {
+            filecoinCid,
+            filecoinBackedUp: typeof filecoinBackedUp === 'boolean' ? filecoinBackedUp : true
+          }
+        },
+        { new: true }
+      );
+
+      if (!file) {
+        return res.status(404).json({ error: 'file not found' });
+      }
+
+      res.json({ ok: true, fileId: file.fileId, filecoinCid: file.filecoinCid });
+    } catch (error) {
+      next(error);
+    }
+  });
+
   router.post('/shards/register', async (req, res, next) => {
     try {
       const { shardId, fileId, order, sizeBytes, checksum, nodeIds } = req.body;
-      if (!shardId || !fileId || !checksum || !Array.isArray(nodeIds) || nodeIds.length === 0) {
-        return res.status(400).json({ error: 'shardId, fileId, checksum and nodeIds are required' });
+      if (!shardId || !fileId || !checksum) {
+        return res.status(400).json({ error: 'shardId, fileId, and checksum are required' });
+      }
+
+      if (nodeIds !== undefined && !Array.isArray(nodeIds)) {
+        return res.status(400).json({ error: 'nodeIds must be an array when provided' });
       }
 
       await ShardModel.findOneAndUpdate(
@@ -562,7 +599,7 @@ function buildRoutes(config) {
         { upsert: true, new: true, setDefaultsOnInsert: true }
       );
 
-      const uniqueNodeIds = [...new Set(nodeIds)];
+      const uniqueNodeIds = [...new Set(Array.isArray(nodeIds) ? nodeIds : [])];
       for (const nodeId of uniqueNodeIds) {
         await ShardPlacementModel.updateOne(
           { shardId, nodeId },
@@ -580,7 +617,9 @@ function buildRoutes(config) {
         );
       }
 
-      await ensureEmergencyReplicasForShard(shardId, config.emergencyReplicaFloor);
+      if (uniqueNodeIds.length > 0) {
+        await ensureEmergencyReplicasForShard(shardId, config.emergencyReplicaFloor);
+      }
 
       res.json({ ok: true });
     } catch (error) {
@@ -730,7 +769,9 @@ function buildRoutes(config) {
           sizeBytes: file.sizeBytes,
           shardCount: file.shardCount,
           cipher: file.cipher,
-          metadata: file.metadata
+          metadata: file.metadata,
+          filecoinCid: file.filecoinCid || null,
+          filecoinBackedUp: Boolean(file.filecoinBackedUp)
         },
         shards: shardManifests
       });

package/src/user/commands.js

@@ -5,6 +5,7 @@ const axios = require('axios');
 const { v4: uuidv4 } = require('uuid');
 const { createApiClient, normalizeUrl } = require('./client');
 const { encryptAes256Gcm, decryptAes256Gcm, sha256Hex } = require('../common/crypto');
+const { uploadToFilecoin, retrieveFromFilecoin } = require('../../services/filecoin');
 
 function splitBuffer(buffer, shardSizeBytes) {
   if (shardSizeBytes <= 0) {
@@ -31,6 +32,159 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function splitEncryptedBufferBySizes(buffer, shardSizes) {
+  const slices = [];
+  let offset = 0;
+
+  for (const sizeBytes of shardSizes) {
+    const size = Number(sizeBytes) || 0;
+    const end = offset + size;
+    if (end > buffer.length) {
+      throw new Error('filecoin buffer is smaller than expected shard sizes');
+    }
+    slices.push(buffer.subarray(offset, end));
+    offset = end;
+  }
+
+  if (offset < buffer.length) {
+    console.warn('[filecoin] extra bytes present after shard split; ignoring remainder');
+  }
+
+  return slices;
+}
+
+function decryptShardsFromBuffers(orderedShards, shardMetaMap, encryptedShardBuffers, keyBuffer) {
+  const plainParts = [];
+
+  for (let index = 0; index < orderedShards.length; index += 1) {
+    const shard = orderedShards[index];
+    const shardMeta = shardMetaMap.get(shard.shardId);
+    if (!shardMeta) {
+      throw new Error(`missing encryption metadata for shard ${shard.shardId}`);
+    }
+
+    const encryptedBuffer = encryptedShardBuffers[index];
+    if (!encryptedBuffer) {
+      throw new Error(`missing encrypted payload for shard ${shard.shardId}`);
+    }
+
+    if (sha256Hex(encryptedBuffer) !== shard.checksum) {
+      throw new Error(`checksum mismatch for shard ${shard.shardId} from filecoin`);
+    }
+
+    try {
+      const plain = decryptAes256Gcm(encryptedBuffer, keyBuffer, shardMeta.iv, shardMeta.authTag);
+      plainParts.push(plain);
+    } catch (error) {
+      if (String(error.message || '').includes('unsupported state or unable to authenticate data')) {
+        throw new Error(
+          `decryption failed for shard ${shard.shardId}: key is incorrect or metadata/key mismatch (double-check key-base64 copy)`
+        );
+      }
+      throw error;
+    }
+  }
+
+  return Buffer.concat(plainParts);
+}
+
+function fireAndForgetFilecoinUpload(api, fileBuffer, fileId) {
+  if (!fileBuffer || fileBuffer.length === 0) {
+    return;
+  }
+
+  void (async () => {
+    const cid = await uploadToFilecoin(fileBuffer, fileId);
+    if (!cid) {
+      return;
+    }
+
+    try {
+      await api.post(`/files/${fileId}/filecoin`, {
+        filecoinCid: cid,
+        filecoinBackedUp: true
+      });
+    } catch (error) {
+      const message = error.response?.data?.error || error.message;
+      console.warn(`[filecoin] failed to persist cid for ${fileId}: ${message}`);
+    }
+  })();
+}
+
+function fireAndForgetLayer1Reseed(api, fileId, orderedShards, encryptedShardBuffers, directTimeoutMs) {
+  void (async () => {
+    for (let index = 0; index < orderedShards.length; index += 1) {
+      const shard = orderedShards[index];
+      const encryptedBuffer = encryptedShardBuffers[index];
+      if (!encryptedBuffer || !Array.isArray(shard.replicas) || shard.replicas.length === 0) {
+        continue;
+      }
+
+      const directWriteResults = await Promise.allSettled(
+        shard.replicas.map(async (replica) => {
+          const putUrl = `${normalizeUrl(replica.url)}/shards/${shard.shardId}`;
+          await axios.put(putUrl, encryptedBuffer, {
+            headers: { 'Content-Type': 'application/octet-stream' },
+            timeout: directTimeoutMs
+          });
+          return replica;
+        })
+      );
+
+      const successfulReplicas = directWriteResults
+        .filter((result) => result.status === 'fulfilled')
+        .map((result) => result.value);
+
+      const failedReplicas = directWriteResults
+        .map((result, replicaIndex) => ({ result, replica: shard.replicas[replicaIndex] }))
+        .filter((entry) => entry.result.status === 'rejected')
+        .map((entry) => ({
+          nodeId: entry.replica.nodeId,
+          url: entry.replica.url,
+          error: entry.result.reason?.message || 'direct write failed'
+        }));
+
+      if (failedReplicas.length > 0) {
+        try {
+          const relayResult = await relayStoreShard(api, {
+            shardId: shard.shardId,
+            fileId,
+            nodeIds: failedReplicas.map((replica) => replica.nodeId),
+            dataBuffer: encryptedBuffer
+          });
+
+          const promotedRelayReplicas = shard.replicas.filter((replica) =>
+            relayResult.successfulNodeIds.includes(replica.nodeId)
+          );
+
+          for (const replica of promotedRelayReplicas) {
+            if (!successfulReplicas.some((item) => item.nodeId === replica.nodeId)) {
+              successfulReplicas.push(replica);
+            }
+          }
+        } catch (relayError) {
+          console.warn(`[filecoin] reseed relay failed for shard ${shard.shardId}: ${relayError.message}`);
+        }
+      }
+
+      if (successfulReplicas.length > 0) {
+        try {
+          await api.post('/shards/register', {
+            shardId: shard.shardId,
+            fileId,
+            order: shard.order,
+            sizeBytes: shard.sizeBytes,
+            checksum: shard.checksum,
+            nodeIds: successfulReplicas.map((replica) => replica.nodeId)
+          });
+        } catch (registerError) {
+          console.warn(`[filecoin] reseed register failed for shard ${shard.shardId}: ${registerError.message}`);
+        }
+      }
+    }
+  })();
+}
+
 async function relayStoreShard(api, { shardId, fileId, nodeIds, dataBuffer, timeoutMs = 45000, pollMs = 200 }) {
   const opId = uuidv4();
   await api.post('/relay/shards/store', {
@@ -147,27 +301,43 @@ async function uploadFile(options) {
   });
 
   const encryptionShardMeta = [];
+  const encryptedShardBuffers = [];
 
   for (let order = 0; order < chunks.length; order += 1) {
     const shardId = `${fileId}-shard-${order}-${uuidv4().slice(0, 8)}`;
     const encrypted = encryptAes256Gcm(chunks[order], keyBuffer);
     const checksum = sha256Hex(encrypted.cipherText);
+    encryptedShardBuffers[order] = encrypted.cipherText;
 
-    const placementResponse = await api.post('/shards/placement-plan', {
-      shardId,
-      sizeBytes: encrypted.cipherText.length,
-      replicas
-    });
-
-    const plannedReplicas = placementResponse.data.replicas || [];
-    if (plannedReplicas.length < replicas) {
-      throw new Error(`placement failed for ${shardId}: expected ${replicas} replicas`);
+    let plannedReplicas = [];
+    try {
+      const placementResponse = await api.post('/shards/placement-plan', {
+        shardId,
+        sizeBytes: encrypted.cipherText.length,
+        replicas
+      });
+
+      plannedReplicas = placementResponse.data.replicas || [];
+      if (plannedReplicas.length < replicas) {
+        console.warn(`[upload] placement returned ${plannedReplicas.length}/${replicas} replicas for ${shardId}`);
+      }
+    } catch (error) {
+      const apiMessage = error.response?.data?.error;
+      const statusCode = error.response?.status;
+      if (statusCode === 409 && String(apiMessage || '').startsWith('insufficient_online_nodes')) {
+        console.warn(`[upload] placement unavailable for ${shardId}: ${apiMessage}`);
+        plannedReplicas = [];
+      } else {
+        throw error;
+      }
     }
 
     let successfulReplicas = [];
     let failedReplicas = [];
 
-    if (relayFirst) {
+    if (plannedReplicas.length === 0) {
+      console.warn(`[upload] no donor replicas available for shard ${shardId}; continuing with Filecoin only`);
+    } else if (relayFirst) {
       failedReplicas = plannedReplicas.map((replica) => ({
         nodeId: replica.nodeId,
         url: replica.url,
@@ -216,7 +386,8 @@ async function uploadFile(options) {
     }
 
     if (successfulReplicas.length === 0) {
-      throw new Error(`failed to write shard ${shardId} to any replica: ${failedReplicas.map((r) => `${r.url} (${r.error})`).join(', ')}`);
+      const failures = failedReplicas.map((r) => `${r.url} (${r.error})`).join(', ');
+      console.warn(`[upload] shard ${shardId} stored on 0 donors${failures ? `: ${failures}` : ''}`);
     }
 
     if (failedReplicas.length > 0) {
@@ -256,6 +427,25 @@ async function uploadFile(options) {
     }
   });
 
+  // Upload to Filecoin as default (synchronous with retries)
+  const encryptedFileBuffer = Buffer.concat(encryptedShardBuffers);
+  console.log(`[filecoin] uploading to Filecoin (this may take a while)...`);
+  const filecoinCid = await uploadToFilecoin(encryptedFileBuffer, fileId);
+  if (filecoinCid) {
+    try {
+      await api.post(`/files/${fileId}/filecoin`, {
+        filecoinCid,
+        filecoinBackedUp: true
+      });
+      console.log(`[filecoin] backup complete, cid: ${filecoinCid}`);
+    } catch (error) {
+      const message = error.response?.data?.error || error.message;
+      console.warn(`[filecoin] warning: failed to persist cid: ${message}`);
+    }
+  } else {
+    console.warn(`[filecoin] warning: upload to Filecoin failed, file backed up to Layer 1 only`);
+  }
+
   console.log(`Upload complete`);
   console.log(`fileId: ${fileId}`);
   console.log(`originalName: ${originalName}`);
@@ -290,70 +480,94 @@ async function downloadFile(options) {
   const shardMetaMap = new Map((encryption.shards || []).map((entry) => [entry.shardId, entry]));
 
   const orderedShards = [...(manifest.shards || [])].sort((a, b) => a.order - b.order);
-  const plainParts = [];
+  let reconstructed = null;
 
-  for (const shard of orderedShards) {
-    const shardMeta = shardMetaMap.get(shard.shardId);
-    if (!shardMeta) {
-      throw new Error(`missing encryption metadata for shard ${shard.shardId}`);
-    }
+  try {
+    const plainParts = [];
 
-    let encryptedBuffer = null;
-    if (!relayFirst) {
-      const directFetchResults = await Promise.allSettled(
-        (shard.replicas || []).map(async (replica) => {
-          const getUrl = `${normalizeUrl(replica.url)}/shards/${shard.shardId}`;
-          const response = await axios.get(getUrl, {
-            responseType: 'arraybuffer',
-            timeout: directTimeoutMs
+    for (const shard of orderedShards) {
+      const shardMeta = shardMetaMap.get(shard.shardId);
+      if (!shardMeta) {
+        throw new Error(`missing encryption metadata for shard ${shard.shardId}`);
+      }
+
+      let encryptedBuffer = null;
+      if (!relayFirst) {
+        const directFetchResults = await Promise.allSettled(
+          (shard.replicas || []).map(async (replica) => {
+            const getUrl = `${normalizeUrl(replica.url)}/shards/${shard.shardId}`;
+            const response = await axios.get(getUrl, {
+              responseType: 'arraybuffer',
+              timeout: directTimeoutMs
+            });
+            const candidate = Buffer.from(response.data);
+            if (sha256Hex(candidate) !== shard.checksum) {
+              throw new Error('checksum mismatch');
+            }
+            return candidate;
+          })
+        );
+
+        const successfulDirectFetch = directFetchResults.find((result) => result.status === 'fulfilled');
+        if (successfulDirectFetch) {
+          encryptedBuffer = successfulDirectFetch.value;
+        }
+      }
+
+      if (!encryptedBuffer && Array.isArray(shard.replicas) && shard.replicas.length > 0) {
+        try {
+          const relayResult = await relayFetchShard(api, {
+            shardId: shard.shardId,
+            nodeIds: shard.replicas.map((replica) => replica.nodeId)
           });
-          const candidate = Buffer.from(response.data);
-          if (sha256Hex(candidate) !== shard.checksum) {
-            throw new Error('checksum mismatch');
+
+          if (relayResult.data && sha256Hex(relayResult.data) === shard.checksum) {
+            encryptedBuffer = relayResult.data;
           }
-          return candidate;
-        })
-      );
+        } catch (relayError) {
+          console.warn(`[download] relay fetch failed for shard ${shard.shardId}: ${relayError.message}`);
+        }
+      }
 
-      const successfulDirectFetch = directFetchResults.find((result) => result.status === 'fulfilled');
-      if (successfulDirectFetch) {
-        encryptedBuffer = successfulDirectFetch.value;
+      if (!encryptedBuffer) {
+        throw new Error(`failed to fetch valid replica for shard ${shard.shardId}`);
       }
-    }
 
-    if (!encryptedBuffer && Array.isArray(shard.replicas) && shard.replicas.length > 0) {
       try {
-        const relayResult = await relayFetchShard(api, {
-          shardId: shard.shardId,
-          nodeIds: shard.replicas.map((replica) => replica.nodeId)
-        });
-
-        if (relayResult.data && sha256Hex(relayResult.data) === shard.checksum) {
-          encryptedBuffer = relayResult.data;
+        const plain = decryptAes256Gcm(encryptedBuffer, keyBuffer, shardMeta.iv, shardMeta.authTag);
+        plainParts.push(plain);
+      } catch (error) {
+        if (String(error.message || '').includes('unsupported state or unable to authenticate data')) {
+          throw new Error(
+            `decryption failed for shard ${shard.shardId}: key is incorrect or metadata/key mismatch (double-check key-base64 copy)`
+          );
         }
-      } catch (relayError) {
-        console.warn(`[download] relay fetch failed for shard ${shard.shardId}: ${relayError.message}`);
+        throw error;
       }
     }
 
-    if (!encryptedBuffer) {
-      throw new Error(`failed to fetch valid replica for shard ${shard.shardId}`);
-    }
+    reconstructed = Buffer.concat(plainParts);
+  } catch (error) {
+    console.warn(`[download] layer1 failed for ${fileId}: ${error.message}`);
 
-    try {
-      const plain = decryptAes256Gcm(encryptedBuffer, keyBuffer, shardMeta.iv, shardMeta.authTag);
-      plainParts.push(plain);
-    } catch (error) {
-      if (String(error.message || '').includes('unsupported state or unable to authenticate data')) {
-        throw new Error(
-          `decryption failed for shard ${shard.shardId}: key is incorrect or metadata/key mismatch (double-check key-base64 copy)`
-        );
-      }
+    const filecoinCid = manifest.file?.filecoinCid;
+    if (!filecoinCid) {
       throw error;
     }
-  }
 
-  const reconstructed = Buffer.concat(plainParts);
+    const encryptedFileBuffer = await retrieveFromFilecoin(filecoinCid);
+    if (!encryptedFileBuffer) {
+      throw new Error('filecoin retrieval failed');
+    }
+
+    const encryptedShardBuffers = splitEncryptedBufferBySizes(
+      encryptedFileBuffer,
+      orderedShards.map((shard) => shard.sizeBytes)
+    );
+
+    reconstructed = decryptShardsFromBuffers(orderedShards, shardMetaMap, encryptedShardBuffers, keyBuffer);
+    fireAndForgetLayer1Reseed(api, fileId, orderedShards, encryptedShardBuffers, directTimeoutMs);
+  }
   await fs.mkdir(path.dirname(output), { recursive: true });
   await fs.writeFile(output, reconstructed);