lsh-framework 3.5.1 → 3.7.0

package/README.md

@@ -10,15 +10,13 @@
 [![Node.js CI](https://github.com/gwicho38/lsh/actions/workflows/node.js.yml/badge.svg)](https://github.com/gwicho38/lsh/actions/workflows/node.js.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What's New in v3.1.19
+## What's New in v3.5.x
 
-- **Type Safety Milestone** - All `@typescript-eslint/no-explicit-any` warnings eliminated (51+ → 0)
-- **Constants Centralization** - Hardcoded strings moved to constants modules
-- **API Response Builder** - Standardized API responses with `sendSuccess`, `sendError`, `ApiErrors`
-- **Test Coverage** - 59 new tests for constants modules (142 total constants tests)
-- **Code Quality** - Lint warnings reduced from 744 to 550 (26.1% reduction)
+- **Focused on secrets** - Removed the dormant pre-pivot platform code (SaaS multi-tenant, job/cron daemon, Supabase/Postgres persistence). LSH is now purely an encrypted `.env` sync tool over IPFS.
+- **Dependency modernization** - Express 5, TypeScript 6, ESLint 10, Jest 30.
+- **Hardening** - Bounded network calls (no hangs), command-injection fix in the Kubo installer, reliable npm publishing.
 
-See [Release Notes](docs/releases/3.1.19.md) for full details.
+See [Release Notes](docs/releases/3.5.0.md) for full details.
 
 ## Quick Start
 
@@ -117,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
@@ -211,22 +224,17 @@ lsh pull --env prod
 
 ## Automatic Secret Rotation
 
-Use the built-in daemon for automated rotation:
+Schedule rotation with any external scheduler (system `cron`, a CI job, etc.) that
+runs your rotation script and then pushes the updated secrets:
 
 ```bash
-# Start daemon
-lsh daemon start
-
-# Schedule monthly key rotation
-lsh cron add \
-  --name "rotate-keys" \
-  --schedule "0 0 1 * *" \
-  --command "./scripts/rotate.sh && lsh push"
-
-# List scheduled jobs
-lsh cron list
+# Example: monthly rotation via crontab — `crontab -e`
+0 0 1 * * cd /path/to/project && ./scripts/rotate.sh && lsh push
 ```
 
+Or as a scheduled CI job (GitHub Actions, etc.) that runs the script and `lsh push`.
+LSH focuses on encrypting and syncing the `.env`; the rotation policy/schedule is yours.
+
 ## Export Formats
 
 Export secrets in multiple formats:
@@ -322,27 +330,6 @@ lsh push
 - **[Installation](docs/deployment/INSTALL.md)** - Detailed installation
 - **[Developer Guide](CLAUDE.md)** - Contributing to LSH
 
-## Advanced Features
-
-LSH includes a full automation platform:
-
-- **Persistent Daemon** - Background job execution
-- **Cron Scheduling** - Time-based job scheduling
-- **REST API** - HTTP API for integration
-- **CI/CD Webhooks** - GitHub/GitLab webhook support
-- **POSIX Shell** - Interactive shell with ZSH features
-
-```bash
-# Start daemon
-lsh daemon start
-
-# API server
-LSH_API_KEY=xxx lsh api start --port 3030
-
-# Interactive shell
-lsh -i
-```
-
 ## Configuration
 
 ### Environment Variables
@@ -355,14 +342,15 @@ LSH_SECRETS_KEY=<your-encryption-key>
 # (configure once with: ipfs pin remote service add <name> <endpoint> <key>)
 LSH_PIN_SERVICE=<service-name>
 
-# Optional - Supabase backend
-SUPABASE_URL=https://xxx.supabase.co
-SUPABASE_ANON_KEY=<key>
+# Optional - pointer discovery backends, comma-separated in priority order.
+# 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 - API server
-LSH_API_ENABLED=true
-LSH_API_PORT=3030
-LSH_API_KEY=<key>
+# 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

@@ -33,6 +33,15 @@ export const ENV_VARS = {
     // Name of the kubo remote pinning service to use for durable sync
     // (configured via `ipfs pin remote service add <name> <endpoint> <key>`).
     LSH_PIN_SERVICE: 'LSH_PIN_SERVICE',
+    // 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',
@@ -143,4 +152,10 @@ export const DEFAULTS = {
     IPNS_RESOLVE_TIMEOUT_MS: 30000, // 30s for DHT lookup
     IPNS_KEY_PREFIX: 'lsh-',
     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/discovery-backend.js

@@ -0,0 +1,150 @@
+/**
+ * Discovery backend seam.
+ *
+ * "Discovery" = mapping a key-derived pointer to the latest content CID
+ * (publish on push, resolve on pull). Today the only backend is IPNS over the
+ * DHT (`IpnsDiscoveryBackend`), which is what LSH has always used — this module
+ * just extracts that behind an interface so additional backends (e.g. a durable
+ * w3name pointer; see issue #194) can be added without touching the storage layer.
+ *
+ * This is a behaviour-preserving refactor: `getDiscoveryBackend()` returns the
+ * IPNS backend, identical to the previous inline logic.
+ */
+import { deriveKeyInfo as defaultDeriveKeyInfo, ensureKeyImported as defaultEnsureKeyImported, } from './ipns-key-manager.js';
+import { w3namePublish as defaultW3namePublish, w3nameResolve as defaultW3nameResolve, } from './w3name-pointer.js';
+import { ENV_VARS, DEFAULTS } from '../constants/config.js';
+import { createLogger } from './logger.js';
+const logger = createLogger('Discovery');
+/**
+ * IPNS-over-DHT discovery: derive a deterministic ed25519 key from the secrets
+ * key, import it into the local Kubo keystore, and publish/resolve via IPNS.
+ */
+export class IpnsDiscoveryBackend {
+    ipfsSync;
+    deps;
+    id = 'ipns';
+    constructor(ipfsSync, deps = {
+        deriveKeyInfo: defaultDeriveKeyInfo,
+        ensureKeyImported: defaultEnsureKeyImported,
+    }) {
+        this.ipfsSync = ipfsSync;
+        this.deps = deps;
+    }
+    async publish({ secretsKey, repoName, env, cid }) {
+        const keyInfo = this.deps.deriveKeyInfo(secretsKey, repoName, env);
+        const ipnsName = await this.deps.ensureKeyImported(this.ipfsSync.getApiUrl(), keyInfo);
+        if (!ipnsName) {
+            return null;
+        }
+        return this.ipfsSync.publishToIPNS(cid, keyInfo.keyName);
+    }
+    async resolve({ secretsKey, repoName, env }) {
+        const keyInfo = this.deps.deriveKeyInfo(secretsKey, repoName, env);
+        const ipnsName = await this.deps.ensureKeyImported(this.ipfsSync.getApiUrl(), keyInfo);
+        if (!ipnsName) {
+            return { cid: null, name: null };
+        }
+        const cid = await this.ipfsSync.resolveIPNS(ipnsName);
+        return { cid, name: ipnsName };
+    }
+}
+/**
+ * Durable discovery via w3name (Storacha). Publishes/resolves a signed IPNS
+ * record hosted at name.web3.storage — survives offline nodes, no DHT TTL, no
+ * account. Uses the SAME seed-derived IPNS name as the `ipns` backend.
+ */
+export class W3nameDiscoveryBackend {
+    deps;
+    id = 'w3name';
+    constructor(deps = {
+        deriveKeyInfo: defaultDeriveKeyInfo,
+        publish: defaultW3namePublish,
+        resolve: defaultW3nameResolve,
+    }) {
+        this.deps = deps;
+    }
+    async publish({ secretsKey, repoName, env, cid }) {
+        const { seed } = this.deps.deriveKeyInfo(secretsKey, repoName, env);
+        return this.deps.publish(seed, cid);
+    }
+    async resolve({ secretsKey, repoName, env }) {
+        const { seed } = this.deps.deriveKeyInfo(secretsKey, repoName, env);
+        return this.deps.resolve(seed);
+    }
+}
+/**
+ * Composes backends in priority order. Publish dual-writes to all (best-effort —
+ * a failure in one doesn't block the others). Resolve tries each in order and
+ * returns the first hit, so a durable backend wins but a fallback still works.
+ */
+export class CompositeDiscoveryBackend {
+    backends;
+    id;
+    constructor(backends) {
+        this.backends = backends;
+        this.id = backends.map((b) => b.id).join('+');
+    }
+    async publish(params) {
+        let firstName = null;
+        for (const backend of this.backends) {
+            try {
+                const name = await backend.publish(params);
+                if (name && !firstName) {
+                    firstName = name;
+                }
+            }
+            catch (error) {
+                logger.warn(`Discovery publish via "${backend.id}" failed: ${error.message}`);
+            }
+        }
+        return firstName;
+    }
+    async resolve(params) {
+        let firstName = null;
+        for (const backend of this.backends) {
+            try {
+                const result = await backend.resolve(params);
+                if (result.name && !firstName) {
+                    firstName = result.name;
+                }
+                if (result.cid) {
+                    return result;
+                }
+            }
+            catch (error) {
+                logger.warn(`Discovery resolve via "${backend.id}" failed: ${error.message}`);
+            }
+        }
+        return { cid: null, name: firstName };
+    }
+}
+/** Construct a single backend by id, or null if unknown. */
+function buildBackend(id, ipfsSync) {
+    switch (id) {
+        case 'ipns':
+            return new IpnsDiscoveryBackend(ipfsSync);
+        case 'w3name':
+            return new W3nameDiscoveryBackend();
+        default:
+            logger.warn(`Unknown discovery backend "${id}" — ignoring.`);
+            return null;
+    }
+}
+/**
+ * Select discovery backend(s) from `LSH_DISCOVERY` (comma-separated, priority
+ * order; default 'w3name,ipns'). Returns a single backend or a composite.
+ * Falls back to IPNS if the setting resolves to nothing valid.
+ */
+export function getDiscoveryBackend(ipfsSync) {
+    const setting = process.env[ENV_VARS.LSH_DISCOVERY] || DEFAULTS.DISCOVERY_BACKENDS;
+    const backends = setting
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean)
+        .map((id) => buildBackend(id, ipfsSync))
+        .filter((b) => b !== null);
+    if (backends.length === 0) {
+        return new IpnsDiscoveryBackend(ipfsSync);
+    }
+    return backends.length === 1 ? backends[0] : new CompositeDiscoveryBackend(backends);
+}

package/dist/lib/ipfs-secrets-storage.js

@@ -13,7 +13,7 @@ import * as os from 'os';
 import * as crypto from 'crypto';
 import { createLogger } from './logger.js';
 import { getIPFSSync } from './ipfs-sync.js';
-import { deriveKeyInfo, ensureKeyImported } from './ipns-key-manager.js';
+import { getDiscoveryBackend } from './discovery-backend.js';
 import { ENV_VARS, DEFAULTS } from '../constants/index.js';
 import { extractErrorMessage } from './lsh-error.js';
 const logger = createLogger('IPFSSecretsStorage');
@@ -95,16 +95,13 @@ export class IPFSSecretsStorage {
                 try {
                     const repoName = gitRepo || DEFAULTS.DEFAULT_ENVIRONMENT;
                     const env = environment || DEFAULTS.DEFAULT_ENVIRONMENT;
-                    const keyInfo = deriveKeyInfo(encryptionKey, repoName, env);
-                    const ipnsName = await ensureKeyImported(ipfsSync.getApiUrl(), keyInfo);
-                    if (ipnsName) {
-                        const publishedName = await ipfsSync.publishToIPNS(cid, keyInfo.keyName);
-                        if (publishedName) {
-                            metadata.ipns_name = publishedName;
-                            this.metadata[this.getMetadataKey(gitRepo, environment)] = metadata;
-                            await this.saveMetadata();
-                            logger.info(`   🔗 Published to IPNS: ${publishedName}`);
-                        }
+                    const discovery = getDiscoveryBackend(ipfsSync);
+                    const publishedName = await discovery.publish({ secretsKey: encryptionKey, repoName, env, cid });
+                    if (publishedName) {
+                        metadata.ipns_name = publishedName;
+                        this.metadata[this.getMetadataKey(gitRepo, environment)] = metadata;
+                        await this.saveMetadata();
+                        logger.info(`   🔗 Published to ${discovery.id}: ${publishedName}`);
                     }
                 }
                 catch (error) {
@@ -140,11 +137,12 @@ export class IPFSSecretsStorage {
                 try {
                     const repoName = gitRepo || DEFAULTS.DEFAULT_ENVIRONMENT;
                     const env = environment || DEFAULTS.DEFAULT_ENVIRONMENT;
-                    const keyInfo = deriveKeyInfo(encryptionKey, repoName, env);
-                    const ipnsName = await ensureKeyImported(ipfsSync.getApiUrl(), keyInfo);
+                    const discovery = getDiscoveryBackend(ipfsSync);
+                    const resolved = await discovery.resolve({ secretsKey: encryptionKey, repoName, env });
+                    const ipnsName = resolved.name;
                     if (ipnsName) {
                         logger.info(`   🔍 Resolving via IPNS: ${ipnsName.substring(0, 20)}...`);
-                        resolvedCid = await ipfsSync.resolveIPNS(ipnsName);
+                        resolvedCid = resolved.cid;
                         if (resolvedCid) {
                             logger.info(`   ✅ IPNS resolved to CID: ${resolvedCid}`);
                             // Update local metadata

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/dist/lib/w3name-pointer.js

@@ -0,0 +1,72 @@
+/**
+ * w3name pointer ops (issue #194, Phase 2).
+ *
+ * Durable IPNS via Storacha's w3name: publish a signed record mapping the
+ * key-derived IPNS name → `/ipfs/<cid>`, hosted at name.web3.storage (no account,
+ * no auth). The name is IDENTICAL to the one Kubo derives from the same seed
+ * (verified in the Phase-2 spike), so this shares one logical pointer with the
+ * IPNS-over-DHT backend.
+ *
+ * w3name + @libp2p/crypto are heavy ESM deps; they are **lazily imported** inside
+ * the functions so the CLI / unit tests don't load them unless w3name is actually
+ * used.
+ */
+import { createLogger } from './logger.js';
+const logger = createLogger('W3namePointer');
+const PUBLISH_TIMEOUT_MS = 15000;
+const RESOLVE_TIMEOUT_MS = 10000;
+function withTimeout(p, ms, label) {
+    return Promise.race([
+        p,
+        new Promise((_, reject) => {
+            const timer = setTimeout(() => reject(new Error(`w3name ${label} timed out after ${ms}ms`)), ms);
+            timer.unref?.();
+        }),
+    ]);
+}
+/** Build a w3name WritableName from a 32-byte ed25519 seed (deterministic). */
+async function writableFromSeed(seed) {
+    const [{ generateKeyPairFromSeed, privateKeyToProtobuf }, Name] = await Promise.all([
+        import('@libp2p/crypto/keys'),
+        import('w3name'),
+    ]);
+    const priv = await generateKeyPairFromSeed('Ed25519', new Uint8Array(seed));
+    const name = await Name.from(privateKeyToProtobuf(priv));
+    return { Name, name };
+}
+/**
+ * Publish `cid` under the seed-derived w3name pointer. Returns the IPNS name.
+ * Handles IPNS sequencing: increments from the current revision if one exists,
+ * else publishes v0.
+ */
+export async function w3namePublish(seed, cid) {
+    const { Name, name } = await writableFromSeed(seed);
+    const value = `/ipfs/${cid}`;
+    let revision;
+    try {
+        const current = await withTimeout(Name.resolve(name), RESOLVE_TIMEOUT_MS, 'resolve(pre-publish)');
+        revision = await Name.increment(current, value);
+    }
+    catch {
+        // No existing record (or unresolvable) → start a fresh revision.
+        revision = await Name.v0(name, value);
+    }
+    await withTimeout(Name.publish(revision, name.key), PUBLISH_TIMEOUT_MS, 'publish');
+    logger.debug(`Published to w3name: ${name.toString()} → ${value}`);
+    return name.toString();
+}
+/** Resolve the latest CID for the seed-derived w3name pointer. */
+export async function w3nameResolve(seed) {
+    const { Name, name } = await writableFromSeed(seed);
+    const nameStr = name.toString();
+    try {
+        const revision = await withTimeout(Name.resolve(Name.parse(nameStr)), RESOLVE_TIMEOUT_MS, 'resolve');
+        const value = revision.value; // "/ipfs/<cid>"
+        const cid = value.startsWith('/ipfs/') ? value.slice('/ipfs/'.length) : null;
+        return { cid, name: nameStr };
+    }
+    catch (error) {
+        logger.debug(`w3name resolve failed for ${nameStr}: ${error.message}`);
+        return { cid: null, name: nameStr };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lsh-framework",
-  "version": "3.5.1",
+  "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": {
@@ -63,6 +63,7 @@
     "package.json"
   ],
   "dependencies": {
+    "@libp2p/crypto": "^5.1.19",
     "@supabase/supabase-js": "^2.57.4",
     "bcrypt": "^6.0.0",
     "chalk": "^5.3.0",
@@ -80,7 +81,8 @@
     "ora": "^9.0.0",
     "pg": "^8.16.3",
     "proper-lockfile": "^4.1.2",
-    "smol-toml": "^1.3.1"
+    "smol-toml": "^1.3.1",
+    "w3name": "^1.1.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",