lsh-framework 3.6.0 → 3.7.0

package/README.md

@@ -115,6 +115,21 @@ lsh sync push --env dev
 
 If exactly one remote service is configured, `lsh` uses it automatically and `LSH_PIN_SERVICE` is optional.
 
+### Quickest: bundled pinner (just a token)
+
+Skip the manual `ipfs pin remote service add`. Set **`LSH_PIN_TOKEN`** and `lsh` auto-registers a
+remote pinning service for you on first push — defaulting to **4EVERLAND** (free 5GB, standard
+Pinning Service API):
+
+```bash
+# Get a free accessToken from the 4EVERLAND "4EVER Pin" page (https://4everland.org)
+export LSH_PIN_TOKEN=<your-4everland-accessToken>
+lsh push --env dev        # auto-registers "lsh-pin" → https://api.4everland.dev, then pins
+```
+
+Use a different provider by overriding the endpoint: `export LSH_PIN_ENDPOINT=<psa-endpoint>`.
+(Note: Pinata's pin-by-CID PSA is paid-only; 4EVERLAND and Filebase offer it free.)
+
 ## Installation
 
 ### Prerequisites
@@ -331,6 +346,11 @@ LSH_PIN_SERVICE=<service-name>
 # Default 'w3name,ipns': durable w3name (signed IPNS via name.web3.storage, no
 # account, no DHT TTL) with IPNS-over-DHT fallback. Set 'ipns' for DHT-only.
 LSH_DISCOVERY=w3name,ipns
+
+# Optional - bundled pinner: with a token set, lsh auto-registers a remote pin
+# service so pushed content is durable. Endpoint defaults to 4EVERLAND (free 5GB).
+LSH_PIN_TOKEN=<psa-access-token>
+LSH_PIN_ENDPOINT=https://api.4everland.dev   # override for another PSA provider
 ```
 
 ### Configuration Files

package/dist/constants/config.js

@@ -36,6 +36,12 @@ export const ENV_VARS = {
     // Discovery backend(s) for the key→CID pointer, comma-separated in priority
     // order. Supported: 'w3name' (durable, hosted), 'ipns' (DHT). Default: 'w3name,ipns'.
     LSH_DISCOVERY: 'LSH_DISCOVERY',
+    // Access token for a bundled IPFS remote pinning service. When set (and no
+    // remote pin service is already configured), lsh auto-registers one so pushed
+    // content is durably pinned. Endpoint defaults to 4EVERLAND (free 5GB).
+    LSH_PIN_TOKEN: 'LSH_PIN_TOKEN',
+    // Override the PSA endpoint used with LSH_PIN_TOKEN (any IPFS Pinning Service).
+    LSH_PIN_ENDPOINT: 'LSH_PIN_ENDPOINT',
     // Feature flags
     LSH_LOCAL_STORAGE_QUIET: 'LSH_LOCAL_STORAGE_QUIET',
     LSH_V1_COMPAT: 'LSH_V1_COMPAT',
@@ -148,4 +154,8 @@ export const DEFAULTS = {
     IPNS_KEY_DERIVATION_CONTEXT: 'lsh-ipns-v1',
     // Default discovery backends (priority order): durable w3name, then DHT-IPNS fallback.
     DISCOVERY_BACKENDS: 'w3name,ipns',
+    // Bundled remote pinning service (used with LSH_PIN_TOKEN). 4EVERLAND free tier (5GB),
+    // standard IPFS Pinning Service API. Override the endpoint via LSH_PIN_ENDPOINT.
+    DEFAULT_PIN_ENDPOINT: 'https://api.4everland.dev',
+    DEFAULT_PIN_SERVICE_NAME: 'lsh-pin',
 };

package/dist/lib/ipfs-sync.js

@@ -15,7 +15,23 @@ import * as path from 'path';
 import * as os from 'os';
 import { createLogger } from './logger.js';
 import { extractErrorMessage } from './lsh-error.js';
-import { ENV_VARS } from '../constants/config.js';
+import { ENV_VARS, DEFAULTS } from '../constants/config.js';
+/**
+ * Pure helper: choose which configured remote pinning service to use.
+ * - explicit `LSH_PIN_SERVICE` wins, but only if it's actually configured;
+ * - else the bundled default service (`lsh-pin`) if present;
+ * - else the sole configured service;
+ * - else null (none / ambiguous).
+ */
+export function chooseRemoteService(services, explicit, defaultName) {
+    if (explicit) {
+        return services.includes(explicit) ? explicit : null;
+    }
+    if (services.includes(defaultName)) {
+        return defaultName;
+    }
+    return services.length === 1 ? services[0] : null;
+}
 const logger = createLogger('IPFSSync');
 /**
  * Native IPFS Sync
@@ -369,12 +385,43 @@ export class IPFSSync {
      * - Returns null when nothing is configured or the choice is ambiguous.
      */
     async resolveRemoteService() {
+        await this.ensureDefaultPinService();
         const services = await this.listRemoteServices();
-        const explicit = process.env[ENV_VARS.LSH_PIN_SERVICE];
-        if (explicit) {
-            return services.includes(explicit) ? explicit : null;
+        return chooseRemoteService(services, process.env[ENV_VARS.LSH_PIN_SERVICE], DEFAULTS.DEFAULT_PIN_SERVICE_NAME);
+    }
+    /**
+     * Bundled pinner: when LSH_PIN_TOKEN is set and no remote pin service named
+     * `lsh-pin` is registered yet, auto-register one (endpoint defaults to
+     * 4EVERLAND, override via LSH_PIN_ENDPOINT). Lets users get durable pinning
+     * with just a token — no manual `ipfs pin remote service add`. Best-effort;
+     * never throws. Respects an existing service of the same name and the
+     * explicit LSH_PIN_SERVICE (handled by chooseRemoteService).
+     */
+    async ensureDefaultPinService() {
+        const token = process.env[ENV_VARS.LSH_PIN_TOKEN];
+        if (!token)
+            return;
+        const name = DEFAULTS.DEFAULT_PIN_SERVICE_NAME;
+        try {
+            const existing = await this.listRemoteServices();
+            if (existing.includes(name))
+                return;
+            const endpoint = process.env[ENV_VARS.LSH_PIN_ENDPOINT] || DEFAULTS.DEFAULT_PIN_ENDPOINT;
+            const url = `${this.LOCAL_IPFS_API}/pin/remote/service/add` +
+                `?arg=${encodeURIComponent(name)}` +
+                `&arg=${encodeURIComponent(endpoint)}` +
+                `&arg=${encodeURIComponent(token)}`;
+            const response = await fetch(url, { method: 'POST', signal: AbortSignal.timeout(10000) });
+            if (response.ok) {
+                logger.info(`📌 Registered bundled pin service "${name}" → ${endpoint}`);
+            }
+            else {
+                logger.warn(`Could not register pin service "${name}": ${await response.text()}`);
+            }
+        }
+        catch (error) {
+            logger.warn(`Pin service registration error: ${extractErrorMessage(error)}`);
         }
-        return services.length === 1 ? services[0] : null;
     }
     /**
      * Pin a CID to a configured remote pinning service so the content survives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lsh-framework",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Simple, cross-platform encrypted secrets manager with automatic sync, IPFS audit logs, and multi-environment support. Just run lsh sync and start managing your secrets.",
   "main": "dist/cli.js",
   "bin": {