nostr-git-client 0.0.1

package/README.md

@@ -0,0 +1,167 @@
+# nostr-git-client
+
+Browser-based git sync via Nostr with optional Bitcoin anchoring.
+
+Subscribe to NIP-34 repo state events (kind 30618) and sync git repositories to browser IndexedDB using isomorphic-git.
+
+## Installation
+
+```bash
+npm install nostr-git-client
+```
+
+## Usage
+
+### Basic Git Sync
+
+```javascript
+import { NostrGitClient } from 'nostr-git-client';
+
+const client = new NostrGitClient({
+  repo: 'https://solid.social/mel/public/myapp',
+  repoId: 'myapp',
+  branch: 'main',
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+  trusted: ['pubkey-hex...']  // Only sync from trusted publishers
+});
+
+client.on('sync', (event) => {
+  if (event.status === 'complete') {
+    console.log('Synced to:', event.commit);
+  }
+});
+
+client.connect();
+await client.sync();
+
+// Read files from synced repo
+const content = await client.readFile('index.html');
+const files = await client.listFiles('src');
+```
+
+### State Management with Bitcoin Anchoring
+
+```javascript
+import { NostrGitClient, StateManager } from 'nostr-git-client';
+
+const client = new NostrGitClient({
+  repo: 'https://solid.social/mel/public/game',
+  trusted: ['pubkey...']
+});
+
+const state = new StateManager({
+  sync: client,
+  file: 'state.json',
+  anchor: {
+    privkey: 'your-bitcoin-privkey-hex',
+    network: 'testnet4'
+  },
+  onChange: (newState) => {
+    console.log('State updated:', newState);
+  }
+});
+
+await state.init();
+client.connect();
+await client.sync();
+
+// Anchor current state to Bitcoin
+const anchor = await state.anchor();
+console.log('Anchored:', anchor.txid);
+```
+
+### Self-Deploying Pages
+
+```javascript
+import { SelfDeploy } from 'nostr-git-client';
+
+// Auto-reload when repo is updated
+SelfDeploy.init({
+  repo: 'https://solid.social/mel/public/myapp',
+  trusted: ['pubkey...'],
+  autoReload: true,
+  onUpdate: (event) => {
+    console.log('Update detected:', event.commit);
+  }
+});
+```
+
+## API
+
+### NostrGitClient
+
+Main client for Nostr-based git sync.
+
+**Constructor options:**
+- `repo` - Git repository URL
+- `repoId` - Repository identifier (default: derived from repo URL)
+- `branch` - Branch to track (default: 'main')
+- `relays` - Nostr relay URLs
+- `trusted` - Trusted publisher pubkeys
+- `corsProxy` - CORS proxy URL (optional)
+
+**Methods:**
+- `connect()` - Connect to relays and start listening
+- `disconnect()` - Disconnect from relays
+- `sync(commit?)` - Sync to specified commit or latest
+- `readFile(path)` - Read file content as string
+- `readFileBytes(path)` - Read file as Uint8Array
+- `listFiles(path?)` - List directory contents
+- `getAllFiles()` - Get all files recursively
+- `getCommit()` - Get current commit info
+- `clear()` - Delete local repository
+
+**Events:**
+- `sync` - Sync status changes
+- `event` - Nostr events received
+- `connect` - Connected to relay
+- `disconnect` - Disconnected from relay
+- `error` - Errors
+
+### StateManager
+
+Manages JSON state with optional Bitcoin anchoring.
+
+**Constructor options:**
+- `sync` - NostrGitClient instance
+- `file` - Path to JSON file (default: 'state.json')
+- `anchor` - Bitcoin config: `{ privkey, network }`
+- `onChange` - Callback on state changes
+
+**Methods:**
+- `init()` - Initialize (loads blocktrails if anchoring)
+- `loadState()` - Load state from file
+- `get()` - Get current state
+- `anchor()` - Anchor state to Bitcoin
+- `getAnchors()` - Get anchor history
+- `verifyChain()` - Verify anchor chain integrity
+
+### SelfDeploy
+
+Auto-updating pages.
+
+**Static methods:**
+- `init(options)` - Initialize self-deploy
+- `loaderScript(options)` - Generate embed script
+- `serviceWorkerCode()` - Generate SW code
+
+**Options:**
+- `repo` - Repository URL (required)
+- `trusted` - Trusted pubkeys (required)
+- `autoReload` - Auto reload on update (default: true)
+- `reloadDelay` - Delay before reload in ms (default: 1000)
+- `onUpdate` - Callback on update
+- `onSync` - Callback after sync
+
+## Dependencies
+
+- [isomorphic-git](https://isomorphic-git.org/) - Git in JavaScript
+- [@isomorphic-git/lightning-fs](https://github.com/isomorphic-git/lightning-fs) - IndexedDB filesystem
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools) - Nostr protocol
+
+**Optional:**
+- [blocktrails](https://www.npmjs.com/package/blocktrails) - Bitcoin state anchoring
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "nostr-git-client",
+  "version": "0.0.1",
+  "description": "Browser-based git sync via Nostr with optional Bitcoin anchoring",
+  "type": "module",
+  "main": "src/index.js",
+  "browser": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "dependencies": {
+    "@isomorphic-git/lightning-fs": "^4.6.0",
+    "isomorphic-git": "^1.27.1",
+    "nostr-tools": "^2.19.4"
+  },
+  "optionalDependencies": {
+    "blocktrails": "^0.0.11"
+  },
+  "keywords": [
+    "nostr",
+    "git",
+    "isomorphic-git",
+    "browser",
+    "sync",
+    "nip-34",
+    "bitcoin",
+    "anchor",
+    "decentralized"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JavaScriptSolidServer/nostr-git-client"
+  },
+  "license": "MIT"
+}

package/src/NostrGitClient.js

@@ -0,0 +1,352 @@
+/**
+ * NostrGitClient - Browser-based git sync via Nostr
+ *
+ * Subscribes to NIP-34 repo state events (kind 30618) and syncs
+ * git repositories to browser IndexedDB using isomorphic-git.
+ */
+
+import git from 'isomorphic-git';
+import { createFS, createHttpClient, parseRepoEvent, verifyEvent } from './utils.js';
+
+export class NostrGitClient {
+  /**
+   * Create a new NostrGitClient
+   * @param {Object} options
+   * @param {string} options.repo - Git repository URL
+   * @param {string} options.repoId - Repository identifier (for Nostr d tag)
+   * @param {string} options.branch - Branch to track (default: 'main')
+   * @param {string[]} options.relays - Nostr relay URLs
+   * @param {string[]} options.trusted - Trusted publisher pubkeys
+   * @param {string} options.dir - Local directory path (default: /<repoId>)
+   * @param {LightningFS} options.fs - Filesystem instance (optional)
+   * @param {Object} options.http - HTTP client (optional)
+   * @param {string} options.corsProxy - CORS proxy URL (optional)
+   */
+  constructor(options) {
+    this.repo = options.repo;
+    this.repoId = options.repoId || options.repo.split('/').pop();
+    this.branch = options.branch || 'main';
+    this.relays = options.relays || ['wss://relay.damus.io', 'wss://nos.lol'];
+    this.trusted = options.trusted || [];
+    this.dir = options.dir || `/${this.repoId}`;
+
+    this.fs = options.fs || createFS();
+    this.pfs = this.fs.promises;
+    this.http = options.http || createHttpClient({ corsProxy: options.corsProxy });
+
+    this.websockets = [];
+    this.listeners = new Map();
+    this.currentCommit = null;
+    this.synced = false;
+    this.syncing = false;
+  }
+
+  /**
+   * Add event listener
+   * @param {string} event - Event name: 'sync', 'event', 'error', 'connect', 'disconnect'
+   * @param {Function} callback - Callback function
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event).push(callback);
+    return this;
+  }
+
+  /**
+   * Remove event listener
+   */
+  off(event, callback) {
+    const listeners = this.listeners.get(event);
+    if (listeners) {
+      const idx = listeners.indexOf(callback);
+      if (idx >= 0) listeners.splice(idx, 1);
+    }
+    return this;
+  }
+
+  /**
+   * Emit event to listeners
+   */
+  emit(event, ...args) {
+    const listeners = this.listeners.get(event) || [];
+    listeners.forEach(cb => {
+      try { cb(...args); } catch (e) { console.error('Listener error:', e); }
+    });
+  }
+
+  /**
+   * Connect to Nostr relays and start listening
+   */
+  connect() {
+    this.disconnect(); // Clean up existing connections
+
+    this.relays.forEach((url, i) => {
+      const ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        this.emit('connect', url);
+
+        // Subscribe to repo state events
+        ws.send(JSON.stringify([
+          'REQ',
+          `ngc-${i}`,
+          {
+            kinds: [30618],
+            '#d': [this.repoId],
+            limit: 1
+          }
+        ]));
+      };
+
+      ws.onmessage = (e) => {
+        try {
+          const msg = JSON.parse(e.data);
+          if (msg[0] === 'EVENT' && msg[2]) {
+            this.handleEvent(msg[2]);
+          }
+        } catch {}
+      };
+
+      ws.onclose = () => {
+        this.emit('disconnect', url);
+      };
+
+      ws.onerror = (err) => {
+        this.emit('error', new Error(`WebSocket error: ${url}`));
+      };
+
+      this.websockets.push(ws);
+    });
+
+    return this;
+  }
+
+  /**
+   * Disconnect from all relays
+   */
+  disconnect() {
+    this.websockets.forEach(ws => ws.close());
+    this.websockets = [];
+    return this;
+  }
+
+  /**
+   * Handle incoming Nostr event
+   */
+  async handleEvent(event) {
+    // Verify signature
+    if (!await verifyEvent(event)) {
+      this.emit('error', new Error('Invalid event signature'));
+      return;
+    }
+
+    // Check if from trusted publisher
+    if (this.trusted.length > 0 && !this.trusted.includes(event.pubkey)) {
+      this.emit('event', { type: 'untrusted', event });
+      return;
+    }
+
+    // Parse event
+    const parsed = parseRepoEvent(event);
+    if (!parsed) return;
+
+    this.emit('event', { type: 'repo', ...parsed });
+
+    // Check if we need to sync
+    if (parsed.repoId === this.repoId && parsed.branch === this.branch) {
+      if (this.currentCommit !== parsed.commit) {
+        await this.sync(parsed.commit);
+      }
+    }
+  }
+
+  /**
+   * Sync repository to specified commit (or latest)
+   * @param {string} targetCommit - Commit hash to checkout (optional)
+   * @returns {Object} Sync result
+   */
+  async sync(targetCommit = null) {
+    if (this.syncing) {
+      return { success: false, error: 'Already syncing' };
+    }
+
+    this.syncing = true;
+    this.emit('sync', { status: 'start', commit: targetCommit });
+
+    try {
+      // Check if already cloned
+      let needsClone = true;
+      try {
+        await this.pfs.stat(`${this.dir}/.git`);
+        needsClone = false;
+      } catch {}
+
+      if (needsClone) {
+        // Ensure directory exists
+        try { await this.pfs.mkdir(this.dir); } catch {}
+
+        await git.clone({
+          fs: this.fs,
+          http: this.http,
+          dir: this.dir,
+          url: this.repo,
+          ref: this.branch,
+          singleBranch: true,
+          depth: 10
+        });
+      } else {
+        // Fetch updates
+        await git.fetch({
+          fs: this.fs,
+          http: this.http,
+          dir: this.dir,
+          url: this.repo,
+          ref: this.branch,
+          singleBranch: true
+        });
+      }
+
+      // Checkout to specific commit or branch head
+      const ref = targetCommit || this.branch;
+      await git.checkout({
+        fs: this.fs,
+        dir: this.dir,
+        ref,
+        force: true
+      });
+
+      // Get current commit info
+      const commits = await git.log({ fs: this.fs, dir: this.dir, depth: 1 });
+      const commit = commits[0];
+      this.currentCommit = commit?.oid;
+      this.synced = true;
+      this.syncing = false;
+
+      const result = {
+        success: true,
+        commit: commit?.oid,
+        message: commit?.commit.message,
+        author: commit?.commit.author.name,
+        date: new Date(commit?.commit.author.timestamp * 1000)
+      };
+
+      this.emit('sync', { status: 'complete', ...result });
+      return result;
+
+    } catch (err) {
+      this.syncing = false;
+      this.emit('sync', { status: 'error', error: err.message });
+      this.emit('error', err);
+      return { success: false, error: err.message };
+    }
+  }
+
+  /**
+   * Read a file from the synced repository
+   * @param {string} path - File path relative to repo root
+   * @returns {string} File content
+   */
+  async readFile(path) {
+    return this.pfs.readFile(`${this.dir}/${path}`, 'utf8');
+  }
+
+  /**
+   * Read a file as bytes
+   * @param {string} path - File path
+   * @returns {Uint8Array} File content
+   */
+  async readFileBytes(path) {
+    return this.pfs.readFile(`${this.dir}/${path}`);
+  }
+
+  /**
+   * List files in directory
+   * @param {string} path - Directory path (default: repo root)
+   * @returns {Array} File entries
+   */
+  async listFiles(path = '') {
+    const fullPath = `${this.dir}/${path}`.replace(/\/+$/, '');
+    const entries = await this.pfs.readdir(fullPath);
+
+    const result = [];
+    for (const entry of entries) {
+      if (entry === '.git') continue;
+      const stat = await this.pfs.stat(`${fullPath}/${entry}`);
+      result.push({
+        name: entry,
+        path: path ? `${path}/${entry}` : entry,
+        type: stat.isDirectory() ? 'dir' : 'file'
+      });
+    }
+
+    return result.sort((a, b) => {
+      if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  /**
+   * Get all files recursively
+   * @returns {Array} All file paths
+   */
+  async getAllFiles() {
+    const files = [];
+    const walk = async (path) => {
+      const entries = await this.listFiles(path);
+      for (const entry of entries) {
+        if (entry.type === 'dir') {
+          await walk(entry.path);
+        } else {
+          files.push(entry.path);
+        }
+      }
+    };
+    await walk('');
+    return files;
+  }
+
+  /**
+   * Get current commit info
+   * @returns {Object} Commit info
+   */
+  async getCommit() {
+    const commits = await git.log({ fs: this.fs, dir: this.dir, depth: 1 });
+    if (commits.length === 0) return null;
+
+    const c = commits[0];
+    return {
+      hash: c.oid,
+      message: c.commit.message,
+      author: c.commit.author.name,
+      email: c.commit.author.email,
+      date: new Date(c.commit.author.timestamp * 1000)
+    };
+  }
+
+  /**
+   * Clear local repository from IndexedDB
+   */
+  async clear() {
+    const deleteRecursive = async (path) => {
+      try {
+        const entries = await this.pfs.readdir(path);
+        for (const entry of entries) {
+          const fullPath = `${path}/${entry}`;
+          const stat = await this.pfs.stat(fullPath);
+          if (stat.isDirectory()) {
+            await deleteRecursive(fullPath);
+          } else {
+            await this.pfs.unlink(fullPath);
+          }
+        }
+        await this.pfs.rmdir(path);
+      } catch {}
+    };
+
+    await deleteRecursive(this.dir);
+    this.currentCommit = null;
+    this.synced = false;
+  }
+}

package/src/SelfDeploy.js

@@ -0,0 +1,226 @@
+/**
+ * SelfDeploy - Auto-updating pages via Nostr git sync
+ *
+ * Enables pages to automatically reload when their source repo
+ * receives updates via Nostr announcements.
+ */
+
+import { NostrGitClient } from './NostrGitClient.js';
+
+export class SelfDeploy {
+  /**
+   * Initialize self-deploying page
+   *
+   * @param {Object} options
+   * @param {string} options.repo - Git repository URL
+   * @param {string} options.repoId - Repository identifier (optional, derived from repo)
+   * @param {string} options.branch - Branch to track (default: 'main')
+   * @param {string[]} options.relays - Nostr relay URLs
+   * @param {string[]} options.trusted - Trusted publisher pubkeys (required for auto-reload)
+   * @param {Function} options.onUpdate - Called when update detected (default: reload page)
+   * @param {Function} options.onSync - Called after sync completes
+   * @param {Function} options.onError - Called on errors
+   * @param {boolean} options.autoReload - Auto reload on update (default: true)
+   * @param {number} options.reloadDelay - Delay before reload in ms (default: 1000)
+   * @param {string} options.corsProxy - CORS proxy URL (optional)
+   * @returns {SelfDeploy} Instance
+   */
+  static init(options) {
+    return new SelfDeploy(options);
+  }
+
+  constructor(options) {
+    if (!options.repo) {
+      throw new Error('repo is required');
+    }
+
+    if (!options.trusted || options.trusted.length === 0) {
+      throw new Error('trusted pubkeys required for SelfDeploy');
+    }
+
+    this.options = {
+      autoReload: true,
+      reloadDelay: 1000,
+      branch: 'main',
+      ...options
+    };
+
+    this.client = new NostrGitClient({
+      repo: this.options.repo,
+      repoId: this.options.repoId,
+      branch: this.options.branch,
+      relays: this.options.relays,
+      trusted: this.options.trusted,
+      corsProxy: this.options.corsProxy
+    });
+
+    this.currentCommit = null;
+    this.setupListeners();
+    this.client.connect();
+  }
+
+  setupListeners() {
+    // Track sync events
+    this.client.on('sync', (event) => {
+      if (event.status === 'complete') {
+        const isUpdate = this.currentCommit && this.currentCommit !== event.commit;
+        this.currentCommit = event.commit;
+
+        if (this.options.onSync) {
+          this.options.onSync(event);
+        }
+
+        if (isUpdate) {
+          this.handleUpdate(event);
+        }
+      }
+
+      if (event.status === 'error' && this.options.onError) {
+        this.options.onError(new Error(event.error));
+      }
+    });
+
+    // Track repo events from trusted publishers
+    this.client.on('event', (event) => {
+      if (event.type === 'repo') {
+        // New commit announced - trigger sync
+        if (event.commit !== this.currentCommit) {
+          this.client.sync(event.commit);
+        }
+      }
+    });
+
+    // Forward errors
+    this.client.on('error', (err) => {
+      if (this.options.onError) {
+        this.options.onError(err);
+      }
+    });
+
+    // Log connections
+    this.client.on('connect', (url) => {
+      console.log(`[SelfDeploy] Connected to ${url}`);
+    });
+  }
+
+  handleUpdate(event) {
+    console.log(`[SelfDeploy] Update detected: ${event.commit?.slice(0, 8)}`);
+
+    if (this.options.onUpdate) {
+      this.options.onUpdate(event);
+    }
+
+    if (this.options.autoReload) {
+      console.log(`[SelfDeploy] Reloading in ${this.options.reloadDelay}ms...`);
+      setTimeout(() => {
+        location.reload();
+      }, this.options.reloadDelay);
+    }
+  }
+
+  /**
+   * Manually trigger sync
+   * @returns {Promise<Object>} Sync result
+   */
+  sync() {
+    return this.client.sync();
+  }
+
+  /**
+   * Get current commit info
+   * @returns {Promise<Object>} Commit info
+   */
+  getCommit() {
+    return this.client.getCommit();
+  }
+
+  /**
+   * Read a file from the synced repo
+   * @param {string} path - File path
+   * @returns {Promise<string>} File content
+   */
+  readFile(path) {
+    return this.client.readFile(path);
+  }
+
+  /**
+   * List files in directory
+   * @param {string} path - Directory path
+   * @returns {Promise<Array>} File entries
+   */
+  listFiles(path) {
+    return this.client.listFiles(path);
+  }
+
+  /**
+   * Check if synced
+   * @returns {boolean}
+   */
+  get synced() {
+    return this.client.synced;
+  }
+
+  /**
+   * Disconnect from relays
+   */
+  disconnect() {
+    this.client.disconnect();
+  }
+
+  /**
+   * Create a minimal loader script for embedding
+   * Returns HTML that can be injected to enable self-deploy
+   *
+   * @param {Object} options - Same as constructor options
+   * @returns {string} Script tag HTML
+   */
+  static loaderScript(options) {
+    const config = JSON.stringify(options);
+    return `<script type="module">
+import { SelfDeploy } from 'nostr-git-client';
+SelfDeploy.init(${config});
+</script>`;
+  }
+
+  /**
+   * Create a service worker for offline-first self-deploy
+   * The service worker syncs in the background and notifies the page
+   *
+   * @returns {string} Service worker code
+   */
+  static serviceWorkerCode() {
+    return `
+// SelfDeploy Service Worker
+// Syncs git repo in background and caches files
+
+const CACHE_NAME = 'selfdeploy-v1';
+
+self.addEventListener('install', (event) => {
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(clients.claim());
+});
+
+self.addEventListener('message', async (event) => {
+  if (event.data.type === 'SYNC') {
+    // Notify all clients of update
+    const clients = await self.clients.matchAll();
+    clients.forEach(client => {
+      client.postMessage({ type: 'UPDATE', commit: event.data.commit });
+    });
+  }
+});
+
+self.addEventListener('fetch', (event) => {
+  // Cache-first strategy for synced files
+  event.respondWith(
+    caches.match(event.request).then(cached => {
+      return cached || fetch(event.request);
+    })
+  );
+});
+`;
+  }
+}

package/src/StateManager.js

@@ -0,0 +1,260 @@
+/**
+ * StateManager - JSON state management with optional Bitcoin anchoring
+ *
+ * Manages a JSON state file from a synced git repository.
+ * Optionally anchors state changes to Bitcoin via blocktrails.
+ */
+
+export class StateManager {
+  /**
+   * Create a StateManager
+   * @param {Object} options
+   * @param {NostrGitClient} options.sync - NostrGitClient instance
+   * @param {string} options.file - Path to JSON state file (default: 'state.json')
+   * @param {Object} options.anchor - Bitcoin anchoring options (optional)
+   * @param {string} options.anchor.privkey - Private key hex for anchoring
+   * @param {string} options.anchor.network - 'testnet4' or 'mainnet' (default: 'testnet4')
+   * @param {Function} options.onChange - Callback when state changes
+   */
+  constructor(options) {
+    this.sync = options.sync;
+    this.file = options.file || 'state.json';
+    this.anchorConfig = options.anchor || null;
+    this.onChange = options.onChange || null;
+
+    this.state = null;
+    this.stateHash = null;
+    this.anchors = [];
+    this.blocktrails = null;
+
+    // Listen for sync events
+    this.sync.on('sync', async (event) => {
+      if (event.status === 'complete') {
+        await this.loadState();
+      }
+    });
+  }
+
+  /**
+   * Initialize the state manager
+   * Loads blocktrails if anchoring is enabled
+   */
+  async init() {
+    // Try to load blocktrails for anchoring
+    if (this.anchorConfig) {
+      try {
+        const bt = await import('blocktrails');
+        this.blocktrails = bt;
+      } catch {
+        console.warn('blocktrails not available - anchoring disabled');
+        this.anchorConfig = null;
+      }
+    }
+
+    // Load initial state if synced
+    if (this.sync.synced) {
+      await this.loadState();
+    }
+
+    return this;
+  }
+
+  /**
+   * Load state from the synced file
+   */
+  async loadState() {
+    try {
+      const content = await this.sync.readFile(this.file);
+      const newState = JSON.parse(content);
+      const newHash = await this.hashState(newState);
+
+      if (newHash !== this.stateHash) {
+        this.state = newState;
+        this.stateHash = newHash;
+
+        if (this.onChange) {
+          this.onChange(this.state);
+        }
+      }
+
+      return this.state;
+    } catch (err) {
+      // File might not exist yet
+      if (err.code === 'ENOENT') {
+        this.state = {};
+        this.stateHash = null;
+        return this.state;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Get current state
+   * @returns {Object} Current state
+   */
+  get() {
+    return this.state;
+  }
+
+  /**
+   * Hash state for anchoring/comparison
+   * @param {Object} state - State to hash
+   * @returns {string} SHA-256 hash hex
+   */
+  async hashState(state) {
+    const json = JSON.stringify(state, null, 2);
+    const bytes = new TextEncoder().encode(json);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(hashBuffer))
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Anchor current state to Bitcoin
+   * Creates a P2TR output committing to the state hash
+   * @returns {Object} Anchor result with txid
+   */
+  async anchor() {
+    if (!this.blocktrails || !this.anchorConfig) {
+      throw new Error('Anchoring not configured');
+    }
+
+    if (!this.state || !this.stateHash) {
+      throw new Error('No state to anchor');
+    }
+
+    const bt = this.blocktrails;
+    const privkey = this.anchorConfig.privkey;
+    const network = this.anchorConfig.network || 'testnet4';
+
+    // Get previous anchor states for chaining
+    const prevStates = this.anchors.map(a => a.hash);
+    const allStates = [...prevStates, this.stateHash];
+
+    // Derive pubkey from privkey
+    const pubkeyBase = bt.getPublicKey(privkey);
+
+    // For first anchor, derive simple tweaked address
+    // For subsequent anchors, use chained derivation
+    let fromPubkey, toPubkey;
+
+    if (prevStates.length === 0) {
+      // First anchor - spend from base key to tweaked key
+      fromPubkey = pubkeyBase;
+      toPubkey = bt.derivePubkey(pubkeyBase, this.stateHash);
+    } else {
+      // Chained anchor - spend from previous tweaked to new tweaked
+      fromPubkey = bt.deriveChainedPubkey(pubkeyBase, prevStates);
+      toPubkey = bt.deriveChainedPubkey(pubkeyBase, allStates);
+    }
+
+    // Get UTXOs from previous address
+    const fromAddress = bt.pubkeyToAddress(fromPubkey, network);
+    const utxos = await bt.fetchUTXOs(fromAddress, network);
+
+    if (utxos.length === 0) {
+      throw new Error(`No funds at ${fromAddress}`);
+    }
+
+    // Use largest UTXO
+    const utxo = utxos.reduce((a, b) => a.value > b.value ? a : b);
+
+    // Create and broadcast transaction
+    const toAddress = bt.pubkeyToAddress(toPubkey, network);
+    const fee = 300; // Minimal fee for P2TR
+
+    const tx = bt.createAnchorTx({
+      utxo,
+      privkey,
+      prevStates,
+      newState: this.stateHash,
+      toAddress,
+      fee,
+      network
+    });
+
+    const txid = await bt.broadcastTx(tx, network);
+
+    // Record anchor
+    const anchor = {
+      txid,
+      hash: this.stateHash,
+      address: toAddress,
+      timestamp: Date.now(),
+      state: JSON.parse(JSON.stringify(this.state))
+    };
+
+    this.anchors.push(anchor);
+
+    return anchor;
+  }
+
+  /**
+   * Get all anchors
+   * @returns {Array} List of anchors
+   */
+  getAnchors() {
+    return this.anchors;
+  }
+
+  /**
+   * Verify anchor chain
+   * Checks that all anchors form a valid chain
+   * @returns {boolean} True if valid
+   */
+  async verifyChain() {
+    if (!this.blocktrails || this.anchors.length === 0) {
+      return true;
+    }
+
+    const bt = this.blocktrails;
+    const network = this.anchorConfig?.network || 'testnet4';
+    const pubkeyBase = bt.getPublicKey(this.anchorConfig.privkey);
+
+    // Verify each anchor has the expected address
+    const states = [];
+    for (const anchor of this.anchors) {
+      states.push(anchor.hash);
+      const expectedPubkey = bt.deriveChainedPubkey(pubkeyBase, states);
+      const expectedAddress = bt.pubkeyToAddress(expectedPubkey, network);
+
+      if (anchor.address !== expectedAddress) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get anchor chain storage key
+   */
+  get storageKey() {
+    return `state-anchors-${this.sync.repoId}-${this.file}`;
+  }
+
+  /**
+   * Save anchors to localStorage
+   */
+  saveAnchors() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.anchors));
+    }
+  }
+
+  /**
+   * Load anchors from localStorage
+   */
+  loadAnchors() {
+    if (typeof localStorage !== 'undefined') {
+      try {
+        const saved = localStorage.getItem(this.storageKey);
+        if (saved) {
+          this.anchors = JSON.parse(saved);
+        }
+      } catch {}
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * nostr-git-client - Browser-based git sync via Nostr
+ *
+ * Usage:
+ *   import { NostrGitClient, StateManager, SelfDeploy } from 'nostr-git-client';
+ */
+
+export { NostrGitClient } from './NostrGitClient.js';
+export { StateManager } from './StateManager.js';
+export { SelfDeploy } from './SelfDeploy.js';
+export { createFS, createHttpClient } from './utils.js';

package/src/utils.js

@@ -0,0 +1,90 @@
+/**
+ * Utility functions for nostr-git-client
+ */
+
+import LightningFS from '@isomorphic-git/lightning-fs';
+
+/**
+ * Create a LightningFS instance for IndexedDB storage
+ * @param {string} name - Database name
+ * @returns {LightningFS} Filesystem instance
+ */
+export function createFS(name = 'nostr-git-client') {
+  return new LightningFS(name);
+}
+
+/**
+ * Create an HTTP client for isomorphic-git
+ * Works with JSS and other git HTTP servers
+ * @param {Object} options
+ * @param {string} options.corsProxy - CORS proxy URL (optional)
+ * @param {Object} options.headers - Additional headers
+ * @returns {Object} HTTP client for isomorphic-git
+ */
+export function createHttpClient(options = {}) {
+  const { corsProxy, headers = {} } = options;
+
+  return {
+    async request({ url, method, headers: reqHeaders, body }) {
+      // Apply CORS proxy if specified
+      const finalUrl = corsProxy ? `${corsProxy}${encodeURIComponent(url)}` : url;
+
+      const res = await fetch(finalUrl, {
+        method,
+        headers: { ...reqHeaders, ...headers },
+        body
+      });
+
+      return {
+        url: res.url,
+        method,
+        statusCode: res.status,
+        statusMessage: res.statusText,
+        headers: Object.fromEntries(res.headers.entries()),
+        body: [new Uint8Array(await res.arrayBuffer())]
+      };
+    }
+  };
+}
+
+/**
+ * Verify Nostr event signature
+ * @param {Object} event - Nostr event
+ * @returns {boolean} True if valid
+ */
+export async function verifyEvent(event) {
+  try {
+    const { verifyEvent } = await import('nostr-tools/pure');
+    return verifyEvent(event);
+  } catch {
+    // Fallback: assume valid if nostr-tools not available
+    console.warn('nostr-tools not available for signature verification');
+    return true;
+  }
+}
+
+/**
+ * Parse a 30618 repo state event
+ * @param {Object} event - Nostr event
+ * @returns {Object|null} Parsed event data
+ */
+export function parseRepoEvent(event) {
+  if (event.kind !== 30618) return null;
+
+  const repoId = event.tags.find(t => t[0] === 'd')?.[1];
+  const refTag = event.tags.find(t => t[0].startsWith('refs/'));
+  const anchorTag = event.tags.find(t => t[0] === 'c');
+
+  if (!repoId || !refTag) return null;
+
+  return {
+    pubkey: event.pubkey,
+    repoId,
+    ref: refTag[0],
+    branch: refTag[0].replace('refs/heads/', ''),
+    commit: refTag[1],
+    anchor: anchorTag?.[1] || null,
+    createdAt: event.created_at,
+    raw: event
+  };
+}