wiki-plugin-lucille 0.0.1

package/CLAUDE.md

@@ -0,0 +1,201 @@
+# wiki-plugin-lucille — Developer Documentation
+
+P2P video hosting for Federated Wiki, backed by DigitalOcean Spaces (cold storage) and WebTorrent (live delivery).
+
+**Current version**: 0.0.1
+
+## Architecture
+
+Follows the Service-Bundling Plugin Pattern. The wiki plugin (`wiki-plugin-lucille`) spawns and proxies a standalone Node.js service (`lucille`). Each wiki instance gets its own DO Spaces bucket and its own BitTorrent tracker.
+
+```
+Federated Wiki
+  └── wiki-plugin-lucille (CommonJS plugin)
+        ├── server/server.js     ← spawns lucille, proxies /plugin/lucille/*
+        ├── client/lucille.js    ← renders items in the wiki journal
+        └── node_modules/lucille ← the lucille service (ESM)
+              ├── lucille.js     ← Express API + tracker + seeder bootstrap
+              └── src/
+                    ├── config.js       ← tiers, federation peers
+                    ├── seeder.js       ← WebTorrent seeder
+                    ├── tracker.js      ← bittorrent-tracker server
+                    ├── spaces.js       ← DO Spaces upload/presign
+                    └── persistence/    ← file-based key-value DB
+```
+
+### Service modes
+
+The lucille service supports three modes via `LUCILLE_MODE` env var:
+
+| Mode | Description |
+|------|-------------|
+| `all` | API + tracker + seeder (default for wiki plugin) |
+| `tracker` | Tracker only (no API, no seeding) |
+| `api` | API only (no tracker, no seeder) |
+
+### Storage and Seeding Flow
+
+1. Client uploads video → `PUT /user/:uuid/video/:title/file`
+2. Server writes to temp file, hashes (SHA-256), uploads to DO Spaces
+3. `seedVideo(spacesKey)` downloads the file from Spaces and seeds via WebTorrent
+4. Magnet URI + infoHash stored in video record
+5. Player at `GET /watch/:videoId` loads player.html, which fetches magnet from `GET /video/:videoId/watch` and streams via WebTorrent.js
+
+### Federation
+
+Each lucille instance publishes its tracker URL at `GET /federation/trackers`. On startup, the seeder fetches all peer tracker URLs from configured federation peers and builds a unified announce list. This means every video is announced on every peer's tracker — no central registry needed.
+
+```
+Instance A startup:
+  1. Start own tracker (ws://wiki-a.example.com:8000)
+  2. Fetch wiki-b.example.com/plugin/lucille/federation/trackers
+  3. Build announce list: [ws://wiki-a:8000, ws://wiki-b:9000]
+  4. seedAll() — each torrent announces to both trackers
+```
+
+## Tiers
+
+Wiki owners configure their own tiers. Defaults:
+
+| Tier | Price | Storage | Videos | Duration |
+|------|-------|---------|--------|----------|
+| Free | 0 MP | 500 MB | 5 | 10 min |
+| Creator | 500 MP | 10 GB | 50 | 1 hr |
+| Pro | 2000 MP | unlimited | unlimited | unlimited |
+
+`0` in storageLimit/videoLimit/durationLimit means unlimited.
+
+Quota is enforced at:
+- `PUT /user/:uuid/video/:title` — video count check
+- `PUT /user/:uuid/video/:title/file` — storage check + video count check
+
+Quota errors return HTTP 402 with `{ error: "...", upgradeRequired: true }`.
+
+## Setup / Onboarding
+
+Wiki owner visits `/plugin/lucille/setup` to configure:
+- **DO Spaces credentials** — key, secret, region, bucket, CDN endpoint
+- **Tracker** — port (must be open in firewall) + public hostname for federation
+- **Tiers** — JSON array of tier definitions
+- **Federation peers** — newline-separated base URLs of other lucille instances
+- **Sanora URL** — for tier upgrade payments via Addie
+
+Config stored at `~/.lucille/config.json`.
+
+## Routes
+
+### Plugin (served by wiki plugin server.js)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET`  | `/plugin/lucille/setup` | Onboarding UI |
+| `POST` | `/plugin/lucille/setup` | Save config + (re)launch lucille |
+| `GET`  | `/plugin/lucille/setup/status` | Config + running status JSON |
+| `GET`  | `/plugin/lucille/version-status` | Installed vs npm version |
+| `POST` | `/plugin/lucille/update` | `npm install lucille@latest` |
+| `*`    | `/plugin/lucille/*` | Proxied to lucille service |
+
+### Lucille service (proxied at `/plugin/lucille/*`)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET`  | `/health` | — | Health check |
+| `GET`  | `/status` | — | Seeder/tracker status |
+| `GET`  | `/config` | — | Current config (no credentials) |
+| `POST` | `/config` | — | Update tiers/peers/sanoraUrl |
+| `GET`  | `/tiers` | — | Tier list |
+| `GET`  | `/federation/trackers` | — | Own tracker URL + lucille base URL |
+| `PUT`  | `/user/create` | Sessionless | Create user |
+| `GET`  | `/user/:uuid` | Sessionless | Get user + tier details |
+| `PUT`  | `/user/:uuid/tier` | Sessionless | Upgrade tier |
+| `PUT`  | `/user/:uuid/video/:title` | Sessionless | Register video metadata |
+| `GET`  | `/user/:uuid/videos` | Sessionless | List user's videos (private) |
+| `GET`  | `/videos/:uuid` | Public | List user's videos (public) |
+| `PUT`  | `/user/:uuid/video/:title/file` | Sessionless (headers) | Upload video file |
+| `GET`  | `/watch/:videoId` | Public | Player page (iframe-embeddable) |
+| `GET`  | `/video/:videoId/watch` | Public | Magnet + tracker JSON |
+| `GET`  | `/magnet?key=videos/…` | Internal | Magnet for a Spaces key |
+| `POST` | `/seed` | Internal | Notify of new video key |
+
+### Sessionless auth
+
+All authed endpoints use the sessionless pattern:
+- Body (PUT): `{ timestamp, pubKey, signature }` where `signature = sign(timestamp + pubKey)`
+- Query (GET): `?timestamp=…&signature=…` where `signature = sign(timestamp + user.pubKey)`
+- File upload (PUT `…/file`): signature in headers `x-pn-timestamp`, `x-pn-signature`
+
+## Wiki item format
+
+```json
+{
+  "type": "lucille",
+  "videoId": "abc123",
+  "text": "My Video Title",
+  "description": "Short description",
+  "price": 0,
+  "playerBase": "/plugin/lucille"
+}
+```
+
+The client plugin renders a thumbnail with a play button. Clicking opens an iframe lightbox pointing to `/plugin/lucille/watch/:videoId`.
+
+## Client plugin
+
+`client/lucille.js` follows the standard `window.plugins.NAME = { emit, bind }` pattern.
+
+- **emit** — renders the video card (thumbnail + title + description + price)
+- **bind** — adds a traffic-light ◉ status indicator showing version state (gray=loading, red=not installed, yellow=update available, green=current)
+
+The shared lightbox (`lucilleOpen`/`lucilleClose`) is injected once into `document.body` and reused across all items on the page.
+
+## Environment variables (lucille service)
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| `PORT` | `5444` | API port |
+| `LUCILLE_MODE` | `all` | `all` / `tracker` / `api` |
+| `DO_SPACES_KEY` | — | DO Spaces access key |
+| `DO_SPACES_SECRET` | — | DO Spaces secret |
+| `DO_SPACES_REGION` | `nyc3` | DO Spaces region |
+| `DO_SPACES_BUCKET` | — | Bucket name |
+| `DO_SPACES_CDN_ENDPOINT` | — | CDN URL (optional) |
+| `TRACKER_PORT` | `8000` | BitTorrent tracker WebSocket port |
+| `TRACKER_URL` | `ws://localhost:8000` | Public tracker URL (used in announce lists) |
+| `SANORA_URL` | — | Sanora base URL for payments |
+| `ALLOWED_TIME_DIFFERENCE` | `600000` | Max timestamp skew (ms) |
+
+## Dependencies
+
+### wiki-plugin-lucille (CommonJS)
+```json
+{
+  "http-proxy": "^1.18.1",
+  "lucille": "file:../../lucille",
+  "node-fetch": "^2.6.1"
+}
+```
+
+### lucille service (ESM)
+```json
+{
+  "@aws-sdk/client-s3": "^3.705.0",
+  "@aws-sdk/s3-request-presigner": "^3.705.0",
+  "bittorrent-tracker": "latest",
+  "cors": "^2.8.5",
+  "express": "^4.21.2",
+  "express-fileupload": "^1.5.1",
+  "sessionless-node": "latest",
+  "webtorrent": "^2.5.1"
+}
+```
+
+## Storage
+
+- `~/.lucille/config.json` — plugin config (DO Spaces credentials, tiers, federation peers)
+- Lucille service uses its own file-based DB in `src/persistence/` for users, videos, and keys
+
+## nginx / firewall requirements
+
+- Tracker port (default 8000) must be open for WebSocket connections for federation to work
+- The wiki's nginx should not proxy-pass the tracker port (it runs on its own port, not through the wiki)
+- For large video uploads, set `client_max_body_size` appropriately (e.g. `500M`)

package/client/lucille.js

@@ -0,0 +1,198 @@
+// wiki-plugin-lucille — client-side plugin
+// Renders lucille items in the fedwiki journal.
+// Item data: { type: 'lucille', videoId, title, description, price }
+
+window.plugins = window.plugins || {};
+
+window.plugins.lucille = (function() {
+
+  // ── Traffic light colors (matching plugmatic) ─────────────────────────────
+  const color = {
+    gray:   '#ccc',
+    red:    '#f55',
+    yellow: '#fb0',
+    green:  '#0e0'
+  };
+
+  // ── Emit: render the item ─────────────────────────────────────────────────
+  function emit($item, item) {
+    const videoId    = item.videoId    || '';
+    const title      = item.text       || item.title || 'Untitled';
+    const description = item.description || '';
+    const price      = item.price      || 0;
+    const playerBase = item.playerBase || '/plugin/lucille';
+
+    // Check owner status and render config section if owner
+    fetch('/plugin/lucille/setup/status', { credentials: 'include' })
+      .then(r => r.json())
+      .then(data => {
+        if (!data.isOwner) return;
+        const configDiv = document.createElement('div');
+        configDiv.style.cssText = 'border:1px solid rgba(167,139,250,0.3);border-radius:8px;padding:12px;margin-top:8px;background:rgba(167,139,250,0.06);font-family:system-ui;';
+        const stripeStatus = data.stripeOnboarded
+          ? '<span style="color:#0e0;font-size:0.75rem;">✅ Stripe payouts enabled</span>'
+          : data.serverAddieReady
+            ? '<a href="/plugin/lucille/setup/stripe" target="_blank" style="color:#fb0;font-size:0.75rem;">⚠️ Complete Stripe setup →</a>'
+            : '';
+        configDiv.innerHTML = `
+          <div style="font-size:0.8rem;color:#a78bfa;margin-bottom:8px;font-weight:600;">Allyabase connection (owner only)</div>
+          <div style="display:flex;gap:6px;align-items:center;">
+            <input id="luc-url-input" value="${escapeHtml(data.allyabaseUrl || '')}" placeholder="https://dev.allyabase.com"
+              style="flex:1;background:#0d001a;border:1px solid rgba(167,139,250,0.3);border-radius:4px;padding:6px 8px;color:#e0d0ff;font-size:0.8rem;">
+            <button id="luc-url-btn"
+              style="background:#7c3aed;border:none;border-radius:4px;padding:6px 12px;color:white;cursor:pointer;font-size:0.8rem;white-space:nowrap;">
+              Save
+            </button>
+          </div>
+          <div id="luc-url-status" style="margin-top:6px;font-size:0.75rem;"></div>
+          ${stripeStatus ? '<div style="margin-top:6px;">' + stripeStatus + '</div>' : ''}`;
+        $item.append(configDiv);
+        configDiv.querySelector('#luc-url-btn').addEventListener('click', function() {
+          const input  = configDiv.querySelector('#luc-url-input');
+          const btn    = configDiv.querySelector('#luc-url-btn');
+          const status = configDiv.querySelector('#luc-url-status');
+          const base   = (input.value || '').trim().replace(/\/$/, '');
+          if (!base) { status.textContent = 'Enter an allyabase URL first'; return; }
+          btn.disabled = true; btn.textContent = 'Saving…';
+          fetch('/plugin/lucille/setup', {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ allyabaseUrl: base })
+          })
+            .then(r => r.json())
+            .then(d => {
+              if (d.error) { status.innerHTML = '<span style="color:#f55;">' + escapeHtml(d.error) + '</span>'; return; }
+              status.innerHTML = '<span style="color:#0e0;">Saved</span>';
+            })
+            .catch(e => { status.innerHTML = '<span style="color:#f55;">' + escapeHtml(e.message) + '</span>'; })
+            .finally(() => { btn.disabled = false; btn.textContent = 'Save'; });
+        });
+      })
+      .catch(() => {});
+
+    if (!videoId) {
+      // No video yet — show setup prompt
+      $item.append(`
+        <div style="
+          background: rgba(167,139,250,0.08);
+          border: 2px dashed rgba(167,139,250,0.3);
+          border-radius: 10px;
+          padding: 20px;
+          text-align: center;
+          color: #a78bfa;
+          font-family: system-ui;
+        ">
+          <div style="font-size: 2rem; margin-bottom: 8px;">🎬</div>
+          <div style="font-weight: 600;">${escapeHtml(title)}</div>
+          <div style="font-size: 0.85rem; margin-top: 8px; opacity: 0.7;">No video uploaded yet</div>
+        </div>
+      `);
+      return;
+    }
+
+    const playerUrl = `${playerBase}/watch/${encodeURIComponent(videoId)}`;
+
+    $item.append(`
+      <div class="lucille-item" style="font-family: system-ui;">
+        <div class="lucille-thumb" style="
+          position: relative;
+          background: #111;
+          border-radius: 8px;
+          overflow: hidden;
+          aspect-ratio: 16/9;
+          cursor: pointer;
+        " onclick="window.lucilleOpen('${escapeAttr(playerUrl)}', '${escapeAttr(title)}')">
+          <div style="
+            position: absolute; inset: 0;
+            display: flex; align-items: center; justify-content: center;
+            background: linear-gradient(135deg, #1a0033 0%, #0a001a 100%);
+          ">
+            <span style="font-size: 48px; opacity: 0.7; filter: drop-shadow(0 0 12px #a78bfa);">▶</span>
+          </div>
+          <div style="
+            position: absolute; bottom: 0; left: 0; right: 0;
+            padding: 10px 12px;
+            background: linear-gradient(to top, rgba(0,0,0,0.8), transparent);
+            color: white;
+            font-size: 0.9rem;
+            font-weight: 600;
+          ">${escapeHtml(title)}</div>
+        </div>
+        ${description ? `<div style="font-size: 0.85rem; color: #666; margin-top: 6px; padding: 0 2px;">${escapeHtml(description)}</div>` : ''}
+        ${price > 0 ? `<div style="font-size: 0.8rem; color: #a78bfa; margin-top: 4px; padding: 0 2px;">${price} MP</div>` : ''}
+      </div>
+    `);
+  }
+
+  // ── Bind: editor & version status ─────────────────────────────────────────
+  function bind($item, item) {
+    // Version status indicator (◉ traffic light — matches plugmatic style)
+    const $status = $('<span>').text('◉ ').css({ color: color.gray, cursor: 'pointer' })
+      .attr('title', 'Lucille service status');
+
+    $item.find('.item-buttons').prepend($status);
+
+    // Check service status
+    fetch('/plugin/lucille/version-status')
+      .then(r => r.json())
+      .then(data => {
+        if (!data.installed) {
+          $status.css('color', color.red).attr('title', 'Lucille not installed');
+        } else if (data.updateAvailable) {
+          $status.css('color', color.yellow).attr('title', `Update available: ${data.installed} → ${data.published}`);
+          $status.on('click', () => {
+            if (confirm(`Update lucille from ${data.installed} to ${data.published}?\nWiki will need a restart.`)) {
+              fetch('/plugin/lucille/update', { method: 'POST' })
+                .then(r => r.json())
+                .then(result => {
+                  if (result.success) alert(`Updated to ${result.version}. Please restart the wiki server.`);
+                  else alert('Update failed: ' + result.error);
+                });
+            }
+          });
+        } else {
+          $status.css('color', color.green).attr('title', `Lucille ${data.installed} — up to date`);
+        }
+      })
+      .catch(() => {
+        $status.css('color', color.red).attr('title', 'Could not reach lucille service');
+      });
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+  function escapeHtml(str) {
+    return String(str).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+  }
+  function escapeAttr(str) {
+    return String(str).replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+  }
+
+  return { emit, bind };
+}());
+
+// ── Video lightbox (shared, injected once) ────────────────────────────────────
+if (!window.lucilleOpen) {
+  // Inject modal into body
+  const modal = document.createElement('div');
+  modal.id = 'lucille-modal';
+  modal.style.cssText = 'display:none;position:fixed;inset:0;z-index:9999;align-items:center;justify-content:center;background:rgba(0,0,0,0.88);';
+  modal.innerHTML = `
+    <div style="position:relative;width:90vw;max-width:960px;aspect-ratio:16/9;background:#000;border-radius:10px;overflow:hidden;box-shadow:0 24px 80px rgba(0,0,0,0.7);">
+      <button onclick="lucilleClose()" style="position:absolute;top:10px;right:12px;z-index:2;background:rgba(0,0,0,0.5);border:none;color:#fff;font-size:20px;padding:4px 10px;border-radius:6px;cursor:pointer;">✕</button>
+      <iframe id="lucille-iframe" src="" allowfullscreen allow="autoplay" style="width:100%;height:100%;border:none;display:block;"></iframe>
+    </div>`;
+  document.body.appendChild(modal);
+
+  window.lucilleOpen = function(url, title) {
+    document.getElementById('lucille-iframe').src = url;
+    modal.style.display = 'flex';
+    document.title = title || document.title;
+  };
+  window.lucilleClose = function() {
+    modal.style.display = 'none';
+    document.getElementById('lucille-iframe').src = '';
+  };
+  document.addEventListener('keydown', e => { if (e.key === 'Escape') window.lucilleClose(); });
+  modal.addEventListener('click', e => { if (e.target === modal) window.lucilleClose(); });
+}

package/factory.json

@@ -0,0 +1,7 @@
+{
+  "name": "lucille",
+  "creator": "Planet Nine",
+  "category": "media",
+  "type": "video",
+  "description": "P2P video hosting with WebTorrent and DigitalOcean Spaces. Each wiki gets its own tracker, federated with the wiki neighborhood for maximum reach."
+}

package/index.js

@@ -0,0 +1,4 @@
+(function() {
+  const { startServer } = require('./server/server.js');
+  module.exports = { startServer };
+}).call(this);

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "wiki-plugin-lucille",
+  "version": "0.0.1",
+  "description": "Federated Wiki plugin — P2P video hosting via Lucille (WebTorrent + DO Spaces)",
+  "keywords": ["wiki", "plugin", "video", "webtorrent", "planet-nine"],
+  "author": "Planet Nine",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "index.js",
+  "dependencies": {
+    "http-proxy": "^1.18.1",
+    "lucille": "latest",
+    "node-fetch": "^2.6.1",
+    "sessionless-node": "latest"
+  }
+}